@greypan/web-ui 11.2.0 → 12.0.0

package/dist/components/context-menu/index.d.ts

@@ -1,314 +1,311 @@
-import { LitElement } from 'lit';
+import { LitElement } from "lit";
 export declare class WebUiContextMenu extends LitElement {
-    static styles: import('lit').CSSResult;
-    disabled: boolean;
-    noScrollLock: boolean;
-    /** opt-in：触屏长按打开 menu。默认关闭，鼠标路径靠原生 contextmenu，无需此属性。 */
-    longPress: boolean;
-    private _longPressDelay;
-    /**
-     * 走包内既有的 `normalizeNumber` 通道（与 `dropdown.offset`、`popover.offset` 同形）。
-     * 不能只靠 `Math.max(0, …)` 挡负数：`Math.max(0, NaN) === NaN`，而属性写错
-     * （`long-press-delay="abc"`）时 Lit 的 Number converter 给的正是 NaN，
-     * `setTimeout(fn, NaN)` 会立刻触发，长按就在 pointerdown 同一帧开 menu、绕过全部时长语义。
-     */
-    get longPressDelay(): number;
-    set longPressDelay(v: number);
-    private _isOpen;
-    private _x;
-    private _y;
-    private _activeSubmenus;
-    private _activeSubmenuItems;
-    private _longPressTimer;
-    private _longPressOrigin;
-    /**
-     * 长按自行开 menu 的时刻。浏览器会为**同一次触摸**补发两个事件，二者都属于
-     * 那一次意图，不是两次独立操作：
-     *
-     * - 原生 `contextmenu`：长按被识别时立刻派发，会重复打开（`_openAt` 走已开分支）。
-     * - 合成 `click`：`touchend` 之后由引擎补发，会把刚打开的 menu 立刻 light-dismiss。
-     *   实测真实触控管线下的顺序为 pointerdown(9ms) → 长按开 menu(≈509ms) →
-     *   touchend(1019ms) → click(1022ms)，缺这一步 menu 开了就被自己的补发事件关掉。
-     *
-     * 因此在窗口内吸收这两个补发事件；窗口由下一次 `pointerdown` 关闭。
-     */
-    private _longPressOpenedAt;
-    /**
-     * 长按手势结束（pointerup）的时刻，补发事件窗口的起点。
-     *
-     * 为 null 表示「这次长按的手势还没结束」——窗口退回以 menu 打开时刻为起点。手势被
-     * pointercancel 打断、或组件在抬手前就被卸载时都会走到这条兜底，行为与此前一致。
-     */
-    private _longPressGestureEndedAt;
-    private readonly _submenuPositionEpochs;
-    private _menu?;
-    /**
-     * 模态 scrim。menu 打开期间存在并处于 `showModal()` 状态，关闭时随 panel 一起移除。
-     *
-     * panel 必须**显式**挂进它（`createMenuPortalOverlay` 的第三参）：`resolveOverlayContainer`
-     * 查的是 target 的**祖先**里有无已打开的 dialog，而 scrim 是 panel 的反方向，祖先发现查不到。
-     */
-    private _scrim?;
-    /**
-     * 本次开启是否**水平居中于触发点**（触屏长按路径）。鼠标 / 键盘路径仍左上角对齐光标。
-     *
-     * 只切换 placement 的对齐量，不切换定位算法 —— 两条入口共用 `_positionMenu` 里的
-     * 同一套 `computePosition` + `flip` / `shift`，垂直契约（上缘对齐触发点、向下展开、
-     * 放不下翻到上方）完全一致。
-     *
-     * 触屏要居中：手指按下去的位置是「这块内容在这里」的意思，menu 在它正下方居中展开，
-     * 正是 iOS / Android 原生长按 menu 的形态；左对齐会让 menu 整体偏到手指右侧，看起来像
-     * 弹在了别的东西上面。
-     *
-     * 鼠标不居中：桌面右键的肌肉记忆是 menu**左上角**出现在光标处。更要紧的是居中会让光标
-     * 落在 panel 上缘正中 —— 也就是落在第一项的命中区里。后果是 menu 一开就有项处于 hover 高亮，
-     * 并且紧接着再右键一次（想开 submenu）会打在 menu item 上而不是空白处。`overlay-in-dialog`
-     * 里 `openAt(100, 400)` 那条用例钉的 `'top left'` 正是这条契约。
-     *
-     * 判据是**开启来源**（调用点显式传入），不靠运行时嗅探 pointerType 或视口宽度：
-     * 后两者会让同一块屏幕上的两种输入拿到两套布局，且与本组件 opt-in 的 `long-press`
-     * 属性不同源。
-     */
-    private _centerOnPressPoint;
-    /**
-     * 本次关闭的来源，决定焦点归还走哪条路。语义见 `close()` 里的说明。
-     *
-     * 只有 menu item 激活这一条需要抢在退场之前出顶层；点外面 / Escape / 程序式关闭一律
-     * 保留 dialog 默认效果 —— 那正是用户「回到原处」的期望。
-     */
-    private _closeSource;
-    /**
-     * 触发「menu item 激活」的那次事件对象；作用域与理由见 `_onMenuItemActivation`。
-     *
-     * 存**事件**而不是布尔标志：判定「这次 `close()` 是不是发生在这一次派发里」可以问事件自己
-     * （`eventPhase !== 0`），不必用定时器去近似。布尔标志只能靠「派发结束时清掉」来划界，
-     * 而划界的那一步必须与派发末尾落在同一个任务、同一个微任务检查点之后——那是个会错的假设。
-     *
-     * 存在的理由是 `close()` 的出顶层判定不能只看 `_closeSource`：消费方完全可以在自己的
-     * menu item 回调里直接调 `close()`（interweave 的右键重命名就是 `emit` 之后自己关），
-     * 那时 `_closeSource` 还是 `'default'`，scrim 就一直留在 top layer 里没退出，
-     * 消费方随后把焦点送进编辑器的动作落在 inert 文档上被浏览器静默丢弃。
-     *
-     * 消费方先关、组件后关的路径（`_onMenuClick` 的 `_closeFromUser('menu-item')`）随后看到的是
-     * `'menu-item'`，两条判定同向，不会互相抵消。
-     */
-    private _menuItemActivationEvent;
-    /** 根 panel 的开启会话 handle；未开启时为 null。查询走它。 */
-    private _menuHandle;
-    /**
-     * submenu panel → 会话 handle。子层经 `adopt` 进根 handle 子树（默认不成为独立候选），
-     * 但仍各自持有 handle：整层关闭或收尾动画结束时按 panel 精确撤销。
-     */
-    private readonly _submenuHandles;
-    private readonly _outsideClickGuard;
-    private readonly _closingSubmenus;
-    private readonly _hoverDelegate;
-    private readonly _hoverBinder;
-    private readonly _keyboardDelegate;
-    private readonly _overlay;
-    private readonly _menuItemAnchors;
-    private readonly _scrollLock;
-    private readonly _userOpenChange;
-    private _shouldOpenInstantly;
-    private _suppressInitialFocusVisible;
-    private _refreshScheduled;
-    private readonly _menuPositionGeneration;
-    private readonly _contentObserver;
-    get isOpen(): boolean;
-    connectedCallback(): void;
-    disconnectedCallback(): void;
-    protected updated(changed: Map<string, unknown>): void;
-    /**
-     * 在指定视口坐标打开 menu。
-     * @param x 水平坐标（px）。
-     * @param y 垂直坐标（px）。
-     * @returns 无返回值；命令式打开不派发 `open-change` 事件。
-     */
-    openAt(x: number, y: number): void;
-    private _openAt;
-    /**
-     * 关闭 menu。
-     * @returns 无返回值；命令式关闭不派发 `open-change` 事件。
-     */
-    close(): void;
-    /**
-     * 「当前是否正处在一次可激活 menu item 的点击派发里」。
-     *
-     * 判据是 `eventPhase !== 0`（DOM 规范：派发开始前置 CAPTURING_PHASE，结束后由派发算法的
-     * terminating 步骤置回 NONE），即**事件自己知道它此刻有没有在派发中**。于是作用域精确等于
-     * 「这一次派发」，既不需要定时器也不需要猜微任务检查点的位置：
-     *
-     * - 消费方在条目自己的监听器里同步调 `close()` → 派发未结束 → 判定为真（要的就是这个）。
-     * - 消费方 `stopPropagation()` 让 menu 留着 → 派发照样结束 → 之后的 Escape / 点外面 / 程序式
-     *   `close()` 一律判定为假，README 承诺的「那三条关闭不抢焦点」不会被这一次点击污染。
-     * - 消费方把 `close()` 推到下一个任务 → 判定为假，退回不提前出顶层（与没有这个标记时一致）。
-     */
-    private _isDispatchingMenuItemActivation;
-    private readonly _closeFromUser;
-    private _scheduleRefresh;
-    private _refreshMenu;
-    /**
-     * 定位：**触屏长按与鼠标右键共用这一条 Floating UI 路径**。
-     *
-     * 两条入口现在只差「触发点的 x/y 从哪来」，布局契约完全一致：
-     * `bottom-start` 表达「panel 上缘 == 触发点 y、向下展开」，水平以触发点 x 为基准。
-     * 之前有一条手写的贴底分支（先按点、再按视口下缘算 `top`），那是把「贴视口底」硬编码
-     * 成算术；真机反馈证明它错（menu 跑到屏幕最底部，与手指按下的位置完全脱节）。现在
-     * 落点交给 `flip` / `shift` 按**实际空间**决定，`placement` 只表达意图。
-     *
-     * 不再按「是否触屏」分流：窄视口的鼠标右键同样期望 menu 贴着光标出现，按输入类型或视口
-     * 宽度分流会让同一块屏幕上的两种输入拿到两套布局。分流所需的 `_anchorAtPressPoint`
-     * 连同 `_positionMenuInViewport` / `_positionMenuAtPressPoint` 两个方法一起删掉 ——
-     * panel 恒为 open scrim `<dialog>` 的直接子节点（`createMenuPortalOverlay` 第三参传入
-     * scrim，`menu-portal.ts` 里 `container = scrim ?? …`），所以旧代码那条
-     * 「非 dialog 容器」的分支对 context-menu 本来就不可达。
-     *
-     * 算出来的 left/top 是**视口坐标**。panel 是 `position: fixed`，而 scrim 刻意不带
-     * transform / filter / contain（见 style.css），因此不构成 fixed 的包含块 ——
-     * 坐标直接相对视口解析。这条等价关系由 style.css 的满屏声明保证，并由 R6 的
-     * 「scrim 无 transform/filter/contain」+ viewport-fit 的几何断言兜底。
-     */
-    private _positionMenu;
-    /**
-     * 视口下缘的安全区高度（px）。
-     *
-     * 改按压点展开之后它**仍然必需**，而且不再只服务触屏：menu 默认从触发点向下长，触发点
-     * 落在屏幕下半部时 panel 下缘会进入 home indicator 区域。它现在折进 flip 与 shift 共用的
-     * 边界 padding（见 `_positionMenu`），不再需要单独一条 `maxBottom` 算术。
-     *
-     * 读宿主的自定义属性而不是 `env()`：自定义属性读回的是**计算后**的解析值，
-     * 而 `env()` 在 JS 里没有对应的求值入口，只能间接经由声明它的属性取。
-     * 属性未解析时 `parseFloat` 得 NaN，落到 0 —— 与 `env(..., 0px)` 的缺省一致。
-     */
-    private _safeAreaBottom;
-    /**
-     * 写下 panel 坐标与进场 transform 的原点。
-     *
-     * 两个 origin 必传且**不**再回退成坐标比较：flip 会改变垂直方向，回退表达式
-     * `y < this._y ? 'bottom' : 'top'` 在「panel 顶边与触发点重合」时两边都成立，等于随机取。
-     * 唯一调用方从 flip 后的 placement 与 shift 位移推出真实侧边，见 `_positionMenu`。
-     */
-    private _applyMenuPosition;
-    /**
-     * 把焦点带进 menu 的第一项。
-     *
-     * `attempt` 是重试计数：menu item 是刚被 `reconcileManagedMenuItems` 搬进来的自定义元素，
-     * 它们的 shadow（`.item-inner`）由各自的 Lit 更新**异步**渲染。`focusMenuItem()` 委托给
-     * 项的 `focusItem()`，那一刻 `.item-inner` 还不存在，于是**静默无操作** —— 不抛错、
-     * 也不留痕，只表现为「menu 开了但焦点没进去」。
-     *
-     * 所以这里不假设一次成功：调用后用 `findFocusedMenuItem` 复核，没落上就在下一帧再试，
-     * 最多 `FOCUS_FIRST_ITEM_ATTEMPTS` 次。上界是必要的 —— menu item 若始终渲染不出来
-     * （空 menu、内容被外部换掉），不能让重试链一直跑下去。
-     */
-    private _focusFirstItem;
-    private _setupMenuItems;
-    private _returnItemsToSlot;
-    /**
-     * 建 scrim 并让它进入模态态，返回容器供 panel 挂载。
-     *
-     * 每次开启都新建而不是复用：scrim 的生命周期必须与「这一次开启」严格同进同出。
-     * 复用一个 dialog 意味着上一轮的 `close()` 事件、`open` 属性与 UA 记下的焦点还原目标
-     * 会跨会话残留，而这些都不是本组件能重置的。
-     */
-    private _openScrim;
-    /**
-     * scrim 的挂载点：**与 panel 在没有 scrim 时会落到的容器同源** —— 最近主题的 theme-owned
-     * overlay root。scrim 就是那个容器的替身（panel 必须挂进 scrim，见 `updated()` 的顺序注释），
-     * 所以它得站在容器该站的位置上。
-     *
-     * 为什么不能在整棵 DOM 里随便挑位置：`--wui-color-*` 由 `<web-ui-theme>` 写在自己的 `:host`
-     * 上，只沿 DOM 树向下继承。scrim 若挂到 `document.body`，而 `<web-ui-theme>` 是 body 的**子节点**，
-     * 这条继承链就断了 —— panel 与 scrim 双双落回 `var(--wui-color-*, <浅色字面量>)` 的 fallback，
-     * 深色外观下 menu 是一块浅色玻璃（app 侧的 `dark:` 变体也够不到它）。挂进 theme overlay root
-     * 之后，panel 与 scrim 跟 dropdown / select 一样吃同一份 token。
-     *
-     * 无主题时保持历史行为挂在 `document.body`：那条路径本来就没有 token 作用域可继承，改用
-     * fallback overlay root 只会改变既有测试与消费者的观察面，不换来任何东西。
-     */
-    private _scrimParent;
-    /**
-     * 关掉并摘除 scrim。幂等：关闭分支与 `disconnectedCallback` 都会调。
-     *
-     * `close()` 触发 UA 的焦点归还，**必须先于 panel `remove()`** —— 理由见 `_closeMenuAfterPresence`。
-     */
-    private _closeScrim;
-    /**
-     * 只让 scrim 出顶层，不摘除元素。panel 挂在 scrim 里，摘了就把退场动画一起摘掉。
-     *
-     * 提前出顶层是为了焦点（理由见 `close()`）。代价是这个尾巴上 scrim 已经在 top layer
-     * 之外：下层恢复可命中，且 panel 的层级退回普通流 —— 在「menu 开在 drawer/dialog 之上」
-     * 的场景里，退场动画会被下层的 top layer 盖住。
-     *
-     * 这条尾巴只有一次退场过渡的时长（默认 160ms），且只发生在 menu item 激活时。
-     * 摘除仍在 `_closeScrim()`，那时 panel 已经走完。
-     */
-    private _releaseScrimModality;
-    /**
-     * 点 scrim = 关 menu（Q12：必关，不给 prop option），与 dialog / drawer 的实现同形：
-     * 只有落点就是 scrim 本身才算「点外面」，落在 panel（scrim 的后代）上不算。
-     *
-     * 落点判据之所以只能是这两个，是模态给的：menu 打开期间下层收不到命中，事件只可能
-     * 落在 scrim 或 panel 上，两者都由本组件判定。
-     *
-     * 更早的实现在 document 捕获阶段挂 click 监听，把「点外面」理解成「命中测试落在 menu
-     * panel 之外」—— 宿主 light DOM 的每一行都满足这个条件，于是判定与行激活成了同一个
-     * click 的两个后果，中间没有任何仲裁，下层目标先被激活。那条监听器连同它的实现已一并
-     * 删除：模态化之后它没有任何还能生效的场景，别再挂回来。
-     */
-    private _onScrimClick;
-    /**
-     * Escape 的**唯一**关闭路径仍是共享仲裁者（`_overlay.requestClose` → `closeDeepestOrAll`），
-     * 它按层深决定是关最深 submenu 还是关整张 menu。原生 dialog 自己也监听 Escape 并派发
-     * `cancel`，若放任默认行为，UA 会直接关掉 scrim —— 那条路径不经过组件状态机，
-     * 既可能漏派 `open-change`，也会把「关最深一层」的语义降级成「整张 menu 没了」。
-     *
-     * 因此这里只吞掉默认行为，不重复关闭。仲裁者那条路径已经会走 `_closeFromUser()`。
-     */
-    private _onScrimCancel;
-    private _closeMenuAfterPresence;
-    private _hideMenuItems;
-    private _openSubmenu;
-    private _closeSubmenusFrom;
-    private _restoreSubmenuItems;
-    private _getItemLevel;
-    private _positionSubmenu;
-    private _dispatchChange;
-    private _onPointerDown;
-    private _onPointerMove;
-    private _onPointerUp;
-    private _onPointerCancel;
-    private _cancelLongPress;
-    /** 该事件是否是长按开 menu 之后、浏览器为同一次触摸补发的事件。 */
-    private _isLongPressFollowUp;
-    /** 结束「同一次手势的补发事件」窗口。与 _longPressOpenedAt 的清零同源，两处都要清。 */
-    private _clearLongPressFollowUp;
-    private _onContextMenu;
-    private _onContextMenuOutside;
-    private _onKeydown;
-    private _onMenuItemActivation;
-    private _onMenuClick;
-    private _getLevelContainer;
-    private _getLevelItems;
-    private _onWheel;
-    private _onTouchMove;
-    private _onDocumentKeydown;
-    private _closeLastSubmenuOrMenu;
-    private _preventBackgroundScroll;
-    private _syncScrollLock;
-    /** 按 panel 撤销一层 submenu 的登记；handle 已随根层递归撤销时幂等无操作。 */
-    private _releaseSubmenu;
-    private _isMenuPanelEvent;
-    render(): import('lit').TemplateResult<1>;
-    private _onSlotChange;
-    readonly $events: {
-        'open-change': CustomEvent<{
-            open: boolean;
-        }>;
-    };
+  static styles: import("lit").CSSResult;
+  disabled: boolean;
+  noScrollLock: boolean;
+  /** opt-in：触屏长按打开 menu。默认关闭，鼠标路径靠原生 contextmenu，无需此属性。 */
+  longPress: boolean;
+  private _longPressDelay;
+  /**
+   * 走包内既有的 `normalizeNumber` 通道（与 `dropdown.offset`、`popover.offset` 同形）。
+   * 不能只靠 `Math.max(0, …)` 挡负数：`Math.max(0, NaN) === NaN`，而属性写错
+   * （`long-press-delay="abc"`）时 Lit 的 Number converter 给的正是 NaN，
+   * `setTimeout(fn, NaN)` 会立刻触发，长按就在 pointerdown 同一帧开 menu、绕过全部时长语义。
+   */
+  get longPressDelay(): number;
+  set longPressDelay(v: number);
+  private _isOpen;
+  private _x;
+  private _y;
+  private _activeSubmenus;
+  private _activeSubmenuItems;
+  private _longPressTimer;
+  private _longPressOrigin;
+  /**
+   * 长按自行开 menu 的时刻。浏览器会为**同一次触摸**补发两个事件，二者都属于
+   * 那一次意图，不是两次独立操作：
+   *
+   * - 原生 `contextmenu`：长按被识别时立刻派发，会重复打开（`_openAt` 走已开分支）。
+   * - 合成 `click`：`touchend` 之后由引擎补发，会把刚打开的 menu 立刻 light-dismiss。
+   *   实测真实触控管线下的顺序为 pointerdown(9ms) → 长按开 menu(≈509ms) →
+   *   touchend(1019ms) → click(1022ms)，缺这一步 menu 开了就被自己的补发事件关掉。
+   *
+   * 因此在窗口内吸收这两个补发事件；窗口由下一次 `pointerdown` 关闭。
+   */
+  private _longPressOpenedAt;
+  /**
+   * 长按手势结束（pointerup）的时刻，补发事件窗口的起点。
+   *
+   * 为 null 表示「这次长按的手势还没结束」——窗口退回以 menu 打开时刻为起点。手势被
+   * pointercancel 打断、或组件在抬手前就被卸载时都会走到这条兜底。
+   */
+  private _longPressGestureEndedAt;
+  private readonly _submenuPositionEpochs;
+  private _menu?;
+  /**
+   * 模态 scrim。menu 打开期间存在并处于 `showModal()` 状态，关闭时随 panel 一起移除。
+   *
+   * panel 必须**显式**挂进它（`createMenuPortalOverlay` 的第三参）：`resolveOverlayContainer`
+   * 查的是 target 的**祖先**里有无已打开的 dialog，而 scrim 是 panel 的反方向，祖先发现查不到。
+   */
+  private _scrim?;
+  /**
+   * 本次开启是否**水平居中于触发点**（触屏长按路径）。鼠标 / 键盘路径仍左上角对齐光标。
+   *
+   * 只切换 placement 的对齐量，不切换定位算法 —— 两条入口共用 `_positionMenu` 里的
+   * 同一套 `computePosition` + `flip` / `shift`，垂直契约（上缘对齐触发点、向下展开、
+   * 放不下翻到上方）完全一致。
+   *
+   * 触屏要居中：手指按下去的位置是「这块内容在这里」的意思，menu 在它正下方居中展开，
+   * 正是 iOS / Android 原生长按 menu 的形态；左对齐会让 menu 整体偏到手指右侧，看起来像
+   * 弹在了别的东西上面。
+   *
+   * 鼠标不居中：桌面右键的肌肉记忆是 menu**左上角**出现在光标处。更要紧的是居中会让光标
+   * 落在 panel 上缘正中 —— 也就是落在第一项的命中区里。后果是 menu 一开就有项处于 hover 高亮，
+   * 并且紧接着再右键一次（想开 submenu）会打在 menu item 上而不是空白处。`overlay-in-dialog`
+   * 里 `openAt(100, 400)` 那条用例钉的 `'top left'` 正是这条契约。
+   *
+   * 判据是**开启来源**（调用点显式传入），不靠运行时嗅探 pointerType 或视口宽度：
+   * 后两者会让同一块屏幕上的两种输入拿到两套布局，且与本组件 opt-in 的 `long-press`
+   * 属性不同源。
+   */
+  private _centerOnPressPoint;
+  /**
+   * 本次关闭的来源，决定焦点归还走哪条路。语义见 `close()` 里的说明。
+   *
+   * 只有 menu item 激活这一条需要抢在退场之前出顶层；点外面 / Escape / 程序式关闭一律
+   * 保留 dialog 默认效果 —— 那正是用户「回到原处」的期望。
+   */
+  private _closeSource;
+  /**
+   * 触发「menu item 激活」的那次事件对象；作用域与理由见 `_onMenuItemActivation`。
+   *
+   * 存**事件**而不是布尔标志：判定「这次 `close()` 是不是发生在这一次派发里」可以问事件自己
+   * （`eventPhase !== 0`），不必用定时器去近似。布尔标志只能靠「派发结束时清掉」来划界，
+   * 而划界的那一步必须与派发末尾落在同一个任务、同一个微任务检查点之后——那是个会错的假设。
+   *
+   * 存在的理由是 `close()` 的出顶层判定不能只看 `_closeSource`：消费方完全可以在自己的
+   * menu item 回调里直接调 `close()`（interweave 的右键重命名就是 `emit` 之后自己关），
+   * 那时 `_closeSource` 还是 `'default'`，scrim 就一直留在 top layer 里没退出，
+   * 消费方随后把焦点送进编辑器的动作落在 inert 文档上被浏览器静默丢弃。
+   *
+   * 消费方先关、组件后关的路径（`_onMenuClick` 的 `_closeFromUser('menu-item')`）随后看到的是
+   * `'menu-item'`，两条判定同向，不会互相抵消。
+   */
+  private _menuItemActivationEvent;
+  /** 根 panel 的开启会话 handle；未开启时为 null。查询走它。 */
+  private _menuHandle;
+  /**
+   * submenu panel → 会话 handle。子层经 `adopt` 进根 handle 子树（默认不成为独立候选），
+   * 但仍各自持有 handle：整层关闭或收尾动画结束时按 panel 精确撤销。
+   */
+  private readonly _submenuHandles;
+  private readonly _outsideClickGuard;
+  private readonly _closingSubmenus;
+  private readonly _hoverDelegate;
+  private readonly _hoverBinder;
+  private readonly _keyboardDelegate;
+  private readonly _overlay;
+  private readonly _menuItemAnchors;
+  private readonly _scrollLock;
+  private readonly _userOpenChange;
+  private _shouldOpenInstantly;
+  private _suppressInitialFocusVisible;
+  private _refreshScheduled;
+  private readonly _menuPositionGeneration;
+  private readonly _contentObserver;
+  get isOpen(): boolean;
+  connectedCallback(): void;
+  disconnectedCallback(): void;
+  protected updated(changed: Map<string, unknown>): void;
+  /**
+   * 在指定视口坐标打开 menu。
+   * @param x 水平坐标（px）。
+   * @param y 垂直坐标（px）。
+   * @returns 无返回值；命令式打开不派发 `open-change` 事件。
+   */
+  openAt(x: number, y: number): void;
+  private _openAt;
+  /**
+   * 关闭 menu。
+   * @returns 无返回值；命令式关闭不派发 `open-change` 事件。
+   */
+  close(): void;
+  /**
+   * 「当前是否正处在一次可激活 menu item 的点击派发里」。
+   *
+   * 判据是 `eventPhase !== 0`（DOM 规范：派发开始前置 CAPTURING_PHASE，结束后由派发算法的
+   * terminating 步骤置回 NONE），即**事件自己知道它此刻有没有在派发中**。于是作用域精确等于
+   * 「这一次派发」，既不需要定时器也不需要猜微任务检查点的位置：
+   *
+   * - 消费方在条目自己的监听器里同步调 `close()` → 派发未结束 → 判定为真（要的就是这个）。
+   * - 消费方 `stopPropagation()` 让 menu 留着 → 派发照样结束 → 之后的 Escape / 点外面 / 程序式
+   *   `close()` 一律判定为假，README 承诺的「那三条关闭不抢焦点」不会被这一次点击污染。
+   * - 消费方把 `close()` 推到下一个任务 → 判定为假，退回不提前出顶层（与没有这个标记时一致）。
+   */
+  private _isDispatchingMenuItemActivation;
+  private readonly _closeFromUser;
+  private _scheduleRefresh;
+  private _refreshMenu;
+  /**
+   * 定位：**触屏长按与鼠标右键共用这一条 Floating UI 路径**。
+   *
+   * 两条入口现在只差「触发点的 x/y 从哪来」，布局契约完全一致：
+   * `bottom-start` 表达「panel 上缘 == 触发点 y、向下展开」，水平以触发点 x 为基准。
+   * 落点交给 `flip` / `shift` 按**实际空间**决定，`placement` 只表达意图：把「贴视口底」硬编码
+   * 成算术，真机反馈证明那是错的（menu 跑到屏幕最底部，与手指按下的位置完全脱节）。
+   *
+   * 不按「是否触屏」分流：窄视口的鼠标右键同样期望 menu 贴着光标出现，按输入类型或视口
+   * 宽度分流会让同一块屏幕上的两种输入拿到两套布局。panel 恒为 open scrim `<dialog>` 的
+   * 直接子节点（`createMenuPortalOverlay` 第三参传入 scrim，`menu-portal.ts` 里
+   * `container = scrim ?? …`），所以「非 dialog 容器」的分支对 context-menu 不可达。
+   *
+   * 算出来的 left/top 是**视口坐标**。panel 是 `position: fixed`，而 scrim 刻意不带
+   * transform / filter / contain（见 style.css），因此不构成 fixed 的包含块 ——
+   * 坐标直接相对视口解析。这条等价关系由 style.css 的满屏声明保证，并由 R6 的
+   * 「scrim 无 transform/filter/contain」+ viewport-fit 的几何断言兜底。
+   */
+  private _positionMenu;
+  /**
+   * 视口下缘的安全区高度（px）。
+   *
+   * 它**仍然必需**，而且不只服务触屏：menu 默认从触发点向下长，触发点
+   * 落在屏幕下半部时 panel 下缘会进入 home indicator 区域。它折进 flip 与 shift 共用的
+   * 边界 padding（见 `_positionMenu`），不需要单独一条 `maxBottom` 算术。
+   *
+   * 读宿主的自定义属性而不是 `env()`：自定义属性读回的是**计算后**的解析值，
+   * 而 `env()` 在 JS 里没有对应的求值入口，只能间接经由声明它的属性取。
+   * 属性未解析时 `parseFloat` 得 NaN，落到 0 —— 与 `env(..., 0px)` 的缺省一致。
+   */
+  private _safeAreaBottom;
+  /**
+   * 写下 panel 坐标与进场 transform 的原点。
+   *
+   * 两个 origin 必传且**不**再回退成坐标比较：flip 会改变垂直方向，回退表达式
+   * `y < this._y ? 'bottom' : 'top'` 在「panel 顶边与触发点重合」时两边都成立，等于随机取。
+   * 唯一调用方从 flip 后的 placement 与 shift 位移推出真实侧边，见 `_positionMenu`。
+   */
+  private _applyMenuPosition;
+  /**
+   * 把焦点带进 menu 的第一项。
+   *
+   * `attempt` 是重试计数：menu item 是刚被 `reconcileManagedMenuItems` 搬进来的自定义元素，
+   * 它们的 shadow（`.item-inner`）由各自的 Lit 更新**异步**渲染。`focusMenuItem()` 委托给
+   * 项的 `focusItem()`，那一刻 `.item-inner` 还不存在，于是**静默无操作** —— 不抛错、
+   * 也不留痕，只表现为「menu 开了但焦点没进去」。
+   *
+   * 所以这里不假设一次成功：调用后用 `findFocusedMenuItem` 复核，没落上就在下一帧再试，
+   * 最多 `FOCUS_FIRST_ITEM_ATTEMPTS` 次。上界是必要的 —— menu item 若始终渲染不出来
+   * （空 menu、内容被外部换掉），不能让重试链一直跑下去。
+   */
+  private _focusFirstItem;
+  private _setupMenuItems;
+  private _returnItemsToSlot;
+  /**
+   * 建 scrim 并让它进入模态态，返回容器供 panel 挂载。
+   *
+   * 每次开启都新建而不是复用：scrim 的生命周期必须与「这一次开启」严格同进同出。
+   * 复用一个 dialog 意味着上一轮的 `close()` 事件、`open` 属性与 UA 记下的焦点还原目标
+   * 会跨会话残留，而这些都不是本组件能重置的。
+   */
+  private _openScrim;
+  /**
+   * scrim 的挂载点：**与 panel 在没有 scrim 时会落到的容器同源** —— 最近主题的 theme-owned
+   * overlay root。scrim 就是那个容器的替身（panel 必须挂进 scrim，见 `updated()` 的顺序注释），
+   * 所以它得站在容器该站的位置上。
+   *
+   * 为什么不能在整棵 DOM 里随便挑位置：`--wui-color-*` 由 `<web-ui-theme>` 写在自己的 `:host`
+   * 上，只沿 DOM 树向下继承。scrim 若挂到 `document.body`，而 `<web-ui-theme>` 是 body 的**子节点**，
+   * 这条继承链就断了 —— panel 与 scrim 双双落回 `var(--wui-color-*, <浅色字面量>)` 的 fallback，
+   * 深色外观下 menu 是一块浅色玻璃（app 侧的 `dark:` 变体也够不到它）。挂进 theme overlay root
+   * 之后，panel 与 scrim 跟 dropdown / select 一样吃同一份 token。
+   *
+   * 无主题时挂在 `document.body`：那条路径本来就没有 token 作用域可继承，改用
+   * fallback overlay root 只会改变既有测试与消费者的观察面，不换来任何东西。
+   */
+  private _scrimParent;
+  /**
+   * 关掉并摘除 scrim。幂等：关闭分支与 `disconnectedCallback` 都会调。
+   *
+   * `close()` 触发 UA 的焦点归还，**必须先于 panel `remove()`** —— 理由见 `_closeMenuAfterPresence`。
+   */
+  private _closeScrim;
+  /**
+   * 只让 scrim 出顶层，不摘除元素。panel 挂在 scrim 里，摘了就把退场动画一起摘掉。
+   *
+   * 提前出顶层是为了焦点（理由见 `close()`）。代价是这个尾巴上 scrim 已经在 top layer
+   * 之外：下层恢复可命中，且 panel 的层级退回普通流 —— 在「menu 开在 drawer/dialog 之上」
+   * 的场景里，退场动画会被下层的 top layer 盖住。
+   *
+   * 这条尾巴只有一次退场过渡的时长（默认 160ms），且只发生在 menu item 激活时。
+   * 摘除仍在 `_closeScrim()`，那时 panel 已经走完。
+   */
+  private _releaseScrimModality;
+  /**
+   * 点 scrim = 关 menu（Q12：必关，不给 prop option），与 dialog / drawer 的实现同形：
+   * 只有落点就是 scrim 本身才算「点外面」，落在 panel（scrim 的后代）上不算。
+   *
+   * 落点判据之所以只能是这两个，是模态给的：menu 打开期间下层收不到命中，事件只可能
+   * 落在 scrim 或 panel 上，两者都由本组件判定。
+   *
+   * 落点判据不能理解成「命中测试落在 menu panel 之外」—— 宿主 light DOM 的每一行都满足这
+   * 个条件，于是判定与行激活就成了同一个 click 的两个后果，中间没有任何仲裁，下层目标
+   * 先被激活。模态化之后这条路没有任何还能生效的场景，别再挂回来。
+   */
+  private _onScrimClick;
+  /**
+   * Escape 的**唯一**关闭路径仍是共享仲裁者（`_overlay.requestClose` → `closeDeepestOrAll`），
+   * 它按层深决定是关最深 submenu 还是关整张 menu。原生 dialog 自己也监听 Escape 并派发
+   * `cancel`，若放任默认行为，UA 会直接关掉 scrim —— 那条路径不经过组件状态机，
+   * 既可能漏派 `open-change`，也会把「关最深一层」的语义降级成「整张 menu 没了」。
+   *
+   * 因此这里只吞掉默认行为，不重复关闭。仲裁者那条路径已经会走 `_closeFromUser()`。
+   */
+  private _onScrimCancel;
+  private _closeMenuAfterPresence;
+  private _hideMenuItems;
+  private _openSubmenu;
+  private _closeSubmenusFrom;
+  private _restoreSubmenuItems;
+  private _getItemLevel;
+  private _positionSubmenu;
+  private _dispatchChange;
+  private _onPointerDown;
+  private _onPointerMove;
+  private _onPointerUp;
+  private _onPointerCancel;
+  private _cancelLongPress;
+  /** 该事件是否是长按开 menu 之后、浏览器为同一次触摸补发的事件。 */
+  private _isLongPressFollowUp;
+  /** 结束「同一次手势的补发事件」窗口。与 _longPressOpenedAt 的清零同源，两处都要清。 */
+  private _clearLongPressFollowUp;
+  private _onContextMenu;
+  private _onContextMenuOutside;
+  private _onKeydown;
+  private _onMenuItemActivation;
+  private _onMenuClick;
+  private _getLevelContainer;
+  private _getLevelItems;
+  private _onWheel;
+  private _onTouchMove;
+  private _onDocumentKeydown;
+  private _closeLastSubmenuOrMenu;
+  private _preventBackgroundScroll;
+  private _syncScrollLock;
+  /** 按 panel 撤销一层 submenu 的登记；handle 已随根层递归撤销时幂等无操作。 */
+  private _releaseSubmenu;
+  private _isMenuPanelEvent;
+  render(): import("lit").TemplateResult<1>;
+  private _onSlotChange;
+  readonly $events: {
+    'open-change': CustomEvent<{
+      open: boolean;
+    }>;
+  };
 }
 declare global {
-    interface HTMLElementTagNameMap {
-        'web-ui-context-menu': WebUiContextMenu;
-    }
+  interface HTMLElementTagNameMap {
+    'web-ui-context-menu': WebUiContextMenu;
+  }
 }
+//# sourceMappingURL=index.d.ts.map