{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "hover-card",
  "title": "HoverCard",
  "description": "A preview of where a link goes, shown when a mouse rests on the link or the keyboard focuses it: a cook's profile, a recipe's summary.",
  "dependencies": [
    "@base-ui/react@^1.8.0"
  ],
  "registryDependencies": [
    "@ouro/lib-class-name-check",
    "@ouro/lib-cn",
    "@ouro/lib-dev",
    "@ouro/lib-env",
    "@ouro/lib-floating",
    "@ouro/lib-last-input",
    "@ouro/lib-portal-container",
    "@ouro/lib-refs",
    "@ouro/lib-server-element",
    "@ouro/lib-use-dev-messages",
    "@ouro/lib-use-media-query"
  ],
  "files": [
    {
      "path": "registry/ouro/components/ouro/hover-card/hover-card.tsx",
      "content": "\"use client\";\n\nimport { PreviewCard } from \"@base-ui/react/preview-card\";\nimport { cloneElement, useEffect, useRef, useState, type FocusEvent, type JSX, type KeyboardEvent, type PointerEvent, type ReactElement, type ReactNode, type Ref } from \"react\";\nimport { useAppearanceClassNameCheck } from \"@/registry/ouro/lib/ouro/class-name-check\";\nimport { cn } from \"@/registry/ouro/lib/ouro/cn\";\nimport { devWarn } from \"@/registry/ouro/lib/ouro/dev\";\nimport {\n  floatingAlign,\n  floatingHint,\n  floatingMotionClass,\n  floatingPlacementWarnings,\n  floatingPortalClass,\n  floatingSide,\n  floatingSurfaceClass,\n  type FloatingAlign,\n  type FloatingSide,\n} from \"@/registry/ouro/lib/ouro/floating\";\nimport { lastInput } from \"@/registry/ouro/lib/ouro/last-input\";\nimport { useMergedRef } from \"@/registry/ouro/lib/ouro/refs\";\nimport { serverElement } from \"@/registry/ouro/lib/ouro/server-element\";\nimport { useDevWarnings } from \"@/registry/ouro/lib/ouro/use-dev-messages\";\nimport { useMediaQuery } from \"@/registry/ouro/lib/ouro/use-media-query\";\nimport { PortalScope, usePortalContainer } from \"@/registry/ouro/lib/ouro/portal-container\";\n\n// Base UI's own delays for a preview card: it opens after the pointer rests on the link, and lingers as it leaves.\nconst OPEN_DELAY = 600;\nconst CLOSE_DELAY = 300;\n\nexport type { FloatingAlign as HoverCardAlign, FloatingSide as HoverCardSide } from \"@/registry/ouro/lib/ouro/floating\";\n\n/** Props for {@link HoverCard}. */\nexport interface HoverCardProps {\n  /**\n   * The link the card previews: `trigger={<Link href=\"/cooks/ari\">Ari</Link>}`. It works\n   * on its own: touch users, and devices that cannot hover, get only the link.\n   */\n  trigger: ReactElement;\n  /** The preview: a few lines about where the link goes. Only what the user can do without; put controls elsewhere. */\n  children: ReactNode;\n  /**\n   * The side of the link the card sits on; it flips when there is no room. @default \"bottom\"\n   *\n   * @claim \"The side of the link the\" registry/ouro/components/ouro/hover-card/hover-card.test.tsx verify:testExists(registry/ouro/components/ouro/hover-card/hover-card.test.tsx::HoverCard > sits on the side and alignment it is given, and className sets layout)\n   * @claim \"it flips when there is no room\" https://base-ui.com/react/components/preview-card verify:urlOk(https://base-ui.com/react/components/preview-card)\n   */\n  side?: FloatingSide | (string & { 'Use \"top\", \"bottom\", \"left\" or \"right\"': never }) | undefined;\n  /** How the card lines up with the link along that side. @default \"center\" */\n  align?: FloatingAlign | (string & { 'Use \"start\", \"center\" or \"end\": left is \"start\", right is \"end\"': never }) | undefined;\n  /**\n   * Layout only, applied to the card: width (18rem, `w-72`, by default) and padding. Your\n   * classes win over Ouro UI's. Appearance classes warn in development.\n   * @claim \"Layout only, applied to the card\" registry/ouro/components/ouro/hover-card/hover-card.tsx verify:fileLine(registry/ouro/components/ouro/hover-card/hover-card.tsx, /\"w-72\\smax-w-\\(--available-width\\)\\sp-4/)\n   */\n  className?: string | undefined;\n\n  /** Not a prop. Ouro UI sets the delays: `<HoverCard trigger={…}>`. */\n  openDelay?: { \"Ouro UI sets the delays\": never };\n  /** Not a prop. Ouro UI sets the delays: `<HoverCard trigger={…}>`. */\n  closeDelay?: { \"Ouro UI sets the delays\": never };\n  /** Not a prop. The preview is the children: `<HoverCard trigger={…}>…</HoverCard>`. */\n  content?: { \"Use children: <HoverCard trigger={...}>...</HoverCard>\": never };\n  /** Not a prop. Ouro UI splits placement into `side` and `align`: `<HoverCard side=\"bottom\" align=\"start\">`. */\n  placement?: { 'Use side=\"bottom\" align=\"start\"': never };\n}\n\n/**\n * A preview of where a link goes, shown when a mouse rests on the link or the keyboard\n * focuses it: a cook's profile, a recipe's summary. It shows only on devices that can\n * hover and never after a touch, so the link must work without it.\n *\n * Use `Tooltip` instead for a short label, and `Popover` for anything the user needs or\n * acts on, since a Popover opens on tap.\n *\n * It stacks above the page at `--ouro-layer`, a z-index of 50 by default (from\n * ouro-base.css), like Dialog and Sheet.\n *\n * @group Overlays\n * @see https://ui.ouroboros.bot/docs/hover-card\n *\n * @example\n * <HoverCard trigger={<Link href=\"/cooks/ari\">Ari Mendelow</Link>}>\n *   <CookSummary cook={ari} />\n * </HoverCard>\n * @claim \"It stacks above the page at\" registry/ouro/components/ouro/hover-card/hover-card.test.tsx verify:testExists(registry/ouro/components/ouro/hover-card/hover-card.test.tsx::HoverCard > portals at the --ouro-layer level, as its own stacking context)\n * @claim \"It stacks above the page at\" registry/ouro/theme/ouro-base.css verify:fileLine(registry/ouro/theme/ouro-base.css, /^\\s+--ouro-layer:\\s50;/)\n * @claim \"It shows only on devices that\" registry/ouro/components/ouro/hover-card/hover-card.touch.test.tsx verify:fileLine(registry/ouro/components/ouro/hover-card/hover-card.touch.test.tsx, /it\\(\"never opens on a device that cannot hover. not from a tap, and not from keyboard focus\"/)\n */\nexport function HoverCard(props: HoverCardProps): JSX.Element {\n  const {\n    trigger,\n    children,\n    side: sideProp,\n    align: alignProp,\n    className,\n    // Guard props (hint types), dropped here so they never reach the DOM.\n    openDelay,\n    closeDelay,\n    content,\n    placement,\n  } = props;\n\n  const side = floatingSide(sideProp, \"bottom\");\n  const align = floatingAlign(alignProp);\n  const key = useRef({});\n  const triggerRef = useRef<HTMLAnchorElement>(null);\n  // The server renders for a device that can hover; the client corrects it after.\n  const canHover = useMediaQuery(\"(any-hover: hover)\", true);\n\n  useAppearanceClassNameCheck(\n    \"HoverCard\",\n    className,\n    process.env.NODE_ENV !== \"production\"\n      ? floatingHint(\"<HoverCard trigger={…}>\", \"</HoverCard>\")\n      : /* istanbul ignore next @preserve -- production only */ \"\",\n  );\n  useDevWarnings(\n    \"HoverCard\",\n    process.env.NODE_ENV !== \"production\"\n      ? () => [\n          ...floatingPlacementWarnings(\"<HoverCard\", sideProp, \"bottom\", alignProp, placement),\n          openDelay !== undefined && [\"openDelay is not a prop; Ouro UI sets the delays\", \"<HoverCard trigger={…}>\"],\n          closeDelay !== undefined && [\"closeDelay is not a prop; Ouro UI sets the delays\", \"<HoverCard trigger={…}>\"],\n          content !== undefined && [\"content is not a prop; the preview is children\", \"<HoverCard trigger={…}>…</HoverCard>\"],\n        ]\n      : /* istanbul ignore next @preserve -- production only */ undefined,\n  );\n\n  // A hover card belongs on a link: everyone who can't hover gets only the link.\n  useEffect(() => {\n    /* istanbul ignore else @preserve -- the else path exists only in production bundles */\n    if (process.env.NODE_ENV !== \"production\") {\n      const element = triggerRef.current!;\n      if (element.tagName !== \"A\" || !element.hasAttribute(\"href\")) {\n        devWarn(\n          \"HoverCard\",\n          \"the trigger is not a link; a hover card previews where a link goes, and touch users get only the link\",\n          '<HoverCard trigger={<Link href=\"/cooks/ari\">Ari</Link>}>',\n          key.current,\n        );\n      }\n    }\n  });\n\n  const portal = usePortalContainer(\"HoverCard\");\n\n  // The card mounts only once someone may want it: on the link's first hover or keyboard focus. Until then the link is\n  // the app's own element with a few handlers, so a page of links (a chat's authors) mounts no card. The link is never\n  // wrapped or drawn again as it arms, so focus and the pointer stay on it.\n  const [armed, setArmed] = useState(false);\n  const [open, setOpen] = useState(false);\n  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);\n  // Opens or closes the card after a delay, in place of whatever was waiting.\n  const after = (delay: number, next: boolean) => {\n    clearTimeout(timer.current);\n    timer.current = setTimeout(() => {\n      // Never on a device that cannot hover, or after a touch: a phone has no way to hover it away.\n      // Stryker disable next-line ConditionalExpression: a device that cannot hover is the touch project's (hover-card.touch.test.tsx), which mutation testing does not run.\n      if (next && (!canHover || lastInput() === \"touch\")) return;\n      setOpen(next);\n    }, delay);\n  };\n  const want = () => {\n    setArmed(true);\n    after(OPEN_DELAY, true);\n  };\n  // A Server Component's link may come wrapped (React's lazy element): the element inside is the one to give handlers.\n  const element = serverElement(trigger);\n  const own = element.props as {\n    ref?: Ref<HTMLAnchorElement>;\n    onPointerEnter?: (event: PointerEvent<HTMLAnchorElement>) => void;\n    onPointerLeave?: (event: PointerEvent<HTMLAnchorElement>) => void;\n    onFocus?: (event: FocusEvent<HTMLAnchorElement>) => void;\n    onBlur?: (event: FocusEvent<HTMLAnchorElement>) => void;\n    onKeyDown?: (event: KeyboardEvent<HTMLAnchorElement>) => void;\n  };\n  const ref = useMergedRef(own.ref, triggerRef);\n  // The link takes the merged ref, which nothing reads during render.\n  // eslint-disable-next-line react-hooks/refs\n  const link = cloneElement(element as ReactElement<Record<string, unknown>>, {\n    ref,\n    // Stryker disable next-line StringLiteral: found by the attribute alone, never by its value.\n    \"data-ouro-hover-card-trigger\": \"\",\n    // Stryker disable next-line StringLiteral: read by the attribute alone, as Base UI's open trigger is.\n    \"data-popup-open\": open ? \"\" : undefined,\n    onPointerEnter: (event: PointerEvent<HTMLAnchorElement>) => {\n      own.onPointerEnter?.(event);\n      want();\n    },\n    onPointerLeave: (event: PointerEvent<HTMLAnchorElement>) => {\n      own.onPointerLeave?.(event);\n      after(CLOSE_DELAY, false);\n    },\n    onFocus: (event: FocusEvent<HTMLAnchorElement>) => {\n      own.onFocus?.(event);\n      if (event.currentTarget.matches(\":focus-visible\")) want();\n    },\n    onBlur: (event: FocusEvent<HTMLAnchorElement>) => {\n      own.onBlur?.(event);\n      after(0, false);\n    },\n    // Escape on the link closes an open card and goes no further, so a dialog or panel around it stays: the card takes\n    // the first Escape, as Base UI's trigger does.\n    onKeyDown: (event: KeyboardEvent<HTMLAnchorElement>) => {\n      own.onKeyDown?.(event);\n      if (event.key !== \"Escape\" || !open) return;\n      after(0, false);\n      event.preventDefault();\n      event.stopPropagation();\n    },\n  });\n  if (!armed) return link;\n  return (\n    <>\n      {link}\n      <PreviewCard.Root\n        open={open}\n        // Base UI asks only to close a card it holds no trigger for: on Escape or a press outside it. The link is not its\n        // trigger, so a press on it counts as outside; the card stays for it, as it does on Base UI's own trigger, and the\n        // link takes Escape itself.\n        onOpenChange={(next, details) => {\n          if (!triggerRef.current!.contains(details.event.target as Node)) after(0, next);\n        }}\n      >\n        <PreviewCard.Portal {...portal} data-ouro=\"hover-card-portal\" className={floatingPortalClass}>\n          <PortalScope>\n            <PreviewCard.Positioner\n              anchor={triggerRef}\n              side={side}\n              align={align}\n              sideOffset={8}\n              collisionPadding={8}\n              data-ouro=\"hover-card-positioner\"\n            >\n              <PreviewCard.Popup\n                data-ouro=\"hover-card\"\n                // The pointer may cross from the link onto the card and stay: the card is part of what it hovers.\n                onPointerEnter={() => clearTimeout(timer.current)}\n                onPointerLeave={() => after(CLOSE_DELAY, false)}\n                className={cn(\n                  floatingSurfaceClass,\n                  floatingMotionClass,\n                  \"w-72 max-w-(--available-width) p-4 text-sm leading-5\",\n                  className,\n                )}\n              >\n                {children}\n              </PreviewCard.Popup>\n            </PreviewCard.Positioner>\n          </PortalScope>\n        </PreviewCard.Portal>\n      </PreviewCard.Root>\n    </>\n  );\n}\n",
      "type": "registry:ui",
      "target": "@components/ouro/hover-card/hover-card.tsx"
    }
  ],
  "docs": "A preview of where a link goes, shown when a mouse rests on the link or the keyboard focuses it: a cook's profile, a recipe's summary. Import: import { HoverCard } from \"@/components/ouro/hover-card/hover-card\", with @/components replaced by your components alias (aliases.components in components.json, such as ~/components). Also installed: the helpers it imports in lib/ouro. Needs ouro-base in your stylesheet: add that item once per app, from the same place as this one, if you have not. Docs: https://ui.ouroboros.bot/docs/hover-card.md Ouro UI v1.3.257.",
  "type": "registry:ui"
}