Meter

/** @jsxImportSource hono/jsx */
import type { Child } from "hono/jsx"
import { cn, type ClassValue } from "@/registry/lib/cn"

// Meter — shadcn-htmx, htmx v4 + Tailwind v4.
//
// Source of truth:
//   shadcn/ui ships no Meter component. This is a native-platform addition
//   distinct from Progress: a gauge of a value within a known range
//   (battery, disk usage, score) — NOT task completion.
//
// We render the real native <meter> element (implicit role="meter"), so the
// browser supplies the role + value semantics and AT announces the gauge.
//   repos/mdn/files/en-us/web/html/reference/elements/meter/index.md
//     - value/min/max/low/high/optimum attributes (lines 33-48)
//     - "Implicit ARIA role: meter" and "Permitted ARIA roles: No role
//       permitted" (lines 123-134) — so we DO NOT set role/aria-value*; the
//       element maps value/min/max onto aria-valuenow/min/max itself.
//
// APG: WAI-ARIA Meter pattern
//   repos/aria-practices/content/patterns/meter/meter-pattern.html
//     - Keyboard Interaction: "Not applicable" (line 46) — a meter is not
//       interactive; no JS keyboard contract.
//     - Accessible name via aria-labelledby (visible label) or aria-label
//       (lines 61-64). We pair with a native <label for> in the docs.
//     - aria-valuetext for human-readable values, e.g. "50% (6 hours)
//       remaining" (lines 56-59) — surfaced via the `valuetext` prop.
//
// Cross-browser styling note: WebKit/Blink expose ::-webkit-meter-* and
// Gecko exposes ::-moz-meter-bar. Both need `appearance: none` to accept
// custom styles. Those pseudo-elements can't take Tailwind classes, so the
// fill/track theming lives in app/styles/input.css scoped to
// [data-slot="meter"]. Tailwind utilities here only size the box.

const meterBase =
  "block h-2 w-full overflow-hidden rounded-full bg-primary/20 align-middle"

export function meterClasses(opts?: { class?: ClassValue }): string {
  return cn(meterBase, opts?.class)
}

type MeterProps = {
  // Current value. Clamped by the browser to [min, max].
  value: number
  min?: number
  max?: number
  // Lower/upper bounds of the "low" and "high" zones. Combined with optimum
  // they drive the optimum / suboptimum / even-less-good fill color.
  low?: number
  high?: number
  optimum?: number
  id?: string
  // Free-form units hint. The WHATWG HTML spec notes <meter> has no units
  // attribute and that title is the only standard way to convey units
  // (e.g. title="gigabytes"). repos/whatwg-html/source meter section.
  title?: string
  // Accessible name — required when there's no linked <label>.
  ariaLabel?: string
  ariaLabelledby?: string
  ariaDescribedby?: string
  // Human-readable value for AT (e.g. "12.4 GB of 16 GB"). Falls back to the
  // child text content the element already carries.
  valuetext?: string
  // Fallback text content for legacy AT and as the visible value in browsers
  // without <meter> support. Defaults to a "value/max" string.
  children?: Child
  class?: ClassValue

  // htmx — refresh the gauge from the server.
  "hx-get"?: string
  "hx-post"?: string
  "hx-target"?: string
  "hx-swap"?: string
  "hx-trigger"?: string
}

export function Meter(props: MeterProps) {
  const {
    value,
    min = 0,
    max = 1,
    low,
    high,
    optimum,
    id,
    title,
    ariaLabel,
    ariaLabelledby,
    ariaDescribedby,
    valuetext,
    children,
    class: className,
    ...rest
  } = props
  const fallback = children ?? `${value} / ${max}`
  return (
    <meter
      id={id}
      data-slot="meter"
      title={title}
      value={value}
      min={min}
      max={max}
      low={low}
      high={high}
      optimum={optimum}
      aria-label={ariaLabel}
      aria-labelledby={ariaLabelledby}
      aria-describedby={ariaDescribedby}
      aria-valuetext={valuetext}
      class={meterClasses({ class: className })}
      {...rest}
    >
      {fallback}
    </meter>
  )
}

{# Meter macro — shadcn-htmx, htmx v4 + Tailwind v4.
   Mirrors registry/ui/meter.tsx. Renders the native <meter> element
   (implicit role="meter"); cross-browser fill/track theming lives in
   input.css scoped to [data-slot="meter"].

   Usage:
       {% from "components/meter.html" import meter %}
       <label for="disk" class="text-sm font-medium">Disk usage</label>
       {{ meter(id="disk", value=0.62, low=0.25, high=0.85, optimum=0.1,
                value_text="12.4 GB of 16 GB") }}
#}

{% macro meter(
    value=0,
    min=0,
    max=1,
    low=none,
    high=none,
    optimum=none,
    id=none,
    title=none,
    aria_label=none,
    aria_labelledby=none,
    aria_describedby=none,
    value_text=none,
    text=none,
    extra_class="",
    **attrs
) %}
{%- set base -%}
block h-2 w-full overflow-hidden rounded-full bg-primary/20 align-middle
{%- endset -%}
<meter class="{{ base }} {{ extra_class }}"
       {%- if id %} id="{{ id }}"{% endif %}
       {#- title is the spec-sanctioned way to convey units, e.g. "gigabytes" #}
       {%- if title %} title="{{ title }}"{% endif %}
       value="{{ value }}" min="{{ min }}" max="{{ max }}"
       {%- if low is not none %} low="{{ low }}"{% endif %}
       {%- if high is not none %} high="{{ high }}"{% endif %}
       {%- if optimum is not none %} optimum="{{ optimum }}"{% endif %}
       {%- if aria_label %} aria-label="{{ aria_label }}"{% endif %}
       {%- if aria_labelledby %} aria-labelledby="{{ aria_labelledby }}"{% endif %}
       {%- if aria_describedby %} aria-describedby="{{ aria_describedby }}"{% endif %}
       {%- if value_text %} aria-valuetext="{{ value_text }}"{% endif %}
       data-slot="meter"
       {%- for k, v in attrs.items() %} {{ k|replace('_', '-') }}="{{ v }}"{% endfor -%}
  >{{ text if text is not none else (value ~ ' / ' ~ max) }}</meter>
{% endmacro %}

{{/*
  Meter template — shadcn-htmx, htmx v4 + Tailwind v4.
  Mirrors registry/ui/meter.tsx. Renders the native <meter> element
  (implicit role="meter"); fill/track theming lives in input.css scoped
  to [data-slot="meter"].

  Usage:

      {{template "meter" (dict
          "ID" "disk" "Value" 0.62 "Low" 0.25 "High" 0.85 "Optimum" 0.1
          "ValueText" "12.4 GB of 16 GB")}}

  Low / High / Optimum are optional; pass them only when zoning the gauge.
*/}}

{{define "meter"}}
{{- $base := "block h-2 w-full overflow-hidden rounded-full bg-primary/20 align-middle" -}}
{{- $value := or .Value 0 -}}
{{- $min := or .Min 0 -}}
{{- $max := or .Max 1 -}}
{{- $text := or .Text (printf "%v / %v" $value $max) -}}
<meter class="{{$base}}{{if .Class}} {{.Class}}{{end}}"
       {{- if .ID}} id="{{.ID}}"{{end}}
       {{- /* title: spec-sanctioned way to convey units, e.g. "gigabytes" */}}
       {{- if .Title}} title="{{.Title}}"{{end}}
       value="{{$value}}" min="{{$min}}" max="{{$max}}"
       {{- if .Low}} low="{{.Low}}"{{end}}
       {{- if .High}} high="{{.High}}"{{end}}
       {{- if .Optimum}} optimum="{{.Optimum}}"{{end}}
       {{- if .AriaLabel}} aria-label="{{.AriaLabel}}"{{end}}
       {{- if .AriaLabelledby}} aria-labelledby="{{.AriaLabelledby}}"{{end}}
       {{- if .AriaDescribedby}} aria-describedby="{{.AriaDescribedby}}"{{end}}
       {{- if .ValueText}} aria-valuetext="{{.ValueText}}"{{end}}
       data-slot="meter"
       {{- range $k, $v := .Attrs}} {{$k}}="{{$v}}"{{end -}}
  >{{$text}}</meter>
{{end}}

defmodule ShadcnHtmx.Components.Meter do
  @moduledoc """
  Meter — shadcn-htmx, htmx v4 + Tailwind v4 for Phoenix.

  Renders the native `<meter>` element (implicit `role="meter"`) — a gauge
  of a value within a known range (battery, disk usage, score), NOT task
  progress. For progress use the Progress component instead.

  `low` / `high` / `optimum` drive the fill color via the cross-browser
  meter pseudo-elements styled in input.css ([data-slot="meter"]).

  ## Examples

      <label for="disk" class="text-sm font-medium">Disk usage</label>
      <.meter id="disk" value={0.62} low={0.25} high={0.85} optimum={0.1}
        value_text="12.4 GB of 16 GB" />

      <.meter value={6} min={0} max={10} aria-label="Score" />
  """

  use Phoenix.Component

  @base "block h-2 w-full overflow-hidden rounded-full bg-primary/20 align-middle"

  attr :value, :float, default: 0.0
  attr :min, :float, default: 0.0
  attr :max, :float, default: 1.0
  attr :low, :float, default: nil
  attr :high, :float, default: nil
  attr :optimum, :float, default: nil
  attr :value_text, :string, default: nil
  attr :text, :string, default: nil
  attr :class, :string, default: nil

  # title is the spec-sanctioned way to convey units on a meter, e.g.
  # title="gigabytes" (WHATWG HTML: <meter> has no units attribute).
  attr :rest, :global,
    include:
      ~w(hx-get hx-post hx-put hx-patch hx-target hx-swap hx-trigger hx-vals hx-include
         id title aria-label aria-labelledby aria-describedby)

  def meter(assigns) do
    assigns =
      assigns
      |> assign(:base, @base)
      |> assign(:body, assigns.text || "#{assigns.value} / #{assigns.max}")

    ~H"""
    <meter
      class={[@base, @class]}
      value={@value}
      min={@min}
      max={@max}
      low={@low}
      high={@high}
      optimum={@optimum}
      aria-valuetext={@value_text}
      data-slot="meter"
      {@rest}
    >{@body}</meter>
    """
  end
end

<!--
  shadcn-htmx — raw HTML meter snippets.

  Mirrors registry/ui/meter.tsx. The native <meter> element carries the
  implicit role="meter" (do NOT add role/aria-value*; the browser maps
  value/min/max onto aria-valuenow/min/max). Cross-browser fill + track
  theming lives in input.css scoped to [data-slot="meter"]; these snippets
  only size the box with Tailwind utilities.

  BASE: block h-2 w-full overflow-hidden rounded-full bg-primary/20 align-middle

  Pair every <meter> with an accessible name — a linked <label for> (best)
  or aria-label.
-->

<!-- Basic — value within a 0..1 range, labelled by a visible <label> -->
<label for="battery" class="text-sm font-medium">Battery</label>
<meter id="battery" data-slot="meter" value="0.75"
       class="block h-2 w-full overflow-hidden rounded-full bg-primary/20 align-middle">75%</meter>

<!-- Zoned — low/high/optimum color the fill (good / warning / danger).
     title carries free-form units: the only spec-sanctioned units channel
     for <meter> (WHATWG HTML — <meter> has no units attribute). -->
<label for="disk" class="text-sm font-medium">Disk usage</label>
<meter id="disk" data-slot="meter" value="0.62" min="0" max="1"
       low="0.25" high="0.85" optimum="0.1" aria-valuetext="12.4 GB of 16 GB"
       title="gigabytes"
       class="block h-2 w-full overflow-hidden rounded-full bg-primary/20 align-middle">12.4 GB of 16 GB</meter>

<!-- Custom range + aria-label (no visible label) -->
<meter data-slot="meter" value="6" min="0" max="10" low="3" high="8" optimum="10"
       aria-label="Exam score"
       class="block h-2 w-full overflow-hidden rounded-full bg-primary/20 align-middle">6 / 10</meter>