{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "placard",
  "type": "registry:ui",
  "title": "Placard",
  "description": "An animated tooltip / hover-card that springs up on hover or focus. The dark-glass card follows the pointer with a subtle velocity-keyed 3D tilt, scales in from 90%, flips on collision, and carries a single cool accent hairline. Fully accessible — role=tooltip, focus + Escape/blur dismissal, aria-describedby wiring — and idle-silent until engaged; reduced motion falls back to an anchored fade.",
  "dependencies": [
    "motion"
  ],
  "registryDependencies": [
    "https://crucibleui.com/r/use-reduced-motion.json"
  ],
  "files": [
    {
      "path": "registry/default/utility/placard/placard.tsx",
      "type": "registry:ui",
      "target": "components/crucible/placard.tsx",
      "content": "\"use client\";\n\nimport {\n  AnimatePresence,\n  motion,\n  useMotionValue,\n  useSpring,\n  useTransform,\n  useVelocity,\n} from \"motion/react\";\nimport * as React from \"react\";\nimport { createPortal } from \"react-dom\";\n\nimport { useReducedMotion } from \"@/hooks/use-reduced-motion\";\nimport { cn } from \"@/lib/utils\";\n\ntype Placement = \"top\" | \"bottom\" | \"left\" | \"right\";\n\nexport interface PlacardSpring {\n  /** @default 300 */\n  stiffness?: number;\n  /** @default 26 */\n  damping?: number;\n  /** @default 0.7 */\n  mass?: number;\n}\n\nexport interface PlacardProps {\n  /**\n   * The trigger — a single focusable React element (button, link, avatar).\n   * Hovering or focusing it reveals the card. It receives `aria-describedby`\n   * wiring automatically.\n   */\n  children: React.ReactElement;\n  /** Content rendered inside the floating card — name/role, rich preview, etc. */\n  content: React.ReactNode;\n  /**\n   * Preferred side of the trigger/pointer the card opens toward. Flips to the\n   * opposite side automatically when it would collide with the viewport edge.\n   * @default \"top\"\n   */\n  placement?: Placement;\n  /**\n   * When true the card follows the pointer while hovering (with a subtle\n   * velocity-keyed tilt). Keyboard focus always anchors to the trigger instead.\n   * @default true\n   */\n  follow?: boolean;\n  /**\n   * Peak 3D lean, in degrees, applied from pointer velocity while following.\n   * Dialed low so the card reads as a physical surface catching light.\n   * @default 8\n   */\n  tilt?: number;\n  /** Spring driving position, scale, and tilt. @default { stiffness: 300, damping: 26, mass: 0.7 } */\n  spring?: PlacardSpring;\n  /** Delay before opening, in ms. @default 120 */\n  openDelay?: number;\n  /** Delay before closing, in ms. @default 120 */\n  closeDelay?: number;\n  /** Render the little pointing arrow on the anchored edge. @default true */\n  arrow?: boolean;\n  /** Minimum gap kept between the card and the viewport edge, in px. @default 8 */\n  collisionPadding?: number;\n  /** Color of the single cool accent hairline at the card's top edge. @default \"#38bdf8\" */\n  accentColor?: string;\n  /** Classes merged onto the floating card. */\n  className?: string;\n}\n\nconst DEFAULT_SPRING = { stiffness: 300, damping: 26, mass: 0.7 } as const;\nconst GAP = 10;\nconst ARROW = 7;\nconst TILT_FACTOR = 0.008;\n\ninterface Rect {\n  left: number;\n  right: number;\n  top: number;\n  bottom: number;\n  cx: number;\n  cy: number;\n}\n\ninterface Solved {\n  x: number;\n  y: number;\n  place: Placement;\n  arrow: number;\n}\n\nconst clamp = (v: number, lo: number, hi: number) => Math.min(Math.max(v, lo), hi);\n\nfunction solve(\n  rect: Rect,\n  w: number,\n  h: number,\n  placement: Placement,\n  hasArrow: boolean,\n  pad: number\n): Solved {\n  const vw = window.innerWidth;\n  const vh = window.innerHeight;\n  const gap = GAP + (hasArrow ? ARROW : 0);\n  let place = placement;\n\n  // Collision flip toward the opposite side when there isn't room.\n  if (place === \"top\" && rect.top - gap - h < pad && rect.bottom + gap + h + pad <= vh) {\n    place = \"bottom\";\n  } else if (place === \"bottom\" && rect.bottom + gap + h > vh - pad && rect.top - gap - h >= pad) {\n    place = \"top\";\n  } else if (place === \"left\" && rect.left - gap - w < pad && rect.right + gap + w + pad <= vw) {\n    place = \"right\";\n  } else if (place === \"right\" && rect.right + gap + w > vw - pad && rect.left - gap - w >= pad) {\n    place = \"left\";\n  }\n\n  let x: number;\n  let y: number;\n  if (place === \"top\") {\n    x = rect.cx - w / 2;\n    y = rect.top - gap - h;\n  } else if (place === \"bottom\") {\n    x = rect.cx - w / 2;\n    y = rect.bottom + gap;\n  } else if (place === \"left\") {\n    x = rect.left - gap - w;\n    y = rect.cy - h / 2;\n  } else {\n    x = rect.right + gap;\n    y = rect.cy - h / 2;\n  }\n\n  // Keep fully on screen.\n  x = clamp(x, pad, Math.max(pad, vw - w - pad));\n  y = clamp(y, pad, Math.max(pad, vh - h - pad));\n\n  // Arrow slides along the anchored edge so it keeps pointing at the anchor\n  // even after the card is clamped.\n  const arrow =\n    place === \"top\" || place === \"bottom\"\n      ? clamp(rect.cx - x, 14, w - 14)\n      : clamp(rect.cy - y, 14, h - 14);\n\n  return { x, y, place, arrow };\n}\n\nconst ORIGIN: Record<Placement, string> = {\n  top: \"center bottom\",\n  bottom: \"center top\",\n  left: \"right center\",\n  right: \"left center\",\n};\n\n/**\n * Placard — an animated tooltip / hover-card. Hovering or focusing the trigger\n * springs up a neutral dark-glass card with a hairline border and a single cool\n * accent line along its top edge. While the pointer moves, the card follows it\n * and leans in 3D by an amount keyed to cursor velocity, so it reads as a\n * physical card catching light; it settles flat and scales in from 90%.\n *\n * Fully accessible: opens on focus as well as hover, exposes `role=\"tooltip\"`\n * with `aria-describedby` wiring on the trigger, and dismisses on blur or\n * Escape. Idle-silent — no listeners, portal, or animation frames run until the\n * trigger is engaged. Under reduced motion it becomes a plain anchored fade\n * with no follow and no tilt.\n */\nexport function Placard({\n  children,\n  content,\n  placement = \"top\",\n  follow = true,\n  tilt = 8,\n  spring,\n  openDelay = 120,\n  closeDelay = 120,\n  arrow = true,\n  collisionPadding = 8,\n  accentColor = \"#38bdf8\",\n  className,\n}: PlacardProps) {\n  const reducedMotion = useReducedMotion();\n  const springConfig = { ...DEFAULT_SPRING, ...spring };\n\n  const [mounted, setMounted] = React.useState(false);\n  const [open, setOpen] = React.useState(false);\n  const [place, setPlace] = React.useState<Placement>(placement);\n\n  const triggerRef = React.useRef<HTMLElement | null>(null);\n  const cardRef = React.useRef<HTMLDivElement | null>(null);\n\n  const hoverRef = React.useRef(false);\n  const focusRef = React.useRef(false);\n  const escapedRef = React.useRef(false);\n  const openRef = React.useRef(false);\n  const placeRef = React.useRef<Placement>(placement);\n  const pointerRef = React.useRef({ x: 0, y: 0 });\n  const openTimer = React.useRef<ReturnType<typeof setTimeout> | undefined>(undefined);\n  const closeTimer = React.useRef<ReturnType<typeof setTimeout> | undefined>(undefined);\n\n  const tooltipId = React.useId();\n\n  // Target position; the springs below chase it for a subtle follow lag.\n  const xt = useMotionValue(0);\n  const yt = useMotionValue(0);\n  const xs = useSpring(xt, springConfig);\n  const ys = useSpring(yt, springConfig);\n  const arrowPos = useMotionValue(0);\n\n  // Pointer position feeds velocity, which drives the tilt.\n  const px = useMotionValue(0);\n  const py = useMotionValue(0);\n  const vx = useVelocity(px);\n  const vy = useVelocity(py);\n  const rotYTarget = useTransform(vx, (v) => clamp(v * TILT_FACTOR, -tilt, tilt));\n  const rotXTarget = useTransform(vy, (v) => clamp(-v * TILT_FACTOR, -tilt, tilt));\n  const rotateY = useSpring(rotYTarget, springConfig);\n  const rotateX = useSpring(rotXTarget, springConfig);\n\n  React.useEffect(() => setMounted(true), []);\n  React.useEffect(() => {\n    openRef.current = open;\n  }, [open]);\n\n  const isFollowing = React.useCallback(\n    () => follow && hoverRef.current && !reducedMotion,\n    [follow, reducedMotion]\n  );\n\n  const reposition = React.useCallback(() => {\n    const card = cardRef.current;\n    if (!card) return;\n    const w = card.offsetWidth;\n    const h = card.offsetHeight;\n\n    let rect: Rect;\n    if (isFollowing()) {\n      const p = pointerRef.current;\n      rect = { left: p.x, right: p.x, top: p.y, bottom: p.y, cx: p.x, cy: p.y };\n    } else {\n      const t = triggerRef.current?.getBoundingClientRect();\n      if (!t) return;\n      rect = {\n        left: t.left,\n        right: t.right,\n        top: t.top,\n        bottom: t.bottom,\n        cx: t.left + t.width / 2,\n        cy: t.top + t.height / 2,\n      };\n    }\n\n    const r = solve(rect, w, h, placement, arrow, collisionPadding);\n    xt.set(r.x);\n    yt.set(r.y);\n    arrowPos.set(r.arrow);\n    if (r.place !== placeRef.current) {\n      placeRef.current = r.place;\n      setPlace(r.place);\n    }\n  }, [isFollowing, placement, arrow, collisionPadding, xt, yt, arrowPos]);\n\n  const sync = React.useCallback(() => {\n    if (openTimer.current) clearTimeout(openTimer.current);\n    if (closeTimer.current) clearTimeout(closeTimer.current);\n    const wantOpen = (hoverRef.current || focusRef.current) && !escapedRef.current;\n    if (wantOpen) {\n      openTimer.current = setTimeout(() => setOpen(true), openDelay);\n    } else {\n      closeTimer.current = setTimeout(() => setOpen(false), closeDelay);\n    }\n  }, [openDelay, closeDelay]);\n\n  // Position instantly (no spring travel) the first frame the card mounts.\n  // Re-place on the next frame too: on the very first open the card ref/layout\n  // may not be measurable yet, so reposition() bails and the springs would sit\n  // at the stale (0,0) — which is what stranded keyboard-focus opens in the\n  // corner (no pointer-move to correct them). The card fades in from opacity 0,\n  // so the one-frame correction isn't visible.\n  React.useLayoutEffect(() => {\n    if (!open) return;\n    const place = () => {\n      reposition();\n      xs.jump(xt.get());\n      ys.jump(yt.get());\n    };\n    place();\n    const id = requestAnimationFrame(place);\n    return () => cancelAnimationFrame(id);\n  }, [open, reposition, xs, ys, xt, yt]);\n\n  // Reposition on scroll/resize while open (only work when engaged).\n  React.useEffect(() => {\n    if (!open) return;\n    const onScroll = () => reposition();\n    window.addEventListener(\"scroll\", onScroll, true);\n    window.addEventListener(\"resize\", onScroll);\n    const card = cardRef.current;\n    const ro =\n      card && typeof ResizeObserver !== \"undefined\"\n        ? new ResizeObserver(() => reposition())\n        : null;\n    if (ro && card) ro.observe(card);\n    return () => {\n      window.removeEventListener(\"scroll\", onScroll, true);\n      window.removeEventListener(\"resize\", onScroll);\n      ro?.disconnect();\n    };\n  }, [open, reposition]);\n\n  // Escape dismisses from anywhere while open — a hover-opened card must be\n  // dismissable without moving the pointer or focusing the trigger.\n  React.useEffect(() => {\n    if (!open) return;\n    const onKey = (e: KeyboardEvent) => {\n      if (e.key !== \"Escape\") return;\n      escapedRef.current = true;\n      if (openTimer.current) clearTimeout(openTimer.current);\n      setOpen(false);\n    };\n    document.addEventListener(\"keydown\", onKey);\n    return () => document.removeEventListener(\"keydown\", onKey);\n  }, [open]);\n\n  React.useEffect(\n    () => () => {\n      if (openTimer.current) clearTimeout(openTimer.current);\n      if (closeTimer.current) clearTimeout(closeTimer.current);\n    },\n    []\n  );\n\n  const handlePointerEnter = (e: React.PointerEvent) => {\n    if (e.pointerType === \"touch\") return;\n    hoverRef.current = true;\n    escapedRef.current = false;\n    pointerRef.current = { x: e.clientX, y: e.clientY };\n    // Seat the velocity sources at the entry point — otherwise the first move\n    // reads as a jump from (0,0) and the card lurches to full tilt.\n    px.jump(e.clientX);\n    py.jump(e.clientY);\n    sync();\n  };\n\n  const handlePointerMove = (e: React.PointerEvent) => {\n    if (e.pointerType === \"touch\") return;\n    pointerRef.current = { x: e.clientX, y: e.clientY };\n    if (isFollowing()) {\n      px.set(e.clientX);\n      py.set(e.clientY);\n      if (openRef.current) reposition();\n    }\n  };\n\n  const handlePointerLeave = () => {\n    hoverRef.current = false;\n    escapedRef.current = false;\n    sync();\n    if (openRef.current) reposition();\n  };\n\n  const handleFocus = () => {\n    focusRef.current = true;\n    escapedRef.current = false;\n    sync();\n    if (openRef.current) reposition();\n  };\n\n  const handleBlur = () => {\n    focusRef.current = false;\n    escapedRef.current = false;\n    sync();\n  };\n\n  const handleKeyDown = (e: React.KeyboardEvent) => {\n    if (e.key === \"Escape\" && openRef.current) {\n      escapedRef.current = true;\n      if (openTimer.current) clearTimeout(openTimer.current);\n      setOpen(false);\n    }\n  };\n\n  const childProps = children.props as { \"aria-describedby\"?: string };\n  const describedBy =\n    [childProps[\"aria-describedby\"], open ? tooltipId : null].filter(Boolean).join(\" \") ||\n    undefined;\n\n  const trigger = (\n    <span\n      ref={(node) => {\n        triggerRef.current = node;\n      }}\n      className=\"inline-flex\"\n      onPointerEnter={handlePointerEnter}\n      onPointerMove={handlePointerMove}\n      onPointerLeave={handlePointerLeave}\n      onFocus={handleFocus}\n      onBlur={handleBlur}\n      onKeyDown={handleKeyDown}\n    >\n      {React.cloneElement(children as React.ReactElement<{ \"aria-describedby\"?: string }>, {\n        \"aria-describedby\": describedBy,\n      })}\n    </span>\n  );\n\n  const arrowSideClass =\n    place === \"top\"\n      ? \"left-0 bottom-0 translate-y-1/2 border-b border-r\"\n      : place === \"bottom\"\n        ? \"left-0 top-0 -translate-y-1/2 border-t border-l\"\n        : place === \"left\"\n          ? \"top-0 right-0 translate-x-1/2 border-t border-r\"\n          : \"top-0 left-0 -translate-x-1/2 border-b border-l\";\n\n  const overlay = open ? (\n    <motion.div\n      style={{\n        position: \"fixed\",\n        top: 0,\n        left: 0,\n        zIndex: 9999,\n        x: xs,\n        y: ys,\n        pointerEvents: \"none\",\n        transformOrigin: ORIGIN[place],\n      }}\n      initial={reducedMotion ? { opacity: 0 } : { opacity: 0, scale: 0.9 }}\n      animate={reducedMotion ? { opacity: 1 } : { opacity: 1, scale: 1 }}\n      exit={reducedMotion ? { opacity: 0 } : { opacity: 0, scale: 0.96 }}\n      transition={\n        reducedMotion\n          ? { duration: 0.14, ease: \"easeOut\" }\n          : { type: \"spring\", ...springConfig, opacity: { duration: 0.12 } }\n      }\n    >\n      <motion.div\n        ref={cardRef}\n        role=\"tooltip\"\n        id={tooltipId}\n        data-crucible=\"placard\"\n        data-placement={place}\n        style={{\n          rotateX: reducedMotion ? 0 : rotateX,\n          rotateY: reducedMotion ? 0 : rotateY,\n          transformPerspective: reducedMotion ? undefined : 800,\n        }}\n        className={cn(\n          \"relative max-w-xs overflow-hidden rounded-xl border border-white/10 bg-neutral-900/85 text-white shadow-2xl shadow-black/60 backdrop-blur-xl\",\n          className\n        )}\n      >\n        {/* Cool accent hairline along the top edge. */}\n        <span\n          aria-hidden\n          className=\"pointer-events-none absolute inset-x-0 top-0 h-px\"\n          style={{\n            background: `linear-gradient(90deg, transparent, ${accentColor}, transparent)`,\n            opacity: 0.7,\n          }}\n        />\n        {/* Faint sheen so the tilt reads as a surface catching light. */}\n        <span\n          aria-hidden\n          className=\"pointer-events-none absolute inset-0 rounded-[inherit]\"\n          style={{\n            background:\n              \"radial-gradient(120% 80% at 30% 0%, rgba(255,255,255,0.08), transparent 60%)\",\n          }}\n        />\n        <div className=\"relative z-10\">{content}</div>\n        {arrow ? (\n          <motion.span\n            aria-hidden\n            className={cn(\n              \"pointer-events-none absolute h-2.5 w-2.5 rotate-45 border-white/10 bg-neutral-900/85\",\n              arrowSideClass\n            )}\n            style={\n              place === \"top\" || place === \"bottom\"\n                ? { x: arrowPos, marginLeft: -5 }\n                : { y: arrowPos, marginTop: -5 }\n            }\n          />\n        ) : null}\n      </motion.div>\n    </motion.div>\n  ) : null;\n\n  return (\n    <>\n      {trigger}\n      {mounted\n        ? createPortal(<AnimatePresence>{overlay}</AnimatePresence>, document.body)\n        : null}\n    </>\n  );\n}\n"
    }
  ]
}