Navigation Menu

# Brok UI: Navigation Menu (`navigation-menu`)

A site navigation menu with hover and focus panels, linked controls, an active (aria-current) state for links and triggers, and complete arrow, Home, End, Enter, Space, Tab, and Escape keyboard access.

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

## Install

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

## Usage

```blade
<x-ui.navigation-menu>
    <x-ui.navigation-menu.list>
        <x-ui.navigation-menu.item>
            <x-ui.navigation-menu.trigger>{{ __('Products') }}</x-ui.navigation-menu.trigger>
            <x-ui.navigation-menu.content>
                <x-ui.navigation-menu.link href="#">{{ __('Analytics') }}</x-ui.navigation-menu.link>
                <x-ui.navigation-menu.link href="#">{{ __('Automation') }}</x-ui.navigation-menu.link>
                <x-ui.navigation-menu.link href="#">{{ __('Integrations') }}</x-ui.navigation-menu.link>
            </x-ui.navigation-menu.content>
        </x-ui.navigation-menu.item>
        <x-ui.navigation-menu.item>
            <x-ui.navigation-menu.trigger>{{ __('Company') }}</x-ui.navigation-menu.trigger>
            <x-ui.navigation-menu.content>
                <x-ui.navigation-menu.link href="#">{{ __('About') }}</x-ui.navigation-menu.link>
                <x-ui.navigation-menu.link href="#">{{ __('Careers') }}</x-ui.navigation-menu.link>
            </x-ui.navigation-menu.content>
        </x-ui.navigation-menu.item>
    </x-ui.navigation-menu.list>
</x-ui.navigation-menu>
```

## Props

- `active` (bool, default `false`) — Declared by @props in the registry Blade source.
- `href` (string, default `#', 'active' => false`) — Declared by @props in the registry Blade source.

## Use when

- Use to orient users and help them move across pages, sections, or commands.
- Building a top-level site navigation bar with dropdown panels for grouped links.
- Needing full keyboard support (arrows, Home, End, Enter, Space, Tab, Escape) and an active-link state, not just a plain nav list.

## Avoid when

- Do not hide primary wayfinding in novelty interactions or deep nested structures if straightforward navigation would be clearer.
- The navigation is a small, flat set of links with no dropdown panels; a plain nav with breadcrumb or segmented-nav links is lighter weight.
- The menu is triggered by a button rather than persistent top-level navigation items; use dropdown or menubar.

## Anti-patterns

- Hiding primary wayfinding in novelty interactions

## Rules

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

/**
 * Navigation menu behavior. A single root tracks the active item by id; hover
 * and focus reveal a content panel, while pointer-leave closes it after a short
 * grace delay so users can move into the panel. Escape closes immediately.
 */
document.addEventListener('alpine:init', () => {
    window.Alpine.data('uiNavigationMenu', () => ({
        active: null,
        closeTimer: null,
        pointerActive: false,
        suppressFocusOpen: false,

        open(id) {
            clearTimeout(this.closeTimer);
            this.active = id;
        },

        toggle(id) {
            this.active = this.active === id ? null : id;
        },

        focusItem(id) {
            if (!this.pointerActive && !this.suppressFocusOpen) this.open(id);
        },

        isOpen(id) {
            return this.active === id;
        },

        close() {
            this.active = null;
        },

        closeWithDelay() {
            this.closeTimer = setTimeout(() => {
                this.active = null;
            }, 150);
        },

        triggers() {
            return Array.from(this.$root.querySelectorAll('[data-slot="navigation-menu-trigger"]'));
        },

        links(item) {
            return Array.from(item?.querySelectorAll('[data-slot="navigation-menu-link"]') ?? []);
        },

        moveTrigger(trigger, delta) {
            const triggers = this.triggers();
            const index = triggers.indexOf(trigger);
            if (index === -1 || triggers.length === 0) return;

            triggers[(index + delta + triggers.length) % triggers.length].focus();
        },

        restoreTrigger(item) {
            const trigger = item?.querySelector('[data-slot="navigation-menu-trigger"]');
            if (!trigger) return;

            this.suppressFocusOpen = true;
            trigger.focus();
            queueMicrotask(() => {
                this.suppressFocusOpen = false;
            });
        },

        onKeydown(event) {
            const trigger = event.target.closest('[data-slot="navigation-menu-trigger"]');
            const link = event.target.closest('[data-slot="navigation-menu-link"]');
            if (!trigger && !link) return;

            const item = event.target.closest('[data-slot="navigation-menu-item"]');
            const links = this.links(item);

            if (trigger) {
                const rtl = getComputedStyle(this.$root).direction === 'rtl';
                const horizontalDelta = event.key === 'ArrowRight' ? (rtl ? -1 : 1) : rtl ? 1 : -1;

                if (event.key === 'ArrowRight' || event.key === 'ArrowLeft') {
                    event.preventDefault();
                    this.moveTrigger(trigger, horizontalDelta);
                } else if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
                    event.preventDefault();
                    const itemId = item?.dataset.navigationId;
                    if (itemId) this.open(itemId);
                    this.$nextTick(() =>
                        (event.key === 'ArrowDown' ? links[0] : links.at(-1))?.focus(),
                    );
                } else if (event.key === 'Home' || event.key === 'End') {
                    event.preventDefault();
                    (event.key === 'Home' ? this.triggers()[0] : this.triggers().at(-1))?.focus();
                } else if (event.key === 'Escape') {
                    event.preventDefault();
                    this.close();
                    trigger.focus();
                } else if (event.key === 'Tab' && this.active === null) {
                    const triggers = this.triggers();
                    const index = triggers.indexOf(trigger);
                    const next = event.shiftKey ? triggers[index - 1] : triggers[index + 1];

                    // WebKit can skip button controls during native Tab
                    // navigation. Keep adjacent closed-menu triggers in the
                    // same predictable keyboard sequence.
                    if (next) {
                        event.preventDefault();
                        next.focus();
                    }
                }

                return;
            }

            const index = links.indexOf(link);
            if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
                event.preventDefault();
                const delta = event.key === 'ArrowDown' ? 1 : -1;
                links[(index + delta + links.length) % links.length]?.focus();
            } else if (event.key === 'Home' || event.key === 'End') {
                event.preventDefault();
                (event.key === 'Home' ? links[0] : links.at(-1))?.focus();
            } else if (event.key === 'Escape') {
                event.preventDefault();
                this.close();
                this.restoreTrigger(item);
            }
        },

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