Menus

# Brok UI: Context Menu (`context-menu`)

A menu of actions revealed by right-clicking a region.

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

## Install

```bash
php artisan ui:add context-menu
```

## Usage

```blade
{{-- A file tile: right-click (or Shift+F10 / Enter with focus) opens its actions. --}}
<x-ui.context-menu>
    <x-ui.context-menu.trigger class="w-64 rounded-lg">
        <div class="flex flex-col gap-4 rounded-lg border border-border bg-card p-6 text-card-foreground shadow-xs">
            <div class="flex h-24 items-center justify-center rounded-md bg-muted">
                <svg class="size-8 text-muted-foreground" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z" /><path d="M14 2v6h6M8 13h8M8 17h5" /></svg>
            </div>
            <div class="min-w-0">
                <p class="truncate text-sm font-medium">{{ __('Q3 report.pdf') }}</p>
                <p class="truncate text-xs text-muted-foreground">{{ __('2.4 MB, edited yesterday') }}</p>
            </div>
            <p class="flex items-center gap-2 text-xs text-muted-foreground">
                <svg class="size-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="6" y="3" width="12" height="18" rx="6" /><path d="M12 7v3M12 3v4" /></svg>
                {{ __('Right-click for actions') }}
            </p>
        </div>
    </x-ui.context-menu.trigger>

    <x-ui.context-menu.content>
        <x-ui.context-menu.label>{{ __('Q3 report.pdf') }}</x-ui.context-menu.label>
        <x-ui.context-menu.item>
            <svg class="size-4 text-muted-foreground" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M15 3h6v6M10 14 21 3M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6" /></svg>
            {{ __('Open') }}
        </x-ui.context-menu.item>
        <x-ui.context-menu.item>
            <svg class="size-4 text-muted-foreground" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 20h9" /><path d="M16.5 3.5a2.1 2.1 0 0 1 3 3L7 19l-4 1 1-4Z" /></svg>
            {{ __('Rename') }}
        </x-ui.context-menu.item>
        <x-ui.context-menu.item>
            <svg class="size-4 text-muted-foreground" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="9" y="9" width="13" height="13" rx="2" /><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" /></svg>
            {{ __('Duplicate') }}
        </x-ui.context-menu.item>
        <x-ui.context-menu.separator />
        <x-ui.context-menu.item>
            <svg class="size-4 text-muted-foreground" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="18" cy="5" r="3" /><circle cx="6" cy="12" r="3" /><circle cx="18" cy="19" r="3" /><path d="m8.6 13.5 6.8 4M15.4 6.5 8.6 10.5" /></svg>
            {{ __('Share') }}
        </x-ui.context-menu.item>
        <x-ui.context-menu.item>
            <svg class="size-4 text-muted-foreground" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4M7 10l5 5 5-5M12 15V3" /></svg>
            {{ __('Download') }}
        </x-ui.context-menu.item>
        <x-ui.context-menu.separator />
        <x-ui.context-menu.item class="!text-destructive-text">
            <svg class="size-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3 6h18" /><path d="M8 6V4h8v2" /><path d="M19 6l-1 14H6L5 6" /><path d="M10 11v6M14 11v6" /></svg>
            {{ __('Move to trash') }}
        </x-ui.context-menu.item>
    </x-ui.context-menu.content>
</x-ui.context-menu>
```

## Props

- `target` (string|null, default `null`) — On the root, a CSS selector for delegated rows inside the trigger (for example [data-row] or tr). One menu then serves every matching row: the row under the pointer, or the focused row for Shift+F10 and the ContextMenu key, becomes context (its data-* values) and contextEl, and the root dispatches context-menu:open with { target, data }. Null keeps the single-region trigger.

## Use when

- Use for secondary actions when compact access is more important than constant visibility.
- Offering a short list of actions for a specific region, such as a table row or canvas element, via right-click.
- Mirroring a native desktop-app right-click experience for power users, in addition to visible controls.

## Avoid when

- Do not hide the most frequent or highest-value actions in a menu when discoverability matters.
- The actions must also be discoverable without right-clicking; pair with a visible trigger such as dropdown, or use dropdown alone.
- Building a persistent menu bar; use menubar instead.

## Anti-patterns

- Hiding primary actions in menus

## Rules

- Use the `<brok:context-menu>` tag (or `<x-ui.context-menu>`) 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/context-menu
- Registry JSON (files, props, contract): https://brokui.dev/r/open/context-menu.json

{{--
    Context menu (interactive). Root holds open state and the pointer point.
    A right-click on the trigger opens the menu at the pointer location.
    Escape and outside click close the menu and return focus to the trigger
    (or, with `target`, to the row that opened it).

    Delegated rows: `<x-ui.context-menu target="[data-row]">` lets one menu
    serve every matching row inside the trigger (a list or a table body)
    instead of one menu per row.

    The panel is <x-ui.dropdown.content> in anchored mode (teleported to
    <body>, placed by the shared `overlay-position.js` engine at the pointer
    point and flipped above it at the viewport edge). Because it is teleported,
    the outside-click check extends to the panel (`$refs.menu`) exactly as the
    anchored dropdown does, so a click inside the menu is never misread.
--}}
@props([
    // Delegated rows: a CSS selector (`[data-row]`, `tr`) for the elements
    // inside the trigger that each own the menu. A right-click, Shift+F10 or
    // the ContextMenu key on one of them opens this one menu for it; the row
    // is `context` (its data-* values) and `contextEl` in the Alpine scope,
    // and the root dispatches `context-menu:open` { target, data }. Outside a
    // matching row the browser's own menu shows. Null keeps the classic
    // single-region trigger.
    'target' => null,
])

@php
    $target = filled($target) ? (string) $target : null;
@endphp

<div
    @if ($target) x-data="uiContextMenu(@js(['target' => $target]))" @else x-data="uiContextMenu()" @endif
    @if ($target) data-target="{{ $target }}" @endif
    data-slot="context-menu"
    {{-- Escape is consumed only while the menu is open. A closed menu lets
         it bubble, so the dialog or sheet around the region still closes. --}}
    @keydown.escape="if (open) { $event.stopPropagation(); closeAndFocus() }"
    @click.outside="if (!$refs.menu?.contains($event.target)) close()"
    {{ $attributes->merge(['class' => 'relative']) }}
>
    {{ $slot }}
</div>

@aware([
    // The root's delegated-row selector. With it, the rows are the focusable
    // targets (their own link or tabindex), so the region itself is not a tab
    // stop, a right-click outside a row keeps the browser menu, and Enter
    // stays with the row.
    'target' => null,
])

@if (blank($target))
<div
    data-slot="context-menu-trigger"
    x-ref="trigger"
    tabindex="0"
    @contextmenu.prevent="openAt($event)"
    @keydown.shift.f10.prevent="openFromKeyboard($event)"
    @keydown.contextmenu.prevent="openFromKeyboard($event)"
    @keydown.enter.self.prevent="openFromKeyboard($event)"
    {{ $attributes->merge(['class' => 'block rounded-sm focus-visible:outline-none focus-visible:ring-[length:var(--ring-width)] focus-visible:ring-ring']) }}
>
    {{ $slot }}
</div>
@else
<div
    data-slot="context-menu-trigger"
    x-ref="trigger"
    @contextmenu="onContextMenu($event)"
    @keydown.shift.f10="openFromKeyboard($event)"
    @keydown.contextmenu="openFromKeyboard($event)"
    {{ $attributes->merge(['class' => 'block rounded-sm focus-visible:outline-none focus-visible:ring-[length:var(--ring-width)] focus-visible:ring-ring']) }}
>
    {{ $slot }}
</div>
@endif

/**
 * Context menu behavior (interactive).
 *
 * A right-click on the trigger opens the menu at the pointer location. The
 * panel is the anchored dropdown panel (teleported to <body>, `position:
 * fixed`), placed by the shared `overlay-position.js` engine against the
 * pointer point: it flips above the point when it would overflow the viewport
 * below (and there is more room above), is clamped into the viewport
 * otherwise, and reports the side it opened on through `data-side`. Keyboard
 * users open it with Shift+F10, the dedicated ContextMenu key, or Enter on
 * the focused trigger; the menu then anchors to the trigger's box instead of
 * a pointer position (WCAG 2.1.1 — every pointer-only action needs a keyboard
 * route). ArrowUp/Down/Home/End move a roving focus across enabled items;
 * Escape and outside click close the menu. Selecting an item closes the menu;
 * Escape and item selection return focus to the trigger.
 *
 * Delegated rows (`target`, a CSS selector): one menu serves every matching
 * row inside the trigger. The row under the pointer, or the row that holds
 * focus for Shift+F10 / the ContextMenu key, becomes the context: `contextEl`
 * and `context` (a copy of its data-* values) in the Alpine scope, a
 * `data-context-menu-open` attribute on the row while the menu is open, and a
 * `context-menu:open` event { target, data } from the root. A right-click
 * outside a matching row leaves the browser's own menu alone. Closing returns
 * focus to the row (or the element inside it that had focus).
 */
import { placeOverlay, trackOverlayPosition } from './overlay-position.js';

document.addEventListener('alpine:init', () => {
    window.Alpine.data('uiContextMenu', (config = {}) => ({
        open: false,
        x: 0,
        y: 0,
        target: config.target || null,
        // The delegated row the menu is open for, and its data-* values.
        contextEl: null,
        context: {},
        // Where focus goes back to on close (the row, or the trigger).
        _returnTo: null,
        // Teardown for the resize/scroll tracker attached while open.
        _untrack: null,

        /** The delegated row for an event, or null. */
        rowFor(node) {
            if (!this.target || !(node instanceof Element)) return null;
            const row = node.closest(this.target);

            return row && this.$refs.trigger?.contains(row) ? row : null;
        },

        /** Right-click: with `target`, only a matching row opens this menu. */
        onContextMenu(e) {
            if (this.target) {
                const row = this.rowFor(e.target);
                if (!row) return;
                this.setContext(row, row.contains(document.activeElement) ? document.activeElement : row);
            }
            e.preventDefault();
            this.openAt(e);
        },

        setContext(row, returnTo) {
            this.clearContext();
            this.contextEl = row;
            this.context = { ...row.dataset };
            this._returnTo = returnTo;
            row.setAttribute('data-context-menu-open', 'true');
            this.$el.dispatchEvent(new CustomEvent('context-menu:open', {
                bubbles: true,
                detail: { target: row, data: { ...row.dataset } },
            }));
        },

        clearContext() {
            this.contextEl?.removeAttribute('data-context-menu-open');
            this.contextEl = null;
            this.context = {};
        },

        openAt(e) {
            this.x = e.clientX;
            this.y = e.clientY;
            this.open = true;
            this.$nextTick(() => {
                this.reposition();
                this.teardownReposition();
                this._untrack = trackOverlayPosition(() => this.reposition());
                this.items()[0]?.focus();
            });
        },

        // Keyboard activation has no pointer: anchor the menu just inside the
        // trigger's start/bottom corner so it visibly belongs to it.
        openFromKeyboard(e) {
            let anchor = e.currentTarget || this.$refs.trigger;
            if (this.target) {
                const row = this.rowFor(e.target);
                if (!row) return;
                this.setContext(row, e.target instanceof HTMLElement ? e.target : row);
                anchor = row;
                e.preventDefault();
            }
            const rect = anchor?.getBoundingClientRect();
            if (!rect) return;
            const rtl = getComputedStyle(this.$el).direction === 'rtl';
            this.openAt({ clientX: rtl ? rect.right - 8 : rect.left + 8, clientY: rect.bottom - 4 });
        },

        /** Place the panel's start corner on the pointer point (no gap). */
        reposition() {
            const panel = this.$refs.menu;
            if (!panel || !this.open) {
                return;
            }
            placeOverlay(panel, { x: this.x, y: this.y }, { gap: 0 });
        },

        teardownReposition() {
            if (this._untrack) {
                this._untrack();
                this._untrack = null;
            }
        },

        close() {
            this.open = false;
            this.teardownReposition();
            this.contextEl?.removeAttribute('data-context-menu-open');
        },

        closeAndFocus() {
            const returnTo = this._returnTo;
            this.close();
            this.$nextTick(() => {
                const el = returnTo?.isConnected ? returnTo : this.$refs.trigger;
                // A row without a tab stop of its own takes focus programmatically.
                if (el && el !== this.$refs.trigger && !el.matches('a[href], button, input, select, textarea, [tabindex]')) {
                    el.setAttribute('tabindex', '-1');
                }
                el?.focus();
            });
        },

        // A click on a plain menu item chooses it: the consumer's own handler
        // on the item has already run by the time the click bubbles here.
        onItemClick(event) {
            const item = event.target.closest('[data-slot="context-menu-item"]');
            if (!item || item.dataset.disabled === 'true' || event.defaultPrevented) return;
            this.closeAndFocus();
        },

        items() {
            const m = this.$refs.menu;
            // Checkbox and radio rows borrowed from dropdown are menu items too.
            return m
                ? Array.from(m.querySelectorAll('[role="menuitem"]:not([aria-disabled="true"]), [role="menuitemcheckbox"]:not([aria-disabled="true"]), [role="menuitemradio"]:not([aria-disabled="true"])'))
                : [];
        },

        onKey(e) {
            const items = this.items();
            if (!items.length) return;
            const cur = items.indexOf(document.activeElement);
            let next;
            switch (e.key) {
                case 'ArrowDown':
                    next = (cur + 1) % items.length;
                    break;
                case 'ArrowUp':
                    next = (cur - 1 + items.length) % items.length;
                    break;
                case 'Home':
                    next = 0;
                    break;
                case 'End':
                    next = items.length - 1;
                    break;
                default:
                    return;
            }
            e.preventDefault();
            items[next].focus();
        },

        destroy() {
            this.teardownReposition();
            this.clearContext();
        },
    }));
});