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

package/dist/custom/accordion/item-ids/item-ids.plugin.js

@@ -0,0 +1,44 @@
+import { TBasePlugin } from "../../../base/base.class.js";
+import { TIdPlugin } from "../../id/id.plugin.js";
+//#region src/custom/accordion/item-ids/item-ids.plugin.ts
+/**
+* TAccordionItemIdsPlugin — связка «заголовок ↔ панель» секции Accordion в
+* документе.
+*
+* Обе стороны — в наборах секции. В `aria` (он стоит на заголовке) — `id`
+* заголовка и `aria-controls` на панель. В `contentAria` (он стоит на панели) —
+* `id` панели и `aria-labelledby` на заголовок. Формула одна, здесь.
+*
+* `id` заголовка, заданный приложением (`TIdPlugin` секции), главнее: он и
+* встаёт на заголовок, и на него ссылается панель. Сменили — плагин
+* переписывает обе стороны ссылки на заголовок, сняли — снова `id` от
+* монтирования. У панели `id` приложения нет, её `id` — формула.
+*
+* Без него — `id` от монтирования секции (`createId`), а не от экземпляра: он
+* нужен только документу, и на сервере и в браузере обязан совпасть. Секция
+* из данных рисуется с готовым экземпляром (`ctrl`), и его конструктор адаптер
+* не зовёт, а монтирование у неё своё. Пишется при установке, синхронно, —
+* связка есть уже в первой (и серверной) отрисовке.
+*/
+var TAccordionItemIdsPlugin = class extends TBasePlugin {
+	install(ctx) {
+		super.install(ctx);
+		const section = ctx.getInstance();
+		if (!section) return;
+		const idPlugin = ctx.get(TIdPlugin);
+		const mountId = ctx.createId("header");
+		const contentId = ctx.createId("content");
+		/** Обе стороны ссылки на заголовок: его `id` и `aria-labelledby` панели. */
+		const linkHeader = () => {
+			const headerId = idPlugin?.id ?? mountId;
+			section.aria.add("id", headerId);
+			section.contentAria.add("aria-labelledby", headerId);
+		};
+		section.contentAria.add("id", contentId);
+		linkHeader();
+		section.aria.add("aria-controls", contentId);
+		idPlugin?.events.on("change:id", linkHeader);
+	}
+};
+//#endregion
+export { TAccordionItemIdsPlugin };

package/dist/custom/action/action.plugin.d.ts

@@ -0,0 +1,178 @@
+import { TBasePlugin } from '../../base';
+import type { IPluginContext } from '../../base';
+import type { IActionPluginOptions, TActionPluginEvents } from './types';
+/**
+ * TActionPlugin — взаимодействие контрола с пользователем.
+ *
+ * Ядру DOM недоступен, поэтому слушатели живут здесь. Элемент плагин не
+ * добывает сам, а берёт у TElementPlugin — тот же приём, что в
+ * TListKeyboardPlugin: композиция плагинов, а не наследование.
+ *
+ * Делает три вещи:
+ *
+ * 1. Нормализует активацию. `press` — клик, не пришедший на disabled, —
+ *    независимо от того, `<button>` под компонентом или `<div>`. Из Enter и
+ *    пробела на корне, где браузер клика не делает, клик делает плагин, как
+ *    браузер у `<button>`: Enter — на keydown, пробел — на keyup. Поэтому на
+ *    клавишу приходит и `click` потребителя, а отмена клика (`preventDefault`)
+ *    одинакова для мыши и клавиатуры. Enter/Space нормализуются, только когда
+ *    фокус на самом корне: вложенные поле, чекбокс или кнопка знают, что с
+ *    ними делать, сами, а их клик всплывёт в корень и даст `press`, как клик
+ *    мышью. Отмени корень их keydown — в Input не напечатается пробел,
+ *    чекбокс не переключится, кнопка не нажмётся.
+ *
+ * 2. Связывает `focused` с настоящим фокусом. До этого плагина `focused` был
+ *    булевым флагом, который никто не выставлял и который ничего не делал.
+ *    Связь двусторонняя: фокус на корне или внутри него пишет в инстанс, а
+ *    запись в инстанс ставит фокус на узел фокуса компонента. Его называет
+ *    правило дескриптора (`focusTarget`): у поля фокус держит вложенный
+ *    `<input>`, у ListBox — узел списка, у Tabs — таб-остановка, а корень у
+ *    них — коробка вокруг. Без правила, и когда оно узла не нашло, узел
+ *    фокуса — корень. Фокус уже внутри корня запись не двигает: компонент и
+ *    так в фокусе. Запись `false` снимает фокус с того узла внутри корня, на
+ *    котором он стоит. Писатель фокуса один — этот плагин: своего обработчика
+ *    `change:focused` у плагинов компонентов нет.
+ *
+ *    Узла правило не нашло, корень фокус не принял, а компонент — владелец
+ *    коллекции (`TCollectionElements` в наборе): остановка в модели уже
+ *    новая, а её узел ещё не нарисован — день нового месяца календаря,
+ *    страница за окном пагинации, таб, добавленный в том же такте. Тогда
+ *    запись ждёт узла: элемент вошёл в коллекцию или объявлен его узел —
+ *    правило зовётся снова, и узел, который оно нашло, получает фокус.
+ *    Ожидание одно; снимают его запись `false` и `blur()`, любой `focusin` в
+ *    документе, снятие корня и `destroy()`. `focus()` идёт тем же путём, что
+ *    запись `true`. `focused` назад не пишется ни после записи, после которой
+ *    фокус не встал, ни после снятого ожидания.
+ *
+ * 3. Пробрасывает сырой `click`. Нужен той стороне, у которой на руках только
+ *    инстанс: в шаблоне DOM-события и так доступны через fallthrough
+ *    (`<Button @click="...">`), а через ctrl — только отсюда.
+ */
+export declare class TActionPlugin extends TBasePlugin<any, TActionPluginEvents> {
+    private _element;
+    private _instance;
+    /** Контекст набора: его получает правило узла фокуса. */
+    private _ctx;
+    private _keys;
+    /** Правило узла фокуса из опций дескриптора; нет — фокус держит корень. */
+    private _focusTarget;
+    private _syncingFocus;
+    /** Снять ожидание узла фокуса (`_wait`); `null` — фокус узла не ждёт. */
+    private _waiting;
+    /** Пробел нажат на корне: клик — когда его отпустят, как у `<button>`. */
+    private _spaceDown;
+    install(ctx: IPluginContext, options?: IActionPluginOptions): void;
+    destroy(): void;
+    /** Корневой элемент контрола. Появляется только после монтирования. */
+    get element(): Element | null;
+    /**
+     * Перевести фокус на контрол — на его узел фокуса (`_moveFocus`): у поля
+     * это `<input>`, а не коробка вокруг. Путь тот же, что у записи
+     * `focused = true`, и узла, которого ещё нет, `focus()` ждёт так же.
+     */
+    focus(): void;
+    /**
+     * Снять фокус с контрола — с того узла внутри корня, на котором он стоит,
+     * как запись `focused = false`: у поля фокус держит вложенный `<input>`, и
+     * `blur()` корня его бы не снял. Фокус, который ещё ждёт узла, снимается
+     * тоже: иначе узел, нарисованный позже, получил бы фокус после `blur()`.
+     */
+    blur(): void;
+    private _attach;
+    private _detach;
+    private get _disabled();
+    /**
+     * Сам ли браузер сделает click из Enter/Space на корне.
+     * Для `<a href>` — только Enter, но Space на ссылке и не должен активировать,
+     * поэтому весь тег целиком отдаём нативному поведению.
+     *
+     * Смотрит на тег корня, а не цели события: клавиши из вложенных элементов
+     * до этой проверки не доходят — `_onKeyDown` нормализует только нажатия с
+     * фокусом на корне.
+     */
+    private get _nativeActivation();
+    private readonly _onClick;
+    /**
+     * Клавиша активации на корне, который браузер в клик не превращает.
+     *
+     * Клик, а не сразу `press`: так у `<button>`, и клавиша проходит тот же
+     * путь, что мышь, — `click` потребителя, его отмена, `press`. Пробел
+     * кликает, когда его отпустят, Enter — сразу.
+     *
+     * Нажатие для `<button>` — действие клавиши по умолчанию: его отменяет
+     * `preventDefault` любого обработчика на пути клавиши, и на предке тоже.
+     * Поэтому решение — в конце рассылки, а не здесь, на корне, где обработчики
+     * предков ещё не прошли: так клавиша, которую взял себе предок (Enter со
+     * строки ListBox выбирает подсвеченный элемент), строку не нажмёт. Конец
+     * рассылки — окно: дальше событие не всплывает. Клавишу, всплытие которой
+     * остановили, корень тоже не нажимает — её взял себе тот, кто остановил.
+     */
+    private readonly _onKeyDown;
+    private readonly _onKeyUp;
+    /** Клавиша активации — на самом корне не-нативного тега, не на disabled. */
+    private _ownKey;
+    /** Клик по корню — тот, что браузер делает из клавиши у `<button>`. */
+    private _click;
+    private readonly _onFocusIn;
+    private readonly _onFocusOut;
+    /**
+     * Инстанс → DOM. Флаг `_syncingFocus` рвёт цикл: focus() вызовет focusin,
+     * тот запишет focused, тот снова придёт сюда.
+     *
+     * В фокусе ли компонент, считается по корню, как в обратную сторону
+     * (`focusin` и `focusout` корня): фокус внутри корня — на кнопке очистки
+     * поля или в поле шапки ListBox — `focused = true` не двигает. Ставит
+     * фокус запись на узел фокуса (`_moveFocus`), снимает — с узла внутри
+     * корня, на котором он стоит.
+     *
+     * Запись `false` снимает и ожидание узла — до проверки, есть ли что
+     * снимать: пока узла ждут, фокуса в корне нет.
+     */
+    private readonly _onFocusedChange;
+    /**
+     * Фокус — на узел фокуса компонента: что нашло правило дескриптора, иначе
+     * корень. Узла правило не нашло, а корень фокус не принял — ждать узла
+     * (`_wait`). Попытка заменяет прежнее ожидание: оно всегда одно.
+     *
+     * Правило зовётся на каждую запись, а не один раз на `ready`: узел фокуса
+     * бывает новым — у Tabs остановка переезжает с активацией.
+     *
+     * Узел плагину приходит как `Element`, поэтому фокусируемость проверяется
+     * гардом: у корня-`svg` фокус есть, а у произвольного `Element` — нет.
+     */
+    private _moveFocus;
+    /** Узел, который нашло правило дескриптора; без правила и когда не нашло — `null`. */
+    private _ruleNode;
+    /**
+     * Ждать узла фокуса, которого правило не нашло: у владельца коллекции
+     * остановка в модели уже новая, а её узел ещё не нарисован — день нового
+     * месяца, страница за окном, таб, добавленный в том же такте. Узел приносит
+     * элемент коллекции, и ждёт его помощник реестра узлов
+     * (`TCollectionElements.waitFor`), взятого в момент записи, как его берут
+     * правила. Без правила и без коллекции ждать нечего: узел фокуса — корень,
+     * и он уже отказал.
+     *
+     * Пока ждём, слушаем `focusin` документа в фазе перехвата: фокус, пришедший
+     * куда угодно, ожидание снимает (`_onDocumentFocusIn`).
+     */
+    private _wait;
+    /**
+     * Проверка ожидания — на регистрацию элемента коллекции и на `ready` его
+     * узла: правило зовётся снова, и цель — его ответ сейчас, а не узел,
+     * запомненный при записи. Нашло — ожидание снимается до `focus()`: свой
+     * `focusin` слушатель документа иначе счёл бы чужим. Не нашло — ждать
+     * дальше.
+     */
+    private readonly _focusFound;
+    /**
+     * Фокус пришёл куда-то, пока узла ждали. В корень — компонент уже в
+     * фокусе; мимо него — пользователь ушёл туда сам, и узел, нарисованный
+     * позже, увёл бы фокус из поля, где уже печатают. Ожидание снимается,
+     * `focused` не трогается.
+     */
+    private readonly _onDocumentFocusIn;
+    private _stopWaiting;
+    /** Узел под фокусом, если фокус на корне или внутри него; иначе `null`. */
+    private _activeWithin;
+    private _writeFocused;
+}

package/dist/custom/action/action.plugin.js

@@ -0,0 +1,339 @@
+import { TBasePlugin } from "../../base/base.class.js";
+import { TElementPlugin } from "../element/element.plugin.js";
+import { TCollectionElements } from "../collection/collection-elements.plugin.js";
+import { isFocusableElement } from "../../utils/isFocusableElement.js";
+//#region src/custom/action/action.plugin.ts
+/** Теги, где браузер сам превращает Enter/Space в click. */
+var NATIVE_ACTIVATION = /* @__PURE__ */ new Set([
+	"button",
+	"input",
+	"select",
+	"textarea"
+]);
+/**
+* TActionPlugin — взаимодействие контрола с пользователем.
+*
+* Ядру DOM недоступен, поэтому слушатели живут здесь. Элемент плагин не
+* добывает сам, а берёт у TElementPlugin — тот же приём, что в
+* TListKeyboardPlugin: композиция плагинов, а не наследование.
+*
+* Делает три вещи:
+*
+* 1. Нормализует активацию. `press` — клик, не пришедший на disabled, —
+*    независимо от того, `<button>` под компонентом или `<div>`. Из Enter и
+*    пробела на корне, где браузер клика не делает, клик делает плагин, как
+*    браузер у `<button>`: Enter — на keydown, пробел — на keyup. Поэтому на
+*    клавишу приходит и `click` потребителя, а отмена клика (`preventDefault`)
+*    одинакова для мыши и клавиатуры. Enter/Space нормализуются, только когда
+*    фокус на самом корне: вложенные поле, чекбокс или кнопка знают, что с
+*    ними делать, сами, а их клик всплывёт в корень и даст `press`, как клик
+*    мышью. Отмени корень их keydown — в Input не напечатается пробел,
+*    чекбокс не переключится, кнопка не нажмётся.
+*
+* 2. Связывает `focused` с настоящим фокусом. До этого плагина `focused` был
+*    булевым флагом, который никто не выставлял и который ничего не делал.
+*    Связь двусторонняя: фокус на корне или внутри него пишет в инстанс, а
+*    запись в инстанс ставит фокус на узел фокуса компонента. Его называет
+*    правило дескриптора (`focusTarget`): у поля фокус держит вложенный
+*    `<input>`, у ListBox — узел списка, у Tabs — таб-остановка, а корень у
+*    них — коробка вокруг. Без правила, и когда оно узла не нашло, узел
+*    фокуса — корень. Фокус уже внутри корня запись не двигает: компонент и
+*    так в фокусе. Запись `false` снимает фокус с того узла внутри корня, на
+*    котором он стоит. Писатель фокуса один — этот плагин: своего обработчика
+*    `change:focused` у плагинов компонентов нет.
+*
+*    Узла правило не нашло, корень фокус не принял, а компонент — владелец
+*    коллекции (`TCollectionElements` в наборе): остановка в модели уже
+*    новая, а её узел ещё не нарисован — день нового месяца календаря,
+*    страница за окном пагинации, таб, добавленный в том же такте. Тогда
+*    запись ждёт узла: элемент вошёл в коллекцию или объявлен его узел —
+*    правило зовётся снова, и узел, который оно нашло, получает фокус.
+*    Ожидание одно; снимают его запись `false` и `blur()`, любой `focusin` в
+*    документе, снятие корня и `destroy()`. `focus()` идёт тем же путём, что
+*    запись `true`. `focused` назад не пишется ни после записи, после которой
+*    фокус не встал, ни после снятого ожидания.
+*
+* 3. Пробрасывает сырой `click`. Нужен той стороне, у которой на руках только
+*    инстанс: в шаблоне DOM-события и так доступны через fallthrough
+*    (`<Button @click="...">`), а через ctrl — только отсюда.
+*/
+var TActionPlugin = class extends TBasePlugin {
+	_element = null;
+	_instance = null;
+	/** Контекст набора: его получает правило узла фокуса. */
+	_ctx = null;
+	_keys = ["Enter", " "];
+	/** Правило узла фокуса из опций дескриптора; нет — фокус держит корень. */
+	_focusTarget = null;
+	_syncingFocus = false;
+	/** Снять ожидание узла фокуса (`_wait`); `null` — фокус узла не ждёт. */
+	_waiting = null;
+	/** Пробел нажат на корне: клик — когда его отпустят, как у `<button>`. */
+	_spaceDown = false;
+	install(ctx, options) {
+		super.install(ctx, options);
+		this._ctx = ctx;
+		this._instance = ctx.getInstance();
+		if (options?.keys) this._keys = options.keys;
+		this._focusTarget = options?.focusTarget ?? null;
+		const elementPlugin = ctx.get(TElementPlugin);
+		elementPlugin?.events.on("ready", (element) => this._attach(element));
+		elementPlugin?.events.on("removed", () => this._detach());
+		this._listenTo(this._instance?.events, "change:focused", ({ newValue }) => this._onFocusedChange(newValue));
+	}
+	destroy() {
+		this._detach();
+		this._instance = null;
+		this._ctx = null;
+		super.destroy();
+	}
+	/** Корневой элемент контрола. Появляется только после монтирования. */
+	get element() {
+		return this._element;
+	}
+	/**
+	* Перевести фокус на контрол — на его узел фокуса (`_moveFocus`): у поля
+	* это `<input>`, а не коробка вокруг. Путь тот же, что у записи
+	* `focused = true`, и узла, которого ещё нет, `focus()` ждёт так же.
+	*/
+	focus() {
+		const element = this._element;
+		if (element) this._moveFocus(element);
+	}
+	/**
+	* Снять фокус с контрола — с того узла внутри корня, на котором он стоит,
+	* как запись `focused = false`: у поля фокус держит вложенный `<input>`, и
+	* `blur()` корня его бы не снял. Фокус, который ещё ждёт узла, снимается
+	* тоже: иначе узел, нарисованный позже, получил бы фокус после `blur()`.
+	*/
+	blur() {
+		this._stopWaiting();
+		const element = this._element;
+		const active = element ? this._activeWithin(element) : null;
+		if (isFocusableElement(active)) active.blur();
+	}
+	_attach(element) {
+		this._detach();
+		this._element = element;
+		const target = element;
+		target.addEventListener("click", this._onClick);
+		target.addEventListener("keydown", this._onKeyDown);
+		target.addEventListener("keyup", this._onKeyUp);
+		target.addEventListener("focusin", this._onFocusIn);
+		target.addEventListener("focusout", this._onFocusOut);
+		if (this._instance?.focused) this._onFocusedChange(true);
+	}
+	_detach() {
+		this._stopWaiting();
+		const target = this._element;
+		if (!target) return;
+		target.removeEventListener("click", this._onClick);
+		target.removeEventListener("keydown", this._onKeyDown);
+		target.removeEventListener("keyup", this._onKeyUp);
+		target.removeEventListener("focusin", this._onFocusIn);
+		target.removeEventListener("focusout", this._onFocusOut);
+		this._element = null;
+		this._spaceDown = false;
+	}
+	get _disabled() {
+		return this._instance?.disabled === true;
+	}
+	/**
+	* Сам ли браузер сделает click из Enter/Space на корне.
+	* Для `<a href>` — только Enter, но Space на ссылке и не должен активировать,
+	* поэтому весь тег целиком отдаём нативному поведению.
+	*
+	* Смотрит на тег корня, а не цели события: клавиши из вложенных элементов
+	* до этой проверки не доходят — `_onKeyDown` нормализует только нажатия с
+	* фокусом на корне.
+	*/
+	get _nativeActivation() {
+		const element = this._element;
+		if (!element) return false;
+		const tag = element.tagName.toLowerCase();
+		return NATIVE_ACTIVATION.has(tag) || tag === "a" && element.hasAttribute("href");
+	}
+	_onClick = (event) => {
+		this.events.emit("click", event);
+		if (this._disabled) return;
+		this.events.emit("press", event);
+	};
+	/**
+	* Клавиша активации на корне, который браузер в клик не превращает.
+	*
+	* Клик, а не сразу `press`: так у `<button>`, и клавиша проходит тот же
+	* путь, что мышь, — `click` потребителя, его отмена, `press`. Пробел
+	* кликает, когда его отпустят, Enter — сразу.
+	*
+	* Нажатие для `<button>` — действие клавиши по умолчанию: его отменяет
+	* `preventDefault` любого обработчика на пути клавиши, и на предке тоже.
+	* Поэтому решение — в конце рассылки, а не здесь, на корне, где обработчики
+	* предков ещё не прошли: так клавиша, которую взял себе предок (Enter со
+	* строки ListBox выбирает подсвеченный элемент), строку не нажмёт. Конец
+	* рассылки — окно: дальше событие не всплывает. Клавишу, всплытие которой
+	* остановили, корень тоже не нажимает — её взял себе тот, кто остановил.
+	*/
+	_onKeyDown = (event) => {
+		if (!this._ownKey(event)) return;
+		const view = this._element?.ownerDocument.defaultView;
+		if (!view) return;
+		view.addEventListener("keydown", (passed) => {
+			if (passed !== event || event.defaultPrevented) return;
+			event.preventDefault();
+			if (event.key === " ") this._spaceDown = true;
+			else this._click();
+		}, { once: true });
+	};
+	_onKeyUp = (event) => {
+		if (event.key !== " " || !this._spaceDown) return;
+		this._spaceDown = false;
+		if (this._ownKey(event)) this._click();
+	};
+	/** Клавиша активации — на самом корне не-нативного тега, не на disabled. */
+	_ownKey(event) {
+		if (!this._keys.includes(event.key)) return false;
+		if (event.target !== this._element) return false;
+		if (this._nativeActivation) return false;
+		return !this._disabled;
+	}
+	/** Клик по корню — тот, что браузер делает из клавиши у `<button>`. */
+	_click() {
+		this._element?.dispatchEvent(new MouseEvent("click", {
+			bubbles: true,
+			cancelable: true,
+			composed: true
+		}));
+	}
+	_onFocusIn = (event) => {
+		this.events.emit("focus", event);
+		this._writeFocused(true);
+	};
+	_onFocusOut = (event) => {
+		if (event.target === this._element) this._spaceDown = false;
+		this.events.emit("blur", event);
+		this._writeFocused(false);
+	};
+	/**
+	* Инстанс → DOM. Флаг `_syncingFocus` рвёт цикл: focus() вызовет focusin,
+	* тот запишет focused, тот снова придёт сюда.
+	*
+	* В фокусе ли компонент, считается по корню, как в обратную сторону
+	* (`focusin` и `focusout` корня): фокус внутри корня — на кнопке очистки
+	* поля или в поле шапки ListBox — `focused = true` не двигает. Ставит
+	* фокус запись на узел фокуса (`_moveFocus`), снимает — с узла внутри
+	* корня, на котором он стоит.
+	*
+	* Запись `false` снимает и ожидание узла — до проверки, есть ли что
+	* снимать: пока узла ждут, фокуса в корне нет.
+	*/
+	_onFocusedChange = (value) => {
+		if (!value) this._stopWaiting();
+		if (this._syncingFocus) return;
+		const element = this._element;
+		if (!element) return;
+		const active = this._activeWithin(element);
+		if (value === (active !== null)) return;
+		this._syncingFocus = true;
+		try {
+			if (value) this._moveFocus(element);
+			else if (isFocusableElement(active)) active.blur();
+		} finally {
+			this._syncingFocus = false;
+		}
+	};
+	/**
+	* Фокус — на узел фокуса компонента: что нашло правило дескриптора, иначе
+	* корень. Узла правило не нашло, а корень фокус не принял — ждать узла
+	* (`_wait`). Попытка заменяет прежнее ожидание: оно всегда одно.
+	*
+	* Правило зовётся на каждую запись, а не один раз на `ready`: узел фокуса
+	* бывает новым — у Tabs остановка переезжает с активацией.
+	*
+	* Узел плагину приходит как `Element`, поэтому фокусируемость проверяется
+	* гардом: у корня-`svg` фокус есть, а у произвольного `Element` — нет.
+	*/
+	_moveFocus(root) {
+		this._stopWaiting();
+		const node = this._ruleNode(root);
+		if (node) {
+			if (isFocusableElement(node)) node.focus();
+			return;
+		}
+		if (isFocusableElement(root)) root.focus();
+		if (this._activeWithin(root) === null) this._wait(root);
+	}
+	/** Узел, который нашло правило дескриптора; без правила и когда не нашло — `null`. */
+	_ruleNode(root) {
+		const rule = this._focusTarget;
+		const ctx = this._ctx;
+		return rule && ctx ? rule(root, ctx) : null;
+	}
+	/**
+	* Ждать узла фокуса, которого правило не нашло: у владельца коллекции
+	* остановка в модели уже новая, а её узел ещё не нарисован — день нового
+	* месяца, страница за окном, таб, добавленный в том же такте. Узел приносит
+	* элемент коллекции, и ждёт его помощник реестра узлов
+	* (`TCollectionElements.waitFor`), взятого в момент записи, как его берут
+	* правила. Без правила и без коллекции ждать нечего: узел фокуса — корень,
+	* и он уже отказал.
+	*
+	* Пока ждём, слушаем `focusin` документа в фазе перехвата: фокус, пришедший
+	* куда угодно, ожидание снимает (`_onDocumentFocusIn`).
+	*/
+	_wait(root) {
+		const elements = this._focusTarget ? this._ctx?.get(TCollectionElements) : void 0;
+		if (!elements) return;
+		const doc = root.ownerDocument;
+		const stop = elements.waitFor(this._focusFound);
+		doc.addEventListener("focusin", this._onDocumentFocusIn, true);
+		this._waiting = () => {
+			stop();
+			doc.removeEventListener("focusin", this._onDocumentFocusIn, true);
+		};
+	}
+	/**
+	* Проверка ожидания — на регистрацию элемента коллекции и на `ready` его
+	* узла: правило зовётся снова, и цель — его ответ сейчас, а не узел,
+	* запомненный при записи. Нашло — ожидание снимается до `focus()`: свой
+	* `focusin` слушатель документа иначе счёл бы чужим. Не нашло — ждать
+	* дальше.
+	*/
+	_focusFound = () => {
+		const root = this._element;
+		const node = root ? this._ruleNode(root) : null;
+		if (!node) return false;
+		this._stopWaiting();
+		if (isFocusableElement(node)) node.focus();
+		return true;
+	};
+	/**
+	* Фокус пришёл куда-то, пока узла ждали. В корень — компонент уже в
+	* фокусе; мимо него — пользователь ушёл туда сам, и узел, нарисованный
+	* позже, увёл бы фокус из поля, где уже печатают. Ожидание снимается,
+	* `focused` не трогается.
+	*/
+	_onDocumentFocusIn = () => {
+		this._stopWaiting();
+	};
+	_stopWaiting() {
+		const stop = this._waiting;
+		this._waiting = null;
+		stop?.();
+	}
+	/** Узел под фокусом, если фокус на корне или внутри него; иначе `null`. */
+	_activeWithin(root) {
+		const active = root.ownerDocument.activeElement;
+		return active && root.contains(active) ? active : null;
+	}
+	_writeFocused(value) {
+		if (!this._instance || this._instance.focused === value) return;
+		this._syncingFocus = true;
+		try {
+			this._instance.focused = value;
+		} finally {
+			this._syncingFocus = false;
+		}
+	}
+};
+//#endregion
+export { TActionPlugin };

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

@@ -0,0 +1,2 @@
+export type { TActionPluginEvents, IActionPluginOptions, TFocusTarget } from './types';
+export { TActionPlugin } from './action.plugin';

package/dist/custom/action/types.d.ts

@@ -0,0 +1,65 @@
+import type { IPluginContext, TPluginEvents } from '../../base';
+/**
+ * События взаимодействия с пользователем.
+ *
+ * Разделены намеренно: `click` — то, что реально произошло в DOM, `press` —
+ * намерение активировать контрол. Они не совпадают. У нативной `<button
+ * disabled>` клик не приходит вообще, а у `<div aria-disabled="true">` —
+ * приходит. `press` сглаживает это, `click` оставляет как есть — иначе с
+ * инстанса не добраться до правды. Enter и пробел на корне-`<div>` плагин
+ * превращает в клик сам, как браузер у `<button>`, поэтому `press` всегда
+ * приходит из клика.
+ */
+export type TActionPluginEvents = TPluginEvents & {
+    /**
+     * Активация контрола: клик — мышью или из Enter/Space с фокусом на корне.
+     * Не приходит на disabled.
+     */
+    press: (event: MouseEvent) => void;
+    /** Сырой DOM-клик, без фильтра по disabled. */
+    click: (event: MouseEvent) => void;
+    /** Фокус внутри корневого элемента. */
+    focus: (event: FocusEvent) => void;
+    /** Фокус ушёл из корневого элемента. */
+    blur: (event: FocusEvent) => void;
+};
+/**
+ * Правило узла фокуса: по корню компонента и контексту его набора находит
+ * узел внутри корня, который держит фокус компонента, — поле формы, узел
+ * списка, таб-остановку. `null` — такого узла нет, и фокус получает корень.
+ *
+ * Корень фокус не принял, а у компонента есть коллекция (`TCollectionElements`
+ * в наборе), — `null` значит «узла ещё нет»: остановка в модели уже новая, а
+ * разметка её не нарисовала. Тогда плагин действия ждёт узла и зовёт правило
+ * снова — на каждую регистрацию элемента коллекции и на `ready` его узла.
+ * Поэтому правило ищет узел заново на каждый вызов, у модели, и ничего не
+ * помнит между вызовами.
+ *
+ * Модель фокуса у каждого компонента своя, и знают её плагины компонента.
+ * Поэтому правило — функция слоя плагинов рядом с теми, кто этот узел уже
+ * ищет (`fieldOf`, `listOf`, `tabStopOf`), а называет его дескриптор
+ * компонента опцией плагина действия.
+ */
+export type TFocusTarget = (root: Element, ctx: IPluginContext) => Element | null;
+export interface IActionPluginOptions {
+    /**
+     * Клавиши, активирующие контрол с фокусом на корне не-нативного тега.
+     * По умолчанию Enter и Space — как требует WAI-ARIA для role="button".
+     */
+    keys?: readonly string[];
+    /**
+     * Куда ставят фокус запись `focused = true` и `focus()` — правило узла
+     * фокуса: `ActionPluginDescriptor.with({ focusTarget: listOf })`. Без
+     * правила, и когда оно вернуло `null`, фокус получает корень. Корень фокус
+     * не принял, а компонент — владелец коллекции, — запись ждёт узла и зовёт
+     * правило снова, когда элемент коллекции вошёл в неё или объявлен его узел
+     * (`TFocusTarget`).
+     *
+     * Нужна компоненту, у которого фокус держит не корень: у поля — вложенный
+     * `<input>`, у ListBox — узел списка рядом с шапкой и подвалом, у Tabs —
+     * таб-остановка. Общего правила «первая остановка Tab внутри» нет: кнопка
+     * в слоте `leading` и поле поиска в шапке — свои остановки перед главной
+     * частью, и фокус ушёл бы на них.
+     */
+    focusTarget?: TFocusTarget;
+}