@slotted/angular 0.0.0-stage → 0.1.0-beta.1

package/docs/navigation-menu.md

@@ -0,0 +1,329 @@
+<!-- index: ./index.md -->
+# navigation-menu
+
+`data-ui="navigation-menu"` · Site sections that open panels of links.
+
+## Import
+
+```ts
+import { SlNavigationMenu, SlNavigationMenuContent, SlNavigationMenuDescription, SlNavigationMenuFooter, SlNavigationMenuGroup, SlNavigationMenuGroupLabel, SlNavigationMenuIcon, SlNavigationMenuItem, SlNavigationMenuLabel, SlNavigationMenuLink, SlNavigationMenuLinks, SlNavigationMenuList, SlNavigationMenuTrigger, provideNavigationMenuDefaults } from '@slotted/angular/navigation-menu';
+```
+
+Selector: `[slNavigationMenu], ul[slNavigationMenuList], li[slNavigationMenuItem], button[slNavigationMenuTrigger], [slNavigationMenuContent], a[slNavigationMenuLink], ul[slNavigationMenuLinks], [slNavigationMenuGroup], [slNavigationMenuGroupLabel], [slNavigationMenuIcon], [slNavigationMenuLabel], [slNavigationMenuDescription], [slNavigationMenuFooter]` · exportAs: `slNavigationMenu, slNavigationMenuItem, slNavigationMenuTrigger, slNavigationMenuContent, slNavigationMenuLink`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<nav slNavigationMenu aria-label="Main">
+  <ul slNavigationMenuList>
+    <li slNavigationMenuItem value="products">
+      <button slNavigationMenuTrigger>Products</button>
+      <div slNavigationMenuContent>…</div>
+    </li>
+    <li slNavigationMenuItem value="docs">
+      <a slNavigationMenuLink routerLink="/docs">Documentation</a>
+    </li>
+  </ul>
+</nav>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the nav carrying slNavigationMenu, or a div inside a panel | yes |
+| `list` | ul | yes |
+| `item` | li | yes |
+| `trigger` | button | no |
+| `indicator` | span | no |
+| `link` | the a carrying slNavigationMenuLink | no |
+| `content` | div | no |
+| `links` | ul | no |
+| `group` | div | no |
+| `group-label` | div | no |
+| `icon` | span | no |
+| `label` | span | no |
+| `description` | span | no |
+| `footer` | div | no |
+| `viewport` | div | yes |
+| `arrow` | span | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `model<string \| null>` | null | slNavigationMenu | The open section’s value, two-way; null is none |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | slNavigationMenu, provideNavigationMenuDefaults | The control step of a trigger and of a top-level link |
+| `orientation` | `'horizontal' \| 'vertical'` | horizontal | slNavigationMenu | A row under which panels open, or a column beside which they open. A nested menu is vertical unless it says otherwise |
+| `openDelay` | `number` | 200 | slNavigationMenu, provideNavigationMenuDefaults | Milliseconds a pointer rests on a trigger before its section opens. With a section open, another one opens at once |
+| `closeDelay` | `number` | 300 | slNavigationMenu, provideNavigationMenuDefaults | Milliseconds a pointer leaving the root waits before the section closes; a return cancels it |
+| `closeOnSelect` | `boolean` | true | slNavigationMenu, provideNavigationMenuDefaults, slNavigationMenuLink | Following a link inside a panel closes every level. A link’s own value wins |
+| `arrow` | `boolean` | false | slNavigationMenu, provideNavigationMenuDefaults | Draws the mark on the surface’s edge that points at the open trigger |
+| `messages` | `Partial<NavigationMenuMessages>` | — | slNavigationMenu | Words laid over the language in force: the landmark’s name when the consumer gives no aria-label (navigation) |
+| `value` | `string` | — | slNavigationMenuItem | The item’s identity: what the root’s value names it by. Reaches the DOM as data-value |
+| `disabled` | `boolean` | false | slNavigationMenuItem, slNavigationMenuLink | The section never opens and its trigger takes the native attribute; a link keeps its href and refuses the press |
+| `columns` | `1 \| 2 \| 3` | 1 | slNavigationMenuContent | How many columns of links or groups the panel lays out; the panel’s width follows |
+| `current` | `boolean` | — | slNavigationMenuLink | This link is the page the reader is on. Unstated, an aria-current="page" that routerLinkActive wrote is read |
+| `the element` | `nav, div, ul, li, button, a, span` | — | every part | Every directive goes on the consumer’s own element, so routerLink, routerLinkActive, native attributes and (click) live where they always do. The trigger projects the consumer’s words and adds the chevron |
+| `exportAs` | `slNavigationMenu, slNavigationMenuItem, slNavigationMenuTrigger, slNavigationMenuContent, slNavigationMenuLink` | — | a template reference | The root instance carries open(value), close(), focus(value?) and the value model; an item its value and open signal |
+| `provideNavigationMenuDefaults()` | `{ size, openDelay, closeDelay, closeOnSelect, arrow }` | — | a component or route’s providers | The decisions an application takes once, through the NAVIGATION_MENU_DEFAULTS token. A menu that states any of them itself still wins |
+| `injectNavigationMenuDefaults()` | `() => NavigationMenuDefaults` | — | inside an injection context | What a menu renders as here, before it states anything of its own |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `valueChangeRequest` | `ChangeRequest<string \| null>: value, previous, reason (pointer \| keyboard \| escape \| outsidePress \| blur \| select \| programmatic), source and cancel()` | Before the open section moves: a press or a resting pointer on a trigger, a pointer leaving the root, Escape, a press outside, focus leaving the root, a panel link followed, or open()/close() on the instance. Cancelling keeps the section, and [(value)] stays where it was. |
+| `(click), (pointerenter) on a trigger; (click) on a link` | `the element’s own events` | Whenever the element fires them, on the consumer’s own element. preventDefault() in (click) refuses the family’s part. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `orientation` | `horizontal`, `vertical` | `horizontal` |
+| `columns` | `1`, `2`, `3` | — |
+| `arrow` | `true`, `false` | `false` |
+
+## Rules
+
+- The pattern is the WAI-ARIA APG’s Disclosure Navigation Menu (w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-navigation/), and no menu, menubar or menuitem role is written: the example’s own note refuses them for a site’s navigation. The DOM is nav > ul > li > (button + div) and (a), so a reader hears a navigation landmark, a list of so many items, a button that is collapsed or expanded, and links.
+- Each panel follows its trigger in the DOM and is hidden while closed, so Tab reaches its links straight after the trigger — the order the pattern assumes — with no sentinel elements and no tabindex written anywhere. The arrow keys, Home and End are the pattern’s optional shortcut over that order, not a replacement for it.
+- Escape closes the open section and returns focus to its trigger; focus leaving the root, a press outside it and a followed link close it too, each with its own reason so an application can tell them apart.
+- The current page is aria-current="page" on its link and nowhere else; routerLinkActive with ariaCurrentWhenActive writes it and the family reads it. The trigger of the section holding it carries data-current for the stylesheet and no ARIA.
+- A disabled link is aria-disabled with its href kept: perceivable, focusable, and refused on press. A disabled section’s trigger takes the native attribute. The item carries data-disabled and never aria-disabled, which ARIA 1.2 deprecates on listitem.
+- Hover never decides anything a press cannot: a touch never opens by hover, and every section opens by its button. Identifiers come from an application-scoped factory, so a server response and the first client render agree.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-line-height`, `--slotted-control-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-control-radius`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-current-edge`, `--slotted-disabled-foreground`, `--slotted-duration-instant`, `--slotted-duration-medium`, `--slotted-duration-short`, `--slotted-easing-enter`, `--slotted-easing-exit`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-weight-medium`, `--slotted-font-weight-regular`, `--slotted-font-weight-semibold`, `--slotted-line-height-md`, `--slotted-line-height-sm`, `--slotted-navigation-menu-active-background`, `--slotted-navigation-menu-border-color`, `--slotted-navigation-menu-color`, `--slotted-navigation-menu-column-size`, `--slotted-navigation-menu-current-background`, `--slotted-navigation-menu-current-color`, `--slotted-navigation-menu-current-edge`, `--slotted-navigation-menu-hover-background`, `--slotted-navigation-menu-muted-color`, `--slotted-navigation-menu-nested-list-size`, `--slotted-navigation-menu-offset`, `--slotted-navigation-menu-radius`, `--slotted-navigation-menu-shadow`, `--slotted-navigation-menu-surface`, `--slotted-navigation-menu-viewport-radius`, `--slotted-radius-lg`, `--slotted-radius-xs`, `--slotted-shadow-md`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-6`, `--slotted-surface-raised`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-z-index-popover`
+
+## Examples
+
+### Anatomy
+
+Every part, each labelled by its own name: a trigger and its panel in one item, a top-level link beside it, a group with its label, a rich link with icon, label and description, the footer, and the surface with its arrow.
+
+Excerpt — not a complete module
+
+```html
+<nav slNavigationMenu arrow [value]="'section'">
+  <ul slNavigationMenuList>
+    <li slNavigationMenuItem value="section">
+      <button slNavigationMenuTrigger>trigger</button>
+      <div slNavigationMenuContent columns="2">
+        <div slNavigationMenuGroup>
+          <div slNavigationMenuGroupLabel>group-label</div>
+          <ul slNavigationMenuLinks>
+            <li>
+              <a slNavigationMenuLink href="/a"
+                ><span slNavigationMenuIcon>…</span><span slNavigationMenuLabel>label</span
+                ><span slNavigationMenuDescription>description</span></a
+              >
+            </li>
+          </ul>
+        </div>
+        <div slNavigationMenuFooter>footer</div>
+      </div>
+    </li>
+    <li slNavigationMenuItem value="link"><a slNavigationMenuLink href="/link">link</a></li>
+  </ul>
+</nav>
+```
+
+### A panel of plain links
+
+The shortest panel: one column of words at the control’s height. Its first letter starts in the column the trigger’s label starts in, because the surface opens at the trigger and the insets add up to the control’s.
+
+Excerpt — not a complete module
+
+```html
+<li slNavigationMenuItem value="company">
+  <button slNavigationMenuTrigger>Company</button>
+  <div slNavigationMenuContent>
+    <ul slNavigationMenuLinks>
+      <li><a slNavigationMenuLink routerLink="/about">About us</a></li>
+      <li><a slNavigationMenuLink routerLink="/careers">Careers</a></li>
+    </ul>
+  </div>
+</li>
+```
+
+### Rich links in two columns
+
+A mark, a title and two lines of description per destination, in columns="2". The mark sits on the title’s letters, not in the middle of its line; a description longer than two lines is cut to the eye and read whole.
+
+Excerpt — not a complete module
+
+```html
+<div slNavigationMenuContent columns="2">
+  <ul slNavigationMenuLinks>
+    <li>
+      <a slNavigationMenuLink routerLink="/warehouse">
+        <span slNavigationMenuIcon><ng-icon name="lucideWarehouse" /></span>
+        <span slNavigationMenuLabel>Warehouse</span>
+        <span slNavigationMenuDescription>Receipts, issues and stock by location.</span>
+      </a>
+    </li>
+  </ul>
+</div>
+```
+
+### Groups as columns
+
+Three titled groups in columns="3", each named by its label for a screen reader. Below 480 pixels of panel the groups stack two and one, and the lists inside fall to one column.
+
+Excerpt — not a complete module
+
+```html
+<div slNavigationMenuContent columns="3">
+  <div slNavigationMenuGroup>
+    <div slNavigationMenuGroupLabel>By industry</div>
+    <ul slNavigationMenuLinks>
+      <li><a slNavigationMenuLink routerLink="/retail">Retail</a></li>
+    </ul>
+  </div>
+</div>
+```
+
+### A footer with a call to action
+
+The panel’s last row under a rule that runs its full width; the words start in the links’ column and the action ends on their edge. The action is the consumer’s own Button.
+
+Excerpt — not a complete module
+
+```html
+<div slNavigationMenuFooter>
+  <span slText size="xs" tone="muted">New: demand forecast per warehouse.</span>
+  <a slButtonLink size="sm" routerLink="/products">See all</a>
+</div>
+```
+
+### Where the reader is
+
+current on a link — or the aria-current a router writes — is the page the reader is on, drawn on the accent ground. The section holding it takes the accent ink on its trigger, so it reads with every panel closed.
+
+Excerpt — not a complete module
+
+```html
+<a slNavigationMenuLink routerLink="/fleet" routerLinkActive ariaCurrentWhenActive="page">Fleet</a>
+```
+
+### A column of sections
+
+orientation="vertical": the panel opens at the column’s end, level with the trigger, and slides in along the line. In a column with no room at its end — a phone — it drops under the trigger and the chevron turns to point at it.
+
+Excerpt — not a complete module
+
+```html
+<nav slNavigationMenu orientation="vertical" arrow>…</nav>
+```
+
+### A second level in the same panel
+
+A slNavigationMenu inside a panel is a second level: a div, vertical, with no surface of its own. Its open section stands beside its list behind a rule that runs the full height, and following a link there closes every level.
+
+Excerpt — not a complete module
+
+```html
+<div slNavigationMenuContent columns="3">
+  <div slNavigationMenu [value]="'tools'">
+    <ul slNavigationMenuList>
+      <li slNavigationMenuItem value="tools">
+        <button slNavigationMenuTrigger>Tools</button>
+        <div slNavigationMenuContent columns="2">…</div>
+      </li>
+    </ul>
+  </div>
+</div>
+```
+
+### States
+
+Rest, an open section holding the pointer’s ground, a current section in the accent ink, a current link on the accent ground, a disabled section and a disabled link — readable, refused, and still in the tab order.
+
+Excerpt — not a complete module
+
+```html
+<li slNavigationMenuItem value="partners" disabled>
+  <button slNavigationMenuTrigger>Partners</button>
+  <div slNavigationMenuContent></div>
+</li>
+<li slNavigationMenuItem value="blog">
+  <a slNavigationMenuLink disabled href="/blog">Blog</a>
+</li>
+```
+
+### Sizes
+
+sm, md and lg read the control scale — 30, 34 and 38 pixels at comfortable — so the row stands at the height of the field and the button beside it in any density.
+
+Excerpt — not a complete module
+
+```html
+<nav slNavigationMenu size="sm">…</nav>
+```
+
+### Content the family did not choose
+
+A section named in eight words, a title that wraps to two lines, a description cut after two, a link with no mark and a reference with no spaces: the panel holds its columns and the surface holds the panel.
+
+Excerpt — not a complete module
+
+```html
+<span slNavigationMenuLabel>Replenishment planning between regional warehouses</span>
+```
+
+### The open section, owned by the application
+
+[(value)] and valueChangeRequest: every request carries its reason — pointer, keyboard, escape, outsidePress, blur, select or programmatic — and the application decides. The log under the row prints each one.
+
+Excerpt — not a complete module
+
+```html
+<nav slNavigationMenu [(value)]="section" (valueChangeRequest)="log($event.reason)">…</nav>
+```
+
+### Decided once for the application
+
+provideNavigationMenuDefaults() sets the hover delays, closeOnSelect, the size and the arrow for every menu under it; an instance that states any of them still wins. Here the menu opens fifty milliseconds after the pointer rests.
+
+Excerpt — not a complete module
+
+```html
+<!-- providers: [provideNavigationMenuDefaults({ arrow: true, openDelay: 50, size: 'sm' })] -->
+<nav slNavigationMenu>…</nav>
+```
+
+### In a site header, with a router
+
+The family in the context region of a slTopNavigation, beside the mark and the account; each link carries a routerLink with routerLinkActive, which writes aria-current, and the family reads it.
+
+Excerpt — not a complete module
+
+```html
+<a slNavigationMenuLink routerLink="/fleet" routerLinkActive ariaCurrentWhenActive="page">Fleet</a>
+```
+
+### Keyboard
+
+Tab reaches every top-level control and the links of an open panel after its trigger. Enter and Space toggle a section; ArrowLeft and ArrowRight walk the row; ArrowDown enters an open panel and ArrowUp from its first link returns to the trigger; Home and End reach the ends; Escape closes and lands on the trigger.
+
+Excerpt — not a complete module
+
+```html
+<nav slNavigationMenu #menu="slNavigationMenu">…</nav>
+<button type="button" (click)="menu.focus('products')">Focus Products</button>
+```
+
+### What a reader hears
+
+A navigation landmark named Main, a list of four items, “Products, button, collapsed”, and on Enter the panel’s links after it in the reading order. No menu role is written anywhere.
+
+Excerpt — not a complete module
+
+```html
+<nav slNavigationMenu aria-label="Main">…</nav>
+```