Meter

---
// src/components/ui/display/meter/Meter.astro — headless primitive (see ../../README.md).
// `<meter>`: the native element nobody remembers exists. Disk usage, storage quota, a score out of
// ten, password strength, a battery — a MEASUREMENT within a known range.
//
// It is not a Progress bar, and the difference is not cosmetic. `<progress>` (and our Progress) is a
// TASK: it starts at nothing, ends at done, and only ever goes up. A meter is a reading: it can go
// down, "full" may be bad news, and it carries something no progress bar can express —
// `low` / `high` / `optimum`, which tell the browser and assistive tech which end of the range is
// the good one. That is why "7.2 GB of 10 GB used" is a meter and a file upload is not.
//
//   <Meter value={7.2} max={10} high={8} optimum={0} label="Storage used" />
//
// Two things are deliberately NOT here:
//
//   • No `appearance: none`. That is the Slider lesson exactly — zeroing the appearance of a native
//     control erases the UA's whole rendering, so shipping it without geometry would turn "unstyled"
//     into "invisible". Restyling a meter is all-or-nothing and belongs to a theme that means it;
//     `theme-default.css` has the worked example. Left alone, you get the browser's control, which
//     works everywhere and needs no CSS at all.
//   • No fallback bar built from divs. The slot IS the fallback: its contents render only in a
//     browser with no <meter>, which in practice means a text version of the same number.
import type { HTMLAttributes } from "astro/types";

type Props = HTMLAttributes<"meter"> & {
  value: number;
  min?: number;
  max?: number;
  /** The top of the "low" band — below this the browser may render the meter as poor. */
  low?: number;
  /** The bottom of the "high" band. */
  high?: number;
  /** Where in the range is GOOD. Put it below `low` when a high reading is the bad news. */
  optimum?: number;
  /** The reading's accessible name. A meter with no name is announced as an unlabelled one. */
  label?: string;
  size?: "sm" | "md" | "lg";
};

const {
  value,
  min = 0,
  max = 100,
  low,
  high,
  optimum,
  label,
  size = "md",
  class: className,
  ...rest
} = Astro.props;
---

<meter
  value={value}
  min={min}
  max={max}
  low={low}
  high={high}
  optimum={optimum}
  aria-label={label}
  class={className}
  data-slot="meter"
  data-size={size}
  {...rest}><slot>{value} / {max}</slot></meter
>

import Meter from "./Meter.astro";

export { Meter };
export default Meter;