forty-cdk 0.2.0 → 0.3.0

package/menubar/README.md

@@ -0,0 +1,140 @@
+# Menubar
+
+Headless implementation of the [WAI-ARIA Menubar pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/): a horizontal (or vertical) bar of triggers, each opening a dropdown menu, with cross-menu ArrowLeft / ArrowRight navigation, hover-after-first-open, and roving tabindex among triggers.
+
+## Usage
+
+```ts
+import { Component, signal } from '@angular/core';
+import { ForMenuContent, ForMenuItem, ForMenuSeparator } from 'forty-cdk/menu';
+import { ForMenubar, ForMenubarTrigger } from 'forty-cdk/menubar';
+
+@Component({
+  selector: 'demo-menubar',
+  imports: [ForMenubar, ForMenubarTrigger, ForMenuContent, ForMenuItem, ForMenuSeparator],
+  template: `
+    <div forMenubar [(value)]="open" aria-label="Main">
+      <button forMenubarTrigger value="file">File</button>
+      @if (open() === 'file') {
+        <div forMenuContent animate.leave="fade-out">
+          <button forMenuItem (activate)="newDoc()">New</button>
+          <button forMenuItem (activate)="openDoc()">Open…</button>
+          <hr forMenuSeparator />
+          <button forMenuItem (activate)="quit()">Quit</button>
+        </div>
+      }
+
+      <button forMenubarTrigger value="edit">Edit</button>
+      @if (open() === 'edit') {
+        <div forMenuContent>
+          <button forMenuItem (activate)="undo()">Undo</button>
+          <button forMenuItem (activate)="redo()">Redo</button>
+        </div>
+      }
+
+      <button forMenubarTrigger value="view" disabled>View</button>
+    </div>
+  `,
+})
+export class DemoMenubar {
+  readonly open = signal<string>('');
+  newDoc() {}
+  openDoc() {}
+  quit() {}
+  undo() {}
+  redo() {}
+}
+```
+
+`@if (open() === '<value>')` controls each menu's mount, so Angular's `animate.enter` / `animate.leave` fire on the natural mount cycle. `[(value)]` is two-way bindable; the menubar flips it on trigger interaction, item activation, Escape, outside dismissal, and cross-menu navigation.
+
+## Pieces
+
+| Class               | Selector              | Role                                                                                                                                                                |
+| ------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ForMenubar`        | `[forMenubar]`        | Root. Owns `value` (the open trigger), orientation, dir, loop, disabled. Provides the `ForMenubarContext` and a multiplexed `ForMenuContext` to `[forMenuContent]`. |
+| `ForMenubarTrigger` | `[forMenubarTrigger]` | A trigger button. `role="menuitem"` with `aria-haspopup="menu"` / `aria-expanded` / `aria-controls`. Participates in roving tabindex and trigger-row keyboard.      |
+
+The menu surface, items, separators, groups, and submenus come from the [`menu/`](../menu/README.md) folder — same primitives as `[forDropdownMenu]` and `[forContextMenu]`. The bar simply pumps a different `ForMenuContext` whose anchor / side / ids reflect the active trigger.
+
+## Inputs (`ForMenubar`)
+
+| API           | Default        | Description                                                                                                                                                                                         |
+| ------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`       | `''`           | Two-way bindable. The open trigger's `value`, or `''` when none.                                                                                                                                    |
+| `orientation` | `'horizontal'` | `'horizontal' \| 'vertical'`. Drives the trigger-row arrow keys (Left/Right horizontal, Up/Down vertical).                                                                                          |
+| `dir`         | `'ltr'`        | Writing direction. RTL inverts ArrowLeft / ArrowRight on the trigger row and inside the open menu.                                                                                                  |
+| `loop`        | `true`         | When `true`, trigger-row navigation and cross-menu nav wrap at the ends.                                                                                                                            |
+| `disabled`    | `false`        | When `true`, every trigger interaction is a no-op.                                                                                                                                                  |
+| `dismissible` | `true`         | When `false`, the open menu ignores Escape, outside interaction, and pointer-leave — it stays pinned open until `value` is flipped (consumer write, trigger / item interaction, or cross-menu nav). |
+| `closeDelay`  | `150`          | ms before the open menu closes after the pointer leaves the bar (and any open menu). Defaults from `provideForMenubarDefaults`.                                                                     |
+| `ariaLabel`   | `null`         | Accessible name for the menubar (`<div forMenubar aria-label="Main">` works too).                                                                                                                   |
+
+## Inputs (`ForMenubarTrigger`)
+
+| API                                                                                                                                       | Default                | Description                                                                                                                    |
+| ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `value`                                                                                                                                   | required               | Identifier for the trigger. The menubar's `value` model holds this when the menu is open.                                      |
+| `disabled`                                                                                                                                | `false`                | Per-trigger disabled, in addition to the menubar's `disabled`.                                                                 |
+| `side` / `align` / `sideOffset` / `alignOffset` / `avoidCollisions` / `collisionPadding` / `arrowPadding` / `sticky` / `hideWhenDetached` | (floating-ui defaults) | Forwarded to the multiplexed `[forMenuContent]` when this trigger's menu is the one open. Same surface as `[forDropdownMenu]`. |
+| `ariaLabel`                                                                                                                               | `null`                 | Manual `aria-label` on `[forMenuContent]` if the trigger isn't a meaningful name.                                              |
+
+## Trigger keyboard
+
+| Key                         | Behavior                                                                                    |
+| --------------------------- | ------------------------------------------------------------------------------------------- |
+| `Click` / `Enter` / `Space` | Toggle this trigger's menu. On open, focus moves to the first enabled item.                 |
+| `ArrowDown`                 | Open and focus the first enabled item.                                                      |
+| `ArrowUp`                   | Open and focus the last enabled item.                                                       |
+| `ArrowLeft` / `ArrowRight`  | Move focus to the previous / next enabled trigger. RTL inverts.                             |
+| `Home` / `End`              | Focus the first / last enabled trigger.                                                     |
+| `Typeahead`                 | Printable keys focus the first sibling trigger whose label starts with the buffered string. |
+
+## In-menu keyboard
+
+Inside an open menu, the standard `[forMenuContent]` keyboard applies — see [`menu/README.md`](../menu/README.md). The menubar adds:
+
+| Key                                                               | Behavior                                                                                                |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `ArrowLeft` / `ArrowRight` (on a top-level item, no submenu open) | Close the current menu and open the previous / next sibling menu, focusing its first item. RTL inverts. |
+| `Escape`                                                          | Close the menu and return focus to its trigger.                                                         |
+| `Tab` / `Shift+Tab`                                               | Close the menu and return focus to its trigger; the natural tab sequence then exits the menubar.        |
+
+Submenus opened from a top-level menu work as in `[forDropdownMenu]` — Escape collapses one level at a time, the open-key opens, the close-key collapses upward. When the submenu's parent is the top of a menubar, the close-key collapses the parent and switches to the previous sibling menu.
+
+## Styling
+
+forty-cdk ships no styles. Add your own class to each piece — the `for*` selectors are the behavior API, not a styling contract (see [Styling forty-cdk](../../../../../docs/styling.md)). Key your CSS off the reflected `data-*` attributes below.
+
+### Data attributes
+
+| Piece                 | Attribute          | Values                     |
+| --------------------- | ------------------ | -------------------------- |
+| `[forMenubar]`        | `data-state`       | `open` \| `closed`         |
+| `[forMenubar]`        | `data-orientation` | `horizontal` \| `vertical` |
+| `[forMenubar]`        | `data-disabled`    | present \| absent          |
+| `[forMenubarTrigger]` | `data-state`       | `open` \| `closed`         |
+| `[forMenubarTrigger]` | `data-orientation` | `horizontal` \| `vertical` |
+| `[forMenubarTrigger]` | `data-disabled`    | present \| absent          |
+
+> Each trigger's menu surface is the shared `[forMenuContent]` (from [`menu/`](../menu/README.md)), which **portals to `document.body`**. Style it with global CSS or a class — scoped/`:host` styles won't reach it. The portaled content also exposes the shared positioner custom properties (`--for-anchor-width` / `-height`, `--for-available-width` / `-height`, `--for-content-transform-origin`); see [Styling floating content](../../../../../docs/styling-floating-content.md) for the full list and how to use them.
+
+```css
+.menubar-trigger[data-state='open'] {
+  background: var(--accent);
+}
+
+.menubar-trigger[data-disabled] {
+  opacity: 0.5;
+}
+```
+
+## Behavior notes
+
+- **One open at a time.** Opening trigger `B` while `A` is open implicitly closes `A` and opens `B` with its first item focused.
+- **First open is intentional, subsequent are hover.** While no menu is open, hovering a trigger does _not_ auto-open, and keyboard focus alone never opens a menu. After the user opens any menu via click / keyboard, hovering a sibling trigger opens it instantly (no delay).
+- **Hover-leave dismisses.** Once a menu is open, moving the pointer off the bar (and away from the open menu) closes it after `closeDelay` (default `150`ms). Re-entering the bar, a trigger, or the open menu before the delay elapses cancels the pending close, so travelling from a trigger down into its menu keeps it open. Touch / pen pointers don't trigger this — they dismiss by tapping outside. Set `[dismissible]="false"` to pin the menu open regardless.
+- **Dismissal.** Escape, an outside pointer interaction, and pointer-leave all close the open menu when `dismissible` is `true` (default). `[dismissible]="false"` suppresses all three.
+- **Roving tabindex.** Only one trigger is in the tab sequence at a time — the open trigger, the most-recently-focused trigger, or the first enabled one when nothing's focused.
+- **Mount equals open.** Each menu's `[forMenuContent]` is wrapped in `@if (value() === '<id>')`, so `animate.enter` / `animate.leave` fire on mount / unmount. The directive does not toggle `[hidden]`.
+- **Disabled triggers stay focusable** (per APG) — they still reflect `data-disabled=""` and `aria-disabled="true"` and are skipped by ArrowLeft / ArrowRight, typeahead, and cross-menu nav.

package/meter/README.md

@@ -0,0 +1,128 @@
+# Meter
+
+Headless implementation of the [WAI-ARIA Meter pattern](https://www.w3.org/WAI/ARIA/apg/patterns/meter/), mirroring the HTML5 `<meter>` element.
+
+A meter represents a **measurement** within a known range — battery, disk space, score, queue depth — _not_ progress on a task. Use [Progress](../progress) for the latter.
+
+## Pieces
+
+| Class               | Selector              | Role                                                                                   |
+| ------------------- | --------------------- | -------------------------------------------------------------------------------------- |
+| `ForMeter`          | `[forMeter]`          | Root. Reflects `role="meter"`, ARIA value attributes, and the computed `data-quality`. |
+| `ForMeterIndicator` | `[forMeterIndicator]` | Visual fill. Reflects `data-quality`, `data-percentage`, and `--for-meter-percentage`. |
+
+## Inputs / models
+
+| API             | Type                                       | Description                                                                                           |
+| --------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
+| `value`         | `model<number>`                            | Two-way bindable. Clamped to `[min, max]` for ARIA / data-\* output; the model retains the raw write. |
+| `min`           | `input<number>`                            | Lower bound. Default `0`.                                                                             |
+| `max`           | `input<number>`                            | Upper bound. Default `100`.                                                                           |
+| `low`           | `input<number \| null>`                    | Lower boundary of the "comfortable" range. Default `null` (= `min`).                                  |
+| `high`          | `input<number \| null>`                    | Upper boundary of the "comfortable" range. Default `null` (= `max`).                                  |
+| `optimum`       | `input<number \| null>`                    | Ideal point. Default `null` (= midpoint). Drives the quality classification.                          |
+| `getValueLabel` | `input<((v, min, max) => string) \| null>` | Override for `aria-valuetext`.                                                                        |
+
+## Quality algorithm
+
+The `data-quality` reflection follows the HTML5 spec:
+
+| Optimum sits in | `value` in            | Quality          |
+| --------------- | --------------------- | ---------------- |
+| middle          | `[low, high]`         | `optimum`        |
+| middle          | outside `[low, high]` | `sub-optimum`    |
+| below `low`     | below `low`           | `optimum`        |
+| below `low`     | `[low, high]`         | `sub-optimum`    |
+| below `low`     | above `high`          | `even-less-good` |
+| above `high`    | above `high`          | `optimum`        |
+| above `high`    | `[low, high]`         | `sub-optimum`    |
+| above `high`    | below `low`           | `even-less-good` |
+
+## Usage
+
+```ts
+import { Component, signal } from '@angular/core';
+import { ForMeter, ForMeterIndicator } from 'forty-cdk/meter';
+
+@Component({
+  selector: 'demo-disk',
+  imports: [ForMeter, ForMeterIndicator],
+  template: `
+    <label for="disk">Disk usage</label>
+    <div id="disk" forMeter class="meter" [value]="used()" [low]="20" [high]="80" [optimum]="40">
+      <div forMeterIndicator class="meter-indicator"></div>
+    </div>
+    <output>{{ used() }}%</output>
+  `,
+  styles: [
+    `
+      .meter {
+        position: relative;
+        height: 8px;
+        width: 200px;
+        background: #f1f1f1;
+        border-radius: 4px;
+        overflow: hidden;
+      }
+      .meter-indicator {
+        height: 100%;
+        width: var(--for-meter-percentage, 0%);
+        transition: width 200ms;
+      }
+      .meter-indicator[data-quality='optimum'] {
+        background: #16a34a;
+      }
+      .meter-indicator[data-quality='sub-optimum'] {
+        background: #ca8a04;
+      }
+      .meter-indicator[data-quality='even-less-good'] {
+        background: #dc2626;
+      }
+    `,
+  ],
+})
+export class DemoDisk {
+  readonly used = signal(72);
+}
+```
+
+## Styling
+
+forty-cdk ships no styles. Add your own class to each piece — the `for*` selectors are the behavior API, not a styling contract (see [Styling forty-cdk](../../../../../docs/styling.md)). Key your CSS off the reflected `data-*` attributes below.
+
+### Data attributes
+
+| Piece                 | Attribute         | Values                                                 |
+| --------------------- | ----------------- | ------------------------------------------------------ |
+| `[forMeter]`          | `data-quality`    | `optimum` &#124; `sub-optimum` &#124; `even-less-good` |
+| `[forMeter]`          | `data-value`      | current value, clamped to `[min, max]`                 |
+| `[forMeter]`          | `data-min`        | lower bound                                            |
+| `[forMeter]`          | `data-max`        | upper bound                                            |
+| `[forMeter]`          | `data-percentage` | `value` as a number in `0`–`100`                       |
+| `[forMeterIndicator]` | `data-quality`    | `optimum` &#124; `sub-optimum` &#124; `even-less-good` |
+| `[forMeterIndicator]` | `data-value`      | current value, clamped to `[min, max]`                 |
+| `[forMeterIndicator]` | `data-min`        | lower bound                                            |
+| `[forMeterIndicator]` | `data-max`        | upper bound                                            |
+| `[forMeterIndicator]` | `data-percentage` | `value` as a number in `0`–`100`                       |
+
+### CSS custom properties
+
+| Property                 | Meaning                                                                                                                       |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| `--for-meter-percentage` | `value` as a CSS percentage of `[min, max]` (`0%`–`100%`), set on `[forMeterIndicator]`. Drive `width` / `transform` from it. |
+
+```css
+.meter-indicator {
+  width: var(--for-meter-percentage, 0%);
+}
+.meter-indicator[data-quality='even-less-good'] {
+  background: #dc2626;
+}
+```
+
+## Accessibility notes
+
+- **`role="meter"`** announces the current value as a fraction of the range. Pair with a visible label and `aria-labelledby` (or `aria-label`) for context — "Disk usage 72 of 100".
+- **Always determinate.** Unlike `<progress>`, a meter must always have a known value. There is no indeterminate mode in HTML5 / ARIA.
+- **Don't use Meter as Progress.** Screen readers announce the two roles differently (and assistive guidance differs); pick the right primitive for the meaning.
+- **Quality is for CSS only.** `data-quality` is a styling hook; assistive tech reads `aria-valuenow` / `aria-valuetext`, not the quality bucket.

package/navigation-menu/README.md

@@ -0,0 +1,253 @@
+# NavigationMenu
+
+Headless implementation of the [WAI-ARIA Disclosure Navigation Menu pattern](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-navigation/) — a `<nav>` of disclosures, **not** an ARIA `menu`.
+
+Triggers are buttons with `aria-expanded` / `aria-controls`, content panels are landmarks with links, Tab moves through links, Escape closes and returns focus.
+
+## Pieces
+
+| Class                        | Selector                       | Role                                                                  |
+| ---------------------------- | ------------------------------ | --------------------------------------------------------------------- |
+| `ForNavigationMenu`          | `[forNavigationMenu]`          | Root. Owns open state, delays, dismiss layer.                         |
+| `ForNavigationMenuList`      | `[forNavigationMenuList]`      | Optional layout wrapper.                                              |
+| `ForNavigationMenuItem`      | `[forNavigationMenuItem]`      | Pairs one trigger with one content panel.                             |
+| `ForNavigationMenuTrigger`   | `[forNavigationMenuTrigger]`   | Button that toggles its panel.                                        |
+| `ForNavigationMenuContent`   | `[forNavigationMenuContent]`   | Panel mounted via `@if`. Carries `aria-labelledby`.                   |
+| `ForNavigationMenuLink`      | `[forNavigationMenuLink]`      | Decorative wrapper that reflects `aria-current` on active links.      |
+| `ForNavigationMenuIndicator` | `[forNavigationMenuIndicator]` | Optional follower (underline / pill) positioned via CSS custom props. |
+| `ForNavigationMenuViewport`  | `[forNavigationMenuViewport]`  | Optional shared surface for mega-menu animations.                     |
+
+## Inputs (root)
+
+| API                 | Type                                | Description                                                                                                                                               |
+| ------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`             | `model<string>`                     | Two-way bindable. Open item id, or `''`.                                                                                                                  |
+| `orientation`       | `input<'horizontal' \| 'vertical'>` | Default `'horizontal'`.                                                                                                                                   |
+| `dir`               | `input<WritingDirection>`           | RTL inverts ArrowLeft / ArrowRight.                                                                                                                       |
+| `loop`              | `input<boolean>`                    | Whether arrow nav wraps. Default `true`.                                                                                                                  |
+| `disabled`          | `input<boolean>`                    | Disables the whole menu.                                                                                                                                  |
+| `ariaLabel`         | `input<string \| null>`             | Reactive `aria-label` for the `<nav>`. Default `null` (and empty string) emits no attribute; prefer native `aria-labelledby` when a visible label exists. |
+| `delayDuration`     | `input<number>`                     | ms before hover/focus opens. Default `200`.                                                                                                               |
+| `closeDelay`        | `input<number>`                     | ms before pointer-leave closes. Default `150`.                                                                                                            |
+| `skipDelayDuration` | `input<number>`                     | ms after a peer closes during which the next open is instant. Default `300`.                                                                              |
+
+## Usage
+
+```ts
+import { Component, signal } from '@angular/core';
+import {
+  ForNavigationMenu,
+  ForNavigationMenuContent,
+  ForNavigationMenuIndicator,
+  ForNavigationMenuItem,
+  ForNavigationMenuLink,
+  ForNavigationMenuList,
+  ForNavigationMenuTrigger,
+} from 'forty-cdk/navigation-menu';
+
+@Component({
+  selector: 'demo-nav',
+  imports: [
+    ForNavigationMenu,
+    ForNavigationMenuList,
+    ForNavigationMenuItem,
+    ForNavigationMenuTrigger,
+    ForNavigationMenuContent,
+    ForNavigationMenuLink,
+    ForNavigationMenuIndicator,
+  ],
+  template: `
+    <nav forNavigationMenu aria-label="Main" [(value)]="open">
+      <ul forNavigationMenuList>
+        <li forNavigationMenuItem value="products">
+          <button forNavigationMenuTrigger class="navigation-menu-trigger">Products</button>
+          @if (open() === 'products') {
+            <div
+              forNavigationMenuContent
+              class="navigation-menu-content"
+              animate.enter="fade-in"
+              animate.leave="fade-out"
+            >
+              <a href="/p/web" forNavigationMenuLink>Web</a>
+              <a href="/p/mobile" forNavigationMenuLink active>Mobile</a>
+            </div>
+          }
+        </li>
+        <li forNavigationMenuItem value="company">
+          <button forNavigationMenuTrigger class="navigation-menu-trigger">Company</button>
+          @if (open() === 'company') {
+            <div forNavigationMenuContent class="navigation-menu-content">
+              <a href="/about" forNavigationMenuLink>About</a>
+              <a href="/jobs" forNavigationMenuLink>Careers</a>
+            </div>
+          }
+        </li>
+        <span forNavigationMenuIndicator class="navigation-menu-indicator"></span>
+      </ul>
+    </nav>
+  `,
+})
+export class DemoNav {
+  readonly open = signal('');
+}
+```
+
+## Styling
+
+forty-cdk ships no styles. Add your own class to each piece — the `for*` selectors are the behavior API, not a styling contract (see [Styling forty-cdk](../../../../../docs/styling.md)). Key your CSS off the reflected `data-*` attributes below.
+
+### Data attributes
+
+| Piece                          | Attribute          | Values                                               |
+| ------------------------------ | ------------------ | ---------------------------------------------------- |
+| `[forNavigationMenu]`          | `data-state`       | `open` \| `closed`                                   |
+| `[forNavigationMenu]`          | `data-orientation` | `horizontal` \| `vertical`                           |
+| `[forNavigationMenu]`          | `data-disabled`    | present \| absent                                    |
+| `[forNavigationMenuList]`      | `data-orientation` | `horizontal` \| `vertical`                           |
+| `[forNavigationMenuItem]`      | `data-state`       | `open` \| `closed`                                   |
+| `[forNavigationMenuItem]`      | `data-disabled`    | present \| absent                                    |
+| `[forNavigationMenuTrigger]`   | `data-state`       | `open` \| `closed`                                   |
+| `[forNavigationMenuTrigger]`   | `data-disabled`    | present \| absent                                    |
+| `[forNavigationMenuContent]`   | `data-state`       | `open` \| `closed`                                   |
+| `[forNavigationMenuContent]`   | `data-motion`      | `from-start` \| `from-end` \| `to-start` \| `to-end` |
+| `[forNavigationMenuLink]`      | `data-active`      | present \| absent                                    |
+| `[forNavigationMenuIndicator]` | `data-state`       | `visible` \| `hidden`                                |
+| `[forNavigationMenuIndicator]` | `data-orientation` | `horizontal` \| `vertical`                           |
+| `[forNavigationMenuViewport]`  | `data-state`       | `open` \| `closed`                                   |
+| `[forNavigationMenuViewport]`  | `data-orientation` | `horizontal` \| `vertical`                           |
+
+`data-motion` is absent on first open and last close, where there is no peer trigger to compare against.
+
+### CSS custom properties
+
+`[forNavigationMenuIndicator]` exposes the active trigger's geometry (relative to `[forNavigationMenuList]`) so the indicator visual can be driven entirely from CSS. The optional shared `[forNavigationMenuViewport]` exposes the active panel's natural size so consumers can transition `width` / `height` between trigger groups.
+
+| Property                                 | Meaning                                                |
+| ---------------------------------------- | ------------------------------------------------------ |
+| `--for-navigation-menu-indicator-x`      | Horizontal offset of the active trigger (px).          |
+| `--for-navigation-menu-indicator-y`      | Vertical offset of the active trigger (px).            |
+| `--for-navigation-menu-indicator-width`  | Active trigger width (px).                             |
+| `--for-navigation-menu-indicator-height` | Active trigger height (px).                            |
+| `--for-navigation-menu-viewport-width`   | Active content's natural width (px), on the Viewport.  |
+| `--for-navigation-menu-viewport-height`  | Active content's natural height (px), on the Viewport. |
+
+```css
+.navigation-menu-trigger svg {
+  transition: transform 150ms;
+}
+.navigation-menu-trigger[data-state='open'] svg {
+  transform: rotate(180deg);
+}
+
+.navigation-menu-indicator {
+  transform: translateX(var(--for-navigation-menu-indicator-x));
+  width: var(--for-navigation-menu-indicator-width);
+  transition:
+    transform 200ms,
+    width 200ms;
+}
+.navigation-menu-indicator[data-state='hidden'] {
+  opacity: 0;
+}
+```
+
+## Keyboard
+
+| Key                                            | Behavior                                                                   |
+| ---------------------------------------------- | -------------------------------------------------------------------------- |
+| Tab                                            | Moves into the trigger row. Inside an open panel, moves through its links. |
+| Enter / Space                                  | Toggles the focused trigger.                                               |
+| ArrowDown (horizontal) / ArrowRight (vertical) | Opens the focused trigger.                                                 |
+| ArrowLeft / ArrowRight (horizontal)            | Moves focus across triggers.                                               |
+| ArrowUp / ArrowDown (vertical)                 | Moves focus across triggers.                                               |
+| Home / End                                     | Jump to first / last enabled trigger.                                      |
+| Escape                                         | Closes and returns focus to the trigger.                                   |
+
+## Accessibility notes
+
+- **Not an ARIA menu.** This implements the _disclosure_ pattern: `<nav>` + buttons + landmark panels. ARIA `role="menu"` is for application menus where Tab leaves but arrows do everything. Site navigation expects Tab to move through links, which is what this primitive supports.
+- **Focus alone does not open.** A trigger opens on hover, click, Enter / Space, or the cross-axis arrow (ArrowDown horizontal / ArrowRight vertical) — never on plain focus. This matches the APG disclosure-navigation pattern: Tabbing across the trigger row does not auto-expand panels, and the return-focus after Escape cannot synchronously re-open the panel that just closed.
+- **Trigger labels are mandatory.** Each `[forNavigationMenuTrigger]` needs visible text or an `aria-label`. The directive does not invent one.
+- **Content panels are mounted via `@if`.** The directive does not apply `[hidden]`; visibility is the consumer's call. Use `animate.enter` / `animate.leave` for transitions.
+- **Indicator follows the active trigger.** A `ResizeObserver` (browser-only) watches the active trigger and the surrounding list and re-measures only when the active trigger switches or one of those boxes resizes — reactive, not per-render polling. Consumers drive the visual via the `--for-navigation-menu-indicator-x|y|width|height` custom properties.
+- **`data-state` on the root.** The `[forNavigationMenu]` host reflects `data-state="open"` whenever any item is open and `"closed"` otherwise — same vocabulary as the trigger / content / item / indicator pieces, useful for top-level CSS hooks (e.g. dimming the rest of the page while the menu is open).
+- **Tab-out closes.** Per APG, moving focus past the last / before the first focusable inside the nav closes any open panel. The root listens for `focusout` and closes when `relatedTarget` falls outside the `<nav>`. Escape and outside pointerdown are already handled by the dismissable layer; this covers the keyboard-Tab case it can't see.
+
+## Mega-menu (shared `Viewport`)
+
+For Stripe / Vercel / Linear-style mega menus that share a single panel between trigger groups, drop a `[forNavigationMenuViewport]` inside the menu and let it host the active content. The Viewport is fully opt-in: with no Viewport in the markup the menu behaves exactly as the disclosure recipe above.
+
+When present, each `[forNavigationMenuContent]` re-parents its host into the Viewport on mount. The Viewport exposes the active panel's natural size as CSS custom properties so consumers can transition `width` / `height` between groups, and each Content reflects `data-motion` so consumers can author directional slide / fade animations:
+
+| Attribute / variable                     | Where            | Meaning                                                   |
+| ---------------------------------------- | ---------------- | --------------------------------------------------------- |
+| `data-state="open" \| "closed"`          | Viewport host    | Whether any content is currently mounted in the Viewport. |
+| `--for-navigation-menu-viewport-width`   | Viewport host    | Active content's natural width (px).                      |
+| `--for-navigation-menu-viewport-height`  | Viewport host    | Active content's natural height (px).                     |
+| `data-motion="from-start" \| "from-end"` | Entering Content | Side the previous trigger sat on, relative to this one.   |
+| `data-motion="to-start" \| "to-end"`     | Leaving Content  | Side the new trigger sits on, relative to this one.       |
+
+`from-start` / `to-start` map to the logical inline-start (left in LTR, right in RTL); writing the keyframes with logical CSS properties (e.g. `inset-inline-start`) makes the animation work in both directions automatically. `data-motion` is absent on first open and last close, where there is no peer trigger to compare against.
+
+```html
+<nav forNavigationMenu [(value)]="open" aria-label="Main">
+  <ul forNavigationMenuList>
+    <li forNavigationMenuItem value="products">
+      <button forNavigationMenuTrigger class="navigation-menu-trigger">Products</button>
+      @if (open() === 'products') {
+      <div forNavigationMenuContent class="navigation-menu-content">…</div>
+      }
+    </li>
+    <li forNavigationMenuItem value="solutions">
+      <button forNavigationMenuTrigger class="navigation-menu-trigger">Solutions</button>
+      @if (open() === 'solutions') {
+      <div forNavigationMenuContent class="navigation-menu-content">…</div>
+      }
+    </li>
+  </ul>
+
+  <!-- Single shared surface. Content panels re-parent into here on open. -->
+  <div forNavigationMenuViewport class="navigation-menu-viewport"></div>
+</nav>
+```
+
+```css
+.navigation-menu-viewport {
+  position: relative;
+  width: var(--for-navigation-menu-viewport-width);
+  height: var(--for-navigation-menu-viewport-height);
+  transition:
+    width 200ms,
+    height 200ms;
+}
+
+.navigation-menu-content {
+  position: absolute;
+  inset-inline-start: 0;
+  top: 0;
+}
+.navigation-menu-content[data-motion='from-start'] {
+  animation: slide-in-from-start 200ms;
+}
+.navigation-menu-content[data-motion='from-end'] {
+  animation: slide-in-from-end 200ms;
+}
+.navigation-menu-content[data-motion='to-start'] {
+  animation: slide-out-to-start 200ms;
+}
+.navigation-menu-content[data-motion='to-end'] {
+  animation: slide-out-to-end 200ms;
+}
+```
+
+The leaving content stays mounted as long as the consumer's `@if` keeps it (typically via `animate.leave`), so two panels can briefly overlap inside the Viewport and cross-fade or slide past each other.
+
+### Panel order is deterministic
+
+The Viewport owns panel ordering: each Content is inserted in its **trigger's document order**, never simply appended in mount order. During an overlapping A→B transition — where the leaving A is still mounted while B enters — the Viewport's child order always matches trigger order, so the panel whose trigger comes first in the DOM is always the first child, regardless of which panel mounted last. Author cross-fade / slide stacking against that order (paired with the `data-motion` hook) rather than against mount timing.
+
+Measurement always tracks the **active** panel. The Viewport's `--for-navigation-menu-viewport-width` / `--for-navigation-menu-viewport-height` reflect the entering panel as soon as it becomes active; a non-active panel kept mounted by `animate.leave` is intentionally no longer measured, so a leaving panel's size never drives the Viewport box mid-transition.
+
+## Limitations (v1)
+
+- Submenús anidados — not implemented; tracked separately.