/**
 * `<context-menu-ui>` — Right-click activated menu — the OS-native context-menu pattern as a
web component. Distinct from `menu-ui` (which is button-triggered):
same item shape (`menu-item-ui` children), different trigger surface
(`contextmenu` event), and pointer-anchored positioning instead of
element-anchored. Pattern: WAI-APG Menu.

Two binding modes:
 **A. Wrap.** Default-slot child becomes the target:
 `<context-menu-ui><my-table>...</my-table>...items</context-menu-ui>`.
 **B. Selector.** Point at one or more existing elements via [for]:
 `<context-menu-ui for="#my-table">...items</context-menu-ui>`.

On `contextmenu` event on a target: `preventDefault()`, position the
menu at the pointer coords, show via Popover API. Touch long-press
(configurable via [long-press-ms]) does the same. Shift+F10 / Menu
key opens at the focused target's center for keyboard users.

 *
 * @see https://ui-kit.exe.xyz/site/components/context-menu
 *
 * Type declarations generated by scripts/build/dts-codegen.mjs from
 * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
 * run `npm run build:components`, then `npm run codegen:dts` to
 * regenerate; or hand-author this file fully if rich event types are
 * needed beyond what the yaml `events:` block can express.
 */

import { UIElement } from '../../core/element.js';

export interface ContextMenuCloseEventDetail {
  /** "select" | "outside" | "escape" */
  reason: string;
}

export type ContextMenuCloseEvent = CustomEvent<ContextMenuCloseEventDetail>;
export interface ContextMenuOpenEventDetail {
  /** The target element the menu was opened on. */
  target: string;
  /** Pointer x coord (viewport-relative); null for keyboard activation. */
  x: number;
  /** Pointer y coord; null for keyboard activation. */
  y: number;
}

export type ContextMenuOpenEvent = CustomEvent<ContextMenuOpenEventDetail>;
export interface ContextMenuSelectEventDetail {
  /** Selected item's text. */
  text: string;
  /** Selected item's value. */
  value: string;
}

export type ContextMenuSelectEvent = CustomEvent<ContextMenuSelectEventDetail>;

export class UIContextMenu extends UIElement {
  /** CSS selector(s) for target element(s). Empty = use default-slot child. */
  for: string;
  /** Programmatic open state. Set true to open at target center. */
  open: boolean;

  addEventListener<K extends keyof HTMLElementEventMap>(
    type: K,
    listener: (this: UIContextMenu, ev: HTMLElementEventMap[K]) => unknown,
    options?: boolean | AddEventListenerOptions,
  ): void;
  addEventListener(type: 'context-menu-close', listener: (ev: ContextMenuCloseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
  addEventListener(type: 'context-menu-open', listener: (ev: ContextMenuOpenEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
  addEventListener(type: 'context-menu-select', listener: (ev: ContextMenuSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
}
