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

package/dist/docs/top-navigation.md

@@ -0,0 +1,145 @@
+<!-- index: ./index.md -->
+# top-navigation
+
+`data-ui="top-navigation"` · Application header with brand, search and account.
+
+## Import
+
+```tsx
+import { TopNavigation, TopNavigationAccount, TopNavigationAction, TopNavigationActions, TopNavigationBrand, TopNavigationContext, TopNavigationCount, TopNavigationDefaultsProvider, TopNavigationHelp, TopNavigationHome, TopNavigationItem, TopNavigationLink, TopNavigationList, TopNavigationMark, TopNavigationName, TopNavigationNav, TopNavigationNotifications, TopNavigationSearch, TopNavigationTrigger } from '@slotted/react';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<TopNavigation defaultValue="painel" skipTo="conteudo">
+  <TopNavigationBrand>
+    <TopNavigationHome href="/">
+      <TopNavigationMark>
+        <AuroraMark />
+      </TopNavigationMark>
+      <TopNavigationName>Aurora Logística</TopNavigationName>
+    </TopNavigationHome>
+  </TopNavigationBrand>
+  <TopNavigationNav>
+    <TopNavigationList>
+      <TopNavigationItem priority="high" value="painel">
+        <TopNavigationLink href="/painel">Painel</TopNavigationLink>
+      </TopNavigationItem>
+      <TopNavigationItem priority="low" value="relatorios">
+        <TopNavigationLink href="/relatorios">Relatórios</TopNavigationLink>
+      </TopNavigationItem>
+    </TopNavigationList>
+  </TopNavigationNav>
+  <TopNavigationSearch>
+    <TextField placeholder="Procurar cargas, clientes, rotas…" type="search" />
+  </TopNavigationSearch>
+  <TopNavigationActions>
+    <TopNavigationHelp href="/ajuda" />
+    <TopNavigationNotifications>
+      <TopNavigationCount>3</TopNavigationCount>
+    </TopNavigationNotifications>
+    <TopNavigationAccount>
+      <Avatar size="xs">AB</Avatar>
+    </TopNavigationAccount>
+  </TopNavigationActions>
+</TopNavigation>;
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | header, or a div inside app-shell, or the element render returns | yes |
+| `skip` | a | no |
+| `brand` | div | yes |
+| `home` | a with an href, or a span without one, or the element render returns | no |
+| `mark` | span | no |
+| `name` | span | no |
+| `context` | div | no |
+| `nav` | nav | no |
+| `list` | ul | no |
+| `item` | li | no |
+| `link` | a, or the element render returns | no |
+| `trigger` | button | no |
+| `indicator` | span | no |
+| `more` | button | no |
+| `panel` | div | no |
+| `panel-list` | ul | no |
+| `search` | div, or the element render returns | no |
+| `search-toggle` | button | no |
+| `search-close` | button | no |
+| `actions` | div | no |
+| `help` | a with an href, or a button, or the element render returns | no |
+| `notifications` | button, or the element render returns | no |
+| `count` | span | no |
+| `account` | button, or the element render returns | no |
+| `action` | a with an href, a button without one, or the element render returns | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string \| null` | — | TopNavigation | The current destination’s value. Present means the consumer owns it; a link that states current itself still wins |
+| `defaultValue` | `string \| null` | — | TopNavigation | The destination an uncontrolled bar starts on, read once |
+| `moreOpen` | `boolean` | — | TopNavigation | Whether the panel is shown. Present means the consumer owns it |
+| `defaultMoreOpen` | `boolean` | false | TopNavigation | Whether an uncontrolled bar starts with its panel open, read once |
+| `searchOpen` | `boolean` | — | TopNavigation | Whether the search has taken the bar, below 600 pixels. Present means the consumer owns it; above 600 it has no effect |
+| `defaultSearchOpen` | `boolean` | false | TopNavigation | Whether an uncontrolled bar starts with its search open, read once |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | TopNavigation, TopNavigationDefaultsProvider | The control height of everything in the bar, from the control scale |
+| `frame` | `boolean` | true | TopNavigation, TopNavigationDefaultsProvider | 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 | TopNavigation, TopNavigationDefaultsProvider | Whether the root is a header. Unstated, it is one on its own and a div inside app-shell’s banner, which is already the landmark |
+| `skipTo` | `string` | — | TopNavigation | The id of the element the skip link jumps to. Absent, no skip link is rendered |
+| `value, defaultValue, onValueChange` | `string \| null, (value, request) => void` | — | TopNavigationNav | The open section, on the nav part, which is a navigation-menu root: every way a section opens or closes asks with its reason. Not the current destination, which is the root’s value |
+| `arrow, openDelay, closeDelay, closeOnSelect` | `boolean, number, number, boolean` | false, 200, 300, true | TopNavigationNav | The navigation menu’s own axes, read from NavigationMenuDefaultsProvider when unstated |
+| `messages` | `Partial<TopNavigationMessages>` | — | TopNavigation | 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` | — | TopNavigationItem | The item’s identity: what value names it by and what onCollapseChange reports |
+| `priority` | `'high' \| 'medium' \| 'low'` | medium | TopNavigationItem | Which step of the width folds the item: low under 1024 pixels, medium under 600, high under 480 |
+| `disabled` | `boolean` | false | TopNavigationItem | The row and everything in it refuse interaction; the link keeps its href and its name |
+| `current` | `boolean` | — | TopNavigationLink | Whether this is the current destination, stated on the row — what a router’s link writes. It wins over the root’s value |
+| `href` | `string` | — | TopNavigationHome, TopNavigationLink, TopNavigationHelp | Where the control leads. Home without one is a span; help without one is a button for the consumer to wrap |
+| `aria-label` | `string` | the family’s message | TopNavigationHelp, TopNavigationNotifications, TopNavigationAccount, TopNavigationAction, TopNavigationNav | The name the consumer writes, kept over the family’s own |
+| `render` | `(props) => ReactNode` | — | root, brand, home, mark, name, context, nav, list, item, link, search, actions, help, notifications, count, account | Substitutes the element and hands it every attribute: a router’s link as the destination, a button as help. The trigger is fixed: the navigation menu wires it |
+| `ref` | `Ref<TopNavigationHandle> on the root, Ref<HTMLElement> on every part` | — | every part | The root’s handle carries focus(), focusSearch(), openMore(), closeMore() and the root element; every other ref reaches the element itself |
+| `useTopNavigation()` | `() => TopNavigationContextValue` | — | inside TopNavigation | What the parts read: the folded priorities, the collapsed values, the three values and the requests that move them, the panel and its list |
+| `useTopNavigationItem()` | `() => TopNavigationItemContextValue` | — | inside TopNavigationItem | What a row reads: its value, its priority, whether it is folded, current or disabled |
+| `TopNavigationDefaultsProvider` | `{ size, frame, landmark }` | — | a subtree | The decisions an application takes once. A bar that states any of them itself still wins |
+| `@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 |
+| --- | --- | --- |
+| `onValueChange(value, request)` | `the destination’s value, and a request with 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. |
+| `onMoreOpenChange(open, request)` | `whether the panel is shown, and a request 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 handle. |
+| `onSearchOpenChange(open, request)` | `whether the search has taken the bar, and a request 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. |
+| `onCollapseChange(values, reason)` | `the values of the folded items in DOM order, and the reason resize` | After the set of folded items changed: the bar crossed one of its three steps. A fact, not a request — the width decided it. |
+| `onClick, onFocus, onKeyDown on every control` | `the element’s own events` | Whenever the a or button fires them. The consumer’s handler runs first, and preventDefault() in onClick 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 root is 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 stands in the DOM 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 rendered into the panel, so a section keeps its panel and a link keeps its badge, its href and its 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, 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).