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

package/dist/docs/menu.md

@@ -0,0 +1,163 @@
+<!-- index: ./index.md -->
+# menu
+
+`data-ui="menu"` · List of actions opened from a trigger.
+
+## Import
+
+```tsx
+import { Menu, MenuCheckboxItem, MenuContent, MenuEmpty, MenuGroup, MenuHeader, MenuItem, MenuItemDescription, MenuItemLabel, MenuRadioGroup, MenuRadioItem, MenuSeparator, MenuTrigger } from '@slotted/react';
+```
+
+## Minimal example
+
+Example
+
+```tsx
+import { Button } from '@slotted/react/button';
+import { Glyph } from '@slotted/react/icon';
+import { Menu, MenuContent, MenuItem, MenuSeparator, MenuTrigger } from '@slotted/react/menu';
+
+export default function MenuBasic() {
+  return (
+    <Menu>
+      <MenuTrigger
+        render={(props) => (
+          <Button {...props} end={<Glyph name="chevron-down" />} variant="outline">
+            Order actions
+          </Button>
+        )}
+      />
+      <MenuContent>
+        <MenuItem>View order</MenuItem>
+        <MenuItem shortcut="Mod+E">Edit order</MenuItem>
+        <MenuItem shortcut="Mod+D">Duplicate</MenuItem>
+        <MenuItem shortcut="Mod+P">Print packing slip</MenuItem>
+        <MenuSeparator />
+        <MenuItem tone="danger">Cancel order…</MenuItem>
+      </MenuContent>
+    </Menu>
+  );
+}
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div, or the element render returns | yes |
+| `content` | div | yes |
+| `header` | div | no |
+| `group` | div | no |
+| `group-label` | div | no |
+| `item` | button, or a when the item is a link | yes |
+| `indicator` | span | no |
+| `icon` | span | no |
+| `label` | span | yes |
+| `description` | span | no |
+| `meta` | span | no |
+| `shortcut` | span | no |
+| `separator` | hr | no |
+| `empty` | div | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `open` | `boolean \| undefined` | — | Menu | Whether the menu is open. Passing it makes the menu controlled for its lifetime; update it from onOpenChange. |
+| `defaultOpen` | `boolean` | false | Menu | Whether an uncontrolled menu starts open. Read once. |
+| `onOpenChange` | `(open, request) => void` | — | Menu | Called before the menu opens or closes, with the reason and the event. The request can be cancelled. |
+| `value` | `string` | — | Menu, MenuRadioGroup, MenuRadioItem | On a Menu inside a Menubar, the name the bar knows it by; a menu on its own needs none. On a MenuRadioGroup, the chosen value, which makes the group controlled. On a MenuRadioItem, the value the item stands for. |
+| `checked` | `boolean \| undefined` | — | MenuCheckboxItem | Whether the option is on. Passing it makes the item controlled. |
+| `defaultChecked` | `boolean` | false | MenuCheckboxItem | Whether an uncontrolled option starts on. |
+| `onCheckedChange` | `(checked, request) => void` | — | MenuCheckboxItem | Called before the option changes, with pointer or keyboard as the reason. |
+| `defaultValue` | `string` | — | MenuRadioGroup | The value an uncontrolled group starts with. |
+| `onValueChange` | `(value, request) => void` | — | MenuRadioGroup | Called before the chosen value changes, with pointer or keyboard as the reason. |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | Menu | The width of the surface and the height of its items. |
+| `side` | `'top' \| 'bottom' \| 'inline-start' \| 'inline-end' \| 'left' \| 'right'` | bottom | Menu | The edge of the trigger the surface opens from. inline-start and inline-end follow the reading direction. |
+| `align` | `'start' \| 'center' \| 'end'` | start | Menu | Where the surface sits along that edge. |
+| `anchor` | `PositionerAnchor \| null` | — | Menu | What the surface is positioned against instead of the trigger, such as a table row or a point. Focus still returns to the trigger. |
+| `finalFocus` | `Element \| RefObject \| string` | the trigger | Menu | Where focus goes when the menu closes, for a trigger that is gone by then, such as the actions button of a deleted row. |
+| `mount` | `'active' \| 'lazy' \| 'eager'` | active | Menu | When the surface is in the document: only while open, from the first open on, or from the start. |
+| `strategy` | `'absolute' \| 'fixed'` | absolute | Menu | The CSS position the layer is placed with. |
+| `closeOnSelect` | `boolean` | true | Menu, MenuItem | Whether running an item closes the menu. Checkbox and radio items keep it open unless they set it themselves. |
+| `loop` | `boolean` | true | Menu | Whether the arrow keys wrap from the last item to the first. |
+| `typeahead` | `boolean` | true | Menu | Whether typing moves focus to the item whose label starts with the typed text. |
+| `openOnHover` | `boolean` | true | Menu | Whether a submenu opens when the pointer rests on its item. |
+| `closeOnEscape` | `boolean` | true | Menu | Whether Escape closes the menu that holds focus. |
+| `closeOnOutsidePress` | `boolean` | true | Menu | Whether a press outside the menu closes every open menu. |
+| `flip` | `boolean` | true | Menu | Whether the surface moves to the opposite side when it would leave the window. |
+| `shift` | `boolean` | true | Menu | Whether the surface slides along its edge to stay in the window. |
+| `hideWhenDetached` | `boolean` | true | Menu | Whether the surface hides once its trigger has scrolled out of view. |
+| `portal` | `boolean` | true | Menu | Whether the layer is rendered at the end of the document. |
+| `disabled` | `boolean` | false | Menu, MenuItem | A disabled menu never opens, and its trigger keeps aria-expanded="false". A disabled item stays focusable and runs nothing. |
+| `loading` | `boolean` | false | MenuContent | Whether the items are on their way. The surface keeps its width, sets aria-busy and shows the MenuEmpty message. |
+| `sideOffset` | `number` | 0 | Menu | Extra distance from the trigger, in pixels, beyond the layer's own gap. |
+| `alignOffset` | `number` | 0 | Menu | Distance along the alignment edge, in pixels. |
+| `collisionPadding` | `number` | 8 | Menu | The distance, in pixels, the surface keeps from the edge of the window. |
+| `submenuOpenDelay` | `number` | 150 | Menu | How long, in milliseconds, the pointer rests on an item before its submenu opens. |
+| `submenuCloseDelay` | `number` | 300 | Menu | How long, in milliseconds, a submenu stays open while the pointer travels toward it without reaching it. |
+| `typeaheadTimeout` | `number` | 500 | Menu | How long, in milliseconds, typed letters keep adding to one search. |
+| `icon` | `ReactNode` | — | MenuItem, MenuTrigger | The icon in the first column of the item. |
+| `description` | `ReactNode` | — | MenuItem | The line under the label, referenced with aria-describedby. |
+| `meta` | `ReactNode` | — | MenuItem, MenuTrigger | A count, a status or the value a submenu holds, in its own column before the shortcut or the chevron. |
+| `shortcut` | `string` | — | MenuItem | A shortcut written as Mod+K, printed for the platform and announced with aria-keyshortcuts. The menu does not bind the key. |
+| `textValue` | `string` | — | MenuItem | The text typeahead matches, when the label does not start with the word a reader would type. |
+| `tone` | `'accent' \| 'secondary' \| 'success' \| 'warning' \| 'danger'` | — | MenuItem | The theme tone of the label, the icon and the highlight. A destructive command takes danger. |
+| `label` | `ReactNode` | — | MenuGroup | The name of the group, rendered as its group-label part. |
+| `render` | `(props) => ReactNode` | — | MenuTrigger, MenuContent, MenuItem | Renders your own element with the wiring, the state attributes and the handlers spread on it. On MenuItem, return an a for a link item. |
+| `MenuDefaultsProvider` | `component` | — | Application | Sets any axis once for every menu under it, and container sets where the layers are rendered. A value set on one menu still wins. |
+| `render` | `prop` | — | MenuTrigger, MenuContent, MenuItem | Replaces the rendered element with your own, keeping the wiring, the state attributes and the handlers. |
+| `MenuHeader` | `component` | — | MenuContent | The block above the commands. Its children are the media, a MenuItemLabel and a MenuItemDescription, and the surface is described by it. |
+| `MenuItemMeta, MenuItemIcon, MenuItemLabel, MenuItemDescription, MenuItemShortcut` | `component` | — | MenuItem children | The parts of an item, for an item written from its parts instead of from props. |
+| `MenuGroupLabel` | `component` | — | MenuGroup | The group-label part, for a label written as a child instead of with label. |
+| `MenuEmpty` | `component` | — | MenuContent | The message shown while loading is set or when the menu holds no items. |
+| `useMenu` | `hook` | — | Inside a Menu | Reads the menu around a part: whether it is open, its resolved axes and toggle(). |
+| `ref` | `prop` | — | Menu | A handle with open(), close() and focus(), for a shortcut your application binds outside the menu. |
+| `native props` | `attributes` | — | Every part | Any attribute the underlying element takes reaches it. Your own onClick, onKeyDown or onPointerEnter runs before the menu's handler, and preventDefault() in it skips the menu's. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onOpenChange` | `(open: boolean, request: MenuChangeRequest)` | 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. |
+| `onCheckedChange` | `(checked: boolean, request: MenuCheckedChangeRequest)` | Before a checkbox item changes. request.reason is pointer or keyboard. |
+| `onValueChange` | `(value: string, request: MenuValueChangeRequest)` | Before a radio group changes its value. request.reason is pointer or keyboard. |
+| `onSelect` | `(event: 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/dist/docs/menubar.json

@@ -0,0 +1,299 @@
+{
+  "family": "menubar",
+  "ui": "menubar",
+  "binding": "react",
+  "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 { Menubar, MenubarDefaultsProvider } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div, or the element render returns",
+          "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": "button",
+          "required": true,
+          "purpose": "One menu's control, as role=\"menuitem\". It is rendered by MenuTrigger inside the bar: the menus on a bar are the menu family unchanged, so the bar itself declares no other part."
+        }
+      ],
+      "api": [
+        {
+          "name": "value",
+          "type": "string | undefined",
+          "defaultValue": "—",
+          "appliesTo": "Menubar",
+          "description": "The menu now open, named by its own value. A bar has at most one, so the state is that name rather than a boolean on each menu."
+        },
+        {
+          "name": "defaultValue",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "Menubar",
+          "description": "The menu an uncontrolled bar starts with open, read once."
+        },
+        {
+          "name": "onValueChange",
+          "type": "(value, request) => void",
+          "defaultValue": "—",
+          "appliesTo": "Menubar",
+          "description": "Asked before the bar moves to another menu, with the reason and the event, and refusable."
+        },
+        {
+          "name": "orientation",
+          "type": "'horizontal' | 'vertical'",
+          "defaultValue": "horizontal",
+          "appliesTo": "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": "Menubar",
+          "description": "The step every trigger and every menu on the bar takes."
+        },
+        {
+          "name": "loop",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "Menubar",
+          "description": "Whether the arrows wrap past the ends of the bar."
+        },
+        {
+          "name": "typeahead",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "Menubar",
+          "description": "Whether typing moves to the trigger whose label begins with it."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Menubar",
+          "description": "A disabled bar opens no menu, and every menu on it reads the same answer."
+        },
+        {
+          "name": "render",
+          "type": "(props) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Menubar",
+          "description": "Renders the consumer's own element as the bar, with the role, the state and the keyboard on it."
+        }
+      ],
+      "composition": [
+        {
+          "name": "MenubarDefaultsProvider",
+          "type": "component",
+          "defaultValue": "—",
+          "appliesTo": "Application",
+          "description": "Sets the orientation, the size, the wrapping and the typeahead once for a subtree. A bar that states one itself still wins."
+        },
+        {
+          "name": "Menu",
+          "type": "component",
+          "defaultValue": "—",
+          "appliesTo": "Inside a 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": "value",
+          "type": "prop",
+          "defaultValue": "—",
+          "appliesTo": "Menu",
+          "description": "The name a menu answers to on the bar. A consumer controlling the bar names its menus; on its own a menu needs none."
+        },
+        {
+          "name": "ref",
+          "type": "prop",
+          "defaultValue": "—",
+          "appliesTo": "Menubar",
+          "description": "A handle carrying focus() and close(), for an application that opens its own menus from a shortcut."
+        },
+        {
+          "name": "native props",
+          "type": "attributes",
+          "defaultValue": "—",
+          "appliesTo": "Menubar",
+          "description": "Anything a div takes reaches the bar, and a consumer's own onKeyDown runs before the family's rather than instead of it."
+        }
+      ],
+      "events": [
+        {
+          "name": "onValueChange",
+          "payload": "(value: string, request: MenubarChangeRequest)",
+          "when": "Before the bar opens another menu or closes the one it has. The request carries pointer, keyboard, escape, outsidePress, select, dismiss or programmatic, the originating event, and cancel()."
+        }
+      ],
+      "accessibility": [
+        "The platform supplies each trigger: it is a native 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: aria-label on the bar, 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 four 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": "tsx",
+      "source": "<Menubar aria-label=\"Main\">\n  <Menu value=\"file\">\n    <MenuTrigger>File</MenuTrigger>\n    <MenuContent>\n      <MenuItem shortcut=\"Mod+N\">New</MenuItem>\n    </MenuContent>\n  </Menu>\n</Menubar>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "bar",
+      "title": "The bar",
+      "note": "Four menus in a header. Pressing one opens it; with one open, moving the pointer along the bar switches menus without another press.",
+      "language": "tsx",
+      "source": "<Menubar aria-label=\"Main\">\n  <Menu value=\"file\">…</Menu>\n  <Menu value=\"edit\">…</Menu>\n  <Menu value=\"view\">…</Menu>\n</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": "tsx",
+      "source": "<Menu value=\"file\">\n  <MenuTrigger>File</MenuTrigger>\n  <MenuContent>\n    <Menu>\n      <MenuTrigger>Export as</MenuTrigger>\n      <MenuContent>\n        <MenuItem>PDF</MenuItem>\n      </MenuContent>\n    </Menu>\n  </MenuContent>\n</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": "tsx",
+      "source": "<MenuContent>\n  <MenuCheckboxItem defaultChecked>Rulers</MenuCheckboxItem>\n  <MenuRadioGroup defaultValue=\"fit\">\n    <MenuRadioItem value=\"fit\">Fit</MenuRadioItem>\n  </MenuRadioGroup>\n</MenuContent>;\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": "tsx",
+      "source": "<Menubar aria-label=\"Workspace\" orientation=\"vertical\">\n  <Menu value=\"project\">…</Menu>\n</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": "tsx",
+      "source": "<Menubar aria-label=\"Main\" disabled={saving}>\n  <Menu disabled value=\"window\">\n    <MenuTrigger>Window</MenuTrigger>\n    <MenuContent>…</MenuContent>\n  </Menu>\n</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": "tsx",
+      "source": "<Menubar aria-label=\"Main\" loop typeahead>\n  <Menu value=\"file\">…</Menu>\n</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": "tsx",
+      "source": "<MenubarDefaultsProvider size=\"sm\">\n  <header>\n    <strong>Acme</strong>\n    <Menubar aria-label=\"Main\">…</Menubar>\n  </header>\n</MenubarDefaultsProvider>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}

package/dist/docs/menubar.md

@@ -0,0 +1,183 @@
+<!-- index: ./index.md -->
+# menubar
+
+`data-ui="menubar"` · Horizontal bar of menus, as in desktop apps.
+
+## Import
+
+```tsx
+import { Menubar, MenubarDefaultsProvider } from '@slotted/react';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<Menubar aria-label="Main">
+  <Menu value="file">
+    <MenuTrigger>File</MenuTrigger>
+    <MenuContent>
+      <MenuItem shortcut="Mod+N">New</MenuItem>
+    </MenuContent>
+  </Menu>
+</Menubar>;
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div, or the element render returns | yes |
+| `trigger` | button | yes |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string \| undefined` | — | Menubar | The menu now open, named by its own value. A bar has at most one, so the state is that name rather than a boolean on each menu. |
+| `defaultValue` | `string` | — | Menubar | The menu an uncontrolled bar starts with open, read once. |
+| `onValueChange` | `(value, request) => void` | — | Menubar | Asked before the bar moves to another menu, with the reason and the event, and refusable. |
+| `orientation` | `'horizontal' \| 'vertical'` | horizontal | Menubar | Which way the bar runs. A vertical bar swaps the two arrow pairs and writes aria-orientation. |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | Menubar | The step every trigger and every menu on the bar takes. |
+| `loop` | `boolean` | true | Menubar | Whether the arrows wrap past the ends of the bar. |
+| `typeahead` | `boolean` | true | Menubar | Whether typing moves to the trigger whose label begins with it. |
+| `disabled` | `boolean` | false | Menubar | A disabled bar opens no menu, and every menu on it reads the same answer. |
+| `render` | `(props) => ReactNode` | — | Menubar | Renders the consumer's own element as the bar, with the role, the state and the keyboard on it. |
+| `MenubarDefaultsProvider` | `component` | — | Application | Sets the orientation, the size, the wrapping and the typeahead once for a subtree. A bar that states one itself still wins. |
+| `Menu` | `component` | — | Inside a 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. |
+| `value` | `prop` | — | Menu | The name a menu answers to on the bar. A consumer controlling the bar names its menus; on its own a menu needs none. |
+| `ref` | `prop` | — | Menubar | A handle carrying focus() and close(), for an application that opens its own menus from a shortcut. |
+| `native props` | `attributes` | — | Menubar | Anything a div takes reaches the bar, and a consumer's own onKeyDown runs before the family's rather than instead of it. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onValueChange` | `(value: string, request: MenubarChangeRequest)` | Before the bar opens another menu or closes the one it has. The request 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 a native 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: aria-label on the bar, 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
+
+Four 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
+
+```tsx
+<Menubar aria-label="Main">
+  <Menu value="file">…</Menu>
+  <Menu value="edit">…</Menu>
+  <Menu value="view">…</Menu>
+</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
+
+```tsx
+<Menu value="file">
+  <MenuTrigger>File</MenuTrigger>
+  <MenuContent>
+    <Menu>
+      <MenuTrigger>Export as</MenuTrigger>
+      <MenuContent>
+        <MenuItem>PDF</MenuItem>
+      </MenuContent>
+    </Menu>
+  </MenuContent>
+</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
+
+```tsx
+<MenuContent>
+  <MenuCheckboxItem defaultChecked>Rulers</MenuCheckboxItem>
+  <MenuRadioGroup defaultValue="fit">
+    <MenuRadioItem value="fit">Fit</MenuRadioItem>
+  </MenuRadioGroup>
+</MenuContent>;
+```
+
+### 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
+
+```tsx
+<Menubar aria-label="Workspace" orientation="vertical">
+  <Menu value="project">…</Menu>
+</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
+
+```tsx
+<Menubar aria-label="Main" disabled={saving}>
+  <Menu disabled value="window">
+    <MenuTrigger>Window</MenuTrigger>
+    <MenuContent>…</MenuContent>
+  </Menu>
+</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
+
+```tsx
+<Menubar aria-label="Main" loop typeahead>
+  <Menu value="file">…</Menu>
+</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
+
+```tsx
+<MenubarDefaultsProvider size="sm">
+  <header>
+    <strong>Acme</strong>
+    <Menubar aria-label="Main">…</Menubar>
+  </header>
+</MenubarDefaultsProvider>;
+```