Hover Card

# Brok UI: Hover Card (`hover-card`)

Shows rich content in a card when a trigger is hovered or focused. A `preview` slot turns it into an inline component preview with a stage and caption; the card opens below or above the trigger.

Brok UI is a Laravel Blade component registry. Installed components are plain Blade files the app owns.

## Install

```bash
php artisan ui:add hover-card
```

## Usage

```blade
{{-- A mention in running text: hover or focus the handle to see who it is. The
     wrapper is a div, not a <p>: the card panel is block content, and a <p>
     would be auto-closed by the parser before it. --}}
<div class="text-sm text-muted-foreground">
    <span>{{ __('Created by') }}</span>
    <x-ui.hover-card>
        <x-ui.hover-card.trigger class="font-medium text-foreground">@janedoe</x-ui.hover-card.trigger>
        <x-ui.hover-card.content class="w-72">
            <div class="flex gap-3">
                <x-ui.avatar fallback="JD" size="md" class="shrink-0" />
                <div class="min-w-0 space-y-1">
                    <p class="text-sm font-semibold leading-tight text-popover-foreground">{{ __('Jane Doe') }} <span class="font-normal text-muted-foreground">@janedoe</span></p>
                    <div class="text-sm text-muted-foreground">{{ __('Product designer building accessible UI components.') }}</p>
                    <p class="flex items-center gap-1 pt-1 text-xs text-muted-foreground">
                        <svg class="size-3" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="4" width="18" height="18" rx="2" /><path d="M16 2v4M8 2v4M3 10h18" /></svg>
                        {{ __('Joined December 2021') }}
                    </p>
                </div>
            </div>
        </x-ui.hover-card.content>
    </x-ui.hover-card>
    <span>{{ __('a few minutes ago.') }}</span>
</div>
```

## Props

- `group` (string|null, default `null`) — Opt-in coordination key set on the root component: opening a hover card closes any other hover card sharing the same group name. Leave unset for standalone hover cards.
- `label` (string|null, default `null`) — Caption title shown under the preview stage when the preview slot is used.
- `description` (string|null, default `null`) — Caption description shown under the label when the preview slot is used.
- `side` (top|bottom, default `bottom`) — Which side of the trigger the card opens on.
- `name` (string|null, default `null`) — A name the window events hover-card:open, hover-card:close and hover-card:toggle address with { name }, for a keyboard peek (a list row's Space handler). The card opens at once and focus stays where it is.
- `openDelay` (int, default `600`) — Hover delay in milliseconds before the card opens.
- `closeDelay` (int, default `250`) — Delay in milliseconds before the card closes after the pointer leaves.
- `lazy` (bool, default `false`) — Declared by @props in the registry Blade source.
- `flush` (bool, default `false`) — Declared by @props in the registry Blade source.

## Use when

- Use for lightweight contextual details or actions near a trigger.
- Revealing rich, non-critical content (a profile summary, a component preview) when a trigger is hovered or focused.
- Needing an inline component preview with a stage and caption via the preview slot.

## Avoid when

- Do not use for long content, required reading, or complex interaction flows.
- The content is plain short text; use tooltip instead.
- The content must be reachable without hover or focus, such as on touch-only devices with no equivalent tap path; use popover.

## Anti-patterns

- Required reading in a popover
- Complex forms in fragile anchored overlays

## Rules

- Use the `<brok:hover-card>` tag (or `<x-ui.hover-card>`) in Blade; do not rewrite the component.
- Prefer the documented props and variants over utility-class overrides; when a utility must win, use the `!` important modifier.
- Use semantic design tokens (`bg-primary`, `text-muted-foreground`), never raw colour utilities.
- Keep the `data-slot` attributes; they are the styling and test hooks.

## Links

- Docs: https://brokui.dev/docs/components/hover-card
- Registry JSON (files, props, contract): https://brokui.dev/r/open/hover-card.json

@props([
    'group' => null,
    // Preview mode (the former component-preview-tooltip): fill the `preview`
    // slot and the root renders its own trigger from the default slot plus a
    // card with a stage for the preview, an optional `label`/`description`
    // caption, opening on `side` (bottom or top). Without a `preview` slot the
    // root is the plain compositional wrapper for .trigger and .content.
    'label' => null,
    'description' => null,
    'side' => 'bottom',
    // Programmatic open for a keyboard "peek": a name the window events
    // `hover-card:open`, `hover-card:close` and `hover-card:toggle` address
    // with { name } (a list row's Space handler dispatches them). The card
    // opens at once, focus stays where it is, and Escape closes it.
    'name' => null,
    // Hover delays in milliseconds (defaults unchanged: 600 to open, 250 to close).
    'openDelay' => 600,
    'closeDelay' => 250,
])

@php
    // `group` (opt-in, default null): coordinate multiple hover cards so
    // opening one closes any sibling sharing the same group name — see
    // popover.blade.php for the identical rationale. Reduces to the original
    // behaviour byte-for-byte when omitted.
    $options = array_filter([
        'name' => filled($name) ? (string) $name : null,
        'openDelay' => (int) $openDelay !== 600 ? max(0, (int) $openDelay) : null,
        'closeDelay' => (int) $closeDelay !== 250 ? max(0, (int) $closeDelay) : null,
    ], fn ($value) => $value !== null);
    $groupArg = $group !== null && $group !== '' ? json_encode($group) : null;
    // The default call stays `uiHoverCard()` so an existing render is unchanged.
    $dataCall = match (true) {
        $options !== [] => 'uiHoverCard('.($groupArg ?? 'null').', '.\Illuminate\Support\Js::from($options).')',
        $groupArg !== null => 'uiHoverCard('.$groupArg.')',
        default => 'uiHoverCard()',
    };
    // component-preview-tooltip renders this component under its own name; the
    // browser keeps only the first of two identical attributes, so read the
    // override out of the bag and print exactly one.
    $slotName = (string) ($attributes->get('data-slot') ?: 'hover-card');
@endphp

{{--
    Hover Card. Reveals rich content in a card when its trigger is hovered or
    focused. Opening and closing are delayed so passing the pointer through the
    trigger does not flicker the card; the card stays open while hovered.
--}}
<div
    x-data="{{ $dataCall }}"
    data-slot="{{ $slotName }}"
    @if (filled($name)) data-name="{{ $name }}" @endif
    @mouseenter="openWithDelay()"
    @mouseleave="closeWithDelay()"
    {{ $attributes->except('data-slot')->merge(['class' => 'relative inline-block']) }}
>
@isset ($preview)
    <x-ui.hover-card.trigger>{{ $slot }}</x-ui.hover-card.trigger>
    <x-ui.hover-card.content :side="$side" flush>
        <div data-slot="hover-card-preview" class="flex items-center justify-center border-b border-border bg-muted/40 p-4">
            {{ $preview }}
        </div>
        @if ($label || $description)
            <div data-slot="hover-card-caption" class="p-3">
                @if ($label)
                    <p class="text-xs font-semibold">{{ $label }}</p>
                @endif
                @if ($description)
                    <p class="mt-0.5 text-xs text-muted-foreground">{{ $description }}</p>
                @endif
            </div>
        @endif
    </x-ui.hover-card.content>
@else
    {{ $slot }}
@endisset
</div>

@props([
    'lazy' => false,
    // Which side of the trigger the card opens on: bottom (default) or top.
    'side' => 'bottom',
    // Drop the inset so edge-to-edge content (a preview stage, an image) can
    // fill the card; the card clips to its own radius.
    'flush' => false,
])

@php
    // `lazy` (opt-in, default false): see popover/content.blade.php for the
    // identical rationale — the slot mounts/unmounts with `open` directly
    // rather than staying mounted after first open, so a long session
    // hovering through many cards does not accumulate DOM. The
    // `@if`/`@else`/`@endif` markup below is deliberately un-indented: an
    // indented directive line leaks stray spaces into the plain (non-lazy)
    // output and breaks the byte-identical default render — see
    // popover/content.blade.php for the full explanation.
    $placement = $side === 'top' ? 'bottom-full mb-2 origin-bottom' : 'mt-2 origin-top';
    $inset = $flush ? 'overflow-hidden' : 'p-4';
@endphp

<div
    data-slot="hover-card-content"
    data-side="{{ $side === 'top' ? 'top' : 'bottom' }}"
    x-show="open"
    x-cloak
    @mouseenter="cancelClose()"
    @mouseleave="closeWithDelay()"
    x-transition:enter="motion-safe:transition motion-safe:duration-150 motion-safe:ease-out"
    x-transition:enter-start="opacity-0 motion-safe:scale-95 motion-safe:-translate-y-1"
    x-transition:enter-end="opacity-100 motion-safe:scale-100 motion-safe:translate-y-0"
    x-transition:leave="motion-safe:transition motion-safe:duration-100 motion-safe:ease-in"
    x-transition:leave-start="opacity-100 motion-safe:scale-100 motion-safe:translate-y-0"
    x-transition:leave-end="opacity-0 motion-safe:scale-95 motion-safe:-translate-y-1"
    {{ $attributes->merge(['class' => 'absolute z-popover w-64 max-w-none rounded-md border border-border bg-popover text-sm text-popover-foreground shadow-md motion-reduce:transition-none '.$placement.' '.$inset]) }}
>
@if ($lazy)
        <template x-if="open">
            {{ $slot }}
        </template>
@else
    {{ $slot }}
@endif
</div>

/**
 * Hover Card behavior. Opens on hover and keyboard focus, with an open delay
 * (so a brief pass-through does not trigger it) and a close delay (so moving
 * the pointer from the trigger into the card keeps it open). Self-registering
 * Alpine data component.
 *
 * v1.2.0 adds an opt-in `group` (see hover-card.blade.php), identical in
 * spirit to popover's: opening dispatches a `ui-hover-card:opened` window
 * event carrying its group name and a per-instance id, and every other hover
 * card sharing that group name closes immediately on hearing it. Ungrouped
 * hover cards (the default) never attach a listener or dispatch the event.
 * The dispatch lives behind an Alpine `$watch('open', ...)` rather than being
 * inlined into `openWithDelay()`, because `open` can also flip true directly
 * from the trigger's `@focusin="open = true"` (keyboard users skip the hover
 * delay entirely) — watching the property catches both paths from one place
 * instead of silently missing the keyboard one. Closing this way skips the
 * normal delay (there's no pointer to debounce against) and, if focus was
 * inside the card being closed, returns it to this card's own trigger rather
 * than leaving it stranded on a removed node.
 *
 * v1.5.0 adds a keyboard "peek": with a `name`, the card listens for the
 * window events `hover-card:open`, `hover-card:close` and `hover-card:toggle`
 * carrying { name } (a list row's Space handler dispatches them). The card
 * opens at once without moving focus, and Escape (a window listener that
 * lives only while a peek is open) closes it. `openDelay` / `closeDelay`
 * tune the hover delays.
 */
document.addEventListener('alpine:init', () => {
    let hoverCardInstanceSeq = 0;

    window.Alpine.data('uiHoverCard', (group = null, options = {}) => ({
        open: false,
        name: options.name ?? null,
        openDelay: Number.isFinite(options.openDelay) ? options.openDelay : 600,
        closeDelay: Number.isFinite(options.closeDelay) ? options.closeDelay : 250,
        _onPeek: null,
        _onPeekEscape: null,
        openTimer: null,
        closeTimer: null,
        group,
        _instanceId: `hover-card-${++hoverCardInstanceSeq}`,
        _onGroupOpen: null,

        init() {
            this.initPeek();
            if (!this.group) {
                return;
            }
            this.$watch('open', (isOpen) => {
                if (!isOpen) {
                    return;
                }
                window.dispatchEvent(
                    new CustomEvent('ui-hover-card:opened', {
                        detail: { group: this.group, id: this._instanceId },
                    })
                );
            });
            this._onGroupOpen = (event) => {
                const detail = event.detail || {};
                if (detail.group !== this.group || detail.id === this._instanceId || !this.open) {
                    return;
                }
                clearTimeout(this.openTimer);
                clearTimeout(this.closeTimer);
                const panel = this.$root.querySelector('[data-slot="hover-card-content"]');
                const stoleFocus = !!panel && panel.contains(document.activeElement);
                this.open = false;
                if (stoleFocus) {
                    this.$refs.trigger?.focus();
                }
            };
            window.addEventListener('ui-hover-card:opened', this._onGroupOpen);
        },

        initPeek() {
            if (!this.name) {
                return;
            }
            this._onPeek = (event) => {
                const detail = event.detail || {};
                if ((detail.name ?? detail.id) !== this.name) {
                    return;
                }
                const action = event.type.split(':')[1];
                if (action === 'open' || (action === 'toggle' && !this.open)) {
                    this.peek();
                } else {
                    this.unpeek();
                }
            };
            ['open', 'close', 'toggle'].forEach((action) => window.addEventListener(`hover-card:${action}`, this._onPeek));
            this._onPeekEscape = (event) => {
                if (event.key !== 'Escape' || !this.open || event.defaultPrevented) {
                    return;
                }
                event.preventDefault();
                this.unpeek();
            };
            this.$watch('open', (isOpen) => {
                if (!isOpen) {
                    window.removeEventListener('keydown', this._onPeekEscape, true);
                }
            });
        },

        /** Open at once, without moving focus (a keyboard peek). */
        peek() {
            clearTimeout(this.openTimer);
            clearTimeout(this.closeTimer);
            this.open = true;
            window.removeEventListener('keydown', this._onPeekEscape, true);
            window.addEventListener('keydown', this._onPeekEscape, true);
        },

        unpeek() {
            clearTimeout(this.openTimer);
            clearTimeout(this.closeTimer);
            this.open = false;
        },

        openWithDelay() {
            clearTimeout(this.closeTimer);
            this.openTimer = setTimeout(() => (this.open = true), this.openDelay);
        },

        closeWithDelay() {
            clearTimeout(this.openTimer);
            this.closeTimer = setTimeout(() => (this.open = false), this.closeDelay);
        },

        cancelClose() {
            clearTimeout(this.closeTimer);
        },

        destroy() {
            clearTimeout(this.openTimer);
            clearTimeout(this.closeTimer);
            if (this._onPeek) {
                ['open', 'close', 'toggle'].forEach((action) => window.removeEventListener(`hover-card:${action}`, this._onPeek));
                this._onPeek = null;
            }
            if (this._onPeekEscape) {
                window.removeEventListener('keydown', this._onPeekEscape, true);
                this._onPeekEscape = null;
            }
            if (this._onGroupOpen) {
                window.removeEventListener('ui-hover-card:opened', this._onGroupOpen);
                this._onGroupOpen = null;
            }
        },
    }));
});