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

package/docs/menu.md

@@ -0,0 +1,155 @@
+<!-- index: ./index.md -->
+# menu
+
+`data-ui="menu"` · List of actions opened from a trigger.
+
+## Import
+
+```ts
+import { SlMenu, SlMenuEmpty, SlMenuGroup, SlMenuHeader, SlMenuItem, SlMenuItemDescription, SlMenuItemIcon, SlMenuItemMeta, SlMenuRadioGroup, SlMenuSeparator, SlMenuTrigger } from '@slotted/angular/menu';
+```
+
+Selector: `sl-menu, [slMenuTriggerFor], button[slMenuItem], a[slMenuItem], button[slMenuCheckboxItem], button[slMenuRadioItem], sl-menu-group, sl-menu-radio-group, hr[slMenuSeparator], [slMenuHeader], [slMenuItemIcon], [slMenuItemDescription], [slMenuItemMeta], [slMenuEmpty]` · exportAs: `slMenu, slMenuTrigger, slMenuItem, slMenuGroup, slMenuRadioGroup`
+
+## Minimal example
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlButton, SlButtonEnd } from '@slotted/angular/button';
+import { SlGlyph } from '@slotted/angular/icon';
+import { SlMenu, SlMenuItem, SlMenuSeparator, SlMenuTrigger } from '@slotted/angular/menu';
+
+@Component({
+  selector: 'app-menu-basic',
+  imports: [SlButton, SlButtonEnd, SlGlyph, SlMenu, SlMenuItem, SlMenuSeparator, SlMenuTrigger],
+  template: `
+    <button slButton variant="outline" [slMenuTriggerFor]="actions">
+      Order actions
+      <span slButtonEnd><svg slGlyph name="chevron-down"></svg></span>
+    </button>
+    <sl-menu #actions>
+      <button slMenuItem>View order</button>
+      <button slMenuItem shortcut="Mod+E">Edit order</button>
+      <button slMenuItem shortcut="Mod+D">Duplicate</button>
+      <button slMenuItem shortcut="Mod+P">Print packing slip</button>
+      <hr slMenuSeparator />
+      <button slMenuItem tone="danger">Cancel order…</button>
+    </sl-menu>
+  `,
+})
+export class MenuBasic {}
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div, built into the portal when the menu opens | yes |
+| `content` | div | yes |
+| `header` | div[slMenuHeader] | no |
+| `group` | sl-menu-group, or sl-menu-radio-group | no |
+| `group-label` | div | no |
+| `item` | button[slMenuItem], or a[slMenuItem] for a link | yes |
+| `indicator` | span, drawn by the item | no |
+| `icon` | span[slMenuItemIcon] | no |
+| `label` | span, drawn by the item around its content | yes |
+| `description` | span[slMenuItemDescription] | no |
+| `meta` | span[slMenuItemMeta] | no |
+| `shortcut` | span, drawn by the item | no |
+| `separator` | hr[slMenuSeparator] | no |
+| `empty` | [slMenuEmpty] | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `open` | `model<boolean>` | false | sl-menu | Whether the menu is open. Bind [(open)] to read and write it; on a menubar the bar holds it instead. |
+| `value` | `string \| undefined` | — | sl-menu, sl-menu-radio-group, button[slMenuRadioItem] | On an sl-menu inside sl-menubar, the name the bar knows it by; a menu on its own needs none. On sl-menu-radio-group, the chosen value, bound with [(value)]. On a radio item, the value the item stands for. |
+| `checked` | `model<boolean>` | false | button[slMenuCheckboxItem] | Whether the option is on. Bind [(checked)] to read and write it. |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | sl-menu | The width of the surface and the height of its items. |
+| `side` | `'top' \| 'bottom' \| 'inline-start' \| 'inline-end' \| 'left' \| 'right'` | bottom | sl-menu | The edge of the trigger the surface opens from. inline-start and inline-end follow the reading direction. |
+| `align` | `'start' \| 'center' \| 'end'` | start | sl-menu | Where the surface sits along that edge. |
+| `mount` | `'active' \| 'lazy' \| 'eager'` | active | sl-menu | When the surface is in the document: only while open, from the first open on, or from the start. A surface kept while closed carries inert. |
+| `strategy` | `'absolute' \| 'fixed'` | absolute | sl-menu | The CSS position the layer is placed with. |
+| `closeOnSelect` | `boolean` | true | sl-menu, button[slMenuItem] | Whether running an item closes the menu. Checkbox and radio items keep it open unless they set it themselves. |
+| `loop` | `boolean` | true | sl-menu | Whether the arrow keys wrap from the last item to the first. |
+| `typeahead` | `boolean` | true | sl-menu | Whether typing moves focus to the item whose label starts with the typed text. |
+| `openOnHover` | `boolean` | true | sl-menu | Whether a submenu opens when the pointer rests on its item. |
+| `closeOnEscape` | `boolean` | true | sl-menu | Whether Escape closes the menu that holds focus. |
+| `closeOnOutsidePress` | `boolean` | true | sl-menu | Whether a press outside the menu closes every open menu. |
+| `flip` | `boolean` | true | sl-menu | Whether the surface moves to the opposite side when it would leave the window. |
+| `shift` | `boolean` | true | sl-menu | Whether the surface slides along its edge to stay in the window. |
+| `hideWhenDetached` | `boolean` | true | sl-menu | Whether the surface hides once its trigger has scrolled out of view. |
+| `portal` | `boolean` | true | sl-menu | Whether the layer is built at the end of the document. |
+| `disabled` | `boolean` | false | sl-menu, button[slMenuItem] | A disabled menu never opens. A disabled item stays focusable and runs nothing. |
+| `loading` | `boolean` | false | sl-menu | Whether the items are on their way. The surface keeps its width, sets aria-busy and shows the slMenuEmpty message. |
+| `sideOffset` | `number` | 0 | sl-menu | Extra distance from the trigger, in pixels, beyond the layer's own gap. |
+| `alignOffset` | `number` | 0 | sl-menu | Distance along the alignment edge, in pixels. |
+| `collisionPadding` | `number` | 8 | sl-menu | The distance, in pixels, the surface keeps from the edge of the window. |
+| `submenuOpenDelay` | `number` | 150 | sl-menu | How long, in milliseconds, the pointer rests on an item before its submenu opens. |
+| `submenuCloseDelay` | `number` | 300 | sl-menu | How long, in milliseconds, a submenu stays open while the pointer travels toward it without reaching it. |
+| `typeaheadTimeout` | `number` | 500 | sl-menu | How long, in milliseconds, typed letters keep adding to one search. |
+| `shortcut` | `string` | — | button[slMenuItem] | A shortcut written as Mod+K, printed for the platform and announced with aria-keyshortcuts. The menu does not bind the key. |
+| `textValue` | `string` | — | button[slMenuItem] | The text typeahead matches, when the label does not start with the word a reader would type. |
+| `tone` | `'accent' \| 'secondary' \| 'success' \| 'warning' \| 'danger'` | — | button[slMenuItem] | The theme tone of the label, the icon and the highlight. A destructive command takes danger. |
+| `label` | `string` | — | sl-menu-group | The name of the group, rendered as its group-label part. |
+| `slMenuTriggerFor` | `SlMenu` | — | [slMenuTriggerFor] | The menu a control opens. It goes on your own button; on an slMenuItem it opens a submenu. |
+| `aria-label` | `string` | — | sl-menu | Names the surface itself, instead of the name it takes from its trigger. |
+| `aria-describedby` | `string` | — | sl-menu | The ids of the elements that describe the menu, written on the element with role="menu". |
+| `provideMenuDefaults` | `provider` | — | Application | Sets any axis once, in the application config or on a route. A value set on one menu still wins. |
+| `slMenuTriggerFor` | `directive` | — | Any control | Goes on your own element instead of replacing it: the wiring, the state attributes and the keyboard arrive on the button you already have, which keeps its own part and styles. |
+| `slMenuHeader` | `directive` | — | sl-menu | The block above the commands. Its children are the media, an element with data-part="label" and an slMenuItemDescription, and the surface is described by it. |
+| `slMenuItemIcon, slMenuItemDescription, slMenuItemMeta` | `directive` | — | Item content | Project an element into the icon, description or meta column of the item. |
+| `slMenuEmpty` | `directive` | — | sl-menu | The message shown while loading is set or when the menu holds no items. |
+| `exportAs` | `template reference` | — | sl-menu, [slMenuTriggerFor] | A template reference such as #menu="slMenu" reaches the instance, for toggle(), closeAll() and the resolved axes. |
+| `ng-content` | `projection` | — | sl-menu, sl-menu-group | The items are your own elements, projected into the surface the menu builds when it opens. |
+| `slMenuItem, slMenuCheckboxItem, slMenuRadioItem` | `attribute` | — | button, a | The attribute you write decides the role of the item. slMenuItem also goes on an a for a link item. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `openChange` | `boolean` | After the menu opens or closes, as the write-back of [(open)]. |
+| `openChangeRequest` | `ChangeRequest<boolean>` | Before the menu opens or closes. request.reason is pointer, keyboard, escape, outsidePress, select, dismiss or programmatic, request.source is the event, and request.cancel() refuses the change. |
+| `checkedChange, checkedChangeRequest` | `boolean, ChangeRequest<boolean>` | After and before a checkbox item changes. The request's reason is pointer or keyboard. |
+| `valueChange, valueChangeRequest` | `string, ChangeRequest<string>` | After and before a radio group changes its value. The request's reason is pointer or keyboard. |
+| `select` | `MenuSelectEvent` | When an item runs. event.reason is pointer or keyboard, and event.preventDefault() keeps the menu open for this press only. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `side` | `bottom`, `top`, `inline-start`, `inline-end`, `left`, `right` | `bottom` |
+| `align` | `start`, `center`, `end` | `start` |
+| `mount` | `active`, `lazy`, `eager` | `active` |
+| `strategy` | `absolute`, `fixed` | `absolute` |
+| `closeOnSelect` | `true`, `false` | `true` |
+| `loop` | `true`, `false` | `true` |
+| `typeahead` | `true`, `false` | `true` |
+| `openOnHover` | `true`, `false` | `true` |
+| `closeOnEscape` | `true`, `false` | `true` |
+| `closeOnOutsidePress` | `true`, `false` | `true` |
+| `flip` | `true`, `false` | `true` |
+| `shift` | `true`, `false` | `true` |
+| `hideWhenDetached` | `true`, `false` | `true` |
+| `portal` | `true`, `false` | `true` |
+| `disabled` | `true`, `false` | `false` |
+
+## Rules
+
+- An item is a native button, so Enter and Space run it and the pointer behaves as the browser's own. role="menuitem" replaces role="button", so a screen reader announces a menu item. A link item is an a that keeps its href and takes the same role.
+- Menu supplies the keyboard of the WAI-ARIA menu pattern: the arrow keys move and wrap, Home and End reach the ends, letters move by typeahead, the inline-end arrow opens a submenu and the inline-start arrow closes it, Escape closes the menu that holds focus, and Tab closes every menu and moves focus past the trigger.
+- A disabled item stays focusable and carries aria-disabled instead of the native disabled attribute, so a keyboard user can still find a command that is unavailable. A natively disabled button cannot take focus.
+- A header is not an item and never takes focus, because role="menu" owns only items, groups and separators. The surface references it with aria-describedby, joined to any description you give, so a screen reader announces who the menu belongs to once, as it opens.
+- The surface is named by its trigger, or by its own aria-label. A checkbox or radio item announces its state through aria-checked, a group is named by its label, and a shortcut is announced through aria-keyshortcuts while the printed keys are hidden, so the item's name stays the command.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-thin`, `--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-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-disabled-foreground`, `--slotted-duration-medium`, `--slotted-duration-short`, `--slotted-easing-enter`, `--slotted-easing-exit`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-width`, `--slotted-font-family-sans`, `--slotted-font-size-xs`, `--slotted-font-weight-semibold`, `--slotted-line-height-md`, `--slotted-line-height-sm`, `--slotted-menu-border-color`, `--slotted-menu-gap`, `--slotted-menu-highlight`, `--slotted-menu-highlight-active`, `--slotted-menu-item-radius`, `--slotted-menu-measure`, `--slotted-menu-measure-lg`, `--slotted-menu-measure-sm`, `--slotted-menu-min-measure`, `--slotted-menu-padding-block`, `--slotted-menu-padding-inline`, `--slotted-menu-radius`, `--slotted-menu-separator-color`, `--slotted-menu-shadow`, `--slotted-menu-surface`, `--slotted-menu-text`, `--slotted-menu-text-muted`, `--slotted-radius-lg`, `--slotted-shadow-md`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-surface-raised`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-subtle-active`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-danger-subtle-active`, `--slotted-tone-danger-surface`, `--slotted-tone-danger-text`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-tone-secondary-surface`, `--slotted-tone-secondary-text`, `--slotted-tone-success-subtle-active`, `--slotted-tone-success-surface`, `--slotted-tone-success-text`, `--slotted-tone-warning-subtle-active`, `--slotted-tone-warning-surface`, `--slotted-tone-warning-text`, `--slotted-z-index-popover`
+
+## Examples
+
+See [menu.examples.md](./menu.examples.md).

package/docs/menubar.json

@@ -0,0 +1,292 @@
+{
+  "family": "menubar",
+  "ui": "menubar",
+  "binding": "angular",
+  "catalog": {
+    "group": "Navigation",
+    "summary": "Horizontal bar of menus, as in desktop apps."
+  },
+  "axes": {
+    "orientation": [
+      "horizontal",
+      "vertical"
+    ],
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "loop": [
+      true,
+      false
+    ],
+    "typeahead": [
+      true,
+      false
+    ],
+    "disabled": [
+      true,
+      false
+    ]
+  },
+  "members": {
+    "menubar": {
+      "nativeElement": "div",
+      "defaults": {
+        "orientation": "horizontal",
+        "size": "md",
+        "loop": true,
+        "typeahead": true,
+        "disabled": false
+      },
+      "capabilities": [
+        "selection",
+        "orientation",
+        "size",
+        "appearance",
+        "disabled",
+        "content",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "open",
+        "disabled"
+      ],
+      "parts": [
+        "root",
+        "trigger"
+      ]
+    }
+  },
+  "docs": {
+    "menubar": {
+      "imports": {
+        "source": "import { SlMenubar, provideMenubarDefaults } from '@slotted/angular/menubar';\nimport { SlMenu, SlMenuItem, SlMenuTrigger } from '@slotted/angular/menu';",
+        "selector": "sl-menubar",
+        "exportAs": "slMenubar"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "sl-menubar",
+          "required": true,
+          "purpose": "The bar. It carries data-ui=\"menubar\", role=\"menubar\", its orientation and its size, holds one tab stop for every trigger on it, and paints no ground of its own — the header it sits in owns that."
+        },
+        {
+          "part": "trigger",
+          "element": "the consumer's control carrying slMenuTriggerFor",
+          "required": true,
+          "purpose": "One menu's control, as role=\"menuitem\". The directive writes the part and the role once it finds a bar in scope: the menus on a bar are the menu family unchanged, so the bar declares no other part."
+        }
+      ],
+      "api": [
+        {
+          "name": "value",
+          "type": "model<string | undefined>",
+          "defaultValue": "—",
+          "appliesTo": "sl-menubar",
+          "description": "The menu now open, named by its own value. A model, so [(value)] is both the value and the write-back; a bar has at most one open menu, so the state is that name rather than a boolean on each."
+        },
+        {
+          "name": "orientation",
+          "type": "'horizontal' | 'vertical'",
+          "defaultValue": "horizontal",
+          "appliesTo": "sl-menubar",
+          "description": "Which way the bar runs. A vertical bar swaps the two arrow pairs and writes aria-orientation."
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "sl-menubar",
+          "description": "The step every trigger and every menu on the bar takes."
+        },
+        {
+          "name": "loop",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "sl-menubar",
+          "description": "Whether the arrows wrap past the ends of the bar."
+        },
+        {
+          "name": "typeahead",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "sl-menubar",
+          "description": "Whether typing moves to the trigger whose label begins with it."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "sl-menubar",
+          "description": "A disabled bar opens no menu, and every menu on it reads the same answer."
+        },
+        {
+          "name": "aria-label",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "sl-menubar",
+          "description": "Names the bar. The role has no name of its own to invent, so the consumer gives it one."
+        }
+      ],
+      "composition": [
+        {
+          "name": "provideMenubarDefaults",
+          "type": "provider",
+          "defaultValue": "—",
+          "appliesTo": "Application",
+          "description": "Sets the orientation, the size, the wrapping and the typeahead once, in the bootstrap or on a route. A bar that states one itself still wins."
+        },
+        {
+          "name": "SlMenu",
+          "type": "component",
+          "defaultValue": "—",
+          "appliesTo": "Inside sl-menubar",
+          "description": "The menus on a bar are the menu family unchanged: every capability it has — submenus, options, shortcuts, tone — reaches the bar without a second API."
+        },
+        {
+          "name": "MENUBAR_SURFACE",
+          "type": "injection token",
+          "defaultValue": "—",
+          "appliesTo": "sl-menubar",
+          "description": "What the bar provides and a menu reads: the open menu's name, the orientation, the size and the two keys that move between menus. The menu entry point declares it, so the dependency runs one way."
+        },
+        {
+          "name": "exportAs",
+          "type": "template reference",
+          "defaultValue": "—",
+          "appliesTo": "sl-menubar",
+          "description": "A template reaches the bar — #bar=\"slMenubar\" — for step() and the resolved axes."
+        },
+        {
+          "name": "ng-content",
+          "type": "projection",
+          "defaultValue": "—",
+          "appliesTo": "sl-menubar",
+          "description": "The triggers and the menus are the consumer's own elements, in the order the bar reads them."
+        }
+      ],
+      "events": [
+        {
+          "name": "valueChange",
+          "payload": "string | undefined",
+          "when": "After the bar has opened another menu or closed the one it had, as the write-back half of [(value)]."
+        },
+        {
+          "name": "valueChangeRequest",
+          "payload": "ChangeRequest<string>",
+          "when": "Before the bar moves. It carries pointer, keyboard, escape, outsidePress, select, dismiss or programmatic, the originating event, and cancel()."
+        }
+      ],
+      "accessibility": [
+        "The platform supplies each trigger: it is the consumer's own button, so the press and the two keys are the browser's own. role=\"menuitem\" replaces role=\"button\", because on a bar the control is an item of a composite widget rather than a button in a row.",
+        "The family supplies the bar's keyboard, as the WAI-ARIA menu and menubar pattern describes it: one tab stop for the whole bar, arrows along its own axis with wrapping, Home and End at the ends, typeahead by name, and — from inside an open menu — the inline arrows closing it and opening the neighbouring one with focus left on the trigger.",
+        "The bar has no name of its own to invent, so the consumer gives it one with aria-label, which is what a reader hears before the first trigger.",
+        "A disabled trigger stays focusable and takes aria-disabled rather than the native attribute, so a reader can find a menu that is currently unavailable instead of walking past a gap in the bar."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-control-font-size-lg",
+    "--slotted-control-font-size-md",
+    "--slotted-control-font-size-sm",
+    "--slotted-control-height-lg",
+    "--slotted-control-height-md",
+    "--slotted-control-height-sm",
+    "--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-disabled-background",
+    "--slotted-disabled-foreground",
+    "--slotted-duration-short",
+    "--slotted-easing-standard",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-width",
+    "--slotted-font-family-sans",
+    "--slotted-font-weight-medium",
+    "--slotted-menubar-gap",
+    "--slotted-menubar-highlight",
+    "--slotted-menubar-highlight-active",
+    "--slotted-menubar-text",
+    "--slotted-menubar-trigger-font-weight",
+    "--slotted-menubar-trigger-radius",
+    "--slotted-space-1",
+    "--slotted-text",
+    "--slotted-tone-secondary-subtle-active",
+    "--slotted-tone-secondary-subtle-hover"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "A bar of three menus, driven by the controls under the canvas. Change the orientation and the size, and the menus follow the bar rather than being told twice.",
+      "language": "html",
+      "source": "<sl-menubar aria-label=\"Main\">\n  <button [slMenuTriggerFor]=\"file\">File</button>\n  <sl-menu #file value=\"file\">\n    <button slMenuItem shortcut=\"Mod+N\">New</button>\n  </sl-menu>\n</sl-menubar>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "bar",
+      "title": "The bar",
+      "note": "Three menus in a header. Pressing one opens it; with one open, moving the pointer along the bar switches menus without another press.",
+      "language": "html",
+      "source": "<sl-menubar aria-label=\"Main\" [(value)]=\"openMenu\">\n  <button [slMenuTriggerFor]=\"file\">File</button>\n  <sl-menu #file value=\"file\">…</sl-menu>\n</sl-menubar>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "submenus",
+      "title": "Submenus",
+      "note": "A bar's menu holds submenus like any other menu, and the inline arrows still move between the bar's own menus once the submenu has closed.",
+      "language": "html",
+      "source": "<sl-menu #file value=\"file\">\n  <button slMenuItem>New</button>\n  <button slMenuItem [slMenuTriggerFor]=\"exportAs\">Export as</button>\n  <sl-menu #exportAs>\n    <button slMenuItem>PDF</button>\n  </sl-menu>\n</sl-menu>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "checkbox-and-radio",
+      "title": "Options on a bar",
+      "note": "A View menu of toggles and a choice, which stay open as they are changed — the bar keeps its menu while the reader turns three things on.",
+      "language": "html",
+      "source": "<sl-menu #view value=\"view\">\n  <button slMenuCheckboxItem [checked]=\"true\">Rulers</button>\n  <sl-menu-radio-group value=\"fit\">\n    <button slMenuRadioItem value=\"fit\">Fit</button>\n  </sl-menu-radio-group>\n</sl-menu>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "orientation",
+      "title": "Orientation",
+      "note": "A sidebar of commands is a vertical menubar: the arrow pairs exchange places, the menus open beside the bar, and aria-orientation says so.",
+      "language": "html",
+      "source": "<sl-menubar aria-label=\"Workspace\" orientation=\"vertical\">\n  <button [slMenuTriggerFor]=\"project\">Project</button>\n  <sl-menu #project value=\"project\">…</sl-menu>\n</sl-menubar>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "States",
+      "note": "The trigger whose menu is open keeps its highlight, a disabled trigger stays focusable and opens nothing, and a disabled bar disables every menu on it.",
+      "language": "html",
+      "source": "<sl-menubar aria-label=\"Main\" [disabled]=\"saving()\">\n  <button [slMenuTriggerFor]=\"window\">Window</button>\n  <sl-menu #window value=\"window\" [disabled]=\"true\">…</sl-menu>\n</sl-menubar>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "Keyboard",
+      "note": "Tab reaches the bar once and lands where it was left; the inline arrows move between triggers and switch menus while one is open; typing jumps to a menu by name.",
+      "language": "html",
+      "source": "<sl-menubar aria-label=\"Main\" [loop]=\"true\" [typeahead]=\"true\">\n  <button [slMenuTriggerFor]=\"file\">File</button>\n  <sl-menu #file value=\"file\">…</sl-menu>\n</sl-menubar>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "In context",
+      "note": "An application header: the bar sits beside a logo and an account control, paints no ground of its own, and takes its size from the provider once.",
+      "language": "ts",
+      "source": "bootstrapApplication(App, { providers: [provideMenubarDefaults({ size: 'sm' })] });\n",
+      "verdict": "excerpt"
+    }
+  ]
+}

package/docs/menubar.md

@@ -0,0 +1,173 @@
+<!-- index: ./index.md -->
+# menubar
+
+`data-ui="menubar"` · Horizontal bar of menus, as in desktop apps.
+
+## Import
+
+```ts
+import { SlMenubar, provideMenubarDefaults } from '@slotted/angular/menubar';
+import { SlMenu, SlMenuItem, SlMenuTrigger } from '@slotted/angular/menu';
+```
+
+Selector: `sl-menubar` · exportAs: `slMenubar`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<sl-menubar aria-label="Main">
+  <button [slMenuTriggerFor]="file">File</button>
+  <sl-menu #file value="file">
+    <button slMenuItem shortcut="Mod+N">New</button>
+  </sl-menu>
+</sl-menubar>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | sl-menubar | yes |
+| `trigger` | the consumer's control carrying slMenuTriggerFor | yes |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `model<string \| undefined>` | — | sl-menubar | The menu now open, named by its own value. A model, so [(value)] is both the value and the write-back; a bar has at most one open menu, so the state is that name rather than a boolean on each. |
+| `orientation` | `'horizontal' \| 'vertical'` | horizontal | sl-menubar | Which way the bar runs. A vertical bar swaps the two arrow pairs and writes aria-orientation. |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | sl-menubar | The step every trigger and every menu on the bar takes. |
+| `loop` | `boolean` | true | sl-menubar | Whether the arrows wrap past the ends of the bar. |
+| `typeahead` | `boolean` | true | sl-menubar | Whether typing moves to the trigger whose label begins with it. |
+| `disabled` | `boolean` | false | sl-menubar | A disabled bar opens no menu, and every menu on it reads the same answer. |
+| `aria-label` | `string` | — | sl-menubar | Names the bar. The role has no name of its own to invent, so the consumer gives it one. |
+| `provideMenubarDefaults` | `provider` | — | Application | Sets the orientation, the size, the wrapping and the typeahead once, in the bootstrap or on a route. A bar that states one itself still wins. |
+| `SlMenu` | `component` | — | Inside sl-menubar | The menus on a bar are the menu family unchanged: every capability it has — submenus, options, shortcuts, tone — reaches the bar without a second API. |
+| `MENUBAR_SURFACE` | `injection token` | — | sl-menubar | What the bar provides and a menu reads: the open menu's name, the orientation, the size and the two keys that move between menus. The menu entry point declares it, so the dependency runs one way. |
+| `exportAs` | `template reference` | — | sl-menubar | A template reaches the bar — #bar="slMenubar" — for step() and the resolved axes. |
+| `ng-content` | `projection` | — | sl-menubar | The triggers and the menus are the consumer's own elements, in the order the bar reads them. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `valueChange` | `string \| undefined` | After the bar has opened another menu or closed the one it had, as the write-back half of [(value)]. |
+| `valueChangeRequest` | `ChangeRequest<string>` | Before the bar moves. It carries pointer, keyboard, escape, outsidePress, select, dismiss or programmatic, the originating event, and cancel(). |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `orientation` | `horizontal`, `vertical` | `horizontal` |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `loop` | `true`, `false` | `true` |
+| `typeahead` | `true`, `false` | `true` |
+| `disabled` | `true`, `false` | `false` |
+
+## Rules
+
+- The platform supplies each trigger: it is the consumer's own button, so the press and the two keys are the browser's own. role="menuitem" replaces role="button", because on a bar the control is an item of a composite widget rather than a button in a row.
+- The family supplies the bar's keyboard, as the WAI-ARIA menu and menubar pattern describes it: one tab stop for the whole bar, arrows along its own axis with wrapping, Home and End at the ends, typeahead by name, and — from inside an open menu — the inline arrows closing it and opening the neighbouring one with focus left on the trigger.
+- The bar has no name of its own to invent, so the consumer gives it one with aria-label, which is what a reader hears before the first trigger.
+- A disabled trigger stays focusable and takes aria-disabled rather than the native attribute, so a reader can find a menu that is currently unavailable instead of walking past a gap in the bar.
+
+## Tokens
+
+`--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--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-disabled-background`, `--slotted-disabled-foreground`, `--slotted-duration-short`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-width`, `--slotted-font-family-sans`, `--slotted-font-weight-medium`, `--slotted-menubar-gap`, `--slotted-menubar-highlight`, `--slotted-menubar-highlight-active`, `--slotted-menubar-text`, `--slotted-menubar-trigger-font-weight`, `--slotted-menubar-trigger-radius`, `--slotted-space-1`, `--slotted-text`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`
+
+## Examples
+
+### The bar
+
+Three menus in a header. Pressing one opens it; with one open, moving the pointer along the bar switches menus without another press.
+
+Excerpt — not a complete module
+
+```html
+<sl-menubar aria-label="Main" [(value)]="openMenu">
+  <button [slMenuTriggerFor]="file">File</button>
+  <sl-menu #file value="file">…</sl-menu>
+</sl-menubar>
+```
+
+### Submenus
+
+A bar's menu holds submenus like any other menu, and the inline arrows still move between the bar's own menus once the submenu has closed.
+
+Excerpt — not a complete module
+
+```html
+<sl-menu #file value="file">
+  <button slMenuItem>New</button>
+  <button slMenuItem [slMenuTriggerFor]="exportAs">Export as</button>
+  <sl-menu #exportAs>
+    <button slMenuItem>PDF</button>
+  </sl-menu>
+</sl-menu>
+```
+
+### Options on a bar
+
+A View menu of toggles and a choice, which stay open as they are changed — the bar keeps its menu while the reader turns three things on.
+
+Excerpt — not a complete module
+
+```html
+<sl-menu #view value="view">
+  <button slMenuCheckboxItem [checked]="true">Rulers</button>
+  <sl-menu-radio-group value="fit">
+    <button slMenuRadioItem value="fit">Fit</button>
+  </sl-menu-radio-group>
+</sl-menu>
+```
+
+### Orientation
+
+A sidebar of commands is a vertical menubar: the arrow pairs exchange places, the menus open beside the bar, and aria-orientation says so.
+
+Excerpt — not a complete module
+
+```html
+<sl-menubar aria-label="Workspace" orientation="vertical">
+  <button [slMenuTriggerFor]="project">Project</button>
+  <sl-menu #project value="project">…</sl-menu>
+</sl-menubar>
+```
+
+### States
+
+The trigger whose menu is open keeps its highlight, a disabled trigger stays focusable and opens nothing, and a disabled bar disables every menu on it.
+
+Excerpt — not a complete module
+
+```html
+<sl-menubar aria-label="Main" [disabled]="saving()">
+  <button [slMenuTriggerFor]="window">Window</button>
+  <sl-menu #window value="window" [disabled]="true">…</sl-menu>
+</sl-menubar>
+```
+
+### Keyboard
+
+Tab reaches the bar once and lands where it was left; the inline arrows move between triggers and switch menus while one is open; typing jumps to a menu by name.
+
+Excerpt — not a complete module
+
+```html
+<sl-menubar aria-label="Main" [loop]="true" [typeahead]="true">
+  <button [slMenuTriggerFor]="file">File</button>
+  <sl-menu #file value="file">…</sl-menu>
+</sl-menubar>
+```
+
+### In context
+
+An application header: the bar sits beside a logo and an account control, paints no ground of its own, and takes its size from the provider once.
+
+Excerpt — not a complete module
+
+```ts
+bootstrapApplication(App, { providers: [provideMenubarDefaults({ size: 'sm' })] });
+```