{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "hotspots",
  "type": "registry:ui",
  "title": "Hotspots",
  "description": "Named buttons placed over a picture or a video at a point, each present only between two moments of the clip, with the same choices as a plain list for people who cannot point at the picture.",
  "categories": [
    "ui"
  ],
  "dependencies": [],
  "registryDependencies": [
    "@rivier-ui/theme",
    "@rivier-ui/announce",
    "@rivier-ui/cn",
    "@rivier-ui/use-media"
  ],
  "files": [
    {
      "path": "registry/ui/hotspots.tsx",
      "type": "registry:ui",
      "target": "components/ui/hotspots.tsx",
      "content": "\"use client\";\n/**\n * @name hotspots\n * @category ui\n * @description Named buttons placed over a picture or a video at a point, each present only between two moments of the clip, with the same choices as a plain list for people who cannot point at the picture.\n * @when Something in the frame can be asked about or chosen while it is on screen: an object in a scene, a place on a still, a choice in a story. Put Hotspots inside the frame (VideoPlayer, or any `relative` box over a picture) and HotspotList after it; both take the same `hotspots`. A hotspot that appears is announced, because nothing else would tell a screen-reader user it is there. For a point on a map use the map's own markers; for marks on the time bar use the scrubber's `marks`.\n * @example\n * const spots = [\n *   { id: \"kiln\", x: 32, y: 55, start: 4, end: 12, label: \"The kiln door\" },\n *   { id: \"shelf\", x: 70, y: 30, start: 9, end: 20, label: \"Drying shelf\" },\n * ];\n * <VideoPlayerProvider>\n *   <VideoPlayer aria-label=\"Inside the workshop\">\n *     <VideoPlayerVideo src=\"/workshop.mp4\" />\n *     <Hotspots hotspots={spots} onSelect={(spot) => openCard(spot.id)} />\n *     <VideoPlayerControls>…</VideoPlayerControls>\n *   </VideoPlayer>\n *   <HotspotList hotspots={spots} onSelect={(spot) => openCard(spot.id)} aria-label=\"In this scene\" />\n * </VideoPlayerProvider>\n */\nimport { useEffect, useRef, type ComponentProps, type ReactNode } from \"react\";\nimport { announce } from \"@/lib/announce\";\nimport { cn } from \"@/lib/cn\";\nimport { useOptionalMediaContext } from \"@/lib/use-media\";\n\nexport type HotspotSpec = {\n  id: string;\n  /** Where its centre is, as a percentage of the frame's width from the left of the picture, and of its height from the top. */\n  x: number;\n  y: number;\n  /** The moments, in seconds, between which it is present. Left out: always. */\n  start?: number;\n  end?: number;\n  /** Its name: what a press chooses. */\n  label: string;\n};\n\nconst activeAt = (hotspots: readonly HotspotSpec[], time: number): HotspotSpec[] =>\n  hotspots.filter((spot) => (spot.start ?? Number.NEGATIVE_INFINITY) <= time && time < (spot.end ?? Number.POSITIVE_INFINITY)).sort((a, b) => (a.start ?? 0) - (b.start ?? 0));\n\ntype HotspotSource = {\n  hotspots: readonly HotspotSpec[];\n  /** The current time in seconds. Left out, it is the player's (0 with no player, so untimed hotspots still show). */\n  time?: number;\n  onSelect?: (hotspot: HotspotSpec) => void;\n};\n\nexport type HotspotsProps = Omit<ComponentProps<\"div\">, \"children\" | \"onSelect\" | \"dir\"> &\n  HotspotSource & {\n    /** What is announced when a hotspot appears. Default: its name. Return \"\" to say nothing. */\n    announcement?: (hotspot: HotspotSpec) => string;\n    /** Replaces what a hotspot draws inside its button (the default is a ring with a dot). */\n    children?: (hotspot: HotspotSpec) => ReactNode;\n  };\n\n/**\n * The layer over the frame. It lets the pointer through except on the hotspots themselves, which are real\n * buttons in the order they appear in the clip, so Tab reaches them in time order. Positions are measured\n * from the left of the picture in every language: a picture is not mirrored in a right-to-left page, so\n * the layer is laid out left to right (the names still find their own direction). Each button is at least\n * 44px across whatever is drawn in it, and arrives by fading in only (at once under reduced motion).\n */\nexport function Hotspots({ className, hotspots, time, onSelect, announcement, children, ...props }: HotspotsProps) {\n  const context = useOptionalMediaContext();\n  const active = activeAt(hotspots, time ?? context?.state.time ?? 0);\n  const ids = active.map((spot) => spot.id).join(\"\\n\");\n\n  const latest = useRef({ active, announcement });\n  /** The hotspots present at the last look. null before the first: what is there as the page loads is not news. */\n  const seen = useRef<Set<string> | null>(null);\n  useEffect(() => {\n    latest.current = { active, announcement };\n  });\n  useEffect(() => {\n    const present = new Set(ids === \"\" ? [] : ids.split(\"\\n\"));\n    for (const spot of latest.current.active) {\n      if (seen.current === null || seen.current.has(spot.id)) continue;\n      const message = latest.current.announcement ? latest.current.announcement(spot) : spot.label;\n      if (message) announce(message);\n    }\n    seen.current = present;\n  }, [ids]);\n\n  return (\n    <div data-slot=\"hotspots\" dir=\"ltr\" className={cn(\"pointer-events-none absolute inset-0 z-10\", className)} {...props}>\n      {active.map((spot) => (\n        <Hotspot key={spot.id} x={spot.x} y={spot.y} aria-label={spot.label} data-hotspot={spot.id} onClick={() => onSelect?.(spot)}>\n          {children?.(spot)}\n        </Hotspot>\n      ))}\n    </div>\n  );\n}\n\nexport type HotspotProps = Omit<ComponentProps<\"button\">, \"type\"> & {\n  /** Percentage of the frame's width from the left of the picture. */\n  x: number;\n  /** Percentage of the frame's height from the top. */\n  y: number;\n};\n\n/** One hotspot, for a layer composed by hand. Name it with `aria-label`. */\nexport function Hotspot({ className, style, x, y, children, ...props }: HotspotProps) {\n  const within = (value: number): number => Math.min(100, Math.max(0, value));\n  return (\n    <button\n      type=\"button\"\n      data-slot=\"hotspot\"\n      className={cn(\n        \"group/hotspot pointer-events-auto absolute inline-flex size-(--control-h-lg) -translate-1/2 animate-in items-center justify-center rounded-full animation-duration-(--duration-base) fade-in-0 motion-reduce:animate-none\",\n        className,\n      )}\n      style={{ insetInlineStart: `${within(x)}%`, top: `${within(y)}%`, ...style }}\n      {...props}\n    >\n      {children ?? (\n        <span\n          aria-hidden=\"true\"\n          className=\"inline-flex size-7 items-center justify-center rounded-full border-2 border-background bg-foreground transition-transform duration-instant ease-out group-hover/hotspot:scale-110 motion-reduce:transition-none motion-reduce:group-hover/hotspot:scale-100\"\n        >\n          <span className=\"size-2 rounded-full bg-background\" />\n        </span>\n      )}\n    </button>\n  );\n}\n\nexport type HotspotListProps = Omit<ComponentProps<\"ul\">, \"children\" | \"onSelect\"> &\n  HotspotSource & {\n    /** Shown when nothing can be chosen at this moment. Left out, the list is simply empty. */\n    empty?: ReactNode;\n  };\n\n/**\n * The hotspots present now, as a list of buttons with their names: the same choices without having to find\n * a point on a picture. Render it after the frame and name it with `aria-label` (\"In this scene\").\n */\nexport function HotspotList({ className, hotspots, time, onSelect, empty, ...props }: HotspotListProps) {\n  const context = useOptionalMediaContext();\n  const active = activeAt(hotspots, time ?? context?.state.time ?? 0);\n  return (\n    <ul data-slot=\"hotspot-list\" className={cn(\"flex min-h-(--control-h) flex-wrap items-center gap-2\", className)} {...props}>\n      {active.map((spot) => (\n        <li key={spot.id}>\n          <button\n            type=\"button\"\n            data-slot=\"hotspot-list-item\"\n            onClick={() => onSelect?.(spot)}\n            className=\"inline-flex h-control-sm items-center rounded-control border border-border-strong bg-background px-3 text-sm font-medium text-foreground transition-colors duration-instant ease-out hover:bg-accent motion-reduce:transition-none pointer-coarse:h-control\"\n          >\n            <span dir=\"auto\">{spot.label}</span>\n          </button>\n        </li>\n      ))}\n      {active.length === 0 && empty ? <li className=\"text-sm text-muted-foreground\">{empty}</li> : null}\n    </ul>\n  );\n}\n"
    }
  ],
  "meta": {
    "category": "ui",
    "when": "Something in the frame can be asked about or chosen while it is on screen: an object in a scene, a place on a still, a choice in a story. Put Hotspots inside the frame (VideoPlayer, or any `relative` box over a picture) and HotspotList after it; both take the same `hotspots`. A hotspot that appears is announced, because nothing else would tell a screen-reader user it is there. For a point on a map use the map's own markers; for marks on the time bar use the scrubber's `marks`.",
    "example": "const spots = [\n  { id: \"kiln\", x: 32, y: 55, start: 4, end: 12, label: \"The kiln door\" },\n  { id: \"shelf\", x: 70, y: 30, start: 9, end: 20, label: \"Drying shelf\" },\n];\n<VideoPlayerProvider>\n  <VideoPlayer aria-label=\"Inside the workshop\">\n    <VideoPlayerVideo src=\"/workshop.mp4\" />\n    <Hotspots hotspots={spots} onSelect={(spot) => openCard(spot.id)} />\n    <VideoPlayerControls>…</VideoPlayerControls>\n  </VideoPlayer>\n  <HotspotList hotspots={spots} onSelect={(spot) => openCard(spot.id)} aria-label=\"In this scene\" />\n</VideoPlayerProvider>",
    "client": true
  }
}
