Rating

---
// src/components/ui/forms/rating/Rating.astro — headless primitive (see ../../README.md).
// A star rating that IS a radio group. The browser already does single-select, arrow-key roving,
// wrap-around and form submission for a set of radios sharing a name — so this ships NO JavaScript
// at all, and works with scripting off. The roadmap listed it as a scripted primitive; it turned out
// not to need any, which is the cheapest kind of win.
//
// What it does ship is the part people leave off: the group's own name (the <legend>), a number as
// each star's accessible name, and the sibling order a theme fills the stars from — see
// RatingItem.astro, where that order is the contract.
//
// `readonly` renders the same stars as a static image with one accessible name ("4 / 5") instead of
// five controls. An average rating is not something to tab through, and a disabled radio group would
// still be announced as one.
//
// ponytail: whole stars, and no control to clear a rating once set (a radio group cannot be unset
// from the keyboard). Add a sixth item with `value={0}` and your own label if a "no rating" option
// matters; half stars need a different control — a Slider with `step={0.5}` is the honest one.
import type { HTMLAttributes } from "astro/types";

import RatingItem from "./RatingItem.astro";

type Props = HTMLAttributes<"fieldset"> & {
  name: string;
  value?: number;
  max?: number;
  label?: string;
  readonly?: boolean;
  /** The name a read-only rating announces with. Defaults to "4 / 5". */
  readonlyLabel?: string;
  size?: "sm" | "md" | "lg";
};

const {
  name,
  value = 0,
  max = 5,
  label = "Rating",
  readonly = false,
  readonlyLabel,
  size = "md",
  class: className,
  ...rest
} = Astro.props;

const stars = Array.from({ length: max }, (_, i) => i + 1);
---

{
  readonly ? (
    <span
      role="img"
      aria-label={readonlyLabel ?? `${value} / ${max}`}
      class={className}
      data-slot="rating"
      data-readonly="true"
      data-size={size}
      data-value={value}
    >
      {stars.map((star) => (
        <slot name="star">
          <svg
            data-slot="rating-star"
            data-filled={star <= value ? "true" : undefined}
            xmlns="http://www.w3.org/2000/svg"
            viewBox="0 0 24 24"
            fill="currentColor"
            aria-hidden="true"
          >
            <path d="M12 2.5l2.9 5.9 6.5.9-4.7 4.6 1.1 6.5-5.8-3-5.8 3 1.1-6.5L2.6 9.3l6.5-.9z" />
          </svg>
        </slot>
      ))}
    </span>
  ) : (
    <fieldset
      role="radiogroup"
      class={className}
      data-slot="rating"
      data-size={size}
      data-value={value}
      {...rest}
    >
      <legend data-slot="rating-label">{label}</legend>
      {stars.map((star) => (
        <RatingItem name={name} value={star} checked={star === value} />
      ))}
    </fieldset>
  )
}

---
// src/components/ui/forms/rating/RatingDisplay.astro — Rating compound part (see ../../README.md).
// The average score you SHOW: "4.2 out of 5" beside a product, a review summary, a listing card.
//
// It is a different component from Rating with `readonly` on it, and the difference is the fraction.
// Rating is a radio group, so it can only ever be a whole star — you cannot check 4.2 radios.
// A displayed average is fractional almost by definition, and rounding it to 4 in the announcement
// silently reports a different number from the one on screen.
//
// So the exact value goes in the accessible name and in `data-value`, and the stars are
// `role="img"` — ONE image with one name, not five glyphs to arrow through. An average is not a
// control: it takes no focus, offers no choice, and a disabled radio group would still be announced
// as a group of radios the user cannot use.
//
// Each star reports its own fill state for the theme:
//   `data-filled="true"`  at least three quarters of that star
//   `data-filled="half"`  a quarter to three quarters — draw it however you like, a gradient, a
//                         clipped overlay, a different glyph; the honest number is on the root
//   (absent)              empty
//
// ponytail: half-star GRANULARITY in the rendering — the exact value is never rounded in the
// announcement or in `data-value`, only in which of the three states each star reports. A theme that
// wants a true 42%-filled star can read `data-value` off the root and clip its own overlay; the
// upgrade path is a theme rule, not a change here.
import type { HTMLAttributes } from "astro/types";

type Props = HTMLAttributes<"span"> & {
  value: number;
  max?: number;
  /** Replaces the whole announced name. Defaults to "4.2 out of 5". */
  label?: string;
  size?: "sm" | "md" | "lg";
};

const { value, max = 5, label, size = "md", class: className, ...rest } = Astro.props;

const stars = Array.from({ length: max }, (_, i) => i + 1);

/** How much of star `n` is filled, 0…1 — the part of `value` that falls inside that star. */
const fillOf = (n: number) => Math.max(0, Math.min(1, value - (n - 1)));
const stateOf = (n: number) => {
  const fill = fillOf(n);
  if (fill >= 0.75) return "true";
  return fill >= 0.25 ? "half" : undefined;
};
---

<span
  role="img"
  aria-label={label ?? `${value} out of ${max}`}
  class={className}
  data-slot="rating-display"
  data-size={size}
  data-value={value}
  data-max={max}
  {...rest}
>
  {
    stars.map((star) => (
      <slot name="star">
        <svg
          data-slot="rating-star"
          data-filled={stateOf(star)}
          xmlns="http://www.w3.org/2000/svg"
          viewBox="0 0 24 24"
          fill="currentColor"
          aria-hidden="true"
        >
          <path d="M12 2.5l2.9 5.9 6.5.9-4.7 4.6 1.1 6.5-5.8-3-5.8 3 1.1-6.5L2.6 9.3l6.5-.9z" />
        </svg>
      </slot>
    ))
  }
</span>

---
// src/components/ui/forms/rating/RatingItem.astro — Rating compound part (see ../../README.md).
// One star: a real radio wrapped in its <label>, followed by the glyph. Nested, so the control is
// implicitly associated with its label and no `id`/`for` pair has to be minted.
//
// SIBLING ORDER IS PART OF THE CONTRACT, exactly as it is for Checkbox, Radio and Switch: the
// <input> comes FIRST and the glyph after it, so a theme can fill the stars from the input's own
// state with plain sibling selectors and no JavaScript —
//
//   [data-slot="rating-input"]:checked ~ [data-slot="rating-star"] { … }
//   [data-slot="rating-item"]:hover ~ [data-slot="rating-item"] [data-slot="rating-star"] { … }
//
// Reorder them and the component looks fine and silently stops reflecting its state.
//
// The accessible name is just the number. The radio group supplies the rest — a screen reader
// announces "Rating, 3, radio button, 3 of 5" — which also means there is no English sentence here
// to translate.
import type { HTMLAttributes } from "astro/types";

type Props = HTMLAttributes<"input"> & {
  name: string;
  value: number;
  label?: string;
};

const { name, value, label, class: className, ...rest } = Astro.props;
---

<label data-slot="rating-item" data-value={value}>
  <input
    type="radio"
    name={name}
    value={value}
    aria-label={label ?? String(value)}
    data-slot="rating-input"
    class={className}
    {...rest}
  />
  <slot name="star"
    ><svg
      data-slot="rating-star"
      xmlns="http://www.w3.org/2000/svg"
      viewBox="0 0 24 24"
      fill="currentColor"
      aria-hidden="true"
    >
      <path d="M12 2.5l2.9 5.9 6.5.9-4.7 4.6 1.1 6.5-5.8-3-5.8 3 1.1-6.5L2.6 9.3l6.5-.9z"></path>
    </svg></slot
  >
</label>

import Rating from "./Rating.astro";
import RatingDisplay from "./RatingDisplay.astro";
import RatingItem from "./RatingItem.astro";

export { Rating, RatingDisplay, RatingItem };
export default Rating;