@rcarls/rc-menubar 0.0.0-next-20260921045401

package/CHANGELOG.md

@@ -0,0 +1,107 @@
+# @rcarls/rc-menubar
+
+## 0.0.0-next-20260921045401
+
+### Patch Changes
+
+- Updated dependencies [50d5610]
+- Updated dependencies [4341311]
+- Updated dependencies [94dc987]
+  - @rcarls/rc-common@0.0.0-next-20260921045401
+  - @rcarls/rc-menu-button@0.0.0-next-20260921045401
+  - @rcarls/rc-menu@0.0.0-next-20260921045401
+
+## 0.6.0
+
+### Patch Changes
+
+- Updated dependencies [7382c71]
+- Updated dependencies [6683eb9]
+- Updated dependencies [ee7ba6c]
+- Updated dependencies [30eb232]
+- Updated dependencies [30eb232]
+- Updated dependencies [57370e4]
+  - @rcarls/rc-menu@0.6.0
+  - @rcarls/rc-menu-button@0.6.0
+  - @rcarls/rc-common@0.6.0
+
+## 0.5.0
+
+### Patch Changes
+
+- Updated dependencies [4ae2ef0]
+- Updated dependencies [d33b92f]
+- Updated dependencies [689340c]
+  - @rcarls/rc-common@0.5.0
+  - @rcarls/rc-menu-button@0.5.0
+  - @rcarls/rc-menu@0.5.0
+
+## 0.4.2
+
+### Patch Changes
+
+- @rcarls/rc-common@0.4.2
+- @rcarls/rc-menu@0.4.2
+- @rcarls/rc-menu-button@0.4.2
+
+## 0.4.1
+
+### Patch Changes
+
+- @rcarls/rc-common@0.4.1
+- @rcarls/rc-menu@0.4.1
+- @rcarls/rc-menu-button@0.4.1
+
+## 0.4.0
+
+### Patch Changes
+
+- 1ba0be2: Document the `label` and `orientation` attributes in the class JSDoc, and fix
+  the package README's read-only getters and `focusItem()` signature to use the
+  `$`-prefixed names the component has shipped for some time (`$items`,
+  `$menuButtons`, `$firstItem`, `$lastItem`, `$nextItem`, `$previousItem`).
+- Updated dependencies [e57277f]
+- Updated dependencies [69e31c1]
+- Updated dependencies [4cb5551]
+- Updated dependencies [ccca8e2]
+- Updated dependencies [037b1b3]
+- Updated dependencies [3e89095]
+  - @rcarls/rc-common@0.4.0
+  - @rcarls/rc-menu-button@0.4.0
+  - @rcarls/rc-menu@0.4.0
+
+## 0.3.2
+
+### Patch Changes
+
+- Updated dependencies [88b4086]
+  - @rcarls/rc-common@0.3.2
+  - @rcarls/rc-menu@0.3.2
+  - @rcarls/rc-menu-button@0.3.2
+
+## 0.3.1
+
+### Patch Changes
+
+- @rcarls/rc-common@0.3.1
+- @rcarls/rc-menu@0.3.1
+- @rcarls/rc-menu-button@0.3.1
+
+## 0.3.0
+
+### Changed
+
+- Configure child menu-button triggers through a flat inherited token contract.
+- Update package metadata, README intro, and docs links.
+
+### Dependencies
+
+- Sync internal dependencies to 0.3.0.
+
+## 0.2.0
+
+### Patch Changes
+
+- @rcarls/rc-common@0.2.0
+- @rcarls/rc-menu@0.2.0
+- @rcarls/rc-menu-button@0.2.0

package/README.md

@@ -0,0 +1,172 @@
+# `@rcarls/rc-menubar`
+
+Menubar coordinator for `rc-menu-button` children with roving tabindex and submenu handoff, following the [WAI-ARIA Menubar pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/).
+
+Docs: [https://richardcarls.github.io/rc-webcomponents/components/rc-menubar](https://richardcarls.github.io/rc-webcomponents/components/rc-menubar).
+
+Manages roving tabindex across `rc-menu-button` triggers and cascades menu open/close as the user navigates. Built with [Lit 3](https://lit.dev).
+
+---
+
+## Installation
+
+```bash
+npm install @rcarls/rc-menubar
+```
+
+## Import
+
+```js
+import '@rcarls/rc-menubar/define'; // side-effect: registers <rc-menubar>
+import { RCMenubar } from '@rcarls/rc-menubar'; // named class export
+```
+
+`rc-menubar` depends on `rc-menu-button` and `rc-menu`. Ensure all three are installed.
+
+---
+
+## Basic usage
+
+Place `rc-menu-button` elements as direct children. The menubar manages focus and opens the appropriate menu as the user navigates.
+
+```html
+<rc-menubar label="Application menu">
+  <rc-menu-button>
+    <button slot="trigger">File</button>
+    <rc-menu label="File">
+      <button>New</button>
+      <button>Open…</button>
+      <button>Save</button>
+    </rc-menu>
+  </rc-menu-button>
+
+  <rc-menu-button>
+    <button slot="trigger">Edit</button>
+    <rc-menu label="Edit">
+      <button>Undo</button>
+      <button>Redo</button>
+      <button>Cut</button>
+      <button>Copy</button>
+      <button>Paste</button>
+    </rc-menu>
+  </rc-menu-button>
+
+  <rc-menu-button>
+    <button slot="trigger">View</button>
+    <rc-menu label="View">
+      <button>Zoom In</button>
+      <button>Zoom Out</button>
+    </rc-menu>
+  </rc-menu-button>
+</rc-menubar>
+```
+
+---
+
+## API
+
+### Properties / attributes
+
+| Property      | Attribute     | Type                         | Default        | Description                                                                                                                |
+| ------------- | ------------- | ---------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `label`       | `label`       | `string`                     | `'Menu'`       | `aria-label` for the menubar. Required — no visible label is rendered by the component.                                    |
+| `orientation` | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction and keyboard navigation axis. Propagated to child `rc-menu-button` elements for arrow-key open direction. |
+
+### CSS custom properties
+
+| Property                               | Default                                          | Description                                       |
+| -------------------------------------- | ------------------------------------------------ | ------------------------------------------------- |
+| `--rc-menubar-gap`                     | `var(--rc-control-gap)`                          | Gap between menu buttons                          |
+| `--rc-menubar-padding-inline`          | `var(--rc-control-padding-inline)`               | Inline padding on the menubar container           |
+| `--rc-menubar-padding-block`           | `var(--rc-control-padding-block)`                | Block padding on the menubar container            |
+| `--rc-menubar-border`                  | `var(--rc-border)`                               | Menubar container border                          |
+| `--rc-menubar-radius`                  | `var(--rc-control-radius)`                       | Menubar container border radius                   |
+| `--rc-menubar-background`              | `Canvas`                                         | Menubar container background                      |
+| `--rc-menubar-color`                   | `CanvasText`                                     | Menubar container text color                      |
+| `--rc-menubar-item-block-size`         | `2.25em`                                         | Minimum block size for child menu-button triggers |
+| `--rc-menubar-item-padding-block`      | `0.25em`                                         | Child trigger block-axis padding                  |
+| `--rc-menubar-item-padding-inline`     | `0.75em`                                         | Child trigger inline-axis padding                 |
+| `--rc-menubar-item-gap`                | `var(--rc-item-gap)`                             | Gap between flex children inside child triggers   |
+| `--rc-menubar-item-border`             | `1px solid transparent`                          | Child trigger border                              |
+| `--rc-menubar-item-radius`             | `var(--rc-control-radius)`                       | Child trigger border radius                       |
+| `--rc-menubar-item-background`         | `transparent`                                    | Child trigger background                          |
+| `--rc-menubar-item-color`              | `inherit`                                        | Child trigger text color                          |
+| `--rc-menubar-item-transition`         | —                                                | Child trigger state transition                    |
+| `--rc-menubar-item-hover-background`   | `color-mix(in srgb, Highlight 8%, transparent)`  | Child trigger hover background                    |
+| `--rc-menubar-item-hover-color`        | `inherit`                                        | Child trigger hover text color                    |
+| `--rc-menubar-item-hover-border-color` | `transparent`                                    | Child trigger hover border color                  |
+| `--rc-menubar-item-open-background`    | `color-mix(in srgb, Highlight 12%, transparent)` | Child trigger background while its menu is open   |
+| `--rc-menubar-item-open-color`         | `inherit`                                        | Child trigger text color while its menu is open   |
+| `--rc-menubar-item-open-border-color`  | `transparent`                                    | Child trigger border color while its menu is open |
+
+### CSS parts
+
+| Part   | Element     | Description                  |
+| ------ | ----------- | ---------------------------- |
+| `root` | Inner `div` | The visual menubar container |
+
+### Slots
+
+| Slot        | Description                                                                                             |
+| ----------- | ------------------------------------------------------------------------------------------------------- |
+| _(default)_ | `rc-menu-button` elements. Non-menu-button elements are rendered but excluded from keyboard navigation. |
+
+### Events
+
+`rc-menubar` dispatches no events of its own. Listen for `rc-menu-button-toggle` and `rc-menu-activate` bubbling up from child components.
+
+### Public methods
+
+```ts
+focusItem($item?: HTMLElement | null): void
+  // Focus a specific trigger element.
+
+closeActiveMenu(): void
+  // Close the currently open menu without returning focus to the trigger.
+```
+
+### Read-only getters
+
+```ts
+$items: HTMLElement[]           // All trigger elements across all child rc-menu-buttons
+$menuButtons: RCMenuButton[]    // All child rc-menu-button elements
+$firstItem: HTMLElement | undefined
+$lastItem: HTMLElement | undefined
+$nextItem: HTMLElement | undefined    // Relative to last-focused trigger
+$previousItem: HTMLElement | undefined
+```
+
+---
+
+## Keyboard behaviour
+
+Horizontal orientation (default):
+
+| Key          | Action                                                                               |
+| ------------ | ------------------------------------------------------------------------------------ |
+| `ArrowRight` | Focus next trigger (wraps); if a menu is open, closes current and opens next         |
+| `ArrowLeft`  | Focus previous trigger (wraps); if a menu is open, closes current and opens previous |
+| `Home`       | Focus first trigger                                                                  |
+| `End`        | Focus last trigger                                                                   |
+| `Escape`     | Close the active menu; focus remains on trigger                                      |
+| `Tab`        | Leaves the menubar (standard tab order)                                              |
+
+For vertical orientation, `ArrowDown`/`ArrowUp` replace `ArrowRight`/`ArrowLeft`. The `rc-menu-button` children automatically inherit the menubar's orientation to determine their own open-axis arrow keys.
+
+---
+
+## ARIA
+
+| Attribute          | Where              | Value                                            |
+| ------------------ | ------------------ | ------------------------------------------------ |
+| `role="menubar"`   | Host element       | —                                                |
+| `aria-orientation` | Host element       | `"horizontal"` or `"vertical"`                   |
+| `aria-label`       | Host element       | Value of `label` property                        |
+| `tabindex="0"`     | Active trigger     | One trigger tabbable at a time (roving tabindex) |
+| `tabindex="-1"`    | All other triggers | Removed from tab order                           |
+
+---
+
+## Browser support
+
+All modern browsers. Requires Web Components support (Chrome 67+, Firefox 63+, Safari 12.1+).