@soxa-ui/plugins 0.0.0-stage → 0.3.0-beta.1

package/dist/custom/menu/ids/index.d.ts

@@ -0,0 +1 @@
+export { TMenuIdsPlugin } from './ids.plugin';

package/dist/custom/menu/index.d.ts

@@ -0,0 +1,11 @@
+export * from './navigation';
+export * from './keyboard';
+export * from './pointer';
+export * from './hover';
+export * from './focus';
+export * from './ids';
+export * from './popup-ids';
+export * from './submenu-keyboard';
+export * from './submenu-focus';
+export * from './popover-item-keyboard';
+export * from './popover-item-focus';

package/dist/custom/menu/keyboard/index.d.ts

@@ -0,0 +1,2 @@
+export { TMenuKeyboardPlugin } from './keyboard.plugin';
+export type { TMenuKeyboardPluginEvents } from './types';

package/dist/custom/menu/keyboard/keyboard.plugin.d.ts

@@ -0,0 +1,41 @@
+import type { IPluginContext } from '../../../base';
+import { TMenuNavigationPlugin } from '../navigation';
+import type { TMenuKeyboardPluginEvents } from './types';
+/**
+ * TMenuKeyboardPlugin — клавиатура меню по паттерну APG Menu Button.
+ *
+ * Панель — общая с подменю (`TMenuNavigationPlugin`): фокус идёт за
+ * подсветкой, ↑/↓, Home и End, набор по первым буквам. Своё у меню — корень,
+ * в котором только триггер: ↓, Enter и пробел открывают меню и подсвечивают
+ * первый пункт, ↑ — последний (APG). Клавиши гасятся `preventDefault`: иначе
+ * Enter и пробел нажали бы кнопку-триггер, а клик по ней переключил бы меню
+ * обратно. Это клавиши кнопки (`openOn: 'press'`); у контекстного меню в
+ * корне область, и её клавиши — её: стрелки ходят по её строкам, Enter
+ * нажимает её кнопки. Меню над ней открывает `contextmenu` — плагин
+ * открытия. Какие клавиши корня слушаются, выбирает подписка на смену
+ * способа, а не проверка в обработчике.
+ *
+ * Открытие на крайнем пункте (`openAt`) зовёт и плагин открытия: контекстное
+ * меню, вызванное клавишей, открывается на первом пункте, как кнопка с
+ * клавиатуры.
+ */
+export declare class TMenuKeyboardPlugin extends TMenuNavigationPlugin<TMenuKeyboardPluginEvents> {
+    private _menu;
+    /**
+     * Клавиши корня по способу открытия: у кнопки — открыть меню, у области
+     * контекстного меню — никаких, её клавиши принадлежат ей.
+     */
+    private _rootKeys;
+    install(ctx: IPluginContext, options?: unknown): void;
+    destroy(): void;
+    /** Клавиши корня — по способу открытия (`_rootKeys`). */
+    protected onKeyDown(e: KeyboardEvent): void;
+    /**
+     * Клавиши корня по способу открытия: у кнопки — свои, у области
+     * контекстного меню — никаких. Подписка на смену способа, а не проверка в
+     * обработчике.
+     */
+    private _syncRootKeys;
+    /** Клавиши кнопки-триггера: открыть меню на крайнем пункте. */
+    private readonly _onTriggerKeyDown;
+}

package/dist/custom/menu/keyboard/keyboard.plugin.js

@@ -0,0 +1,68 @@
+import { TMenuNavigationPlugin } from "../navigation/navigation.plugin.js";
+//#region src/custom/menu/keyboard/keyboard.plugin.ts
+/**
+* TMenuKeyboardPlugin — клавиатура меню по паттерну APG Menu Button.
+*
+* Панель — общая с подменю (`TMenuNavigationPlugin`): фокус идёт за
+* подсветкой, ↑/↓, Home и End, набор по первым буквам. Своё у меню — корень,
+* в котором только триггер: ↓, Enter и пробел открывают меню и подсвечивают
+* первый пункт, ↑ — последний (APG). Клавиши гасятся `preventDefault`: иначе
+* Enter и пробел нажали бы кнопку-триггер, а клик по ней переключил бы меню
+* обратно. Это клавиши кнопки (`openOn: 'press'`); у контекстного меню в
+* корне область, и её клавиши — её: стрелки ходят по её строкам, Enter
+* нажимает её кнопки. Меню над ней открывает `contextmenu` — плагин
+* открытия. Какие клавиши корня слушаются, выбирает подписка на смену
+* способа, а не проверка в обработчике.
+*
+* Открытие на крайнем пункте (`openAt`) зовёт и плагин открытия: контекстное
+* меню, вызванное клавишей, открывается на первом пункте, как кнопка с
+* клавиатуры.
+*/
+var TMenuKeyboardPlugin = class extends TMenuNavigationPlugin {
+	_menu = null;
+	/**
+	* Клавиши корня по способу открытия: у кнопки — открыть меню, у области
+	* контекстного меню — никаких, её клавиши принадлежат ей.
+	*/
+	_rootKeys = null;
+	install(ctx, options) {
+		super.install(ctx, options);
+		this._menu = ctx.getInstance() ?? null;
+		this._syncRootKeys();
+		this._listenTo(this._menu?.events, "change:openOn", () => this._syncRootKeys());
+	}
+	destroy() {
+		this._menu = null;
+		this._rootKeys = null;
+		super.destroy();
+	}
+	/** Клавиши корня — по способу открытия (`_rootKeys`). */
+	onKeyDown(e) {
+		this._rootKeys?.(e);
+	}
+	/**
+	* Клавиши корня по способу открытия: у кнопки — свои, у области
+	* контекстного меню — никаких. Подписка на смену способа, а не проверка в
+	* обработчике.
+	*/
+	_syncRootKeys() {
+		this._rootKeys = this._menu?.openOn === "press" ? this._onTriggerKeyDown : null;
+	}
+	/** Клавиши кнопки-триггера: открыть меню на крайнем пункте. */
+	_onTriggerKeyDown = (e) => {
+		switch (e.key) {
+			case "ArrowDown":
+			case "Enter":
+			case " ":
+				e.preventDefault();
+				this.openAt("first");
+				return;
+			case "ArrowUp":
+				e.preventDefault();
+				this.openAt("last");
+				return;
+		}
+	};
+};
+//#endregion
+export { TMenuKeyboardPlugin };

package/dist/custom/menu/keyboard/types.d.ts

@@ -0,0 +1,2 @@
+import type { TListNavigationPluginEvents } from '../../list/navigation';
+export type TMenuKeyboardPluginEvents = TListNavigationPluginEvents;

package/dist/custom/menu/navigation/index.d.ts

@@ -0,0 +1,2 @@
+export { TMenuNavigationPlugin } from './navigation.plugin';
+export type { TMenuNavigationPluginEvents } from './types';

package/dist/custom/menu/navigation/navigation.plugin.d.ts

@@ -0,0 +1,116 @@
+import type { IMenuOwner } from '@soxa-ui/core';
+import type { IPluginContext } from '../../../base';
+import { TDismissPlugin } from '../../dismiss';
+import { TCollectionElements } from '../../collection';
+import { TListNavigationPlugin } from '../../list/navigation';
+import type { TListEdge } from '../../list/navigation';
+import type { TMenuNavigationPluginEvents } from './types';
+/**
+ * TMenuNavigationPlugin — клавиатура панели одного уровня меню: корня или
+ * подменю.
+ *
+ * Общая механика — привязка к коллекции, учёт подсветки, циклический сдвиг,
+ * пропуск недоступных пунктов — в `TListNavigationPlugin`, как у ListBox и
+ * Select. Своё у меню — модель фокуса: **фокус идёт за подсветкой**.
+ * Подсвеченный пункт держит DOM-фокус на своей строке (`tabindex="-1"` пишет
+ * коллекция), а без подсветки фокус на самой панели. Поэтому подсветка здесь
+ * и есть фокус: сменилась — фокус строке, снята у открытого меню — панели.
+ * Закрытие подсветку снимает, фокус не трогая: куда его вернуть, решает модель
+ * фокуса уровня.
+ *
+ * **Фокус ставится без прокрутки** (`preventScroll`), откуда бы ни пришла
+ * подсветка — от клавиш или от указателя. К подсвеченному пункту список
+ * докручивает `TListScrollPlugin` по событию подсветки, тем же правилом, что у
+ * ListBox и Select: ближайшим краем. Браузер, который докручивал к фокусу сам,
+ * делал это только за клавишами и по-своему, а открытие меню стрелкой вверх
+ * (фокус ставит модель фокуса, тоже без прокрутки) оставляло последний пункт
+ * за краем.
+ *
+ * Панель слушается, пока меню открыто, — её находит `TDismissPlugin` по
+ * пометке владельцем: панель телепортирована, и до корня её клавиши не
+ * всплывают. ↑/↓ — по кругу, Home и End — к крайним, буква — набор по первым
+ * буквам (`TTypeahead`); пробел — буква, только пока набор идёт. Клавишу
+ * панель берёт только с себя и со строк своих пунктов, как ListBox: клавиши
+ * содержимого слотов (поле в пункте) принадлежат им. Клавишу, которую уже
+ * обработали (`defaultPrevented`), панель не трогает: строка пункта с
+ * подменю гасит свои — стрелку к концу строки, Enter и пробел, — и своё
+ * подменю открывает сама (`TMenuSubmenuKeyboardPlugin`), а набор её пробела
+ * не перехватывает; строка пункта с панелью так же гасит стрелку к концу
+ * строки (`TMenuPopoverItemKeyboardPlugin`).
+ *
+ * Enter и пробел на строке не трогаются: строка — `Button` на `div`, и клик
+ * из них делает её `TActionPlugin`, как браузер у `<button>`. Нажатие пункта
+ * одно — клик по строке, и второго пути к нему нет. Escape и Tab — у модели
+ * фокуса.
+ *
+ * Что слушает корень и что ещё значат клавиши панели, решает наследник:
+ * у меню у кнопки корень — триггер (`TMenuKeyboardPlugin`), у подменю корень
+ * — его строка в меню над ним, а стрелка к началу строки в его панели
+ * закрывает уровень (`TMenuSubmenuKeyboardPlugin`).
+ *
+ * Наружу — открытие на крайнем пункте, подсветка пункта, её снятие и строка
+ * подсвеченного: открывает и подсвечивает пункт и указатель, а строку берёт
+ * модель фокуса — туда она ставит фокус при открытии.
+ */
+export declare abstract class TMenuNavigationPlugin<TEvents extends TMenuNavigationPluginEvents = TMenuNavigationPluginEvents> extends TListNavigationPlugin<TEvents> {
+    /** Владелец пунктов — меню или пункт с подменю. */
+    protected _owner: IMenuOwner<any> | null;
+    protected _dismiss: TDismissPlugin | null;
+    protected _elements: TCollectionElements | null;
+    /** Панель со слушателем клавиш — пока меню открыто. */
+    private _panel;
+    private readonly _typeahead;
+    /** Frame that highlights the edge item once the panel's first opening has drawn the items. */
+    private _edgeFrame;
+    install(ctx: IPluginContext, options?: unknown): void;
+    destroy(): void;
+    /** Строка подсвеченного пункта; `null` — подсветки нет или пункта нет в документе. */
+    get highlightedRow(): Element | null;
+    /**
+     * Подсветить пункт — фокус его строке. Недоступный не подсвечивается.
+     *
+     * @returns подсвечен ли пункт
+     */
+    highlightItem(uid: string | number): boolean;
+    /** Снять подсветку: у открытого меню фокус уходит панели. */
+    unhighlight(): void;
+    /**
+     * Open the menu and highlight its edge item — focus goes to that item's
+     * row. This is how a key opens it: the button — ↓, Enter, Space and ↑, the
+     * context menu — its key and Shift+F10, a submenu — the arrow towards the
+     * end of the line, Enter and Space on its row.
+     *
+     * The panel's items are mounted with its first opening
+     * (`contentRendered`): on that opening the collection is still empty, and
+     * the adapter draws the items after this call. The edge is then
+     * highlighted on the next frame — every adapter has drawn them by then,
+     * and their rows are in the document. A closing before that frame cancels
+     * it.
+     */
+    openAt(edge: TListEdge): void;
+    /**
+     * Своя клавиша панели сверх общих — у подменю стрелка к началу строки.
+     * Обработал — `true`, и клавиша гасится здесь.
+     */
+    protected onPanelKey(_e: KeyboardEvent): boolean;
+    /** Справа налево ли панель: стрелки по строке — по её направлению. */
+    protected isRtl(): boolean;
+    /**
+     * Подсветка — фокус: подсвеченному пункту — его строке, без подсветки у
+     * открытого меню — панели. Без прокрутки: к пункту докручивает
+     * `TListScrollPlugin`. Строки нет в документе (панель ещё скрыта, её
+     * откроет следующий кадр) — фокус ставит модель фокуса при открытии.
+     */
+    protected onHighlightChanged(uid: string | number | null): void;
+    /** Панель открытого меню; закрытое фокус не получает. */
+    private _openPanel;
+    /** Слушать панель, пока меню открыто, — на её открытии и на объявлении корня. */
+    private _syncPanel;
+    private _cancelEdgeFrame;
+    private _unlistenPanel;
+    /** Клавиша панели — с неё самой или со строки показанного пункта. */
+    private _isOwnKey;
+    private readonly _onPanelKeyDown;
+    /** Буква набора: подсветка — на найденный пункт, нет такого — на месте. */
+    private _typeTo;
+}

package/dist/custom/menu/navigation/navigation.plugin.js

@@ -0,0 +1,222 @@
+import { TElementPlugin } from "../../element/element.plugin.js";
+import { TCollectionElements } from "../../collection/collection-elements.plugin.js";
+import { isFocusableElement } from "../../../utils/isFocusableElement.js";
+import { isPrintableKey } from "../../../utils/isPrintableKey.js";
+import { rowOf } from "../../list/row.js";
+import { TDismissPlugin } from "../../dismiss/dismiss.plugin.js";
+import { TListNavigationPlugin } from "../../list/navigation/navigation.plugin.js";
+import { TTypeahead, itemText } from "../../list/typeahead.js";
+//#region src/custom/menu/navigation/navigation.plugin.ts
+/**
+* TMenuNavigationPlugin — клавиатура панели одного уровня меню: корня или
+* подменю.
+*
+* Общая механика — привязка к коллекции, учёт подсветки, циклический сдвиг,
+* пропуск недоступных пунктов — в `TListNavigationPlugin`, как у ListBox и
+* Select. Своё у меню — модель фокуса: **фокус идёт за подсветкой**.
+* Подсвеченный пункт держит DOM-фокус на своей строке (`tabindex="-1"` пишет
+* коллекция), а без подсветки фокус на самой панели. Поэтому подсветка здесь
+* и есть фокус: сменилась — фокус строке, снята у открытого меню — панели.
+* Закрытие подсветку снимает, фокус не трогая: куда его вернуть, решает модель
+* фокуса уровня.
+*
+* **Фокус ставится без прокрутки** (`preventScroll`), откуда бы ни пришла
+* подсветка — от клавиш или от указателя. К подсвеченному пункту список
+* докручивает `TListScrollPlugin` по событию подсветки, тем же правилом, что у
+* ListBox и Select: ближайшим краем. Браузер, который докручивал к фокусу сам,
+* делал это только за клавишами и по-своему, а открытие меню стрелкой вверх
+* (фокус ставит модель фокуса, тоже без прокрутки) оставляло последний пункт
+* за краем.
+*
+* Панель слушается, пока меню открыто, — её находит `TDismissPlugin` по
+* пометке владельцем: панель телепортирована, и до корня её клавиши не
+* всплывают. ↑/↓ — по кругу, Home и End — к крайним, буква — набор по первым
+* буквам (`TTypeahead`); пробел — буква, только пока набор идёт. Клавишу
+* панель берёт только с себя и со строк своих пунктов, как ListBox: клавиши
+* содержимого слотов (поле в пункте) принадлежат им. Клавишу, которую уже
+* обработали (`defaultPrevented`), панель не трогает: строка пункта с
+* подменю гасит свои — стрелку к концу строки, Enter и пробел, — и своё
+* подменю открывает сама (`TMenuSubmenuKeyboardPlugin`), а набор её пробела
+* не перехватывает; строка пункта с панелью так же гасит стрелку к концу
+* строки (`TMenuPopoverItemKeyboardPlugin`).
+*
+* Enter и пробел на строке не трогаются: строка — `Button` на `div`, и клик
+* из них делает её `TActionPlugin`, как браузер у `<button>`. Нажатие пункта
+* одно — клик по строке, и второго пути к нему нет. Escape и Tab — у модели
+* фокуса.
+*
+* Что слушает корень и что ещё значат клавиши панели, решает наследник:
+* у меню у кнопки корень — триггер (`TMenuKeyboardPlugin`), у подменю корень
+* — его строка в меню над ним, а стрелка к началу строки в его панели
+* закрывает уровень (`TMenuSubmenuKeyboardPlugin`).
+*
+* Наружу — открытие на крайнем пункте, подсветка пункта, её снятие и строка
+* подсвеченного: открывает и подсвечивает пункт и указатель, а строку берёт
+* модель фокуса — туда она ставит фокус при открытии.
+*/
+var TMenuNavigationPlugin = class extends TListNavigationPlugin {
+	/** Владелец пунктов — меню или пункт с подменю. */
+	_owner = null;
+	_dismiss = null;
+	_elements = null;
+	/** Панель со слушателем клавиш — пока меню открыто. */
+	_panel = null;
+	_typeahead = new TTypeahead();
+	/** Frame that highlights the edge item once the panel's first opening has drawn the items. */
+	_edgeFrame = null;
+	install(ctx, options) {
+		super.install(ctx, options);
+		this._owner = ctx.getInstance() ?? null;
+		this._dismiss = ctx.get(TDismissPlugin) ?? null;
+		this._elements = ctx.get(TCollectionElements) ?? null;
+		const elementPlugin = ctx.get(TElementPlugin);
+		elementPlugin?.events.on("ready", () => this._syncPanel());
+		elementPlugin?.events.on("removed", () => this._unlistenPanel());
+		this._listenTo(this._owner?.events, "change:open", ({ newValue: open }) => {
+			this._syncPanel();
+			if (open) return;
+			this._cancelEdgeFrame();
+			this._typeahead.reset();
+			this.clearHighlight();
+		});
+	}
+	destroy() {
+		this._unlistenPanel();
+		this._cancelEdgeFrame();
+		this._owner = null;
+		this._dismiss = null;
+		this._elements = null;
+		super.destroy();
+	}
+	/** Строка подсвеченного пункта; `null` — подсветки нет или пункта нет в документе. */
+	get highlightedRow() {
+		return this._highlightedUid === null ? null : rowOf(this._elements, this._highlightedUid);
+	}
+	/**
+	* Подсветить пункт — фокус его строке. Недоступный не подсвечивается.
+	*
+	* @returns подсвечен ли пункт
+	*/
+	highlightItem(uid) {
+		if (!this.itemByUid(uid)) return false;
+		this.highlight(uid);
+		return true;
+	}
+	/** Снять подсветку: у открытого меню фокус уходит панели. */
+	unhighlight() {
+		this.clearHighlight();
+	}
+	/**
+	* Open the menu and highlight its edge item — focus goes to that item's
+	* row. This is how a key opens it: the button — ↓, Enter, Space and ↑, the
+	* context menu — its key and Shift+F10, a submenu — the arrow towards the
+	* end of the line, Enter and Space on its row.
+	*
+	* The panel's items are mounted with its first opening
+	* (`contentRendered`): on that opening the collection is still empty, and
+	* the adapter draws the items after this call. The edge is then
+	* highlighted on the next frame — every adapter has drawn them by then,
+	* and their rows are in the document. A closing before that frame cancels
+	* it.
+	*/
+	openAt(edge) {
+		const owner = this._owner;
+		if (!owner) return;
+		owner.open = true;
+		this._cancelEdgeFrame();
+		if (this.items().length > 0) {
+			this.highlightEdge(edge);
+			return;
+		}
+		this._edgeFrame = requestAnimationFrame(() => {
+			this._edgeFrame = null;
+			if (this._owner?.open) this.highlightEdge(edge);
+		});
+	}
+	/**
+	* Своя клавиша панели сверх общих — у подменю стрелка к началу строки.
+	* Обработал — `true`, и клавиша гасится здесь.
+	*/
+	onPanelKey(_e) {
+		return false;
+	}
+	/** Справа налево ли панель: стрелки по строке — по её направлению. */
+	isRtl() {
+		const panel = this._openPanel();
+		return panel !== null && getComputedStyle(panel).direction === "rtl";
+	}
+	/**
+	* Подсветка — фокус: подсвеченному пункту — его строке, без подсветки у
+	* открытого меню — панели. Без прокрутки: к пункту докручивает
+	* `TListScrollPlugin`. Строки нет в документе (панель ещё скрыта, её
+	* откроет следующий кадр) — фокус ставит модель фокуса при открытии.
+	*/
+	onHighlightChanged(uid) {
+		const target = uid === null ? this._openPanel() : rowOf(this._elements, uid);
+		if (isFocusableElement(target)) target.focus({ preventScroll: true });
+	}
+	/** Панель открытого меню; закрытое фокус не получает. */
+	_openPanel() {
+		return this._owner?.open ? this._dismiss?.findPanel() ?? null : null;
+	}
+	/** Слушать панель, пока меню открыто, — на её открытии и на объявлении корня. */
+	_syncPanel() {
+		const panel = this._openPanel();
+		if (panel === this._panel) return;
+		this._unlistenPanel();
+		if (!panel) return;
+		this._panel = panel;
+		panel.addEventListener("keydown", this._onPanelKeyDown);
+	}
+	_cancelEdgeFrame() {
+		if (this._edgeFrame === null) return;
+		cancelAnimationFrame(this._edgeFrame);
+		this._edgeFrame = null;
+	}
+	_unlistenPanel() {
+		this._panel?.removeEventListener("keydown", this._onPanelKeyDown);
+		this._panel = null;
+	}
+	/** Клавиша панели — с неё самой или со строки показанного пункта. */
+	_isOwnKey(e) {
+		if (e.target === e.currentTarget) return true;
+		return this.shown().some((item) => rowOf(this._elements, item.uid) === e.target);
+	}
+	_onPanelKeyDown = (e) => {
+		if (e.defaultPrevented || !this._isOwnKey(e)) return;
+		switch (e.key) {
+			case "ArrowDown":
+				e.preventDefault();
+				this.move(1);
+				return;
+			case "ArrowUp":
+				e.preventDefault();
+				this.move(-1);
+				return;
+			case "Home":
+				e.preventDefault();
+				this.highlightEdge("first");
+				return;
+			case "End":
+				e.preventDefault();
+				this.highlightEdge("last");
+				return;
+		}
+		if (this.onPanelKey(e)) {
+			e.preventDefault();
+			return;
+		}
+		if (e.key === " " && !this._typeahead.typing()) return;
+		if (!isPrintableKey(e)) return;
+		e.preventDefault();
+		this._typeTo(e.key);
+	};
+	/** Буква набора: подсветка — на найденный пункт, нет такого — на месте. */
+	_typeTo(char) {
+		const current = this._highlightedUid === null ? null : this.itemByUid(this._highlightedUid);
+		const match = this._typeahead.next(char, this.items(), current, itemText);
+		if (match) this.highlight(match.uid);
+	}
+};
+//#endregion
+export { TMenuNavigationPlugin };

package/dist/custom/menu/navigation/types.d.ts

@@ -0,0 +1,2 @@
+import type { TListNavigationPluginEvents } from '../../list/navigation';
+export type TMenuNavigationPluginEvents = TListNavigationPluginEvents;

package/dist/custom/menu/nested-layer.d.ts

@@ -0,0 +1,13 @@
+import type { TDismissPlugin } from '../dismiss';
+/**
+ * Держит ли вложенный слой меню фокус — подменю или панель пункта с панелью:
+ * фокус в нём по правилу его `TDismissPlugin` (строка пункта, панель и слои
+ * над ней) или нигде.
+ *
+ * Модели фокуса таких слоёв по нему решают, возвращать ли фокус на строку
+ * пункта при закрытии (`_returnsFocus`). Слой, закрытый вместе с меню, фокус
+ * на строку спрятанной панели не тянет: меню уже вернуло его на триггер, — а
+ * подписчики открытости меню и слоя идут в любом порядке, и правило держит
+ * оба.
+ */
+export declare function holdsFocus(root: Element, dismiss: TDismissPlugin | null): boolean;

package/dist/custom/menu/nested-layer.js

@@ -0,0 +1,20 @@
+//#region src/custom/menu/nested-layer.ts
+/**
+* Держит ли вложенный слой меню фокус — подменю или панель пункта с панелью:
+* фокус в нём по правилу его `TDismissPlugin` (строка пункта, панель и слои
+* над ней) или нигде.
+*
+* Модели фокуса таких слоёв по нему решают, возвращать ли фокус на строку
+* пункта при закрытии (`_returnsFocus`). Слой, закрытый вместе с меню, фокус
+* на строку спрятанной панели не тянет: меню уже вернуло его на триггер, — а
+* подписчики открытости меню и слоя идут в любом порядке, и правило держит
+* оба.
+*/
+function holdsFocus(root, dismiss) {
+	const doc = root.ownerDocument;
+	const active = doc.activeElement;
+	if (!active || active === doc.body || active === doc.documentElement) return true;
+	return dismiss?.isInside(active) ?? false;
+}
+//#endregion
+export { holdsFocus };

package/dist/custom/menu/pointer/index.d.ts

@@ -0,0 +1,2 @@
+export { TMenuPointerPlugin } from './pointer.plugin';
+export type { TMenuPointerPluginEvents } from './types';

package/dist/custom/menu/pointer/pointer.plugin.d.ts

@@ -0,0 +1,45 @@
+import type { TMenuPoint } from '@soxa-ui/core';
+import { TBasePlugin } from '../../../base';
+import type { IPluginContext } from '../../../base';
+import type { IMenuOpenHost } from './strategies';
+import type { TMenuPointerPluginEvents } from './types';
+/**
+ * TMenuPointerPlugin — открытие меню указателем.
+ *
+ * Открытие — стратегия по способу владельца (`openOn`, `strategies/`): у
+ * кнопки (`TMenuPressStrategy`) клик по корню переключает меню, у
+ * контекстного меню (`TMenuContextStrategy`) `contextmenu` и долгое касание
+ * над областью вызывают его у точки вызова (`point` владельца). Стратегию
+ * выбирает подписка на `change:openOn`, а не проверка в обработчике, и
+ * слушатели корня у каждого способа свои. Вызванное клавишей контекстное
+ * меню открывается на первом пункте — через клавиатуру меню, как кнопка с
+ * клавиатуры.
+ *
+ * Указатель в открытой панели — подсветка пунктов и подменю — у
+ * `TMenuHoverPlugin`: он общий у меню и подменю, а способ открытия есть
+ * только у меню.
+ */
+export declare class TMenuPointerPlugin extends TBasePlugin<any, TMenuPointerPluginEvents> implements IMenuOpenHost {
+    private _owner;
+    private _keyboard;
+    /** Корень — под стратегию открытия. */
+    private _root;
+    /** Способ открытия на корне — по `openOn` владельца. */
+    private _strategy;
+    install(ctx: IPluginContext): void;
+    destroy(): void;
+    /** Открыто ли меню — для стратегий открытия. */
+    get isOpen(): boolean;
+    /** Переключить меню — нажатие кнопки. */
+    toggle(): void;
+    /**
+     * Вызвать меню у точки окна, открытое — переставить к ней: точку отдаёт
+     * якорю панели разметка. Вызвали клавишей — меню открывается на первом
+     * пункте, как кнопка с клавиатуры, указателем — фокус на панели.
+     */
+    invoke(point: TMenuPoint, byKeyboard: boolean): void;
+    /** Закрыть меню. */
+    close(): void;
+    /** Стратегия открытия — по способу владельца, на объявленном корне. */
+    private _syncStrategy;
+}