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

package/docs/top-navigation.md

@@ -0,0 +1,138 @@
+<!-- index: ./index.md -->
+# top-navigation
+
+`data-ui="top-navigation"` · Application header with brand, search and account.
+
+## Import
+
+```ts
+import { SlTopNavigation, SlTopNavigationAccount, SlTopNavigationAction, SlTopNavigationActions, SlTopNavigationBrand, SlTopNavigationContext, SlTopNavigationCount, SlTopNavigationHelp, SlTopNavigationHome, SlTopNavigationItem, SlTopNavigationLink, SlTopNavigationList, SlTopNavigationMark, SlTopNavigationName, SlTopNavigationNav, SlTopNavigationNotifications, SlTopNavigationSearch, SlTopNavigationTrigger, provideTopNavigationDefaults } from '@slotted/angular/top-navigation';
+```
+
+Selector: `[slTopNavigation], [slTopNavigationBrand], [slTopNavigationHome], [slTopNavigationMark], [slTopNavigationName], [slTopNavigationContext], nav[slTopNavigationNav], ul[slTopNavigationList], li[slTopNavigationItem], a[slTopNavigationLink], button[slTopNavigationTrigger], [slTopNavigationSearch], [slTopNavigationActions], a[slTopNavigationHelp], button[slTopNavigationHelp], button[slTopNavigationNotifications], [slTopNavigationCount], button[slTopNavigationAccount], a[slTopNavigationAction], button[slTopNavigationAction]` · exportAs: `slTopNavigation, slTopNavigationNav, slTopNavigationList, slTopNavigationItem, slTopNavigationLink, slTopNavigationTrigger, slTopNavigationSearch, slTopNavigationActions, slTopNavigationHelp, slTopNavigationNotifications, slTopNavigationAccount, slTopNavigationAction, slTopNavigationMore`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<header slTopNavigation value="painel" skipTo="conteudo">
+  <div slTopNavigationBrand>
+    <a slTopNavigationHome routerLink="/">
+      <span slTopNavigationMark><ng-icon name="auroraMark" /></span>
+      <span slTopNavigationName>Aurora Logística</span>
+    </a>
+  </div>
+  <nav slTopNavigationNav>
+    <ul slTopNavigationList>
+      <li slTopNavigationItem value="painel" priority="high">
+        <a slTopNavigationLink routerLink="/painel">Painel</a>
+      </li>
+      <li slTopNavigationItem value="relatorios" priority="low">
+        <a slTopNavigationLink routerLink="/relatorios">Relatórios</a>
+      </li>
+    </ul>
+  </nav>
+  <div slTopNavigationSearch>
+    <div slTextField variant="subtle">
+      <input slTextFieldInput type="search" placeholder="Procurar cargas, clientes, rotas…" />
+    </div>
+  </div>
+  <div slTopNavigationActions>
+    <a slTopNavigationHelp routerLink="/ajuda"></a>
+    <button slTopNavigationNotifications><span slTopNavigationCount>3</span></button>
+    <button slTopNavigationAccount>
+      <span slAvatar size="xs"><span slAvatarFallback>AB</span></span>
+    </button>
+  </div>
+</header>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the header carrying slTopNavigation, or a div inside app-shell | yes |
+| `skip` | a, rendered by the root | no |
+| `brand` | div | yes |
+| `home` | a with an href, or a span without one | no |
+| `mark` | span | no |
+| `name` | span | no |
+| `context` | div | no |
+| `nav` | nav | no |
+| `list` | ul | no |
+| `item` | li | no |
+| `link` | a | no |
+| `trigger` | button | no |
+| `indicator` | span, rendered by the trigger | no |
+| `more` | button, rendered by the list | no |
+| `panel` | div, built by the nav | no |
+| `panel-list` | ul, built by the nav | no |
+| `search` | div | no |
+| `search-toggle` | button, rendered by the actions | no |
+| `search-close` | button, rendered by the search | no |
+| `actions` | div | no |
+| `help` | a with an href, or a button | no |
+| `notifications` | button | no |
+| `count` | span | no |
+| `account` | button | no |
+| `action` | a with an href, or a button | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `model<string \| null>` | null | slTopNavigation | The current destination’s value, two-way. A link that states current itself, or carries the router’s aria-current, still wins |
+| `moreOpen` | `model<boolean>` | false | slTopNavigation | Whether the panel is shown, two-way |
+| `searchOpen` | `model<boolean>` | false | slTopNavigation | Whether the search has taken the bar, below 600 pixels, two-way. Above 600 it has no effect |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | slTopNavigation, provideTopNavigationDefaults | The control height of everything in the bar, from the control scale |
+| `frame` | `boolean` | true | slTopNavigation, provideTopNavigationDefaults | Whether the root paints its own ground, rule and inset. Unstated, it does on its own and not inside app-shell, whose banner already paints |
+| `landmark` | `boolean` | true | slTopNavigation, provideTopNavigationDefaults | The intent the element carries: a header on its own, a div inside app-shell’s banner. The element is the consumer’s |
+| `skipTo` | `string` | — | slTopNavigation | The id of the element the skip link jumps to. Absent, no skip link is rendered |
+| `messages` | `Partial<TopNavigationMessages>` | — | slTopNavigation | Words laid over the language in force, key by key — navigation, more, moreCount, search, closeSearch, help, notifications, account, skip: the words on the controls that have no visible text |
+| `value` | `string` | — | slTopNavigationItem | The item’s identity: what value names it by and what collapseChange reports |
+| `priority` | `'high' \| 'medium' \| 'low'` | medium | slTopNavigationItem | Which step of the width folds the item: low under 1024 pixels, medium under 600, high under 480 |
+| `disabled` | `boolean` | false | slTopNavigationItem | The row and everything in it refuse interaction; the link keeps its href and its name |
+| `current` | `boolean` | — | slTopNavigationLink | Whether this is the current destination, stated on the row. Unstated, an aria-current the router wrote is read instead; both win over the root’s value |
+| `aria-label` | `string` | the family’s message | slTopNavigationNav, slTopNavigationHelp, slTopNavigationNotifications, slTopNavigationAccount | The name the consumer writes on the element, read before the family writes its own |
+| `the element` | `header, div, nav, ul, li, a, button, span` | — | every part | Every directive goes on the consumer’s own element, so routerLink, routerLinkActive, slMenuTriggerFor, slPopoverTrigger, native attributes and (click) live where they always do |
+| `exportAs` | `slTopNavigation, slTopNavigationItem, slTopNavigationLink, slTopNavigationTrigger, slTopNavigationSearch, slTopNavigationMore` | — | a template reference | The root instance carries focus(), focusSearch(), openMore(), closeMore(), the three models, collapsed() and folded(); an item its value, priority, collapsed and current signals |
+| `provideTopNavigationDefaults()` | `{ size, frame, landmark }` | — | a component or route’s providers | The decisions an application takes once, through the TOP_NAVIGATION_DEFAULTS token. A bar that states any of them itself still wins |
+| `injectTopNavigationDefaults()` | `() => TopNavigationDefaults` | — | inside an injection context | What a bar renders as here, before it states anything of its own |
+| `@container slotted-top-navigation` | `a container query in the consumer’s stylesheet` | — | anything placed in context, search or actions | The bar is a named query container, so a consumer’s own control answers the bar’s width — (inline-size < 600px) — without measuring anything |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `valueChangeRequest` | `ChangeRequest<string \| null>: value, previous, reason (pointer \| keyboard \| programmatic), source and cancel()` | Before the current destination moves, on a press of a link. Cancelling refuses; the navigation itself is the anchor’s. value itself is a model, so [(value)] follows. |
+| `moreOpenChangeRequest` | `ChangeRequest<boolean> with reason (pointer \| keyboard \| select \| escape \| outsidePress \| resize \| programmatic)` | Before the panel opens or closes: a press on more, a link pressed inside the panel, Escape, a press outside, the width widening until nothing is folded, or openMore()/closeMore() on the instance. moreOpen is a model. |
+| `searchOpenChangeRequest` | `ChangeRequest<boolean> with reason (pointer \| keyboard \| escape \| blur \| resize \| programmatic)` | Below 600 pixels: before the magnifier opens the field, and before Escape, the cross, focus leaving the field or the width widening past 600 closes it. Above, the value has no effect. searchOpen is a model. |
+| `collapseChange` | `readonly string[]: the values of the folded items in DOM order` | After the set of folded items changed: the bar crossed one of its three steps. A fact, not a request — the width decided it. |
+| `(click), (focus), (keydown) on every control` | `the element’s own events` | Whenever the a or button 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` |
+| `landmark` | `true`, `false` | `true` |
+| `frame` | `true`, `false` | `true` |
+| `priority` | `high`, `medium`, `low` | — |
+
+## Rules
+
+- The bar is the banner landmark — a header in the context of the body, with no role written — and its destinations are the navigation landmark, a nav named Navigation unless the consumer names it. Inside app-shell the consumer writes a div, because the shell’s banner is already the banner and two banners in one document is what the resolution prevents.
+- The destinations follow the WAI-ARIA APG’s Disclosure Navigation Menu example (w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-navigation/): nav > ul > li > a, so a reader hears a list of so many links, one of them aria-current="page". The Navigation Menubar example’s own caution — that menubar demands functionality a site’s navigation does not need — is why nothing here is a menubar, nothing writes tabindex and no arrow key moves focus: every control is a tab stop.
+- more is a button with aria-expanded and aria-controls pointing at the panel, and its name carries the count of what folded — More, 3, the moreCount message. The panel is built right after the nav, so Tab from more enters it, the way the disclosure pattern assumes; closed, it is visibility: hidden and its rows leave the tab sequence. Escape closes it and returns focus to more.
+- The folded destinations are the consumer’s own elements, moved into the panel and back, so a section keeps its panel and a link keeps its badge, its href and the router’s aria-current. Below 480 pixels the name is clipped rather than removed, so the home link keeps its name; help’s label is clipped in the bar and shown in the panel, so help has one name in both places.
+- Every icon-only control — the magnifier, the cross, help, the bell, the account, more — carries an accessible name from the family’s messages or the consumer’s aria-label, read with HostAttributeToken before the family writes its own, and repeats it in a tooltip on hover and on visible focus. The count stands inside the bell’s button, so a reader hears Notifications, 3 without the family composing a string.
+- Below 600 pixels the open search moves focus into the field and the closed search returns it to the magnifier, unless focus already went somewhere else — which is what closed it. A disabled destination is aria-disabled with its href kept: perceivable, focusable, refused on press. The item carries data-disabled and never aria-disabled, which ARIA 1.2 deprecates on listitem.
+
+## Tokens
+
+`--slotted-app-shell-row-font-size`, `--slotted-app-shell-row-height`, `--slotted-app-shell-row-inset`, `--slotted-app-shell-row-line-height`, `--slotted-border-subtle`, `--slotted-border-width-thick`, `--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-lg`, `--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-size-lg`, `--slotted-font-size-md`, `--slotted-font-size-sm`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-font-weight-semibold`, `--slotted-line-height-md`, `--slotted-line-height-sm`, `--slotted-line-height-xs`, `--slotted-radius-full`, `--slotted-radius-lg`, `--slotted-shadow-md`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-surface`, `--slotted-surface-raised`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-on-solid`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-top-navigation-active-background`, `--slotted-top-navigation-block-size`, `--slotted-top-navigation-border-color`, `--slotted-top-navigation-color`, `--slotted-top-navigation-count-background`, `--slotted-top-navigation-count-color`, `--slotted-top-navigation-current-background`, `--slotted-top-navigation-current-color`, `--slotted-top-navigation-current-edge`, `--slotted-top-navigation-hover-background`, `--slotted-top-navigation-inset`, `--slotted-top-navigation-muted-color`, `--slotted-top-navigation-name-font-size`, `--slotted-top-navigation-name-max`, `--slotted-top-navigation-panel-radius`, `--slotted-top-navigation-panel-shadow`, `--slotted-top-navigation-panel-size`, `--slotted-top-navigation-panel-surface`, `--slotted-top-navigation-radius`, `--slotted-top-navigation-search-min`, `--slotted-top-navigation-search-size`, `--slotted-top-navigation-surface`, `--slotted-z-index-popover`
+
+## Examples
+
+See [top-navigation.examples.md](./top-navigation.examples.md).