Hover Card

/** @jsxImportSource hono/jsx */
import type { PropsWithChildren } from "hono/jsx"
import { cloneElement, isValidElement } from "hono/jsx"
import { cn, type ClassValue } from "@/registry/lib/cn"

// Hover Card — shadcn-htmx, htmx v4 + Tailwind v4.
//
// A rich preview surface revealed when the user shows INTEREST in a trigger
// (hover, keyboard focus, or long-press). Unlike Tooltip — which the APG
// forbids from holding interactive content and which defers to this primitive
// — a Hover Card MAY contain links, buttons and other interactive content
// (e.g. a "Follow" button on a user preview).
//
// Built entirely on the native Popover API "interest invoker" mechanism — zero
// JS:
//   - The trigger (an <a> or <button>) carries `interestfor` pointing at the
//     card's id. The browser reveals the card on hover / focus / long-press
//     and hides it on lose-interest, with NO state machine of ours.
//   - The card is `popover="hint"`. Per spec a `hint` popover does NOT light-
//     dismiss `auto` popovers, can itself be light-dismissed, and responds to
//     ESC (close request) — exactly the contract we want for a preview card.
//   - Associating a popover with its interest invoker creates an IMPLICIT
//     anchor reference, so the card is positioned with CSS `position-area`
//     relative to the trigger — no JS positioner, unlike registry/ui/popover.tsx
//     which targets older click-popovers without anchor support.
//
// Progressive enhancement: in browsers without interest invokers the trigger
// is just a normal <a>/<button> (which still works), and `popover="hint"`
// falls back to `popover="manual"`, so the card simply stays hidden — no error,
// no broken UI.
//
// Refs:
//   repos/mdn/files/en-us/web/api/popover_api/using_interest_invokers/index.md
//   repos/mdn/files/en-us/web/api/popover_api/index.md  (popover="hint" state)
//   repos/mdn/files/en-us/web/html/reference/elements/a/index.md:89  (interestfor)
//   repos/mdn/files/en-us/web/css/reference/properties/position-area/index.md
//   repos/shadcn-ui/apps/v4/registry/  (HoverCard anatomy: trigger + content)

export type HoverCardSide = "top" | "right" | "bottom" | "left"

// Layout-only positioning utilities (see app/styles/input.css). They map a
// side hint onto a CSS `position-area` tile relative to the implicit anchor
// (the interest invoker), and fall back to a centred placement in browsers
// without CSS Anchor Positioning. Colour comes from theme tokens below.
const sideAnchor: Record<HoverCardSide, string> = {
  top: "anchor-hovercard-top",
  bottom: "anchor-hovercard-bottom",
  left: "anchor-hovercard-left",
  right: "anchor-hovercard-right",
}

const contentBase =
  "z-50 m-0 w-64 rounded-md border bg-popover p-4 text-sm text-popover-foreground shadow-md outline-none " +
  // Native [popover] is display:none until shown; reveal + animate on open.
  "[&:not(:popover-open)]:hidden " +
  // animate-fade/scale-in keyframed in input.css (shared scn-popover-in).
  "[&:popover-open]:animate-[scn-popover-in_120ms_ease-out]"

export function hoverCardContentClasses(opts?: {
  side?: HoverCardSide
  class?: ClassValue
}): string {
  const side = opts?.side ?? "bottom"
  return cn(contentBase, sideAnchor[side], opts?.class)
}

type HoverCardTriggerProps = PropsWithChildren<{
  // Id of the HoverCard this reveals (its `interestfor` target).
  cardFor: string
  // Render the wrapped child element (e.g. an <a href>) with the trigger
  // wiring merged onto it, instead of the default bare <a>. SSR-friendly
  // equivalent of shadcn's Radix `asChild`.
  asChild?: boolean
  // Destination for the default <a>. Interest invokers REVEAL on hover/focus
  // but the trigger still navigates on click, so a real href keeps it useful
  // (and functional in non-supporting browsers).
  href?: string
  class?: ClassValue
  id?: string
}>

export function HoverCardTrigger(props: HoverCardTriggerProps) {
  const { cardFor, asChild, href, class: className, id, children, ...rest } = props

  // asChild: clone the single child (an <a>/<button>) and merge the interest-
  // invoker wiring onto it so the markup the page already has becomes the
  // trigger — no extra wrapper element in the accessibility tree.
  if (asChild && isValidElement(children)) {
    const child = children as any
    return cloneElement(child, {
      ...rest,
      interestfor: cardFor,
      "data-slot": "hover-card-trigger",
      class: cn(child?.props?.class, className),
    })
  }

  // Default: a real <a>. interestfor reveals the card on interest; click still
  // navigates. Anchors are the canonical interest-invoker element (MDN).
  return (
    <a
      id={id}
      href={href ?? "#"}
      interestfor={cardFor}
      data-slot="hover-card-trigger"
      class={cn(className)}
      {...rest}
    >
      {children}
    </a>
  )
}

type HoverCardProps = PropsWithChildren<{
  // Required — referenced by the trigger's `interestfor`.
  id: string
  // Placement relative to the trigger. Drives `position-area` (anchor) with a
  // centred fallback. Default "bottom".
  side?: HoverCardSide
  class?: ClassValue
  // Forward hx-*, data-*, aria-* (e.g. hx-get to lazily fetch the preview).
  [key: string]: unknown
}>

export function HoverCard(props: HoverCardProps) {
  const { id, side = "bottom", class: className, children, ...rest } = props
  return (
    <div
      id={id}
      // `hint`: shows on interest, light-dismissable, ESC-closeable, and does
      // NOT close sibling `auto` popovers. Falls back to `manual` (stays
      // hidden) in unsupporting browsers — safe progressive enhancement.
      // Cast: hono/jsx's `popover` type predates the `"hint"` state.
      {...({ popover: "hint" } as Record<string, string>)}
      data-slot="hover-card"
      data-side={side}
      class={hoverCardContentClasses({ side, class: className })}
      {...rest}
    >
      {children}
    </div>
  )
}

{# Hover Card macros — shadcn-htmx, htmx v4 + Tailwind v4.

   A rich preview surface revealed on INTEREST (hover / focus / long-press)
   of a trigger. Unlike Tooltip it MAY hold interactive content. Built on the
   native Popover API interest-invoker mechanism — zero JS:
     - the trigger carries `interestfor` pointing at the card's id;
     - the card is `popover="hint"` (shows on interest, ESC-closeable, does
       not light-dismiss `auto` popovers; falls back to `manual` when the
       feature is unsupported);
     - the implicit anchor reference lets CSS `position-area` place the card.

   Refs:
     repos/mdn/files/en-us/web/api/popover_api/using_interest_invokers/index.md
     repos/mdn/files/en-us/web/api/popover_api/index.md  (popover="hint")
     repos/mdn/files/en-us/web/css/reference/properties/position-area/index.md

   Usage:
     {% from "components/hover-card.html" import hover_card_trigger, hover_card_open, hover_card_close %}

     {{ hover_card_trigger("@productdevbook", card_for="user-card", href="/u/productdevbook", class_="font-medium underline") }}

     {% call hover_card_open(id="user-card") %}
       <p>Card body — links and buttons are allowed here.</p>
     {% endcall %} #}

{% macro hover_card_trigger(label, card_for, href="#", class_="", id=none) %}
<a {% if id %}id="{{ id }}"{% endif %}
   href="{{ href }}"
   interestfor="{{ card_for }}"
   data-slot="hover-card-trigger"
   class="{{ class_ }}">{{ label }}</a>
{% endmacro %}

{% macro hover_card_open(id, side="bottom", extra_class="", attrs={}) %}
{%- set sides = {
    "top":    "anchor-hovercard-top",
    "bottom": "anchor-hovercard-bottom",
    "left":   "anchor-hovercard-left",
    "right":  "anchor-hovercard-right"
} -%}
<div id="{{ id }}"
     popover="hint"
     data-slot="hover-card" data-side="{{ side }}"
     class="z-50 m-0 w-64 rounded-md border bg-popover p-4 text-sm text-popover-foreground shadow-md outline-none [&:not(:popover-open)]:hidden [&:popover-open]:animate-[scn-popover-in_120ms_ease-out] {{ sides[side] }} {{ extra_class }}"
     {% for k, v in attrs.items() %}{{ k|replace('_','-') }}="{{ v }}" {% endfor %}>
{% endmacro %}

{% macro hover_card_close() %}</div>{% endmacro %}

{{/*
  Hover Card templates — shadcn-htmx, htmx v4 + Tailwind v4.

  A rich preview surface revealed on INTEREST (hover / focus / long-press) of a
  trigger. Unlike Tooltip it MAY hold interactive content. Built on the native
  Popover API interest-invoker mechanism — zero JS:
    - the trigger carries `interestfor` pointing at the card's id;
    - the card is `popover="hint"` (shows on interest, ESC-closeable, does not
      light-dismiss `auto` popovers; falls back to `manual` when unsupported);
    - the implicit anchor reference lets CSS `position-area` place the card.

  Refs:
    repos/mdn/files/en-us/web/api/popover_api/using_interest_invokers/index.md
    repos/mdn/files/en-us/web/api/popover_api/index.md  (popover="hint")
    repos/mdn/files/en-us/web/css/reference/properties/position-area/index.md

      type HoverCardArgs struct {
          ID, Side string
          Body     template.HTML
      }
      type HoverCardTriggerArgs struct {
          Label, CardFor, Href, Class, ID string
      }
*/}}

{{define "hover_card"}}
{{- $side := or .Side "bottom" -}}
{{- $sides := dict "top" "anchor-hovercard-top" "bottom" "anchor-hovercard-bottom" "left" "anchor-hovercard-left" "right" "anchor-hovercard-right" -}}
<div id="{{.ID}}" popover="hint" data-slot="hover-card" data-side="{{$side}}"
     class="z-50 m-0 w-64 rounded-md border bg-popover p-4 text-sm text-popover-foreground shadow-md outline-none [&:not(:popover-open)]:hidden [&:popover-open]:animate-[scn-popover-in_120ms_ease-out] {{index $sides $side}}">
  {{.Body}}
</div>
{{end}}

{{define "hover_card_trigger"}}
<a {{if .ID}}id="{{.ID}}"{{end}}
   href="{{or .Href "#"}}"
   interestfor="{{.CardFor}}"
   data-slot="hover-card-trigger"
   class="{{.Class}}">{{.Label}}</a>
{{end}}

defmodule ShadcnHtmx.Components.HoverCard do
  @moduledoc """
  Hover Card — shadcn-htmx, htmx v4 + Tailwind v4 for Phoenix.

  A rich preview surface revealed on INTEREST (hover / focus / long-press) of a
  trigger. Unlike Tooltip it MAY hold interactive content (links, buttons).
  Built on the native Popover API interest-invoker mechanism — zero JS:

    * the trigger carries `interestfor` pointing at the card's id;
    * the card is `popover="hint"` — shows on interest, ESC-closeable, does not
      light-dismiss `auto` popovers; falls back to `manual` when unsupported;
    * the implicit anchor reference lets CSS `position-area` place the card.

  Refs:
    repos/mdn/files/en-us/web/api/popover_api/using_interest_invokers/index.md
    repos/mdn/files/en-us/web/api/popover_api/index.md  (popover="hint")
    repos/mdn/files/en-us/web/css/reference/properties/position-area/index.md

  ## Examples

      <.hover_card_trigger card_for="user-card" href="/u/productdevbook" class="font-medium underline">
        @productdevbook
      </.hover_card_trigger>

      <.hover_card id="user-card">
        <p>Card body — links and buttons are allowed here.</p>
      </.hover_card>
  """

  use Phoenix.Component

  @sides %{
    "top" => "anchor-hovercard-top",
    "bottom" => "anchor-hovercard-bottom",
    "left" => "anchor-hovercard-left",
    "right" => "anchor-hovercard-right"
  }

  attr :id, :string, required: true
  attr :side, :string, default: "bottom", values: ~w(top right bottom left)
  attr :class, :string, default: nil
  attr :rest, :global
  slot :inner_block, required: true

  def hover_card(assigns) do
    assigns = assign(assigns, :side_class, Map.fetch!(@sides, assigns.side))

    ~H"""
    <div
      id={@id}
      popover="hint"
      data-slot="hover-card"
      data-side={@side}
      class={[
        "z-50 m-0 w-64 rounded-md border bg-popover p-4 text-sm text-popover-foreground shadow-md outline-none",
        "[&:not(:popover-open)]:hidden",
        "[&:popover-open]:animate-[scn-popover-in_120ms_ease-out]",
        @side_class,
        @class
      ]}
      {@rest}
    >
      {render_slot(@inner_block)}
    </div>
    """
  end

  attr :card_for, :string, required: true
  attr :href, :string, default: "#"
  attr :class, :string, default: nil
  attr :rest, :global
  slot :inner_block, required: true

  def hover_card_trigger(assigns) do
    ~H"""
    <a
      href={@href}
      interestfor={@card_for}
      data-slot="hover-card-trigger"
      class={@class}
      {@rest}
    >
      {render_slot(@inner_block)}
    </a>
    """
  end
end

<!--
  shadcn-htmx — raw HTML hover-card snippet.

  A rich preview surface revealed on INTEREST (hover / focus / long-press) of a
  trigger. Unlike a tooltip it MAY hold interactive content (links, buttons).
  Built on the native Popover API interest-invoker mechanism — NO JS required:
    - the trigger <a> carries `interestfor` pointing at the card's id;
    - the card is `popover="hint"` — shows on interest, ESC-closeable, and does
      not light-dismiss `auto` popovers. It falls back to `popover="manual"`
      (stays hidden) in browsers without interest-invoker support, so the link
      still works — pure progressive enhancement.
    - the implicit anchor reference lets CSS `position-area` (anchor-hovercard-*)
      place the card relative to the trigger.

  Relies only on theme tokens + the anchor-hovercard-* utilities in styles.css.
-->

<p>
  Built by
  <a href="/u/productdevbook" interestfor="user-card"
     data-slot="hover-card-trigger"
     class="font-medium text-primary underline-offset-4 hover:underline">@productdevbook</a>.
</p>

<div id="user-card" popover="hint" data-slot="hover-card" data-side="bottom"
  class="z-50 m-0 w-64 rounded-md border bg-popover p-4 text-sm text-popover-foreground shadow-md outline-none [&:not(:popover-open)]:hidden [&:popover-open]:animate-[scn-popover-in_120ms_ease-out] anchor-hovercard-bottom">
  <div class="flex gap-3">
    <span data-slot="avatar"
      class="relative inline-flex size-10 shrink-0 overflow-hidden rounded-full bg-muted">
      <span class="flex size-full items-center justify-center text-sm font-medium text-muted-foreground">PD</span>
    </span>
    <div class="space-y-1">
      <p class="font-semibold">@productdevbook</p>
      <p class="text-muted-foreground">Building shadcn-htmx. Web standards first.</p>
      <button type="button"
        class="mt-1 inline-flex h-7 items-center rounded-md bg-primary px-2.5 text-xs font-medium text-primary-foreground hover:bg-primary/90">
        Follow
      </button>
    </div>
  </div>
</div>