{
  "schemaVersion": 1,
  "target": "react",
  "name": "rating",
  "version": "0.1.0",
  "category": "forms",
  "title": "Rating",
  "description": "Stars or a custom icon with half steps, a light hover preview, and a solid fill that sweeps across the icons when a value is picked, plus a read-only mode with a review count.",
  "tags": [
    "rating",
    "stars",
    "review",
    "slider",
    "form",
    "feedback"
  ],
  "requires": {
    "projectTypes": [
      "next",
      "vite-react"
    ],
    "styling": "tailwind-v4"
  },
  "npmDependencies": {},
  "registryDependencies": [],
  "docsPath": "/components/rating",
  "props": [
    {
      "name": "value / defaultValue / onValueChange",
      "type": "number",
      "default": "0",
      "description": "The rating from 0 (none) to max. Read-only values may be any fraction, such as 4.6."
    },
    {
      "name": "max",
      "type": "number",
      "default": "5",
      "description": "Number of icons."
    },
    {
      "name": "allowHalf",
      "type": "boolean",
      "default": "false",
      "description": "Lets picks land on halves."
    },
    {
      "name": "readOnly",
      "type": "boolean",
      "default": "false",
      "description": "Displays the value as one labeled image, with the number and count beside it."
    },
    {
      "name": "clearable",
      "type": "boolean",
      "default": "true",
      "description": "Picking the current value again, Backspace, Delete, 0, or the clear button resets to 0."
    },
    {
      "name": "icon",
      "type": "ReactNode",
      "description": "A 24 x 24 SVG with fill=\"currentColor\" used instead of the star."
    },
    {
      "name": "size",
      "type": "\"sm\" | \"md\" | \"lg\"",
      "default": "\"md\"",
      "description": "Icon size: 14, 20 or 28px."
    },
    {
      "name": "labels",
      "type": "string[]",
      "description": "One word per whole step, shown beside the icons while hovering and after picking, and read out in the value text."
    },
    {
      "name": "showValue",
      "type": "boolean",
      "default": "true when read-only or with labels",
      "description": "Shows the number or label beside the icons."
    },
    {
      "name": "count",
      "type": "number",
      "description": "Review count shown as \"(1,284)\" and included in the read-only label."
    },
    {
      "name": "disabled / name / locale / aria-label / aria-labelledby / id / className",
      "type": "boolean / string",
      "description": "State, a hidden input for forms, number formatting, naming, and attributes."
    }
  ],
  "accessibility": [
    "An interactive rating is one role=\"slider\" with aria-valuemin 0, aria-valuemax max, aria-valuenow, and a value text such as \"4 out of 5, Very\" or \"No rating\".",
    "Right and Up step up, Left and Down step down (by a half with allowHalf), Home and End jump to the lowest and highest, Page Up and Page Down move a whole step, digits 1 to 9 set a value, and Backspace, Delete or 0 clear it when clearable.",
    "The clear button is labeled \"Clear rating\" and leaves the tab order while there is nothing to clear.",
    "Read-only ratings are role=\"img\" with a label such as \"Rated 4.6 out of 5, 1,284 reviews\"; the visible number is hidden from screen readers to avoid reading it twice.",
    "The hover preview is a lighter fill and the label turns secondary, so a preview never looks like a saved value.",
    "The fill sweep (240 to 465ms, quint ease-out) plays only with motion allowed; with reduced motion the fill changes at once, and keyboard changes always fill in under 100ms."
  ],
  "states": [
    "empty",
    "hover preview",
    "picked",
    "half steps",
    "read-only",
    "custom icon",
    "disabled"
  ],
  "files": [
    {
      "path": "ui/rating.tsx",
      "content": "\"use client\";\n\nimport { type KeyboardEvent, type PointerEvent, type ReactNode, useEffect, useRef, useState } from \"react\";\n\nfunction cx(...classes: (string | false | null | undefined)[]) {\n  return classes.filter(Boolean).join(\" \");\n}\n\nconst sizes = {\n  sm: { icon: 14, gap: 2, text: \"text-xs\" },\n  md: { icon: 20, gap: 4, text: \"text-sm\" },\n  lg: { icon: 28, gap: 5, text: \"text-[15px]\" },\n} as const;\n\nexport interface RatingProps {\n  /** The rating, from 0 (none) to `max`. Read-only ratings may be any fraction, such as 4.6. */\n  value?: number;\n  defaultValue?: number;\n  onValueChange?: (value: number) => void;\n  /** Number of icons. */\n  max?: number;\n  /** Lets a pick land on halves. */\n  allowHalf?: boolean;\n  /** Shows the rating without taking input, for averages and review summaries. */\n  readOnly?: boolean;\n  disabled?: boolean;\n  /** Picking the current value again, Backspace, or the clear button resets to 0. */\n  clearable?: boolean;\n  /** A 24 x 24 SVG drawn with `fill=\"currentColor\"`, used instead of the star. */\n  icon?: ReactNode;\n  size?: keyof typeof sizes;\n  /** One word per whole step, such as [\"Poor\", \"Fair\", \"Good\", \"Great\", \"Excellent\"]. Shown beside the icons and read out. */\n  labels?: string[];\n  /** Shows the number (or the label) beside the icons. On by default when read-only or with labels. */\n  showValue?: boolean;\n  /** Review count, shown after the value in read-only mode, as \"(1,284)\". */\n  count?: number;\n  /** BCP 47 locale for the value and count. */\n  locale?: string;\n  /** Accessible name. */\n  \"aria-label\"?: string;\n  \"aria-labelledby\"?: string;\n  /** Submits the value under this name with a hidden input. */\n  name?: string;\n  id?: string;\n  className?: string;\n}\n\ntype Phase = \"settle\" | \"hover\" | \"key\";\n\n/**\n * A star rating with half steps. Interactive ratings are a slider: arrows step, Home and End jump\n * to the ends, Backspace clears. Hovering previews a pick as a light fill; picking pours the solid\n * fill across the icons to meet it. Read-only ratings render as one labeled image.\n */\nexport function Rating({\n  value: valueProp,\n  defaultValue = 0,\n  onValueChange,\n  max = 5,\n  allowHalf = false,\n  readOnly = false,\n  disabled = false,\n  clearable = true,\n  icon,\n  size = \"md\",\n  labels,\n  showValue = readOnly || !!labels,\n  count,\n  locale,\n  name,\n  id,\n  className,\n  ...aria\n}: RatingProps) {\n  const [inner, setInner] = useState(defaultValue);\n  const value = Math.max(0, Math.min(max, valueProp ?? inner));\n  const [hover, setHover] = useState<number | null>(null);\n  const [phase, setPhase] = useState<Phase>(\"settle\");\n  // The fill starts empty and sweeps in once mounted.\n  const [mounted, setMounted] = useState(false);\n  useEffect(() => {\n    const frame = requestAnimationFrame(() => setMounted(true));\n    return () => cancelAnimationFrame(frame);\n  }, []);\n\n  const { icon: iconSize, gap, text } = sizes[size];\n  const stepSize = allowHalf ? 0.5 : 1;\n  const width = max * iconSize + (max - 1) * gap;\n  const interactive = !readOnly && !disabled;\n  const rootRef = useRef<HTMLDivElement>(null);\n\n  function offset(amount: number) {\n    const whole = Math.floor(amount);\n    return Math.min(width, whole * (iconSize + gap) + (amount - whole) * iconSize);\n  }\n\n  function set(next: number) {\n    const clamped = Math.max(0, Math.min(max, next));\n    if (valueProp === undefined) setInner(clamped);\n    if (clamped !== value) onValueChange?.(clamped);\n  }\n\n  function fromPointer(event: PointerEvent<HTMLDivElement>) {\n    const rect = event.currentTarget.getBoundingClientRect();\n    const x = Math.max(0, Math.min(width - 0.01, event.clientX - rect.left));\n    const index = Math.floor(x / (iconSize + gap));\n    const within = (x - index * (iconSize + gap)) / iconSize;\n    const fraction = allowHalf && within <= 0.5 ? 0.5 : 1;\n    return Math.min(max, index + fraction);\n  }\n\n  function onKeyDown(event: KeyboardEvent<HTMLDivElement>) {\n    if (!interactive) return;\n    const floor = clearable ? 0 : stepSize;\n    const moves: Record<string, () => number> = {\n      ArrowRight: () => value + stepSize,\n      ArrowUp: () => value + stepSize,\n      ArrowLeft: () => value - stepSize,\n      ArrowDown: () => value - stepSize,\n      Home: () => floor,\n      End: () => max,\n      PageUp: () => value + 1,\n      PageDown: () => value - 1,\n    };\n    let next: number | null = null;\n    if (moves[event.key]) next = Math.max(floor, Math.min(max, moves[event.key]!()));\n    else if (clearable && (event.key === \"Backspace\" || event.key === \"Delete\" || event.key === \"0\")) next = 0;\n    else if (/^[1-9]$/.test(event.key) && Number(event.key) <= max) next = Number(event.key);\n    if (next === null) return;\n    event.preventDefault();\n    // Keyboard changes fill almost at once; the sweep is for pointer picks.\n    setPhase(\"key\");\n    set(Math.round(next / stepSize) * stepSize);\n  }\n\n  const numberFormat = new Intl.NumberFormat(locale, { maximumFractionDigits: 1, minimumFractionDigits: readOnly ? 1 : 0 });\n  const countFormat = new Intl.NumberFormat(locale);\n  const shown = hover ?? value;\n  const word = labels && shown > 0 ? labels[Math.max(0, Math.ceil(shown) - 1)] : undefined;\n  const valueText = value === 0 ? \"No rating\" : `${numberFormat.format(value)} out of ${max}${labels ? `, ${labels[Math.ceil(value) - 1] ?? \"\"}` : \"\"}`;\n\n  const solid = mounted ? (hover !== null ? Math.min(value, hover) : value) : 0;\n  const ghost = hover ?? 0;\n  const duration = phase === \"hover\" ? 140 : phase === \"key\" ? 90 : Math.round(240 + Math.min(max, Math.abs(value)) * 45);\n\n  const star = icon ?? (\n    <svg viewBox=\"0 0 24 24\" fill=\"currentColor\">\n      <path d=\"M11.13 3.1a.97.97 0 0 1 1.74 0l2.2 4.46a.97.97 0 0 0 .73.53l4.92.72c.8.11 1.11 1.09.54 1.65l-3.56 3.47a.97.97 0 0 0-.28.86l.84 4.9a.97.97 0 0 1-1.41 1.02l-4.4-2.31a.97.97 0 0 0-.9 0l-4.4 2.31a.97.97 0 0 1-1.41-1.02l.84-4.9a.97.97 0 0 0-.28-.86L2.74 10.46c-.57-.56-.26-1.54.54-1.65l4.92-.72a.97.97 0 0 0 .73-.53l2.2-4.46Z\" />\n    </svg>\n  );\n\n  function row(tone: string) {\n    return (\n      <span aria-hidden=\"true\" className={cx(\"flex\", tone)} style={{ gap }}>\n        {Array.from({ length: max }, (_, index) => (\n          <span key={index} className=\"block shrink-0 [&>svg]:size-full\" style={{ width: iconSize, height: iconSize }}>\n            {star}\n          </span>\n        ))}\n      </span>\n    );\n  }\n\n  const clip = (amount: number) => `inset(0 ${width - offset(amount)}px 0 0)`;\n\n  const icons = (\n    <div\n      ref={rootRef}\n      id={readOnly ? id : undefined}\n      role={readOnly ? \"img\" : \"slider\"}\n      tabIndex={interactive ? 0 : undefined}\n      aria-label={\n        readOnly\n          ? `${aria[\"aria-label\"] ? `${aria[\"aria-label\"]}: ` : \"\"}Rated ${numberFormat.format(value)} out of ${max}${count !== undefined ? `, ${countFormat.format(count)} ${count === 1 ? \"review\" : \"reviews\"}` : \"\"}`\n          : (aria[\"aria-label\"] ?? (aria[\"aria-labelledby\"] ? undefined : \"Rating\"))\n      }\n      aria-labelledby={readOnly ? undefined : aria[\"aria-labelledby\"]}\n      aria-valuemin={readOnly ? undefined : 0}\n      aria-valuemax={readOnly ? undefined : max}\n      aria-valuenow={readOnly ? undefined : value}\n      aria-valuetext={readOnly ? undefined : valueText}\n      aria-disabled={!readOnly && disabled ? true : undefined}\n      onKeyDown={onKeyDown}\n      onPointerMove={(event) => {\n        if (!interactive || event.pointerType === \"touch\") return;\n        const next = fromPointer(event);\n        if (next !== hover) {\n          setPhase(\"hover\");\n          setHover(next);\n        }\n      }}\n      onPointerLeave={() => {\n        if (!interactive) return;\n        setPhase(\"settle\");\n        setHover(null);\n      }}\n      onClick={(event) => {\n        if (!interactive) return;\n        const next = fromPointer(event as unknown as PointerEvent<HTMLDivElement>);\n        setPhase(\"settle\");\n        set(clearable && next === value ? 0 : next);\n      }}\n      className={cx(\n        \"relative shrink-0 touch-manipulation rounded-md outline-hidden\",\n        interactive && \"cursor-pointer focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-4 focus-visible:outline-sky-500\",\n        disabled && \"opacity-45\",\n      )}\n      style={{ width, height: iconSize }}\n    >\n      {row(\"text-zinc-950/[0.09] dark:text-white/[0.13]\")}\n      {/* The preview: a light fill out to the hovered step. */}\n      <span\n        className=\"absolute inset-0 transition-[clip-path] duration-100 ease-out motion-reduce:transition-none\"\n        style={{ clipPath: clip(ghost) }}\n      >\n        {row(\"text-zinc-950/30 dark:text-white/35\")}\n      </span>\n      {/* The value: one solid layer, so a change sweeps across the icons instead of flipping each. */}\n      <span\n        className=\"absolute inset-0 transition-[clip-path] ease-[cubic-bezier(0.23,1,0.32,1)] motion-reduce:transition-none\"\n        style={{ clipPath: clip(solid), transitionDuration: `${duration}ms` }}\n      >\n        {row(\"text-zinc-950 dark:text-white\")}\n      </span>\n    </div>\n  );\n\n  return (\n    <div\n      id={readOnly ? undefined : id}\n      data-slot=\"rating\"\n      data-readonly={readOnly || undefined}\n      className={cx(\"inline-flex items-center gap-2 align-middle\", text, className)}\n    >\n      {icons}\n      {showValue ? (\n        <span aria-hidden={readOnly || undefined} className=\"inline-flex min-w-0 items-baseline gap-1 tabular-nums\">\n          {word ? (\n            <span className={cx(\"font-medium\", hover !== null ? \"text-zinc-600 dark:text-zinc-400\" : \"text-zinc-950 dark:text-white\")}>{word}</span>\n          ) : shown > 0 || readOnly ? (\n            <span className={cx(\"font-medium\", hover !== null ? \"text-zinc-600 dark:text-zinc-400\" : \"text-zinc-950 dark:text-white\")}>{numberFormat.format(shown)}</span>\n          ) : (\n            <span className=\"text-zinc-500\">Not rated</span>\n          )}\n          {count !== undefined ? <span className=\"text-zinc-500\">({countFormat.format(count)})</span> : null}\n        </span>\n      ) : null}\n      {clearable && interactive ? (\n        <button\n          type=\"button\"\n          aria-label=\"Clear rating\"\n          tabIndex={value > 0 ? 0 : -1}\n          onClick={() => {\n            setPhase(\"settle\");\n            set(0);\n          }}\n          className={cx(\n            \"-ms-1 inline-flex size-6 shrink-0 items-center justify-center rounded-md text-zinc-500\",\n            \"transition-[opacity,background-color,color,scale] duration-150 ease-out motion-safe:active:scale-[0.94] motion-reduce:transition-none\",\n            \"hover:bg-zinc-950/[0.04] hover:text-zinc-950 dark:hover:bg-white/[0.06] dark:hover:text-white\",\n            \"focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-0 focus-visible:outline-sky-500\",\n            value > 0 ? \"opacity-100\" : \"pointer-events-none opacity-0\",\n          )}\n        >\n          <svg aria-hidden=\"true\" viewBox=\"0 0 16 16\" fill=\"none\" stroke=\"currentColor\" strokeWidth=\"1.5\" strokeLinecap=\"round\" className=\"size-3.5\">\n            <path d=\"m4.5 4.5 7 7m0-7-7 7\" />\n          </svg>\n        </button>\n      ) : null}\n      {name ? <input type=\"hidden\" name={name} value={value} /> : null}\n    </div>\n  );\n}\n"
    }
  ],
  "example": {
    "content": "\"use client\";\n\nimport { useState } from \"react\";\nimport { Rating } from \"@/components/shaken/ui/rating\";\n\nconst breakdown = [\n  { stars: 5, count: 912 },\n  { stars: 4, count: 241 },\n  { stars: 3, count: 78 },\n  { stars: 2, count: 29 },\n  { stars: 1, count: 24 },\n];\nconst total = breakdown.reduce((sum, row) => sum + row.count, 0);\n\nexport default function RatingExample() {\n  const [score, setScore] = useState(0);\n\n  return (\n    <div className=\"grid w-full max-w-sm gap-6\">\n      <div className=\"grid gap-2\">\n        <span id=\"answer-rating\" className=\"text-sm font-medium text-zinc-950 dark:text-white\">\n          How useful was this answer?\n        </span>\n        <Rating aria-labelledby=\"answer-rating\" value={score} onValueChange={setScore} labels={[\"Not useful\", \"Slightly\", \"Somewhat\", \"Very\", \"Exactly right\"]} />\n      </div>\n      <section aria-label=\"Reviews\" className=\"grid gap-3 border-t border-zinc-950/[0.07] pt-5 dark:border-white/[0.08]\">\n        <div className=\"flex items-center justify-between gap-3\">\n          <h3 className=\"text-sm font-semibold text-zinc-950 dark:text-white\">Postgres connector</h3>\n          <Rating readOnly value={4.6} count={total} size=\"sm\" />\n        </div>\n        <dl className=\"grid gap-1.5\">\n          {breakdown.map((row) => (\n            <div key={row.stars} className=\"grid grid-cols-[3.5rem_1fr_2.5rem] items-center gap-3 text-xs\">\n              <dt className=\"text-zinc-600 dark:text-zinc-400\">{row.stars} {row.stars === 1 ? \"star\" : \"stars\"}</dt>\n              <dd className=\"h-1 overflow-hidden rounded-full bg-zinc-950/[0.06] dark:bg-white/[0.09]\">\n                <span className=\"block h-full rounded-full bg-zinc-950 dark:bg-white\" style={{ width: `${(row.count / total) * 100}%` }} />\n              </dd>\n              <dd className=\"text-right font-mono text-zinc-500 tabular-nums\">{row.count}</dd>\n            </div>\n          ))}\n        </dl>\n      </section>\n    </div>\n  );\n}\n"
  }
}
