@rcarls/rc-menu-button 0.0.0-next-20260921045401

package/CHANGELOG.md

@@ -0,0 +1,165 @@
+# @rcarls/rc-menu-button
+
+## 0.0.0-next-20260921045401
+
+### Minor Changes
+
+- 94dc987: `rc-menu-button`'s, `rc-select`'s, and `rc-combobox`'s popup/listbox now fade
+  in and out through CSS alone, using `@starting-style` and a discrete
+  `display`/`overlay` transition, driven by new `--rc-menu-button-popup-duration`,
+  `--rc-select-listbox-duration`, and `--rc-combobox-listbox-duration`
+  properties. `showPopover()`/`hidePopover()` (via `openPopup()`/`closePopup()`)
+  stay synchronous, and nothing waits on the transition finishing.
+
+  These animate opacity only, not a scale or slide transform: all three
+  position their popup with the shared `AnchorController`, which applies its
+  own viewport-clamping `translate` and reads `getBoundingClientRect()` to
+  compute the next correction. A second, CSS-driven transform on the same
+  element and property would fight that positioning math on every open, not
+  only during an edge case.
+
+  `rc-fab-menu` already had a scale-based entrance for its popup (verified safe
+  here: unlike the general `AnchorController` case, this popup isn't
+  collision-clamped), but no exit animation at all and no directional easing.
+  Both are added: the popup now fades and scales back out on close, and enter
+  uses a decelerating curve while exit uses an accelerating one.
+
+### Patch Changes
+
+- Updated dependencies [50d5610]
+- Updated dependencies [4341311]
+  - @rcarls/rc-common@0.0.0-next-20260921045401
+  - @rcarls/rc-menu@0.0.0-next-20260921045401
+
+## 0.6.0
+
+### Minor Changes
+
+- 30eb232: Add icon-only activation-area sizing and Material icon-button variants. Align menu
+  selection and submenu affordances, and keep anchored popups within the viewport
+  across native and fallback positioning.
+- 30eb232: Add `--rc-menu-button-touch-target-overlap-inline-start` and
+  `-inline-end` for an `icon-only` trigger, zero by default. A theme or
+  consumer sets one to let the accessible touch-target inflation on that
+  side overlap into whatever sits just outside the host, such as a toolbar's
+  own edge padding, instead of also reserving layout space there: the
+  visible trigger shifts flush with that edge while the invisible hit
+  region keeps its full accessible size. Mirrors `@rcarls/rc-button`'s own
+  touch-target overlap tokens.
+
+### Patch Changes
+
+- 7382c71: Add a priority-aware action toolbar that moves original controls into an
+  overflow menu. Which actions are promoted is a purely declarative computation
+  from `max-shown` and each action's `data-priority`/authored `slot`, with no
+  runtime measurement of the toolbar's or its children's rendered size: a
+  consumer whose promoted count needs to react to available space owns that
+  decision and writes the resulting `max-shown` value down. Include controlled
+  and uncontrolled open state, keyboard navigation, light dismissal, and a
+  non-Popover fallback.
+
+  Fix `--rc-adaptive-menu-touch-target-overlap-inline-start`/`-end`: the host's
+  own `max-inline-size: 100%` self-referenced a shrink-to-fit ancestor's
+  already-margin-reduced auto size (an app bar's own trailing group, for
+  example), quietly clamping the host back down and canceling the overlap out
+  from under it. The cap now grows by the overlap amount so it only ever bounds
+  the host's real content.
+
+- 57370e4: Align component metadata, aggregate framework typings, development-time native-child
+  validation, controlled menu state, package declarations, and public documentation before the
+  next release.
+- Updated dependencies [7382c71]
+- Updated dependencies [6683eb9]
+- Updated dependencies [ee7ba6c]
+- Updated dependencies [30eb232]
+  - @rcarls/rc-menu@0.6.0
+  - @rcarls/rc-common@0.6.0
+
+## 0.5.0
+
+### Minor Changes
+
+- d33b92f: Use the native Popover API for the popup panel instead of a `hidden` attribute
+  and `z-index`. Removes `--rc-menu-button-popup-z-index`; stacking is now
+  governed by top-layer insertion order.
+
+### Patch Changes
+
+- Updated dependencies [4ae2ef0]
+- Updated dependencies [689340c]
+  - @rcarls/rc-common@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
+
+## 0.4.1
+
+### Patch Changes
+
+- @rcarls/rc-common@0.4.1
+- @rcarls/rc-menu@0.4.1
+
+## 0.4.0
+
+### Minor Changes
+
+- 3e89095: Replace rc-menu's generated submenu glyph with an author-supplied `indicator`
+  slot on rc-menu-button. Keep the decorative indicator inside the trigger bounds,
+  reserve label space for it, and expose theme-neutral size, color, and inset
+  tokens for Material, Substrate, and application themes.
+
+### Patch Changes
+
+- 69e31c1: Document the `open`, `default-open`, and `orientation` attributes in the class
+  JSDoc and package README. Only `placement` had an `@attr` tag, so the
+  generated ApiTable and README were missing three of the four settable
+  attributes.
+- 4cb5551: Fix `defaultOpen` so it no longer reopens the menu after an explicit controlled
+  `open = false` write. The setter compared against the live `_open` value
+  instead of tracking whether a controlled write had occurred, so a common
+  pattern like React always passing `open={false}` left the component thinking
+  it was still uncontrolled.
+- Updated dependencies [e57277f]
+- Updated dependencies [ccca8e2]
+- Updated dependencies [037b1b3]
+- Updated dependencies [3e89095]
+  - @rcarls/rc-common@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
+
+## 0.3.1
+
+### Patch Changes
+
+- @rcarls/rc-common@0.3.1
+- @rcarls/rc-menu@0.3.1
+
+## 0.3.0
+
+### Changed
+
+- Normalize trigger styling around inherited menu-button custom properties.
+- 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

package/README.md

@@ -0,0 +1,169 @@
+# `@rcarls/rc-menu-button`
+
+Trigger button that opens an `rc-menu` popup, following the [WAI-ARIA Menu Button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/).
+
+Docs: [https://richardcarls.github.io/rc-webcomponents/components/rc-menu-button](https://richardcarls.github.io/rc-webcomponents/components/rc-menu-button).
+
+Wraps a trigger element and an `rc-menu` popup, wiring ARIA attributes,
+light-dismiss, and keyboard open/close automatically.
+
+---
+
+## Installation
+
+```bash
+npm install @rcarls/rc-menu-button
+```
+
+## Import
+
+```js
+import '@rcarls/rc-menu-button/define'; // side-effect: registers <rc-menu-button>
+import { RCMenuButton } from '@rcarls/rc-menu-button'; // named class export
+```
+
+`rc-menu-button` depends on `rc-menu`. Ensure both are installed.
+
+---
+
+## Basic usage
+
+Place a trigger element in the `trigger` slot and an `rc-menu` in the default slot.
+
+```html
+<rc-menu-button>
+  <button slot="trigger">File</button>
+  <span slot="indicator" aria-hidden="true">›</span>
+
+  <rc-menu label="File">
+    <button>New</button>
+    <button>Open…</button>
+    <button>Save</button>
+  </rc-menu>
+</rc-menu-button>
+```
+
+The component automatically sets `aria-haspopup="menu"` and `aria-expanded` on
+the trigger, and closes the menu when the user clicks outside or selects an
+item.
+
+---
+
+## API
+
+### Properties / attributes
+
+| Property      | Attribute      | Type                                      | Default          | Description                                                                                                                                                                                               |
+| ------------- | -------------- | ----------------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `open`        | `open`         | `boolean`                                 | `false`          | Whether the menu popup is visible. Reflects to attribute. Controlled mode: host writes silently.                                                                                                          |
+| `defaultOpen` | `default-open` | `boolean`                                 | `false`          | Initial open state for uncontrolled mode. Ignored after the first controlled write to `open`.                                                                                                             |
+| `orientation` | `orientation`  | `'horizontal' \| 'vertical' \| undefined` | `undefined`      | Arrow-key axis for opening the menu. Vertical triggers span their allocated menu-row width. When unset, inherited from a parent `rc-menubar` or `[role="menubar"]` element. Falls back to `'horizontal'`. |
+| `placement`   | `placement`    | `AnchorPlacement`                         | `'bottom-start'` | Preferred placement of the popup relative to the trigger. Switches to `'right-start'` under vertical orientation unless explicitly overridden.                                                            |
+|               | `icon-only`    | boolean attribute                         | absent           | Hints that the trigger has no visible label so themes can apply icon-button sizing and activation-area geometry.                                                                                          |
+
+### CSS custom properties
+
+| Property                                             | Default                                          | Description                                                     |
+| ---------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------- |
+| `--rc-menu-button-trigger-block-size`                | `var(--rc-control-block-size)`                   | Minimum block size of the trigger                               |
+| `--rc-menu-button-trigger-padding-block`             | `var(--rc-control-padding-block)`                | Trigger block-axis padding                                      |
+| `--rc-menu-button-trigger-padding-inline`            | `var(--rc-control-padding-inline)`               | Trigger inline-axis padding                                     |
+| `--rc-menu-button-trigger-gap`                       | `var(--rc-item-gap)`                             | Gap between flex children inside the trigger                    |
+| `--rc-menu-button-trigger-border`                    | `var(--rc-border)`                               | Trigger border                                                  |
+| `--rc-menu-button-trigger-radius`                    | `var(--rc-control-radius)`                       | Trigger border radius                                           |
+| `--rc-menu-button-trigger-background`                | `var(--rc-button-bg)`                            | Trigger background                                              |
+| `--rc-menu-button-trigger-color`                     | `var(--rc-button-text)`                          | Trigger text color                                              |
+| `--rc-menu-button-trigger-transition`                | `none`                                           | Trigger state transition                                        |
+| `--rc-menu-button-trigger-hover-background`          | `color-mix(in srgb, Highlight 8%, transparent)`  | Trigger hover background                                        |
+| `--rc-menu-button-trigger-hover-color`               | `inherit`                                        | Trigger hover text color                                        |
+| `--rc-menu-button-trigger-hover-border-color`        | `currentColor`                                   | Trigger hover border color                                      |
+| `--rc-menu-button-trigger-open-background`           | `color-mix(in srgb, Highlight 12%, transparent)` | Trigger background while the menu is open                       |
+| `--rc-menu-button-trigger-open-color`                | `inherit`                                        | Trigger text color while the menu is open                       |
+| `--rc-menu-button-trigger-open-border-color`         | `currentColor`                                   | Trigger border color while the menu is open                     |
+| `--rc-menu-button-indicator-size`                    | `1em`                                            | Inline and block size reserved for the optional indicator       |
+| `--rc-menu-button-indicator-color`                   | `currentColor`                                   | Color of the optional indicator                                 |
+| `--rc-menu-button-indicator-inset`                   | Trigger inline padding                           | Indicator distance from the trigger's inline end                |
+| `--rc-menu-button-icon-size`                         | Trigger block size                               | Visible inline size of an `icon-only` trigger                   |
+| `--rc-menu-button-touch-target-block-size`           | `3rem`                                           | Minimum block size of an `icon-only` trigger's activation area  |
+| `--rc-menu-button-touch-target-inline-size`          | Activation-area block size                       | Minimum inline size of an `icon-only` trigger's activation area |
+| `--rc-menu-button-touch-target-overlap-inline-start` | `0px`                                            | Allows touch-target inflation to overlap the leading neighbor   |
+| `--rc-menu-button-touch-target-overlap-inline-end`   | `0px`                                            | Allows touch-target inflation to overlap the trailing neighbor  |
+
+### CSS parts
+
+| Part    | Element     | Description                                             |
+| ------- | ----------- | ------------------------------------------------------- |
+| `root`  | Outer `div` | Root wrapper                                            |
+| `popup` | Popup `div` | Container that shows/hides around the slotted `rc-menu` |
+
+### Slots
+
+| Slot        | Description                                                                                                                                    |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `trigger`   | The button (or other interactive element) that toggles the menu. Receives `aria-haspopup` and `aria-expanded` automatically.                   |
+| `indicator` | Optional author-supplied decorative submenu indicator. Rendered at the trigger's inline end with pointer events passed through to the trigger. |
+| _(default)_ | The `rc-menu` to show as the popup.                                                                                                            |
+
+### Events
+
+| Event                   | Bubbles        | Cancelable | Detail              | When                 |
+| ----------------------- | -------------- | ---------- | ------------------- | -------------------- |
+| `rc-menu-button-toggle` | Yes (composed) | No         | `{ open: boolean }` | Menu opens or closes |
+
+### Public methods
+
+```ts
+openMenu(focusTarget?: 'first' | 'last'): void
+  // Open the menu. Focuses the first or last item after render.
+
+closeMenu(returnFocus?: boolean): void
+  // Close the menu. If returnFocus is true (default), restores focus to the trigger.
+
+toggleMenu(): void
+  // Toggle open/closed.
+```
+
+---
+
+## Keyboard behavior
+
+Keyboard handling depends on the resolved `orientation` (horizontal by
+default, or inherited from a parent menubar).
+
+| Key               | Condition              | Action                              |
+| ----------------- | ---------------------- | ----------------------------------- |
+| `ArrowDown`       | Horizontal orientation | Open menu, focus first item         |
+| `ArrowUp`         | Horizontal orientation | Open menu, focus last item          |
+| `ArrowRight`      | Vertical orientation   | Open menu, focus first item         |
+| `ArrowLeft`       | Vertical orientation   | Open menu, focus last item          |
+| `Enter` / `Space` | Menu closed            | Open menu                           |
+| `Enter` / `Space` | Menu open              | Activate focused item, close menu   |
+| `Escape`          | Menu open              | Close menu, return focus to trigger |
+
+---
+
+## ARIA
+
+| Attribute              | Where           | Value                                          |
+| ---------------------- | --------------- | ---------------------------------------------- |
+| `aria-haspopup="menu"` | Trigger element | Set automatically on slot change               |
+| `aria-expanded`        | Trigger element | `"true"` / `"false"`, kept in sync with `open` |
+| `open`                 | Host element    | Reflected boolean attribute when menu is open  |
+
+---
+
+## Notes
+
+**Popup positioning** uses `AnchorController`, with native CSS Anchor
+Positioning when available and a viewport-aware fallback otherwise. Set the
+`placement` property or attribute to choose the preferred direction.
+
+**Light dismiss** is active at all times. A capture-phase `click` listener on
+`document` closes the menu whenever the click falls outside the component
+boundary (checked via `composedPath()`).
+
+---
+
+## Browser support
+
+All modern browsers. Requires Web Components support (Chrome 67+, Firefox 63+, Safari 12.1+).