@hanifhan1f/vidstack 1.12.13

package/src/components/ui/menu/menu-button.ts

@@ -0,0 +1,95 @@
+import { Component, effect, onDispose, prop, signal, useContext } from 'maverick.js';
+import { DOMEvent } from 'maverick.js/std';
+
+import { FocusVisibleController } from '../../../foundation/observers/focus-visible';
+import { onPress, setAttributeIfEmpty } from '../../../utils/dom';
+import { menuContext, type MenuContext } from './menu-context';
+
+/**
+ * A button that controls the opening and closing of a menu component. The button will become a
+ * menuitem when used inside a submenu.
+ *
+ * @attr data-root - Whether this is the root menu button.
+ * @attr data-submenu - Whether menu button is part of a submenu.
+ * @attr data-open - Whether menu is currently open.
+ * @attr data-focus - Whether button is being keyboard focused.
+ * @attr data-hocus - Whether button is being keyboard focused or hovered over.
+ * @docs {@link https://www.vidstack.io/docs/player/components/menu/menu}
+ */
+export class MenuButton extends Component<MenuButtonProps, {}, MenuButtonEvents> {
+  static props: MenuButtonProps = {
+    disabled: false,
+  };
+
+  #menu!: MenuContext;
+  #hintEl = signal<HTMLElement | null>(null);
+
+  @prop
+  get expanded() {
+    return this.#menu?.expanded() ?? false;
+  }
+
+  constructor() {
+    super();
+    new FocusVisibleController();
+  }
+
+  protected override onSetup(): void {
+    this.#menu = useContext(menuContext);
+  }
+
+  protected override onAttach(el: HTMLElement) {
+    this.#menu.attachMenuButton(this);
+    effect(this.#watchDisabled.bind(this));
+    setAttributeIfEmpty(el, 'type', 'button');
+  }
+
+  protected override onConnect(el: HTMLElement) {
+    effect(this.#watchHintEl.bind(this));
+
+    this.#onMutation();
+    const mutations = new MutationObserver(this.#onMutation.bind(this));
+    mutations.observe(el, { attributeFilter: ['data-part'], childList: true, subtree: true });
+    onDispose(() => mutations.disconnect());
+
+    onPress(el, (trigger) => {
+      this.dispatch('select', { trigger });
+    });
+  }
+
+  #watchDisabled() {
+    this.#menu.disableMenuButton(this.$props.disabled());
+  }
+
+  #watchHintEl() {
+    const el = this.#hintEl();
+    if (!el) return;
+    effect(() => {
+      const text = this.#menu.hint();
+      if (text) el.textContent = text;
+    });
+  }
+
+  #onMutation() {
+    const hintEl = this.el?.querySelector<HTMLElement>('[data-part="hint"]');
+    this.#hintEl.set(hintEl ?? null);
+  }
+}
+
+export interface MenuButtonProps {
+  /**
+   * Whether the button should be disabled (non-interactive).
+   */
+  disabled: boolean;
+}
+
+export interface MenuButtonEvents {
+  select: MenuButtonSelectEvent;
+}
+
+/**
+ * Fired when the button is pressed via mouse, touch, or keyboard.
+ */
+export interface MenuButtonSelectEvent extends DOMEvent<void> {
+  target: MenuButton;
+}

package/src/components/ui/menu/menu-context.ts

@@ -0,0 +1,27 @@
+import { createContext, type ReadSignal, type WriteSignal } from 'maverick.js';
+
+import type { Menu } from './menu';
+import type { MenuButton } from './menu-button';
+import type { MenuItems } from './menu-items';
+
+export interface MenuContext {
+  readonly submenu: boolean;
+  readonly expanded: ReadSignal<boolean>;
+  readonly hint: WriteSignal<string>;
+  readonly button: ReadSignal<HTMLElement | null>;
+  readonly content: ReadSignal<HTMLElement | null>;
+  attachMenuButton(button: MenuButton): void;
+  attachMenuItems(menuItems: MenuItems): void;
+  attachObserver(observer: MenuObserver): void;
+  disable(disable: boolean): void;
+  disableMenuButton(disable: boolean): void;
+  addSubmenu(menu: Menu): void;
+  onTransitionEvent(callback: (event: TransitionEvent) => void): void;
+}
+
+export interface MenuObserver {
+  onOpen?(trigger?: Event): void;
+  onClose?(trigger?: Event): void;
+}
+
+export const menuContext = createContext<MenuContext>();

package/src/components/ui/menu/menu-focus-controller.ts

@@ -0,0 +1,205 @@
+import { onDispose } from 'maverick.js';
+import { EventsController, listenEvent, wasEnterKeyPressed } from 'maverick.js/std';
+
+import { isElementParent, isHTMLElement } from '../../../utils/dom';
+import { scrollIntoCenter } from '../../../utils/scroll';
+
+const FOCUSABLE_ELEMENTS_SELECTOR = /* #__PURE__*/ [
+  'a[href]',
+  '[tabindex]',
+  'input',
+  'select',
+  'button',
+]
+  .map((selector) => `${selector}:not([aria-hidden='true'])`)
+  .join(',');
+
+const VALID_KEYS = /* #__PURE__*/ new Set([
+  'Escape',
+  'Tab',
+  'ArrowUp',
+  'ArrowDown',
+  'Home',
+  'PageUp',
+  'End',
+  'PageDown',
+  'Enter',
+  ' ',
+]);
+
+export interface MenuFocusControllerDelegate {
+  closeMenu(trigger?: Event): void;
+}
+
+export class MenuFocusController {
+  #index = -1;
+  #el: HTMLElement | null = null;
+  #elements: HTMLElement[] = [];
+  #delegate: MenuFocusControllerDelegate;
+
+  get items() {
+    return this.#elements;
+  }
+
+  constructor(delegate: MenuFocusControllerDelegate) {
+    this.#delegate = delegate;
+  }
+
+  attachMenu(el: HTMLElement) {
+    listenEvent(el, 'focus', this.#onFocus.bind(this));
+
+    this.#el = el;
+    onDispose(() => {
+      this.#el = null;
+    });
+  }
+
+  listen() {
+    if (!this.#el) return;
+
+    this.update();
+
+    new EventsController(this.#el)
+      .add('keyup', this.#onKeyUp.bind(this))
+      .add('keydown', this.#onKeyDown.bind(this));
+
+    onDispose(() => {
+      this.#index = -1;
+      this.#elements = [];
+    });
+  }
+
+  update() {
+    this.#index = 0;
+    this.#elements = this.#getFocusableElements();
+  }
+
+  scroll(index = this.#findActiveIndex()) {
+    const element = this.#elements[index];
+    if (element) {
+      requestAnimationFrame(() => {
+        requestAnimationFrame(() => {
+          scrollIntoCenter(element, {
+            behavior: 'smooth',
+            boundary: (el) => {
+              return !el.hasAttribute('data-root');
+            },
+          });
+        });
+      });
+    }
+  }
+
+  focusActive(scroll = true) {
+    const index = this.#findActiveIndex();
+    this.#focusAt(index >= 0 ? index : 0, scroll);
+  }
+
+  #focusAt(index: number, scroll = true) {
+    this.#index = index;
+    if (this.#elements[index]) {
+      this.#elements[index].focus({ preventScroll: true });
+      if (scroll) this.scroll(index);
+    } else {
+      this.#el?.focus({ preventScroll: true });
+    }
+  }
+
+  #findActiveIndex() {
+    return this.#elements.findIndex(
+      (el) =>
+        document.activeElement === el ||
+        (el.getAttribute('role') === 'menuitemradio' && el.getAttribute('aria-checked') === 'true'),
+    );
+  }
+
+  #onFocus() {
+    if (this.#index >= 0) return;
+    this.update();
+    this.focusActive();
+  }
+
+  #validateKeyEvent(event: KeyboardEvent) {
+    const el = event.target;
+
+    if (wasEnterKeyPressed(event) && el instanceof Element) {
+      const role = el.getAttribute('role');
+      return !/a|input|select|button/.test(el.localName) && !role;
+    }
+
+    return VALID_KEYS.has(event.key);
+  }
+
+  #onKeyUp(event: KeyboardEvent) {
+    if (!this.#validateKeyEvent(event)) return;
+
+    event.stopPropagation();
+    event.preventDefault();
+  }
+
+  #onKeyDown(event: KeyboardEvent) {
+    if (!this.#validateKeyEvent(event)) return;
+
+    event.stopPropagation();
+    event.preventDefault();
+
+    switch (event.key) {
+      case 'Escape':
+        this.#delegate.closeMenu(event);
+        break;
+      case 'Tab':
+        this.#focusAt(this.#nextIndex(event.shiftKey ? -1 : +1));
+        break;
+      case 'ArrowUp':
+        this.#focusAt(this.#nextIndex(-1));
+        break;
+      case 'ArrowDown':
+        this.#focusAt(this.#nextIndex(+1));
+        break;
+      case 'Home':
+      case 'PageUp':
+        this.#focusAt(0);
+        break;
+      case 'End':
+      case 'PageDown':
+        this.#focusAt(this.#elements.length - 1);
+        break;
+    }
+  }
+
+  #nextIndex(delta: number) {
+    let index = this.#index;
+    do {
+      index = (index + delta + this.#elements.length) % this.#elements.length;
+    } while (this.#elements[index]?.offsetParent === null);
+    return index;
+  }
+
+  #getFocusableElements() {
+    if (!this.#el) return [];
+
+    const focusableElements = this.#el!.querySelectorAll(FOCUSABLE_ELEMENTS_SELECTOR),
+      elements: HTMLElement[] = [];
+
+    const is = (node: Element) => {
+      return node.getAttribute('role') === 'menu';
+    };
+
+    for (const el of focusableElements) {
+      // Filter out elements that belong to child submenus.
+      if (
+        isHTMLElement(el) &&
+        el.offsetParent !== null && // does not have display: none
+        isElementParent(this.#el, el, is)
+      ) {
+        elements.push(el);
+      }
+    }
+
+    return elements;
+  }
+}
+
+export function getMenuController(el: HTMLElement) {
+  return document.getElementById(el.getAttribute('aria-describedby')!);
+}

package/src/components/ui/menu/menu-item.ts

@@ -0,0 +1,9 @@
+import { MenuButton } from './menu-button';
+
+/**
+ * Represents a specific option or action, typically displayed as a text label or icon, which
+ * users can select to access or perform a particular function or view related content.
+ *
+ * @docs {@link https://www.vidstack.io/docs/player/components/menu/menu}
+ */
+export class MenuItem extends MenuButton {}

package/src/components/ui/menu/menu-items.ts

@@ -0,0 +1,129 @@
+import {
+  Component,
+  effect,
+  hasProvidedContext,
+  onDispose,
+  provideContext,
+  useContext,
+} from 'maverick.js';
+
+import { FocusVisibleController } from '../../../foundation/observers/focus-visible';
+import { autoPlacement } from '../../../utils/dom';
+import { menuContext, type MenuContext } from './menu-context';
+import { menuPortalContext } from './menu-portal';
+
+/**
+ * Menu items can be used to display settings or arbitrary content in a floating panel.
+ *
+ * @attr data-root - Whether this is the root menu items.
+ * @attr data-submenu - Whether menu items are part of a submenu.
+ * @attr data-open - Whether menu items are currently visible.
+ * @attr data-keyboard - Whether the menu is opened via keyboard.
+ * @attr data-placement - The placement prop setting.
+ * @attr data-focus - Whether item are being keyboard focused.
+ * @attr data-hocus - Whether items are being keyboard focused or hovered over.
+ * @attr data-transition - Whether the menu is resizing.
+ * @docs {@link https://www.vidstack.io/docs/player/components/menu/menu}
+ */
+export class MenuItems extends Component<MenuItemsProps> {
+  static props: MenuItemsProps = {
+    placement: null,
+    offset: 0,
+    alignOffset: 0,
+  };
+
+  #menu!: MenuContext;
+
+  constructor() {
+    super();
+
+    new FocusVisibleController();
+
+    const { placement } = this.$props;
+    this.setAttributes({
+      'data-placement': placement,
+    });
+  }
+
+  protected override onAttach(el: HTMLElement) {
+    this.#menu = useContext(menuContext);
+    this.#menu.attachMenuItems(this);
+    if (hasProvidedContext(menuPortalContext)) {
+      const portal = useContext(menuPortalContext);
+      if (portal) {
+        // Remove portal so submenus don't attach.
+        provideContext(menuPortalContext, null);
+        portal.attach(el);
+        onDispose(() => portal.attach(null));
+      }
+    }
+  }
+
+  protected override onConnect(el: HTMLElement): void {
+    effect(this.#watchPlacement.bind(this));
+  }
+
+  #watchPlacement() {
+    const { expanded } = this.#menu;
+
+    if (!this.el || !expanded()) return;
+
+    const placement = this.$props.placement();
+    if (!placement) return;
+
+    Object.assign(this.el.style, {
+      position: 'absolute',
+      top: 0,
+      left: 0,
+      width: 'max-content',
+    });
+
+    const { offset: mainOffset, alignOffset } = this.$props;
+
+    onDispose(
+      autoPlacement(this.el, this.#getButton(), placement, {
+        offsetVarName: 'media-menu',
+        xOffset: alignOffset(),
+        yOffset: mainOffset(),
+      }),
+    );
+
+    onDispose(this.#hide.bind(this));
+  }
+
+  #hide() {
+    if (!this.el) return;
+    this.el.removeAttribute('style');
+    this.el.style.display = 'none';
+  }
+
+  #getButton() {
+    return this.#menu.button();
+  }
+}
+
+export type MenuPlacement = MenuPlacementSide | `${MenuPlacementSide} ${MenuPlacementAlign}`;
+
+export type MenuPlacementSide = 'top' | 'right' | 'bottom' | 'left';
+export type MenuPlacementAlign = 'start' | 'center' | 'end';
+
+export interface MenuItemsProps {
+  /**
+   * A space-separated list which specifies the side and alignment of the menu relative
+   * to the menu button.
+   *
+   * @example `top center`
+   * @example `bottom end`
+   */
+  placement: MenuPlacement | null;
+  /**
+   * The distance in pixels between the menu items and the menu button. You can also set
+   * the CSS variable `--media-menu-y-offset` to adjust this offset.
+   */
+  offset: number;
+  /**
+   * The offset in pixels from the start/center/end aligned position. You can also set
+   * the CSS variable `--media-menu-x-offset` to adjust this offset.
+   */
+  alignOffset: number;
+}

package/src/components/ui/menu/menu-portal.ts

@@ -0,0 +1,105 @@
+import { Component, createContext, effect, provideContext } from 'maverick.js';
+import { setAttribute } from 'maverick.js/std';
+
+import { useMediaContext, type MediaContext } from '../../../core/api/media-context';
+import { isHTMLElement, requestScopedAnimationFrame } from '../../../utils/dom';
+
+/**
+ * Portals menu items into the document body.
+ *
+ * @attr data-portal - Whether portal is active (determined by `disabled` prop).
+ * @docs {@link https://www.vidstack.io/docs/player/components/menu#portal}
+ */
+export class MenuPortal extends Component<MenuPortalProps> {
+  static props: MenuPortalProps = {
+    container: null,
+    disabled: false,
+  };
+
+  #target: HTMLElement | null = null;
+  #media!: MediaContext;
+
+  protected override onSetup(): void {
+    this.#media = useMediaContext();
+    provideContext(menuPortalContext, {
+      attach: this.#attachElement.bind(this),
+    });
+  }
+
+  protected override onAttach(el: HTMLElement): void {
+    el.style.setProperty('display', 'contents');
+  }
+
+  // Need this so connect scope is defined.
+  protected override onConnect(el: HTMLElement): void {
+    // no-op
+  }
+
+  protected override onDestroy(): void {
+    this.#target?.remove();
+    this.#target = null;
+  }
+
+  #attachElement(el: HTMLElement | null) {
+    this.#portal(false);
+    this.#target = el;
+    // Wait two animations frames: first is for connected callback, second is to allow icon
+    // slots to be replaced.
+    requestScopedAnimationFrame(() => {
+      requestScopedAnimationFrame(() => {
+        if (!this.connectScope) return;
+        effect(this.#watchDisabled.bind(this));
+      });
+    });
+  }
+
+  #watchDisabled() {
+    const { fullscreen } = this.#media.$state,
+      { disabled } = this.$props;
+    this.#portal(disabled() === 'fullscreen' ? !fullscreen() : !disabled());
+  }
+
+  #portal(shouldPortal: boolean) {
+    if (!this.#target) return;
+
+    let container = this.#getContainer(this.$props.container());
+    if (!container) return;
+
+    const isPortalled = this.#target.parentElement === container;
+    setAttribute(this.#target, 'data-portal', shouldPortal);
+
+    if (shouldPortal) {
+      if (!isPortalled) {
+        this.#target.remove();
+        container!.append(this.#target);
+      }
+    } else if (isPortalled && this.#target.parentElement === container) {
+      this.#target.remove();
+      this.el?.append(this.#target);
+    }
+  }
+
+  #getContainer(selector: MenuPortalProps['container']) {
+    if (isHTMLElement(selector)) return selector;
+    return selector ? document.querySelector<HTMLElement>(selector) : document.body;
+  }
+}
+
+export interface MenuPortalProps {
+  /**
+   * Specifies a DOM element or query selector for the container that the menu should be portalled
+   * inside. Defaults to `document.body` when set to `null`.
+   */
+  container: string | HTMLElement | null;
+  /**
+   * Whether the portal should be disabled. The value can be the string "fullscreen" to disable
+   * portals while media is fullscreen. This is to ensure the menu remains visible.
+   */
+  disabled: boolean | 'fullscreen';
+}
+
+export interface MenuPortalContext {
+  attach(element: HTMLElement | null): void;
+}
+
+export const menuPortalContext = createContext<MenuPortalContext | null>();