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

package/dist/types/packages/rc-menu-button/src/rc-menu-button.d.ts

@@ -0,0 +1,222 @@
+import { LitElement } from 'lit';
+import { AnchorController, AnchorPlacement, KeyboardNavigationAction } from '@rcarls/rc-common';
+import { RCMenu } from '@rcarls/rc-menu';
+declare global {
+    interface HTMLElementTagNameMap {
+        'rc-menu-button': RCMenuButton;
+    }
+}
+/** Detail payload for the `rc-menu-button-toggle` event. */
+export interface RCMenuButtonToggleEvent {
+    /** Whether the menu transitioned to open (`true`) or closed (`false`). */
+    open: boolean;
+}
+/**
+ * Trigger button that opens an rc-menu popup, following the WAI-ARIA Menu Button pattern.
+ *
+ *
+ * @see {@link https://richardcarls.github.io/rc-webcomponents/components/rc-menu-button rc-menu-button docs}
+ * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/ WAI-ARIA Menu Button pattern}
+ *
+ * @slot trigger - The button element that triggers the menu
+ * @slot indicator - Optional decorative indicator rendered at the trigger's inline end
+ * @slot default - The rc-menu element to display as popup
+ *
+ * @fires rc-menu-button-toggle - Fired when the menu opens or closes
+ *
+ * @cssprop [--rc-menu-button-trigger-block-size=var(--rc-control-block-size)] - Minimum block size of the trigger
+ * @cssprop [--rc-menu-button-trigger-padding-block=var(--rc-control-padding-block)] - Trigger block-axis padding
+ * @cssprop [--rc-menu-button-trigger-padding-inline=var(--rc-control-padding-inline)] - Trigger inline-axis padding
+ * @cssprop [--rc-menu-button-trigger-gap=var(--rc-item-gap)] - Gap between flex children in the trigger
+ * @cssprop [--rc-menu-button-trigger-border=var(--rc-border)] - Trigger border
+ * @cssprop [--rc-menu-button-trigger-radius=var(--rc-control-radius)] - Trigger border radius
+ * @cssprop [--rc-menu-button-trigger-background=var(--rc-button-bg)] - Trigger background
+ * @cssprop [--rc-menu-button-trigger-color=var(--rc-button-text)] - Trigger text color
+ * @cssprop [--rc-menu-button-trigger-transition] - CSS transition applied to the trigger
+ * @cssprop [--rc-menu-button-trigger-hover-background=color-mix(in srgb, Highlight 8%, transparent)] - Trigger hover background
+ * @cssprop [--rc-menu-button-trigger-hover-color=inherit] - Trigger hover text color
+ * @cssprop [--rc-menu-button-trigger-hover-border-color=currentColor] - Trigger hover border color
+ * @cssprop [--rc-menu-button-trigger-open-background=color-mix(in srgb, Highlight 12%, transparent)] - Trigger background when the menu is open
+ * @cssprop [--rc-menu-button-trigger-open-color=inherit] - Trigger text color when the menu is open
+ * @cssprop [--rc-menu-button-trigger-open-border-color=currentColor] - Trigger border color when the menu is open
+ * @cssprop [--rc-menu-button-indicator-size=1em] - Inline and block size of the slotted indicator
+ * @cssprop [--rc-menu-button-indicator-color=currentColor] - Color of the slotted indicator
+ * @cssprop [--rc-menu-button-indicator-inset=var(--rc-menu-button-trigger-padding-inline)] - Indicator distance from the trigger's inline end
+ * @cssprop [--rc-menu-button-icon-size] - Inline size of an `icon-only` trigger's visible box.
+ *   Square by default (equal to `--rc-menu-button-trigger-block-size`); set narrower or wider
+ *   to change only the trigger's width, independent of its height.
+ * @cssprop [--rc-menu-button-touch-target-block-size=3rem] - Minimum accessible touch target
+ *   block size for an `icon-only` trigger. A floor, not a fixed size: has no effect once
+ *   `--rc-menu-button-trigger-block-size` already meets or exceeds it. Grows the shadow-DOM
+ *   trigger wrapper (reserving layout space) and the light-DOM hit-slop (the actual larger
+ *   clickable region) together; the visible trigger itself stays at its own size, centered.
+ * @cssprop [--rc-menu-button-touch-target-inline-size] - Minimum accessible touch target inline
+ *   size for an `icon-only` trigger. Defers to `--rc-menu-button-touch-target-block-size` when
+ *   unset.
+ * @cssprop [--rc-menu-button-touch-target-overlap-inline-start=0px] - Zero by default. A theme
+ *   or consumer sets this on an `icon-only` trigger that sits at a real leading edge (no
+ *   neighbor on that side) to let its touch-target inflation overlap into whatever sits just
+ *   outside the host, such as a container's own edge padding, instead of also reserving layout
+ *   space there.
+ * @cssprop [--rc-menu-button-touch-target-overlap-inline-end=0px] - The trailing-edge
+ *   counterpart to `--rc-menu-button-touch-target-overlap-inline-start`.
+ * @cssprop [--rc-menu-button-popup-duration=150ms] - Popup open/close fade transition duration.
+ *
+ * @csspart root - The root container element
+ * @csspart popup - The popup container element
+ *
+ * @attr open - Whether the menu popup is visible. Controlled mode: host writes silently.
+ * @attr default-open - Initial open state for uncontrolled mode. Ignored after the first
+ *   controlled write to `open`.
+ * @attr orientation - Arrow-key axis for opening the menu. Inherits from a parent
+ *   `rc-menubar` or `[role="menubar"]` when unset.
+ * @attr placement - Preferred placement of the popup relative to the trigger.
+ * @attr icon-only - Hints that the slotted trigger has no visible label, so themes can size
+ *   it and its touch target as an icon button (see `--rc-menu-button-icon-size` and
+ *   `--rc-menu-button-touch-target-*` above). Purely a styling hook; RCMenuButton does not read
+ *   or derive it — set it whenever the trigger is rendered icon-only.
+ */
+export declare class RCMenuButton extends LitElement {
+    static styles: import('lit').CSSResult[];
+    /**
+     * Enables delegatesFocus so the browser routes focus() on the host element
+     * to the slotted trigger button.
+     */
+    static shadowRootOptions: ShadowRootInit;
+    protected static readonly _styledRoots: Set<Document | ShadowRoot>;
+    protected static _ensureBaseStyles(root: Document | ShadowRoot): void;
+    private _defaultOpen;
+    private _open;
+    private _uncontrolledOpen;
+    private _openInitialized;
+    /**
+     * Whether the menu is currently open.
+     *
+     * In controlled mode the host owns this value; writing the property applies
+     * the state silently without dispatching `rc-menu-button-toggle`.
+     */
+    get open(): boolean;
+    /** Applies open state in controlled mode without dispatching an event. */
+    set open(value: boolean | undefined);
+    /**
+     * Initial open state for uncontrolled mode.
+     *
+     * Ignored after the first controlled write; use `open` to update state
+     * programmatically after mount.
+     */
+    get defaultOpen(): boolean;
+    /** Applies the uncontrolled default before any controlled write occurs. */
+    set defaultOpen(value: boolean);
+    /**
+     * Orientation of this menu button, affects which arrow keys open/close the menu.
+     *
+     * If not set, inherits from a parent rc-menubar or element with role="menubar".
+     */
+    orientation: 'horizontal' | 'vertical' | undefined;
+    /** Preferred placement of the popup relative to the trigger button. */
+    placement: AnchorPlacement;
+    /**
+     * Popup placement adjusted for orientation.
+     *
+     * Switches from `bottom-start` to `right-start` when the resolved orientation
+     * is `vertical`, so vertical menubars open submenus to the side.
+     */
+    protected get _effectivePlacement(): AnchorPlacement;
+    /**
+     * Resolved orientation, considering inheritance from parent menubar.
+     * Falls back to 'horizontal' if no orientation is set or inherited.
+     */
+    protected get _resolvedOrientation(): 'horizontal' | 'vertical';
+    /** Shadow DOM root container. Serves as the anchor element for `_anchorCtrl`. */
+    protected _$root: HTMLElement;
+    /** Shadow DOM popup container. Hidden when `open` is `false`. */
+    protected _$popup: HTMLElement;
+    /** Weak reference to the slotted trigger button. */
+    protected _$trigger: WeakRef<HTMLElement> | undefined;
+    /** Weak reference to the slotted `rc-menu` element. */
+    protected _$menu: WeakRef<RCMenu> | undefined;
+    /** Positions the popup relative to the trigger using CSS anchor positioning. */
+    protected _anchorCtrl: AnchorController;
+    /** Bound handler for document click (light dismiss). Stored for `removeEventListener` pairing. */
+    protected _boundHandleDocumentClick: (e: MouseEvent) => void;
+    /**
+     * Watches the host's own `tabindex` attribute so the trigger button's
+     * tabindex can be kept in sync.
+     *
+     * When a parent (e.g. rc-toolbar) places the
+     * host under roving-tabindex management it sets/removes tabindex on the
+     * host; we mirror that to the trigger so it doesn't become an independent
+     * tab stop. When the host has no tabindex the trigger keeps its natural
+     * tabindex=0 for standalone usage.
+     */
+    protected _tabObserver?: MutationObserver;
+    /** Installs the tabindex mutation observer and the document-level click listener. */
+    connectedCallback(): void;
+    /** Disconnects the tabindex observer and removes the document-level click listener. */
+    disconnectedCallback(): void;
+    /**
+     * Opens the menu and moves focus into it.
+     *
+     * @param focusTarget - which item receives initial focus when the menu opens
+     */
+    openMenu(focusTarget?: 'first' | 'last'): void;
+    /**
+     * Closes the menu.
+     *
+     * @param returnFocus - when `true`, returns focus to the trigger button after closing
+     */
+    closeMenu(returnFocus?: boolean): void;
+    /** Toggles the menu between open and closed. */
+    toggleMenu(): void;
+    /** Dispatches the `rc-menu-button-toggle` bubbling composed event with the requested open state. */
+    protected _dispatchToggle(open?: boolean): void;
+    /** Caches a weak reference to the first assigned trigger element and syncs its ARIA and tabindex state. */
+    protected _handleTriggerSlotChange(e: Event): void;
+    /** Tracks optional indicator content so the trigger reserves its inline-end space. */
+    protected _handleIndicatorSlotChange(e: Event): void;
+    /**
+     * Mirrors the host's `tabindex` attribute to the trigger button.
+     *
+     * When a roving-tabindex parent (e.g. rc-toolbar) marks this host inactive
+     * with `tabindex="-1"`, the trigger must also be suppressed so it does not
+     * become an independent tab stop. When the host is the active item
+     * (`tabindex="0"`) or standalone (no tabindex), the trigger retains its
+     * natural focusability so that Chrome's delegatesFocus can route sequential
+     * Tab navigation through the host to the trigger.
+     */
+    protected _syncTriggerTabindex(): void;
+    /**
+     * Overrides the default focus() so that programmatic focus calls (e.g. from
+     * a roving-tabindex parent navigating back to this element via arrow keys)
+     * always reach the trigger.
+     *
+     * Chrome's delegatesFocus will not delegate to a tabindex="-1" element, so
+     * when the toolbar marks this host inactive it suppresses the trigger — and
+     * the next focusItem() call silently fails. Lifting the suppression here and
+     * directly calling trigger.focus() bypasses that restriction.
+     */
+    focus(options?: FocusOptions): void;
+    /** Caches a weak reference to the first assigned `rc-menu` element. */
+    protected _handleMenuSlotChange(e: Event): void;
+    /**
+     * Keyboard navigation handler.
+     *
+     * Opens or closes the menu in response to arrow/Enter/Escape keys.
+     **/
+    protected _onNavigate: (action: KeyboardNavigationAction) => void;
+    /** Prevents the default button action and delegates to `toggleMenu`. */
+    protected _handleTriggerClick(e: MouseEvent): void;
+    /** Closes the menu when an `rc-menu-close` event bubbles up from the popup. */
+    protected _handleMenuClose(): void;
+    /** Closes the menu when an `rc-menu-activate` event bubbles up from the popup. */
+    protected _handleMenuActivate(): void;
+    /** Closes the menu on clicks outside this component (light dismiss). */
+    protected _handleDocumentClick(e: MouseEvent): void;
+    /** Syncs trigger ARIA when `open` changes; updates anchor placement when `placement` or `orientation` change. */
+    protected updated(changedProperties: Map<PropertyKey, unknown>): void;
+    protected _setOpen(open: boolean, dispatch: boolean): void;
+    /** Writes `aria-haspopup` and `aria-expanded` to the trigger button to match the current open state. */
+    protected _syncTriggerAria(): void;
+    protected render(): import('lit').TemplateResult<1>;
+}
+export default RCMenuButton;

package/dist/types/packages/rc-menu-button/src/rc-menu-button.styles.d.ts

@@ -0,0 +1,2 @@
+export declare const menuButtonStyles: import('lit').CSSResult;
+export default menuButtonStyles;

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@rcarls/rc-menu-button",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.0.0-next-20260921045401",
+  "description": "Trigger button that opens an rc-menu popup.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/richardcarls/rc-webcomponents.git",
+    "directory": "packages/rc-menu-button"
+  },
+  "homepage": "https://richardcarls.github.io/rc-webcomponents/components/rc-menu-button",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "module": "./dist/rc-menu-button.js",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/packages/rc-menu-button/src/index.d.ts",
+        "default": "./dist/rc-menu-button.js"
+      }
+    },
+    "./define": {
+      "import": {
+        "types": "./dist/types/packages/rc-menu-button/src/define.d.ts",
+        "default": "./dist/rc-menu-button-define.js"
+      }
+    }
+  },
+  "types": "./dist/types/packages/rc-menu-button/src/index.d.ts",
+  "sideEffects": [
+    "./dist/rc-menu-button-define.js"
+  ],
+  "customElements": "dist/custom-elements.json",
+  "scripts": {
+    "build": "tsc && vite build && cem analyze",
+    "cem:analyze": "cem analyze",
+    "preview": "vite preview",
+    "test:browser": "vitest --run",
+    "test:browser:chrome": "vitest --run --project=chromium",
+    "test:browser:firefox": "vitest --run --project=firefox"
+  },
+  "dependencies": {
+    "@rcarls/rc-common": "0.0.0-next-20260921045401",
+    "@rcarls/rc-menu": "0.0.0-next-20260921045401"
+  },
+  "devDependencies": {
+    "@custom-elements-manifest/analyzer": "0.11.0",
+    "@types/node": "^25.6.0",
+    "@vitest/browser-playwright": "4.1.5",
+    "lit": "^3.0.0",
+    "playwright": "^1.56.0",
+    "rollup": "^4.60.2",
+    "typescript": "~5.9.3",
+    "vite": "^7.1.7",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.0.6",
+    "vitest-browser-lit": "^1.0.1"
+  },
+  "peerDependencies": {
+    "lit": "^3.0.0"
+  }
+}