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

package/dist/docs/top-navigation.json

@@ -0,0 +1,695 @@
+{
+  "family": "top-navigation",
+  "ui": "top-navigation",
+  "binding": "react",
+  "catalog": {
+    "group": "Navigation",
+    "summary": "Application header with brand, search and account."
+  },
+  "axes": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "landmark": [
+      true,
+      false
+    ],
+    "frame": [
+      true,
+      false
+    ],
+    "priority": [
+      "high",
+      "medium",
+      "low"
+    ]
+  },
+  "members": {
+    "topNavigation": {
+      "nativeElement": "header",
+      "defaults": {
+        "size": "md",
+        "landmark": true,
+        "frame": true
+      },
+      "capabilities": [
+        "open",
+        "current",
+        "overflow",
+        "size",
+        "appearance",
+        "disabled",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "current",
+        "open",
+        "disabled"
+      ],
+      "parts": [
+        "root",
+        "skip",
+        "brand",
+        "home",
+        "mark",
+        "name",
+        "context",
+        "nav",
+        "list",
+        "item",
+        "link",
+        "trigger",
+        "indicator",
+        "more",
+        "panel",
+        "panel-list",
+        "search",
+        "search-toggle",
+        "search-close",
+        "actions",
+        "help",
+        "notifications",
+        "count",
+        "account",
+        "action"
+      ],
+      "defaultsReason": "Axis defaults only. The uncontrolled starting values are the state models' own uncontrolled names and exist in React alone: Angular ships one model() for each of moreOpen, searchOpen and value, which is both sides. priority is an item's axis and has no root default"
+    }
+  },
+  "docs": {
+    "topNavigation": {
+      "imports": {
+        "source": "import { TopNavigation, TopNavigationAccount, TopNavigationAction, TopNavigationActions, TopNavigationBrand, TopNavigationContext, TopNavigationCount, TopNavigationDefaultsProvider, TopNavigationHelp, TopNavigationHome, TopNavigationItem, TopNavigationLink, TopNavigationList, TopNavigationMark, TopNavigationName, TopNavigationNav, TopNavigationNotifications, TopNavigationSearch, TopNavigationTrigger } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "header, or a div inside app-shell, or the element render returns",
+          "required": true,
+          "purpose": "The bar, and the query container it answers: data-ui=\"top-navigation\", data-size, data-frame while it paints its own ground, data-search-open while the search has taken the bar. A header on its own — the banner landmark; inside the shell’s banner, which already is one, a div."
+        },
+        {
+          "part": "skip",
+          "element": "a",
+          "required": false,
+          "purpose": "The first focusable thing in the bar: a link to #skipTo, visible only while focused. Rendered when skipTo names a target; inside app-shell the shell already renders one per region."
+        },
+        {
+          "part": "brand",
+          "element": "div",
+          "required": true,
+          "purpose": "The start cluster: app-shell’s nav-toggle when the bar is in the shell, then home. It starts on the row inset the shell publishes, so the toggle and the mark stand over the marks in the column."
+        },
+        {
+          "part": "home",
+          "element": "a with an href, or a span without one, or the element render returns",
+          "required": false,
+          "purpose": "The mark and the name, linked to the start of the application. Below 480 pixels the name leaves the eye and not the DOM, so the link keeps its accessible name."
+        },
+        {
+          "part": "mark",
+          "element": "span",
+          "required": false,
+          "purpose": "The box the logo stands in: square, the height of the bar’s controls, aria-hidden."
+        },
+        {
+          "part": "name",
+          "element": "span",
+          "required": false,
+          "purpose": "The product’s name, one line, cut with an ellipsis at --slotted-top-navigation-name-max."
+        },
+        {
+          "part": "context",
+          "element": "div",
+          "required": false,
+          "purpose": "What the application is right now — the workspace, the store, the environment — as the consumer’s own content. It keeps its width in the bar; below 600 pixels it is presented at the top of the panel."
+        },
+        {
+          "part": "nav",
+          "element": "nav",
+          "required": false,
+          "purpose": "The navigation landmark, named by messages.navigation unless the consumer writes aria-label, and a navigation-menu root on the same element: data-ui=\"navigation-menu\", the shared surface after its list, and the open section’s value, request and delays on TopNavigationNav. The panel follows it in DOM order."
+        },
+        {
+          "part": "list",
+          "element": "ul",
+          "required": false,
+          "purpose": "The destinations, in the consumer’s order, with more in its own li at the end."
+        },
+        {
+          "part": "item",
+          "element": "li",
+          "required": false,
+          "purpose": "One destination or one section. Carries data-value, data-priority, data-collapsed while the width has folded it, data-current and data-disabled."
+        },
+        {
+          "part": "link",
+          "element": "a, or the element render returns",
+          "required": false,
+          "purpose": "The destination, with aria-current=\"page\" while current. aria-disabled and a refused press while disabled, the href kept."
+        },
+        {
+          "part": "trigger",
+          "element": "button",
+          "required": false,
+          "purpose": "A section that opens: the navigation-menu trigger of the NavigationMenuContent after it in the same item — aria-expanded, aria-controls, data-open, the chevron, a press and a resting pointer. Always a native button."
+        },
+        {
+          "part": "indicator",
+          "element": "span",
+          "required": false,
+          "purpose": "The trigger’s chevron, the chevron-down Glyph element, turned half a turn while open."
+        },
+        {
+          "part": "more",
+          "element": "button",
+          "required": false,
+          "purpose": "The disclosure button of the panel: aria-expanded, aria-controls, data-overflow with the count of what folded, data-current while the current destination is folded. Shown by the stylesheet as soon as anything folds."
+        },
+        {
+          "part": "panel",
+          "element": "div",
+          "required": false,
+          "purpose": "What did not fit, inside the root and right after the nav: the context, the panel-list, the help. Under the bar, full width below 480 pixels. Present in the DOM closed, out of sight and out of the tab order."
+        },
+        {
+          "part": "panel-list",
+          "element": "ul",
+          "required": false,
+          "purpose": "The list that receives the folded items — rendered into it while the panel is present, so a section keeps its panel, which opens in line under its trigger there, and a link keeps its badge."
+        },
+        {
+          "part": "search",
+          "element": "div, or the element render returns",
+          "required": false,
+          "purpose": "The search region, with the consumer’s TextField inside, standing at the start of the middle of the bar and growing to 28rem, never under 12rem: the first thing to give way when the bar is short of room. Below 600 pixels it exists only while searchOpen, and then takes the whole bar."
+        },
+        {
+          "part": "search-toggle",
+          "element": "button",
+          "required": false,
+          "purpose": "The magnifier that asks searchOpen to be true, rendered by Actions whenever the bar has a search and shown below 600 pixels while the search is closed."
+        },
+        {
+          "part": "search-close",
+          "element": "button",
+          "required": false,
+          "purpose": "The cross at the end of the open search below 600 pixels: the pointer’s way back."
+        },
+        {
+          "part": "actions",
+          "element": "div",
+          "required": false,
+          "purpose": "The end cluster, in the consumer’s order. Recommended: search, help, notifications, account — Carbon’s order, which a reader has learnt."
+        },
+        {
+          "part": "help",
+          "element": "a with an href, or a button, or the element render returns",
+          "required": false,
+          "purpose": "The question mark. Its children are its label, clipped in the bar and shown as a row in the panel below 480 pixels; the family’s message when there are none."
+        },
+        {
+          "part": "notifications",
+          "element": "button, or the element render returns",
+          "required": false,
+          "purpose": "The bell, with count in its corner. It never folds."
+        },
+        {
+          "part": "count",
+          "element": "span",
+          "required": false,
+          "purpose": "The number of what is waiting, drawn by the family over the bell’s top-end corner as tabular figures on an accent disc that becomes a pill from two digits, out of the flow so the control keeps the bell’s width. Inside the button, so inside its name."
+        },
+        {
+          "part": "account",
+          "element": "button, or the element render returns",
+          "required": false,
+          "purpose": "A pill around the consumer’s Avatar — xs at md, one step under the control — and, above 600 pixels, a name beside it. Wrapped in Menu by the consumer. It never folds."
+        },
+        {
+          "part": "action",
+          "element": "a with an href, a button without one, or the element render returns",
+          "required": false,
+          "purpose": "A global control of the product’s own — approvals, tasks — in the same square, ink and states as the marked controls. The consumer projects its glyph, sized by the control, and names it with aria-label. TopNavigationCount inside it stands over its corner. It never folds."
+        }
+      ],
+      "api": [
+        {
+          "name": "value",
+          "type": "string | null",
+          "defaultValue": "—",
+          "appliesTo": "TopNavigation",
+          "description": "The current destination’s value. Present means the consumer owns it; a link that states current itself still wins"
+        },
+        {
+          "name": "defaultValue",
+          "type": "string | null",
+          "defaultValue": "—",
+          "appliesTo": "TopNavigation",
+          "description": "The destination an uncontrolled bar starts on, read once"
+        },
+        {
+          "name": "moreOpen",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "TopNavigation",
+          "description": "Whether the panel is shown. Present means the consumer owns it"
+        },
+        {
+          "name": "defaultMoreOpen",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "TopNavigation",
+          "description": "Whether an uncontrolled bar starts with its panel open, read once"
+        },
+        {
+          "name": "searchOpen",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "TopNavigation",
+          "description": "Whether the search has taken the bar, below 600 pixels. Present means the consumer owns it; above 600 it has no effect"
+        },
+        {
+          "name": "defaultSearchOpen",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "TopNavigation",
+          "description": "Whether an uncontrolled bar starts with its search open, read once"
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "TopNavigation, TopNavigationDefaultsProvider",
+          "description": "The control height of everything in the bar, from the control scale"
+        },
+        {
+          "name": "frame",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "TopNavigation, TopNavigationDefaultsProvider",
+          "description": "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"
+        },
+        {
+          "name": "landmark",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "TopNavigation, TopNavigationDefaultsProvider",
+          "description": "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"
+        },
+        {
+          "name": "skipTo",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "TopNavigation",
+          "description": "The id of the element the skip link jumps to. Absent, no skip link is rendered"
+        },
+        {
+          "name": "value, defaultValue, onValueChange",
+          "type": "string | null, (value, request) => void",
+          "defaultValue": "—",
+          "appliesTo": "TopNavigationNav",
+          "description": "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"
+        },
+        {
+          "name": "arrow, openDelay, closeDelay, closeOnSelect",
+          "type": "boolean, number, number, boolean",
+          "defaultValue": "false, 200, 300, true",
+          "appliesTo": "TopNavigationNav",
+          "description": "The navigation menu’s own axes, read from NavigationMenuDefaultsProvider when unstated"
+        },
+        {
+          "name": "messages",
+          "type": "Partial<TopNavigationMessages>",
+          "defaultValue": "—",
+          "appliesTo": "TopNavigation",
+          "description": "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"
+        },
+        {
+          "name": "value",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "TopNavigationItem",
+          "description": "The item’s identity: what value names it by and what onCollapseChange reports"
+        },
+        {
+          "name": "priority",
+          "type": "'high' | 'medium' | 'low'",
+          "defaultValue": "medium",
+          "appliesTo": "TopNavigationItem",
+          "description": "Which step of the width folds the item: low under 1024 pixels, medium under 600, high under 480"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "TopNavigationItem",
+          "description": "The row and everything in it refuse interaction; the link keeps its href and its name"
+        },
+        {
+          "name": "current",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "TopNavigationLink",
+          "description": "Whether this is the current destination, stated on the row — what a router’s link writes. It wins over the root’s value"
+        },
+        {
+          "name": "href",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "TopNavigationHome, TopNavigationLink, TopNavigationHelp",
+          "description": "Where the control leads. Home without one is a span; help without one is a button for the consumer to wrap"
+        },
+        {
+          "name": "aria-label",
+          "type": "string",
+          "defaultValue": "the family’s message",
+          "appliesTo": "TopNavigationHelp, TopNavigationNotifications, TopNavigationAccount, TopNavigationAction, TopNavigationNav",
+          "description": "The name the consumer writes, kept over the family’s own"
+        }
+      ],
+      "composition": [
+        {
+          "name": "render",
+          "type": "(props) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "root, brand, home, mark, name, context, nav, list, item, link, search, actions, help, notifications, count, account",
+          "description": "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"
+        },
+        {
+          "name": "ref",
+          "type": "Ref<TopNavigationHandle> on the root, Ref<HTMLElement> on every part",
+          "defaultValue": "—",
+          "appliesTo": "every part",
+          "description": "The root’s handle carries focus(), focusSearch(), openMore(), closeMore() and the root element; every other ref reaches the element itself"
+        },
+        {
+          "name": "useTopNavigation()",
+          "type": "() => TopNavigationContextValue",
+          "defaultValue": "—",
+          "appliesTo": "inside TopNavigation",
+          "description": "What the parts read: the folded priorities, the collapsed values, the three values and the requests that move them, the panel and its list"
+        },
+        {
+          "name": "useTopNavigationItem()",
+          "type": "() => TopNavigationItemContextValue",
+          "defaultValue": "—",
+          "appliesTo": "inside TopNavigationItem",
+          "description": "What a row reads: its value, its priority, whether it is folded, current or disabled"
+        },
+        {
+          "name": "TopNavigationDefaultsProvider",
+          "type": "{ size, frame, landmark }",
+          "defaultValue": "—",
+          "appliesTo": "a subtree",
+          "description": "The decisions an application takes once. A bar that states any of them itself still wins"
+        },
+        {
+          "name": "@container slotted-top-navigation",
+          "type": "a container query in the consumer’s stylesheet",
+          "defaultValue": "—",
+          "appliesTo": "anything placed in context, search or actions",
+          "description": "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": "onValueChange(value, request)",
+          "payload": "the destination’s value, and a request with previous, reason (pointer | keyboard | programmatic), source and cancel()",
+          "when": "Before the current destination moves, on a press of a link. Cancelling refuses; the navigation itself is the anchor’s."
+        },
+        {
+          "name": "onMoreOpenChange(open, request)",
+          "payload": "whether the panel is shown, and a request with reason (pointer | keyboard | select | escape | outsidePress | resize | programmatic)",
+          "when": "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."
+        },
+        {
+          "name": "onSearchOpenChange(open, request)",
+          "payload": "whether the search has taken the bar, and a request with reason (pointer | keyboard | escape | blur | resize | programmatic)",
+          "when": "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."
+        },
+        {
+          "name": "onCollapseChange(values, reason)",
+          "payload": "the values of the folded items in DOM order, and the reason resize",
+          "when": "After the set of folded items changed: the bar crossed one of its three steps. A fact, not a request — the width decided it."
+        },
+        {
+          "name": "onClick, onFocus, onKeyDown on every control",
+          "payload": "the element’s own events",
+          "when": "Whenever the a or button fires them. The consumer’s handler runs first, and preventDefault() in onClick refuses the family’s part."
+        }
+      ],
+      "accessibility": [
+        "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": [
+    {
+      "id": "playground",
+      "title": "The bar of a freight operator",
+      "note": "Aurora Logística’s bar with every region filled, in a desktop room. The room scrolls sideways where the page is narrower; the steps the bar folds at are the next demonstration.",
+      "language": "tsx",
+      "source": "<TopNavigation defaultValue=\"painel\" skipTo=\"conteudo\">\n  <TopNavigationBrand>\n    <TopNavigationHome href=\"/\">\n      <TopNavigationMark>\n        <AuroraMark />\n      </TopNavigationMark>\n      <TopNavigationName>Aurora Logística</TopNavigationName>\n    </TopNavigationHome>\n  </TopNavigationBrand>\n  <TopNavigationNav>\n    <TopNavigationList>\n      <TopNavigationItem priority=\"high\" value=\"painel\">\n        <TopNavigationLink href=\"/painel\">Painel</TopNavigationLink>\n      </TopNavigationItem>\n      <TopNavigationItem priority=\"low\" value=\"relatorios\">\n        <TopNavigationLink href=\"/relatorios\">Relatórios</TopNavigationLink>\n      </TopNavigationItem>\n    </TopNavigationList>\n  </TopNavigationNav>\n  <TopNavigationSearch>\n    <TextField placeholder=\"Procurar cargas, clientes, rotas…\" type=\"search\" />\n  </TopNavigationSearch>\n  <TopNavigationActions>\n    <TopNavigationHelp href=\"/ajuda\" />\n    <TopNavigationNotifications>\n      <TopNavigationCount>3</TopNavigationCount>\n    </TopNavigationNotifications>\n    <TopNavigationAccount>\n      <Avatar size=\"xs\">AB</Avatar>\n    </TopNavigationAccount>\n  </TopNavigationActions>\n</TopNavigation>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "anatomy",
+      "title": "Every part, named",
+      "note": "The bar with each part labelled by its data-part: the brand, the context, the destinations with a section trigger, the search, and the four global controls. The panel and its list stand in the DOM after the nav, closed.",
+      "language": "tsx",
+      "source": "<TopNavigation>\n  <TopNavigationBrand>\n    <TopNavigationHome href=\"/\">\n      <TopNavigationMark>…</TopNavigationMark>\n      <TopNavigationName>name</TopNavigationName>\n    </TopNavigationHome>\n  </TopNavigationBrand>\n  <TopNavigationContext>…</TopNavigationContext>\n  <TopNavigationNav>\n    <TopNavigationList>\n      <TopNavigationItem value=\"link\">\n        <TopNavigationLink href=\"/link\">link</TopNavigationLink>\n      </TopNavigationItem>\n      <TopNavigationItem value=\"trigger\">\n        <TopNavigationTrigger>trigger</TopNavigationTrigger>\n      </TopNavigationItem>\n    </TopNavigationList>\n  </TopNavigationNav>\n  <TopNavigationSearch>…</TopNavigationSearch>\n  <TopNavigationActions>\n    <TopNavigationHelp href=\"/help\" />\n    <TopNavigationNotifications>\n      <TopNavigationCount>3</TopNavigationCount>\n    </TopNavigationNotifications>\n    <TopNavigationAccount>…</TopNavigationAccount>\n  </TopNavigationActions>\n</TopNavigation>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "priority",
+      "title": "Three steps of the width",
+      "note": "The same bar in four rooms of a stated width. On a desktop everything shows; on a laptop (under 1024) the low items have folded into more; a tablet at 640 folds the same low items and keeps the rest; on a phone the medium ones fold under 600, where the search becomes a magnifier and the context moves to the panel, and the high ones and the help fold under 480, where the name leaves the eye.",
+      "language": "tsx",
+      "source": "<TopNavigationList>\n  <TopNavigationItem priority=\"high\" value=\"painel\">\n    <TopNavigationLink href=\"/painel\">Painel</TopNavigationLink>\n  </TopNavigationItem>\n  <TopNavigationItem value=\"rotas\">\n    <TopNavigationLink href=\"/rotas\">Rotas</TopNavigationLink>\n  </TopNavigationItem>\n  <TopNavigationItem priority=\"low\" value=\"faturacao\">\n    <TopNavigationLink href=\"/faturacao\">Faturação</TopNavigationLink>\n  </TopNavigationItem>\n</TopNavigationList>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "panel",
+      "title": "What folded, under the bar",
+      "note": "Press more: on a phone the panel takes the bar’s whole width, on a tablet it stands under the bar’s end. The folded destinations are rows, the workspace at the top and help at the bottom. A press on a row closes it with the reason select; Escape returns focus to more; a press outside closes it too.",
+      "language": "tsx",
+      "source": "const [moreOpen, setMoreOpen] = useState(false);\n\n<TopNavigation moreOpen={moreOpen} onMoreOpenChange={(open) => setMoreOpen(open)}>\n  …\n</TopNavigation>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "search",
+      "title": "The search gives way to a magnifier",
+      "note": "On a laptop the field stands at the start of the middle of the bar, after the brand and the destinations. On a phone it is a magnifier in the actions; pressing it opens the field over the whole bar with focus inside, and Escape, the cross or focus leaving it hand the bar back.",
+      "language": "tsx",
+      "source": "<TopNavigationSearch>\n  <TextField\n    aria-label=\"Procurar\"\n    end={<Shortcut keys=\"mod+k\" size=\"sm\" variant=\"soft\" />}\n    placeholder=\"Procurar cargas, clientes, rotas…\"\n    start={<Search aria-hidden size={16} />}\n    type=\"search\"\n    variant=\"subtle\"\n  />\n</TopNavigationSearch>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sections",
+      "title": "A section that opens a panel of destinations",
+      "note": "Frota is a section of the navigation menu the nav part already is: its panel opens on the shared surface under the bar, a resting pointer opens it after a delay, and a second section switches without one. Folded into the panel, the section opens its links in line.",
+      "language": "tsx",
+      "source": "<TopNavigationItem value=\"frota\">\n  <TopNavigationTrigger>Frota</TopNavigationTrigger>\n  <NavigationMenuContent>\n    <NavigationMenuLinks>\n      <li>\n        <NavigationMenuLink href=\"/fleet/vehicles\">Veículos</NavigationMenuLink>\n      </li>\n    </NavigationMenuLinks>\n  </NavigationMenuContent>\n</TopNavigationItem>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "current",
+      "title": "Where the reader is",
+      "note": "value on the root names the destination and a press asks it to move with the device’s reason; a link that states current itself wins. Where the current destination has folded, more carries the mark in its place.",
+      "language": "tsx",
+      "source": "const [value, setValue] = useState<string | null>('cargas');\n\n<TopNavigation value={value} onValueChange={(next) => setValue(next)}>\n  …\n</TopNavigation>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "actions",
+      "title": "The global controls",
+      "note": "Help as a link to a help centre or as the trigger of a popover; the bell with a count over its corner that grows to a pill away from it; the account as a menu’s trigger; a control of the product’s own — approvals — in the same square, with its own glyph and the same count. Each carries its name for a reader and repeats it in a tooltip.",
+      "language": "tsx",
+      "source": "<TopNavigationActions>\n  <TopNavigationHelp href=\"/ajuda\" />\n  <Popover>\n    <PopoverTrigger\n      render={(props) => (\n        <TopNavigationAction {...props} aria-label={`Aprovações, ${pending} pendentes`}>\n          <ClipboardCheck />\n          <TopNavigationCount>{pending}</TopNavigationCount>\n        </TopNavigationAction>\n      )}\n    />\n    <PopoverContent>…</PopoverContent>\n  </Popover>\n  <Popover>\n    <PopoverTrigger\n      render={(props) => (\n        <TopNavigationNotifications {...props}>\n          <TopNavigationCount>12</TopNavigationCount>\n        </TopNavigationNotifications>\n      )}\n    />\n    <PopoverContent>…</PopoverContent>\n  </Popover>\n  <Menu>\n    <MenuTrigger\n      render={(props) => (\n        <TopNavigationAccount {...props}>\n          <Avatar size=\"xs\">AB</Avatar>\n        </TopNavigationAccount>\n      )}\n    />\n    <MenuContent>…</MenuContent>\n  </Menu>\n</TopNavigationActions>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "context",
+      "title": "What the application is right now",
+      "note": "A workspace switcher and an environment badge after the brand. On a phone the whole region moves to the top of the panel — the same elements, so the switcher still opens its menu there.",
+      "language": "tsx",
+      "source": "<TopNavigationContext>\n  <Menu>\n    <MenuTrigger\n      render={(props) => (\n        <Button\n          {...props}\n          end={<ChevronsUpDown aria-hidden />}\n          size=\"sm\"\n          tone=\"secondary\"\n          variant=\"ghost\"\n        >\n          Porto · Operações\n        </Button>\n      )}\n    />\n    <MenuContent>…</MenuContent>\n  </Menu>\n  <Badge size=\"sm\" tone=\"warning\" variant=\"soft\">\n    Homologação\n  </Badge>\n</TopNavigationContext>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "size",
+      "title": "Three control heights",
+      "note": "sm, md and lg move every control in the bar together — the mark, the destinations, the four global controls — and the bar’s own height with them. All three move again with density.",
+      "language": "tsx",
+      "source": "<TopNavigation size=\"sm\">…</TopNavigation>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "The states a destination can be in",
+      "note": "Current, a section open, disabled — a disabled destination keeps its href and its name and refuses the press — and the hover, press and focus every control answers. Help and the account with their layers open hold the pointer’s ground.",
+      "language": "tsx",
+      "source": "<TopNavigationItem disabled value=\"faturacao\">\n  <TopNavigationLink href=\"/faturacao\">Faturação</TopNavigationLink>\n</TopNavigationItem>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Content the family did not choose",
+      "note": "A product name of nine words, cut with an ellipsis and, when the room runs out, given up before any control; destinations of four words each; a count of three characters; the account with a name beside the avatar; and the same bar in a right-to-left document.",
+      "language": "tsx",
+      "source": "<TopNavigationAccount>\n  <Avatar size=\"xs\">MB</Avatar>\n  <span>Maria Bartolomeu</span>\n</TopNavigationAccount>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "shell",
+      "title": "Inside the shell",
+      "note": "The bar as the only child of app-shell’s banner: a div rather than a second banner, no ground of its own, the shell’s nav-toggle in the brand and the mark over the column’s marks. Press the toggle and the bar keeps its place.",
+      "language": "tsx",
+      "source": "<AppShell>\n  <AppShellBanner>\n    <TopNavigation defaultValue=\"painel\">\n      <TopNavigationBrand>\n        <AppShellNavToggle />\n        <TopNavigationHome href=\"/\">…</TopNavigationHome>\n      </TopNavigationBrand>\n      …\n    </TopNavigation>\n  </AppShellBanner>\n  <AppShellNav>…</AppShellNav>\n  <AppShellMain>…</AppShellMain>\n</AppShell>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "standalone",
+      "title": "On its own, above a page",
+      "note": "A header with its own ground, rule and inset, a skip link that appears on the first Tab, and a page under it. Nothing here is sticky: an application that wants the bar pinned writes position: sticky on it.",
+      "language": "tsx",
+      "source": "<>\n  <TopNavigation skipTo=\"conteudo\">…</TopNavigation>\n  <main id=\"conteudo\" tabIndex={-1}>\n    …\n  </main>\n</>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "defaults",
+      "title": "Decided once for an application",
+      "note": "The provider carries the size and the frame for every bar under it — an application at the large step — and a bar that states one itself still wins. The words on the icon-only controls come from the language in force.",
+      "language": "tsx",
+      "source": "<TopNavigationDefaultsProvider size=\"lg\">\n  <TopNavigation>…</TopNavigation>\n</TopNavigationDefaultsProvider>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Composed with what sits beside it",
+      "note": "A router’s link as the destination through render, which is where aria-current comes from; a Badge in the context; a Kbd in the search; Menu on a section, on the account and on the workspace; Popover on the bell.",
+      "language": "tsx",
+      "source": "<TopNavigationItem value=\"cargas\">\n  <TopNavigationLink render={(props) => <NavLink {...props} to=\"/cargas\" />}>\n    Cargas\n  </TopNavigationLink>\n</TopNavigationItem>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "The keyboard",
+      "note": "Tab reaches every control, in the order they stand: the skip link, the mark, each destination, more, the panel when it is open, the search, help, the bell, the account. Escape closes the panel or the open search and lands on the control that opened it. The reason each request carries is shown.",
+      "language": "tsx",
+      "source": "<TopNavigation\n  onMoreOpenChange={(open, request) => log(request.reason)}\n  onSearchOpenChange={(open, request) => log(request.reason)}\n  onValueChange={(value, request) => log(request.reason)}\n>\n  …\n</TopNavigation>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "accessibility",
+      "title": "What a reader hears",
+      "note": "A banner landmark holding a navigation landmark with a list of links, one of them current; a button named Mais that expands a panel; a search; and three buttons named for what they open. Nothing is a menubar and nothing writes tabindex.",
+      "language": "tsx",
+      "source": "<TopNavigation aria-label=\"Aurora\">\n  <TopNavigationNav aria-label=\"Principal\">…</TopNavigationNav>\n</TopNavigation>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}