# Navigation Menu

Horizontal website navigation primitive with top-level triggers, direct links, and explicit Angular content templates.

This implementation follows the shadcn Navigation Menu information architecture while keeping the panel layout owned by the consuming template through `ng-template[NavigationMenuContent]`.

## Import

```ts
import {
  NavigationMenuComponent,
  NavigationMenuContentDirective,
  NavigationMenuItemComponent,
  NavigationMenuLinkDirective,
  NavigationMenuListComponent,
  NavigationMenuTriggerDirective,
} from '@edsis/component/navigation-menu';
```

## Composition

```text
NavigationMenu
└── NavigationMenuList
    ├── NavigationMenuItem
    │   ├── button[NavigationMenuTrigger]
    │   └── ng-template[NavigationMenuContent]
    │       └── custom panel markup with a[NavigationMenuLink]
    └── NavigationMenuItem
        └── a[NavigationMenuLink] variant="trigger"
```

## Basic usage

```html
<NavigationMenu ariaLabel="Primary documentation navigation">
  <NavigationMenuList>
    <NavigationMenuItem>
      <button type="button" [NavigationMenuTrigger]="gettingStartedMenu">Getting started</button>
      <ng-template NavigationMenuContent #gettingStartedMenu="NavigationMenuContent">
        <div class="w-[540px] rounded-xl border border-border bg-popover p-4 shadow-md">
          <div class="grid gap-3 md:grid-cols-[1.05fr_1.25fr]">
            <a
              NavigationMenuLink
              href="/docs/introduction"
              class="flex min-h-[220px] flex-col justify-end rounded-lg bg-gradient-to-b from-muted/80 to-muted/40 p-6"
            >
              <span class="text-sm font-semibold text-foreground">Acme UI</span>
              <p class="text-sm leading-5 text-muted-foreground">
                Build consistent interfaces with Angular-first primitives and theme tokens.
              </p>
            </a>
            <div class="grid gap-2">
              <a NavigationMenuLink href="/docs/getting-started/installation">
                <div class="text-sm font-medium">Installation</div>
                <p class="text-sm leading-5 text-muted-foreground">
                  Set up the package, providers, and theme layer.
                </p>
              </a>
              <a NavigationMenuLink href="/docs/components/shadcn/navigation-menu">
                <div class="text-sm font-medium">Navigation Menu docs</div>
                <p class="text-sm leading-5 text-muted-foreground">
                  Learn the Angular composition and API surface of this entrypoint.
                </p>
              </a>
            </div>
          </div>
        </div>
      </ng-template>
    </NavigationMenuItem>

    <NavigationMenuItem>
      <a NavigationMenuLink variant="trigger" href="/docs/introduction">Docs</a>
    </NavigationMenuItem>
  </NavigationMenuList>
</NavigationMenu>
```

## Common patterns

### Dropdown groups

Use `NavigationMenuTrigger` for top-level items that should open a content panel. The panel layout is just template markup, so you can mix hero cards, compact lists, grids, and external links without a rigid viewport component.

### Direct links

Use `a[NavigationMenuLink] variant="trigger"` when a top-level item should navigate immediately instead of opening a panel.

### RTL

Wrap the root in `dir="rtl"` when the page runs in a right-to-left language. The root uses computed direction to reverse left and right keyboard movement.

## API reference

### `NavigationMenuComponent`

| Input       | Type      | Default             |
| ----------- | --------- | ------------------- |
| `class`     | `string`  | `''`                |
| `ariaLabel` | `string`  | `'Main navigation'` |
| `loop`      | `boolean` | `true`              |

Role: `navigation`.

### `NavigationMenuListComponent`

Top-level row wrapper with `role="menubar"`.

### `NavigationMenuItemComponent`

Structural wrapper for one trigger or direct-link item.

### `NavigationMenuTriggerDirective`

| Input                   | Type                             | Default   |
| ----------------------- | -------------------------------- | --------- |
| `NavigationMenuTrigger` | `NavigationMenuContentDirective` | required  |
| `align`                 | `'start' \| 'center' \| 'end'`   | `'start'` |
| `class`                 | `string`                         | `''`      |
| `disabled`              | `boolean`                        | `false`   |

Output: `openedChange: boolean`.

Methods: `open()`, `close()`, `toggle()`.

### `NavigationMenuContentDirective`

Template hook for dropdown panel markup.

### `NavigationMenuLinkDirective`

| Input      | Type                     | Default     |
| ---------- | ------------------------ | ----------- |
| `variant`  | `'trigger' \| 'content'` | `'content'` |
| `class`    | `string`                 | `''`        |
| `disabled` | `boolean`                | `false`     |

Use the default content variant for panel cards and `variant="trigger"` for top-level direct links.

## Styling and theming

- Pass `class` to the root, list, item, trigger, or link primitives when the layout needs local adjustments.
- Style panel width, grid, and card composition inside the `ng-template` block.
- Use shared tokens such as `border-border`, `bg-popover`, and `text-muted-foreground` inside panel cards.

## Accessibility

- Set `ariaLabel` when the page contains more than one navigation landmark.
- Use real anchors for destinations so browser and assistive-technology link semantics stay intact.
- Keep panel cards concise and descriptive so trigger-to-content relationships stay understandable.

## Keyboard interactions

- `ArrowLeft` and `ArrowRight` move focus across the top-level items.
- `Home` and `End` jump to the first and last top-level item.
- `ArrowDown` opens the active trigger and moves focus into the first focusable panel item.
- `Escape` closes the active panel and returns focus to the trigger.

## Angular notes

- The Angular surface uses `ng-template[NavigationMenuContent]` instead of a JSX-style child component so overlay ownership stays explicit.
- There is no `asChild` prop. Compose anchors and buttons directly with the provided directives.
- Use `variant="trigger"` on `NavigationMenuLink` when the top-level item should navigate immediately.