Gauge

---
/**
 * Gauge — a ring or an arc that fills to a value as it scrolls into view, the value counting up in the middle with it.
 * The SVG is drawn on the server: a track the length of the shape and, over it, the value's stroke as one dash that
 * grows from the start (its offset transitions to zero). The colour can follow the value through bands, picked at
 * build. Composes Reveal for the trigger and CountUp for the number; no script of its own. The element is a meter, so
 * a screen reader hears the label and the value once.
 */
import type { HTMLAttributes, HTMLTag } from 'astro/types';
import Reveal from './Reveal.astro';
import CountUp from './CountUp.astro';

interface Band {
  /** The band holds every value up to this one (inclusive). */
  upTo: number;
  /** Any CSS colour. */
  color: string;
}

interface Props extends HTMLAttributes<'div'> {
  /** The value shown. */
  value: number;
  /** The low end of the scale. */
  min?: number;
  /** The high end of the scale. */
  max?: number;
  /** What it measures, under the value (or inside a half gauge); also the meter's name. */
  label?: string;
  /** Text after the number, e.g. "%" or " ms". */
  suffix?: string;
  /** Text before the number. */
  prefix?: string;
  /** Decimal places of the number, 0–4. */
  decimals?: number;
  /** ring: a full circle from the top; arc: three quarters, open at the bottom; half: the upper half. */
  shape?: 'ring' | 'arc' | 'half';
  /** The drawing's width; any CSS length. */
  size?: string;
  /** Stroke width in the 100-unit viewBox. */
  thickness?: number;
  /** The value's colour. */
  color?: string;
  /** Colours by value: the first band whose upTo holds the value wins, over color. */
  bands?: Band[];
  /** The track's colour. */
  track?: string;
  /** Fill duration in ms. Unset, the preset's --ma-duration-slow. */
  duration?: number;
  /** Delay before filling, in ms. */
  delay?: number;
  /** Element to render. */
  as?: HTMLTag;
}

const {
  value,
  min = 0,
  max = 100,
  label,
  suffix = '',
  prefix = '',
  decimals = 0,
  shape = 'ring',
  size,
  thickness = 9,
  color,
  bands,
  track,
  duration,
  delay,
  as = 'div',
  class: className,
  style,
  ...rest
} = Astro.props;

const w = Math.min(Math.max(thickness, 1), 24);
const r = 50 - w / 2;
const clamp = Math.min(Math.max(value, Math.min(min, max)), Math.max(min, max));
const f = max === min ? 1 : (clamp - min) / (max - min);
// the share of the circle each shape draws, and where it starts (degrees clockwise from three o'clock)
const span = shape === 'ring' ? 100 : shape === 'arc' ? 75 : 50;
const start = shape === 'ring' ? -90 : shape === 'arc' ? 135 : 180;
const len = +(span * f).toFixed(3);
const band = bands?.slice().sort((a, b) => a.upTo - b.upTo).find((b) => clamp <= b.upTo);
const stroke = band?.color ?? color;
const viewH = shape === 'half' ? 50 + w / 2 + 1 : 100;
const places = Math.max(0, Math.min(decimals, 4));
const text = `${prefix}${clamp.toFixed(places)}${suffix}`;
const vars = [
  size && `--ma-gauge-size:${size}`,
  stroke && `--ma-gauge-color:${stroke}`,
  track && `--ma-gauge-track:${track}`,
  duration != null && `--ma-gauge-dur:${duration}ms`,
  delay != null && `--ma-gauge-delay:${delay}ms`,
  `--ma-gauge-len:${len}`,
  typeof style === 'string' ? style : '',
]
  .filter(Boolean)
  .join(';');
---

<Reveal
  as={as}
  from="none"
  duration={300}
  delay={delay}
  class={['ma-gauge', className].filter(Boolean).join(' ')}
  data-shape={shape}
  role="meter"
  aria-valuemin={min}
  aria-valuemax={max}
  aria-valuenow={clamp}
  aria-valuetext={text}
  aria-label={label ?? text}
  style={vars}
  {...rest}
>
  <svg class="ma-gauge__svg" viewBox={`0 0 100 ${viewH}`} aria-hidden="true" focusable="false">
    <circle class="ma-gauge__track" cx="50" cy="50" r={r} pathLength="100" stroke-width={w} stroke-dasharray={`${span} 100`} transform={`rotate(${start} 50 50)`} />
    {len > 0 && <circle class="ma-gauge__value" cx="50" cy="50" r={r} pathLength="100" stroke-width={w} stroke-dasharray={`${len} 100`} transform={`rotate(${start} 50 50)`} />}
  </svg>
  <span class="ma-gauge__center" aria-hidden="true">
    <CountUp class="ma-gauge__number" to={clamp} decimals={places} prefix={prefix} suffix={suffix} duration={duration ?? 900} delay={delay} />
    {label && <span class="ma-gauge__label">{label}</span>}
  </span>
</Reveal>

<style is:global>
  @layer components {
    :where(.ma-gauge) {
      position: relative;
      display: inline-grid;
      inline-size: var(--ma-gauge-size, 9rem);
      max-inline-size: 100%;
      color: inherit;
      font-variant-numeric: tabular-nums;
    }
    :where(.ma-gauge__svg) {
      display: block;
      inline-size: 100%;
      block-size: auto;
      overflow: visible;
    }
    :where(.ma-gauge__track),
    :where(.ma-gauge__value) {
      fill: none;
      stroke-linecap: round;
    }
    :where(.ma-gauge__track) {
      stroke: var(--ma-gauge-track, color-mix(in oklab, currentColor 14%, transparent));
    }
    :where(.ma-gauge__value) {
      stroke: var(--ma-gauge-color, var(--chart-1, currentColor));
      stroke-dashoffset: 0;
      transition: stroke-dashoffset var(--ma-gauge-dur, var(--ma-duration-slow, 700ms)) var(--ma-ease-out) var(--ma-gauge-delay, 0ms);
    }
    /* the number and its label sit in the middle of a ring or an arc, and on the baseline of a half */
    :where(.ma-gauge__center) {
      position: absolute;
      inset: 0;
      display: grid;
      place-content: center;
      justify-items: center;
      gap: 0.15em;
      padding: 18%;
      text-align: center;
      line-height: 1.1;
    }
    :where(.ma-gauge[data-shape='half'] .ma-gauge__center) {
      place-content: end center;
      padding: 0 20% 0;
    }
    :where(.ma-gauge__number) {
      font-size: calc(var(--ma-gauge-size, 9rem) * 0.19);
      font-weight: 650;
      letter-spacing: -0.02em;
    }
    :where(.ma-gauge__label) {
      font-size: max(0.6875rem, calc(var(--ma-gauge-size, 9rem) * 0.085));
      opacity: var(--ma-dim, 0.75);
    }
    /* Under the JS gate the stroke starts undrawn and grows once Reveal marks the gauge in view. */
    :where([data-ma-js] .ma-gauge:not(.ma-in) .ma-gauge__value) {
      stroke-dashoffset: var(--ma-gauge-len, 0);
      transition: none;
    }
    @media (prefers-reduced-motion: reduce) {
      :where(.ma-gauge__value) {
        transition: none;
      }
      :where([data-ma-js] .ma-gauge:not(.ma-in) .ma-gauge__value) {
        stroke-dashoffset: 0;
      }
    }
  }
</style>