{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "model-annotations",
  "type": "registry:component",
  "title": "Model Annotations",
  "description": "Labels pinned to points on a 3D model that follow them as the model turns, each a button that opens its note, hidden while its point is behind the camera or out of view; the same notes are always given as a list, so nobody has to find them by turning.",
  "categories": [
    "three"
  ],
  "dependencies": [
    "@react-three/fiber",
    "three"
  ],
  "devDependencies": [
    "@types/three"
  ],
  "registryDependencies": [
    "@rivier-ui/theme",
    "@rivier-ui/cn"
  ],
  "files": [
    {
      "path": "registry/three/model-annotations.tsx",
      "type": "registry:component",
      "target": "components/three/model-annotations.tsx",
      "content": "\"use client\";\n/**\n * @name model-annotations\n * @category three\n * @description Labels pinned to points on a 3D model that follow them as the model turns, each a button that opens its note, hidden while its point is behind the camera or out of view; the same notes are always given as a list, so nobody has to find them by turning.\n * @when Pointing out parts of a 3D object: the parts of a machine, features of a building, finds on a scan. Put the tracker inside the scene and the labels over it, in the same positioned box. For a flat picture use hotspots; for a model with no notes use model-viewer.\n * @example\n * const store = useAnnotationStore();\n * <div className=\"relative\">\n *   <Scene label=\"A vase\" aspect={1}>\n *     <ModelStage><Vase /></ModelStage>\n *     <ModelAnnotationTracker store={store} points={[{ id: \"handle\", position: [0.6, 0.4, 0] }]} />\n *   </Scene>\n *   <ModelAnnotations store={store} annotations={[{ id: \"handle\", label: \"Handle\", note: \"Added later, in a darker clay.\" }]} />\n * </div>\n */\nimport { useFrame, useThree } from \"@react-three/fiber\";\nimport { useRef, useState, type ComponentProps } from \"react\";\nimport { Vector3 } from \"three\";\nimport { cn } from \"@/lib/cn\";\n\n/** Connects the tracker in the canvas to the labels on the page: the tracker writes each label's place straight onto it every frame. */\nexport type AnnotationStore = { elements: Map<string, HTMLElement> };\n\n/** A store for one set of annotations. */\nexport function useAnnotationStore(): AnnotationStore {\n  const [store] = useState<AnnotationStore>(() => ({ elements: new Map() }));\n  return store;\n}\n\nexport type AnnotationPoint = { id: string; position: readonly [number, number, number] };\n\n/** Inside the scene: projects each point to the canvas every frame and moves its label there. */\nexport function ModelAnnotationTracker({ store, points }: { store: AnnotationStore; points: readonly AnnotationPoint[] }) {\n  const camera = useThree((state) => state.camera);\n  const size = useThree((state) => state.size);\n  const scratch = useRef(new Vector3());\n  useFrame(() => {\n    for (const point of points) {\n      const element = store.elements.get(point.id);\n      if (!element) continue;\n      const v = scratch.current.set(point.position[0], point.position[1], point.position[2]);\n      // The point in the camera's space: behind the camera when z is past 1 after projection.\n      v.project(camera);\n      const visible = v.z < 1 && Math.abs(v.x) <= 1.05 && Math.abs(v.y) <= 1.05;\n      element.style.transform = `translate(${((v.x + 1) / 2) * size.width}px, ${((1 - v.y) / 2) * size.height}px) translate(-50%, -50%)`;\n      element.dataset[\"hidden\"] = visible ? \"false\" : \"true\";\n    }\n  });\n  return null;\n}\n\nexport type ModelAnnotation = { id: string; label: string; note?: string };\n\nexport type ModelAnnotationsProps = Omit<ComponentProps<\"div\">, \"children\"> & {\n  store: AnnotationStore;\n  annotations: readonly ModelAnnotation[];\n  /** The heading of the list of notes. Default \"Notes\". */\n  listLabel?: string;\n};\n\n/** Over the scene: a button per point, and under it the same notes as a list. */\nexport function ModelAnnotations({ store, annotations, listLabel = \"Notes\", className, ...props }: ModelAnnotationsProps) {\n  const [open, setOpen] = useState<string | null>(null);\n  return (\n    <>\n      <div data-slot=\"model-annotations\" aria-hidden=\"true\" className={cn(\"pointer-events-none absolute inset-0 overflow-hidden\", className)} {...props}>\n        {annotations.map((annotation, index) => (\n          <div\n            key={annotation.id}\n            ref={(node) => {\n              if (node) store.elements.set(annotation.id, node);\n              else store.elements.delete(annotation.id);\n            }}\n            data-hidden=\"true\"\n            // Placed from the canvas's own left edge: the projection is in screen pixels, which do not mirror.\n            className=\"pointer-events-auto absolute left-0 top-0 transition-opacity duration-instant data-[hidden=true]:pointer-events-none data-[hidden=true]:opacity-0 motion-reduce:transition-none\"\n          >\n            <button\n              type=\"button\"\n              tabIndex={-1}\n              onClick={() => setOpen(open === annotation.id ? null : annotation.id)}\n              className=\"flex items-center gap-1.5 rounded-control border bg-background px-2 py-1 text-xs font-medium\"\n            >\n              <span className=\"flex size-5 items-center justify-center rounded-full bg-primary text-primary-foreground tabular-nums\">{index + 1}</span>\n              {annotation.label}\n            </button>\n            {open === annotation.id && annotation.note ? <p className=\"mt-1 max-w-56 rounded-surface border bg-popover p-2 text-xs text-popover-foreground\">{annotation.note}</p> : null}\n          </div>\n        ))}\n      </div>\n      <ol data-slot=\"model-annotations-list\" aria-label={listLabel} className=\"mt-3 flex flex-col gap-1 text-sm\">\n        {annotations.map((annotation, index) => (\n          <li key={annotation.id} className=\"flex gap-2\">\n            <span aria-hidden=\"true\" className=\"flex size-5 shrink-0 items-center justify-center rounded-full bg-primary text-xs text-primary-foreground tabular-nums\">\n              {index + 1}\n            </span>\n            <span>\n              <span className=\"font-medium\">{annotation.label}</span>\n              {annotation.note ? <span className=\"text-muted-foreground\"> — {annotation.note}</span> : null}\n            </span>\n          </li>\n        ))}\n      </ol>\n    </>\n  );\n}\n"
    }
  ],
  "meta": {
    "category": "three",
    "when": "Pointing out parts of a 3D object: the parts of a machine, features of a building, finds on a scan. Put the tracker inside the scene and the labels over it, in the same positioned box. For a flat picture use hotspots; for a model with no notes use model-viewer.",
    "example": "const store = useAnnotationStore();\n<div className=\"relative\">\n  <Scene label=\"A vase\" aspect={1}>\n    <ModelStage><Vase /></ModelStage>\n    <ModelAnnotationTracker store={store} points={[{ id: \"handle\", position: [0.6, 0.4, 0] }]} />\n  </Scene>\n  <ModelAnnotations store={store} annotations={[{ id: \"handle\", label: \"Handle\", note: \"Added later, in a darker clay.\" }]} />\n</div>",
    "client": true
  }
}
