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

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

@@ -0,0 +1,174 @@
+import { TBasePlugin } from '../../base';
+import type { IPluginContext } from '../../base';
+import type { IDismissPluginOptions, TDismissPluginEvents } from './types';
+/**
+ * TDismissPlugin — «нажали мимо».
+ *
+ * Общий для всего, что открывается поверх страницы: Select, Menu, Popover,
+ * Tooltip, модальное окно. Сообщает событием `dismiss`, а владельца, чью
+ * открытость ведёт (`property`), закрывает уже после этого — подписчики
+ * застают его открытым и знают причину закрытия. Без привязки
+ * (`property: null`) только сообщает.
+ *
+ * Почему `pointerdown`, а не `click`. Клик приходит после отпускания кнопки,
+ * и до него успевает произойти смена фокуса — панель закрывается уже после
+ * того, как фокус ушёл, и порядок событий для скринридера ломается.
+ *
+ * Касание пальцем решается на `pointerup`. На тач-устройстве с того же
+ * `pointerdown` начинается прокрутка страницы, и панель закрывалась бы, едва
+ * пользователь начал листать. Поэтому касание мимо только запоминает свой
+ * `pointerId`, а `dismiss` шлёт `pointerup` того же касания. Порог сдвига не
+ * нужен: забрав касание под прокрутку, браузер шлёт `pointercancel`, и
+ * `pointerup` не приходит. `click` не годится и здесь — `pointerType` в нём
+ * есть не у всех браузеров. Порядку фокуса это не вредит: на касании фокус
+ * переходит только перед `click`, уже после `pointerup`. Мышь остаётся на
+ * `pointerdown`.
+ *
+ * Перо решается первым из двух событий: `pointerup` того же `pointerId` или
+ * совместимым `mousedown`. По `pointerType` стилус на сенсорном экране (Apple
+ * Pencil, S Pen, перо Windows-планшета) не отличить от пера графического
+ * планшета, а ведут они себя по-разному. Решать перо на `pointerdown`, как
+ * мышь, нельзя: стилус листает страницу, как палец. Ждать `pointerup`, как у
+ * касания, тоже нельзя: перо планшета ведёт себя как мышь — `mousedown`, а с
+ * ним и смена фокуса, идёт сразу за `pointerdown`, и панель закрылась бы уже
+ * после ухода фокуса. Поэтому устройство не угадываем, а решаем по порядку
+ * событий, который задаёт браузер. На планшете первым приходит `mousedown`, и
+ * панель закрывается до смены фокуса. Стилусу на экране совместимые события
+ * мыши приходят только после отпускания: решает `pointerup`, а прокрутка
+ * (`pointercancel`) снимает ожидание и ничего не закрывает. Исключение одно:
+ * страница отменила `pointerdown`. Совместимых событий тогда нет, и перо
+ * решает `pointerup` и на планшете.
+ *
+ * Как считается «мимо». Панель обычно телепортирована в `body`, то есть
+ * лежит вне поддерева владельца — простой `contains()` по корню посчитал бы
+ * нажатие внутри панели нажатием снаружи. Поэтому панель помечается
+ * `data-owner="<id>"` — `id` части `owner` монтирования владельца
+ * (`createId`), — и плагин проверяет обе границы. Это чистый DOM: работает
+ * одинаково во всех шести адаптерах и не требует проводки между компонентами.
+ *
+ * Третья граница — слои. Список Select в поповере, поповер в поповере — это
+ * тоже панели в `body`, соседи панели владельца, а не её потомки. Нажатие в
+ * них — нажатие внутри: слой открыт поверх панели владельца, из неё. Порядок
+ * слоёв ведёт `TLayer` — Frame и модальное окно (`data-layer`, номер растёт с
+ * каждым показом), и нажатие в панель, чей слой выше слоя своей, мимо не
+ * считается. Слой ниже или узел без слоя — мимо: так закрывается вложенный
+ * слой нажатием во внешний.
+ *
+ * С `focusOutside` то же правило решает и уход фокуса: `focusin` мимо
+ * владельца, его панели и слоёв выше даёт `dismiss`.
+ */
+export declare class TDismissPlugin extends TBasePlugin<any, TDismissPluginEvents> {
+    /** Умолчания опций, объявленных пропами, — см. `TAnchorPlugin.defaultValues`. */
+    static defaultValues: Required<Pick<IDismissPluginOptions, 'enabled'>>;
+    private _element;
+    /**
+     * Пометка панели владельца — значение `data-owner`. От монтирования, а не
+     * от `uid`: пометка уходит в разметку, и на сервере и в браузере обязана
+     * совпасть.
+     */
+    private _ownerMark;
+    /**
+     * Открытость владельца (`property`): по ней плагин включается, ею же
+     * `dismiss` закрывает владельца. `null` — привязки нет, плагин только
+     * сообщает.
+     */
+    private _open;
+    private _enabled;
+    private _focusOutside;
+    private _listening;
+    /** Нажатие мимо, которое ждёт решения, — касание или перо (см. `_onPointerDown`). */
+    private _pending;
+    install(ctx: IPluginContext, options?: IDismissPluginOptions): void;
+    /**
+     * Сообщает о нажатии или фокусе мимо, потом закрывает владельца.
+     *
+     * Закрывает здесь, после подписчиков `dismiss`, а не первым подписчиком:
+     * иначе остальные узнавали бы о нажатии мимо уже закрытыми и не отличали
+     * бы его от закрытия по другой причине.
+     *
+     * Закрывает с причиной `outside`: владелец, который принимает запрос
+     * закрытия (модальное окно), решает сам — закрыться, отклонить нажатие
+     * мимо или отдать решение подписчику. `dismiss` при этом уже пришёл:
+     * нажатие мимо было, закроется окно или нет.
+     */
+    private _dismiss;
+    /**
+     * Следит ли плагин за нажатиями (с `focusOutside` — и за фокусом).
+     * Владелец включает его на открытии.
+     */
+    get enabled(): boolean;
+    set enabled(value: boolean);
+    /**
+     * Атрибут для панели владельца. Разметка раскладывает его спредом на
+     * телепортированный узел, иначе нажатие внутри панели будет считаться
+     * нажатием мимо.
+     */
+    get ownerAttribute(): Record<string, string>;
+    /**
+     * Панель владельца — узел с его `ownerAttribute` в документе корня. `null`,
+     * пока корень не объявлен или панели в документе нет.
+     *
+     * Панель телепортирована, и ссылки на неё у плагинов нет: разметка отдаёт
+     * им только корень. Поэтому её находят по той же пометке, по которой
+     * плагин отличает нажатие в неё. Нужна и соседям по набору: плагин фокуса
+     * Popover уводит фокус в панель и слушает на ней клавиши.
+     */
+    findPanel(): Element | null;
+    /**
+     * Пришлось ли нажатие или фокус внутрь владельца, его панели или слоя выше
+     * неё — панели, открытой поверх своей (см. шапку). Правило слоёв общее с
+     * `THideOutsidePlugin`, поэтому живёт в утилитах (`isAboveLayer`).
+     *
+     * Нужно и соседям по набору: возврат поля Select на уходе фокуса решает
+     * по тем же границам.
+     */
+    isInside(target: EventTarget | null): boolean;
+    destroy(): void;
+    /** Селектор панели владельца — по её пометке. */
+    private get _panelSelector();
+    /**
+     * Мышь решает на нажатии, касание и перо ждут (см. шапку).
+     *
+     * Ожидание одно — для последнего опущенного нажатия, поэтому любое нажатие
+     * (мышью, пальцем или пером, внутрь или мимо) сначала снимает прежнее.
+     * Иначе панель, с которой уже работают, закрыло бы отпускание пальца,
+     * лёгшего мимо раньше, или `mousedown` мыши, нажатой внутрь, пока перо
+     * лежит мимо: он засчитался бы за перо.
+     */
+    private readonly _onPointerDown;
+    /** Касание ничего не закрывает — только запоминается, если пришлось мимо. */
+    private _startTouch;
+    /**
+     * Перо тоже только запоминается, если пришлось мимо. Решит его то, что
+     * придёт первым: `pointerup` (стилус на экране) или совместимый `mousedown`
+     * (перо графического планшета).
+     */
+    private _startPen;
+    /**
+     * Касание или перо мимо отпустили, не начав прокрутку, — это и есть нажатие
+     * мимо. Перо, которое уже решил его `mousedown`, ожидания не оставляет, и
+     * отпускание его не повторяет.
+     */
+    private readonly _onPointerUp;
+    /** Браузер забрал касание или перо под прокрутку или жест — закрывать нечего. */
+    private readonly _onPointerCancel;
+    /**
+     * Совместимый `mousedown` решает перо, если пришёл раньше его `pointerup`:
+     * так ведёт себя перо планшета, и панель закрывается до смены фокуса.
+     *
+     * Касание он не решает: прослойки, которые шлют `mousedown` на
+     * `touchstart`, вернули бы закрытие в начале прокрутки. Мышь к нему уже
+     * решена своим `pointerdown` и ожидания не оставляет. Переносить её сюда
+     * нельзя: страница, отменившая `pointerdown` (так делают drag-библиотеки),
+     * совместимого `mousedown` не получает.
+     */
+    private readonly _onMouseDown;
+    /**
+     * Фокус ушёл мимо — с `focusOutside`. Слушатель на документе, в фазе
+     * перехвата, как у нажатий: `focusin` всплывает, и остановить его до
+     * документа содержимое не может.
+     */
+    private readonly _onFocusIn;
+    /** Слушатели на документе живут, только пока они нужны. */
+    private _sync;
+}

package/dist/custom/dismiss/dismiss.plugin.js

@@ -0,0 +1,287 @@
+import { TBasePlugin } from "../../base/base.class.js";
+import { TElementPlugin } from "../element/element.plugin.js";
+import { isAboveLayer } from "../../utils/isAboveLayer.js";
+import { bindOverlayOpen } from "../overlay/open-state.js";
+//#region src/custom/dismiss/dismiss.plugin.ts
+/** Атрибут, которым панель помечается владельцем (`ownerAttribute`). */
+var OWNER_ATTRIBUTE = "data-owner";
+/**
+* TDismissPlugin — «нажали мимо».
+*
+* Общий для всего, что открывается поверх страницы: Select, Menu, Popover,
+* Tooltip, модальное окно. Сообщает событием `dismiss`, а владельца, чью
+* открытость ведёт (`property`), закрывает уже после этого — подписчики
+* застают его открытым и знают причину закрытия. Без привязки
+* (`property: null`) только сообщает.
+*
+* Почему `pointerdown`, а не `click`. Клик приходит после отпускания кнопки,
+* и до него успевает произойти смена фокуса — панель закрывается уже после
+* того, как фокус ушёл, и порядок событий для скринридера ломается.
+*
+* Касание пальцем решается на `pointerup`. На тач-устройстве с того же
+* `pointerdown` начинается прокрутка страницы, и панель закрывалась бы, едва
+* пользователь начал листать. Поэтому касание мимо только запоминает свой
+* `pointerId`, а `dismiss` шлёт `pointerup` того же касания. Порог сдвига не
+* нужен: забрав касание под прокрутку, браузер шлёт `pointercancel`, и
+* `pointerup` не приходит. `click` не годится и здесь — `pointerType` в нём
+* есть не у всех браузеров. Порядку фокуса это не вредит: на касании фокус
+* переходит только перед `click`, уже после `pointerup`. Мышь остаётся на
+* `pointerdown`.
+*
+* Перо решается первым из двух событий: `pointerup` того же `pointerId` или
+* совместимым `mousedown`. По `pointerType` стилус на сенсорном экране (Apple
+* Pencil, S Pen, перо Windows-планшета) не отличить от пера графического
+* планшета, а ведут они себя по-разному. Решать перо на `pointerdown`, как
+* мышь, нельзя: стилус листает страницу, как палец. Ждать `pointerup`, как у
+* касания, тоже нельзя: перо планшета ведёт себя как мышь — `mousedown`, а с
+* ним и смена фокуса, идёт сразу за `pointerdown`, и панель закрылась бы уже
+* после ухода фокуса. Поэтому устройство не угадываем, а решаем по порядку
+* событий, который задаёт браузер. На планшете первым приходит `mousedown`, и
+* панель закрывается до смены фокуса. Стилусу на экране совместимые события
+* мыши приходят только после отпускания: решает `pointerup`, а прокрутка
+* (`pointercancel`) снимает ожидание и ничего не закрывает. Исключение одно:
+* страница отменила `pointerdown`. Совместимых событий тогда нет, и перо
+* решает `pointerup` и на планшете.
+*
+* Как считается «мимо». Панель обычно телепортирована в `body`, то есть
+* лежит вне поддерева владельца — простой `contains()` по корню посчитал бы
+* нажатие внутри панели нажатием снаружи. Поэтому панель помечается
+* `data-owner="<id>"` — `id` части `owner` монтирования владельца
+* (`createId`), — и плагин проверяет обе границы. Это чистый DOM: работает
+* одинаково во всех шести адаптерах и не требует проводки между компонентами.
+*
+* Третья граница — слои. Список Select в поповере, поповер в поповере — это
+* тоже панели в `body`, соседи панели владельца, а не её потомки. Нажатие в
+* них — нажатие внутри: слой открыт поверх панели владельца, из неё. Порядок
+* слоёв ведёт `TLayer` — Frame и модальное окно (`data-layer`, номер растёт с
+* каждым показом), и нажатие в панель, чей слой выше слоя своей, мимо не
+* считается. Слой ниже или узел без слоя — мимо: так закрывается вложенный
+* слой нажатием во внешний.
+*
+* С `focusOutside` то же правило решает и уход фокуса: `focusin` мимо
+* владельца, его панели и слоёв выше даёт `dismiss`.
+*/
+var TDismissPlugin = class TDismissPlugin extends TBasePlugin {
+	/** Умолчания опций, объявленных пропами, — см. `TAnchorPlugin.defaultValues`. */
+	static defaultValues = { enabled: false };
+	_element = null;
+	/**
+	* Пометка панели владельца — значение `data-owner`. От монтирования, а не
+	* от `uid`: пометка уходит в разметку, и на сервере и в браузере обязана
+	* совпасть.
+	*/
+	_ownerMark = "";
+	/**
+	* Открытость владельца (`property`): по ней плагин включается, ею же
+	* `dismiss` закрывает владельца. `null` — привязки нет, плагин только
+	* сообщает.
+	*/
+	_open = null;
+	_enabled = TDismissPlugin.defaultValues.enabled;
+	_focusOutside = false;
+	_listening = false;
+	/** Нажатие мимо, которое ждёт решения, — касание или перо (см. `_onPointerDown`). */
+	_pending = null;
+	install(ctx, options) {
+		super.install(ctx, options);
+		this._ownerMark = ctx.createId("owner");
+		ctx.get(TElementPlugin)?.events.on("ready", (element) => {
+			this._element = element;
+			this._sync();
+		});
+		ctx.get(TElementPlugin)?.events.on("removed", () => {
+			this._element = null;
+			this._sync();
+		});
+		this._enabled = options?.enabled ?? this._enabled;
+		this._focusOutside = options?.focusOutside ?? this._focusOutside;
+		this._open = bindOverlayOpen(ctx, options, (open) => {
+			this.enabled = open;
+		});
+		if (this._open) this.enabled = this._open.read();
+	}
+	/**
+	* Сообщает о нажатии или фокусе мимо, потом закрывает владельца.
+	*
+	* Закрывает здесь, после подписчиков `dismiss`, а не первым подписчиком:
+	* иначе остальные узнавали бы о нажатии мимо уже закрытыми и не отличали
+	* бы его от закрытия по другой причине.
+	*
+	* Закрывает с причиной `outside`: владелец, который принимает запрос
+	* закрытия (модальное окно), решает сам — закрыться, отклонить нажатие
+	* мимо или отдать решение подписчику. `dismiss` при этом уже пришёл:
+	* нажатие мимо было, закроется окно или нет.
+	*/
+	_dismiss(event) {
+		this.events.emit("dismiss", event);
+		this._open?.close("outside");
+	}
+	/**
+	* Следит ли плагин за нажатиями (с `focusOutside` — и за фокусом).
+	* Владелец включает его на открытии.
+	*/
+	get enabled() {
+		return this._enabled;
+	}
+	set enabled(value) {
+		const oldEnabled = this.enabled;
+		if (this._enabled === value) return;
+		this._enabled = value;
+		this._sync();
+		this.events.emit("change:enabled", {
+			newValue: value,
+			oldValue: oldEnabled
+		});
+	}
+	/**
+	* Атрибут для панели владельца. Разметка раскладывает его спредом на
+	* телепортированный узел, иначе нажатие внутри панели будет считаться
+	* нажатием мимо.
+	*/
+	get ownerAttribute() {
+		return { [OWNER_ATTRIBUTE]: this._ownerMark };
+	}
+	/**
+	* Панель владельца — узел с его `ownerAttribute` в документе корня. `null`,
+	* пока корень не объявлен или панели в документе нет.
+	*
+	* Панель телепортирована, и ссылки на неё у плагинов нет: разметка отдаёт
+	* им только корень. Поэтому её находят по той же пометке, по которой
+	* плагин отличает нажатие в неё. Нужна и соседям по набору: плагин фокуса
+	* Popover уводит фокус в панель и слушает на ней клавиши.
+	*/
+	findPanel() {
+		return this._element?.ownerDocument.querySelector(this._panelSelector) ?? null;
+	}
+	/**
+	* Пришлось ли нажатие или фокус внутрь владельца, его панели или слоя выше
+	* неё — панели, открытой поверх своей (см. шапку). Правило слоёв общее с
+	* `THideOutsidePlugin`, поэтому живёт в утилитах (`isAboveLayer`).
+	*
+	* Нужно и соседям по набору: возврат поля Select на уходе фокуса решает
+	* по тем же границам.
+	*/
+	isInside(target) {
+		if (!(target instanceof Element)) return false;
+		if (this._element?.contains(target)) return true;
+		if (target.closest(this._panelSelector)) return true;
+		return isAboveLayer(target, this.findPanel());
+	}
+	destroy() {
+		this._enabled = false;
+		this._sync();
+		this._open?.unbind();
+		this._open = null;
+		this._element = null;
+		super.destroy();
+	}
+	/** Селектор панели владельца — по её пометке. */
+	get _panelSelector() {
+		return `[${OWNER_ATTRIBUTE}="${this._ownerMark}"]`;
+	}
+	/**
+	* Мышь решает на нажатии, касание и перо ждут (см. шапку).
+	*
+	* Ожидание одно — для последнего опущенного нажатия, поэтому любое нажатие
+	* (мышью, пальцем или пером, внутрь или мимо) сначала снимает прежнее.
+	* Иначе панель, с которой уже работают, закрыло бы отпускание пальца,
+	* лёгшего мимо раньше, или `mousedown` мыши, нажатой внутрь, пока перо
+	* лежит мимо: он засчитался бы за перо.
+	*/
+	_onPointerDown = (event) => {
+		this._pending = null;
+		if (event.pointerType === "touch") {
+			this._startTouch(event);
+			return;
+		}
+		if (event.pointerType === "pen") {
+			this._startPen(event);
+			return;
+		}
+		if (this.isInside(event.target)) return;
+		this._dismiss(event);
+	};
+	/** Касание ничего не закрывает — только запоминается, если пришлось мимо. */
+	_startTouch(event) {
+		if (this.isInside(event.target)) return;
+		this._pending = {
+			pointerId: event.pointerId,
+			pointerType: "touch"
+		};
+	}
+	/**
+	* Перо тоже только запоминается, если пришлось мимо. Решит его то, что
+	* придёт первым: `pointerup` (стилус на экране) или совместимый `mousedown`
+	* (перо графического планшета).
+	*/
+	_startPen(event) {
+		if (this.isInside(event.target)) return;
+		this._pending = {
+			pointerId: event.pointerId,
+			pointerType: "pen"
+		};
+	}
+	/**
+	* Касание или перо мимо отпустили, не начав прокрутку, — это и есть нажатие
+	* мимо. Перо, которое уже решил его `mousedown`, ожидания не оставляет, и
+	* отпускание его не повторяет.
+	*/
+	_onPointerUp = (event) => {
+		if (event.pointerId !== this._pending?.pointerId) return;
+		this._pending = null;
+		this._dismiss(event);
+	};
+	/** Браузер забрал касание или перо под прокрутку или жест — закрывать нечего. */
+	_onPointerCancel = (event) => {
+		if (event.pointerId !== this._pending?.pointerId) return;
+		this._pending = null;
+	};
+	/**
+	* Совместимый `mousedown` решает перо, если пришёл раньше его `pointerup`:
+	* так ведёт себя перо планшета, и панель закрывается до смены фокуса.
+	*
+	* Касание он не решает: прослойки, которые шлют `mousedown` на
+	* `touchstart`, вернули бы закрытие в начале прокрутки. Мышь к нему уже
+	* решена своим `pointerdown` и ожидания не оставляет. Переносить её сюда
+	* нельзя: страница, отменившая `pointerdown` (так делают drag-библиотеки),
+	* совместимого `mousedown` не получает.
+	*/
+	_onMouseDown = (event) => {
+		if (this._pending?.pointerType !== "pen") return;
+		this._pending = null;
+		this._dismiss(event);
+	};
+	/**
+	* Фокус ушёл мимо — с `focusOutside`. Слушатель на документе, в фазе
+	* перехвата, как у нажатий: `focusin` всплывает, и остановить его до
+	* документа содержимое не может.
+	*/
+	_onFocusIn = (event) => {
+		if (this.isInside(event.target)) return;
+		this._dismiss(event);
+	};
+	/** Слушатели на документе живут, только пока они нужны. */
+	_sync() {
+		const shouldListen = this._enabled && !!this._element;
+		if (shouldListen === this._listening) return;
+		const doc = this._element?.ownerDocument ?? globalThis.document;
+		if (!doc) return;
+		if (shouldListen) {
+			doc.addEventListener("pointerdown", this._onPointerDown, true);
+			doc.addEventListener("pointerup", this._onPointerUp, true);
+			doc.addEventListener("pointercancel", this._onPointerCancel, true);
+			doc.addEventListener("mousedown", this._onMouseDown, true);
+			if (this._focusOutside) doc.addEventListener("focusin", this._onFocusIn, true);
+		} else {
+			doc.removeEventListener("pointerdown", this._onPointerDown, true);
+			doc.removeEventListener("pointerup", this._onPointerUp, true);
+			doc.removeEventListener("pointercancel", this._onPointerCancel, true);
+			doc.removeEventListener("mousedown", this._onMouseDown, true);
+			doc.removeEventListener("focusin", this._onFocusIn, true);
+			this._pending = null;
+		}
+		this._listening = shouldListen;
+	}
+};
+//#endregion
+export { TDismissPlugin };

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

@@ -0,0 +1,2 @@
+export { TDismissPlugin } from './dismiss.plugin';
+export type { IDismissPluginOptions, TDismissPluginEvents, IDismissPluginProps } from './types';

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

@@ -0,0 +1,59 @@
+import type { TValuePayload } from '@soxa-ui/core';
+import type { TPluginEvents } from '../../base';
+import type { IOverlayOpenOptions } from '../overlay/types';
+export interface IDismissPluginOptions extends IOverlayOpenOptions {
+    /**
+     * Слушать ли документ сразу после установки.
+     *
+     * Обычно этого не задают: плагин сам следит за открытостью владельца
+     * (`property`) — пока она `false`, глобального слушателя нет, а нажатие
+     * мимо ставит её в `false`. Вручную слежение ведут через `enabled` при
+     * `property: null`.
+     */
+    enabled?: boolean;
+    /**
+     * Закрывать ли и уходом фокуса: `focusin` вне владельца, его панели и
+     * слоёв выше неё даёт `dismiss`, как нажатие мимо. По умолчанию выключено.
+     *
+     * Нужно тому, в чью панель уходит фокус (Popover): фокус, ушедший из
+     * панели на страницу — Tab, программный `focus()`, — иначе оставлял бы её
+     * открытой над тем, с чем пользователь уже работает. Select не включает:
+     * фокус у него не покидает поле, а уход с поля он обрабатывает сам.
+     */
+    focusOutside?: boolean;
+}
+/**
+ * Нажатие мимо, которое ждёт решения. Касание решает `pointerup` того же
+ * `pointerId`, перо — он же или совместимый `mousedown`, смотря что придёт
+ * первым.
+ */
+export type TDismissPendingPress = {
+    pointerId: number;
+    pointerType: 'touch' | 'pen';
+};
+export type TDismissPluginEvents = TPluginEvents & {
+    /**
+     * Нажатие пришлось мимо владельца и его панелей. Приходит событие, которое
+     * это решило: у мыши — `pointerdown`; у касания — `pointerup`, прокрутка
+     * пальцем не закрывает; у пера — то, что пришло первым: `pointerup`
+     * (стилус на экране) или совместимый `mousedown` (перо графического
+     * планшета). Отсюда `MouseEvent`: `PointerEvent` — его подтип. С
+     * `focusOutside` — ещё и `focusin` фокуса, ушедшего мимо: `FocusEvent`.
+     *
+     * Приходит до закрытия владельца: подписчик застаёт его открытым и знает
+     * причину закрытия (плагин фокуса Popover по ней не возвращает фокус).
+     */
+    dismiss: (event: MouseEvent | FocusEvent) => void;
+    /** change:enabled */
+    'change:enabled': (payload: TValuePayload<boolean>) => void;
+};
+/**
+ * Пропсы плагина такими, какими их объявляет contribution — без неймспейса.
+ *
+ * Неймспейс (`dismiss_enabled`) навешивает `DescriptorAllProps` в `@soxa-ui/setup`
+ * по `namespace` из `definePlugin`; здесь только собственные имена пропсов.
+ * Защищённого `ownerAttribute` здесь нет: это выход, в разметку его не пишут.
+ */
+export interface IDismissPluginProps {
+    enabled?: boolean;
+}

package/dist/custom/drag-and-drop/drag.plugin.d.ts

@@ -0,0 +1,87 @@
+import type { IDragAndDrop, TCollectionEngine } from '@soxa-ui/core';
+import { TBasePlugin } from '../../base';
+import type { IPluginContext } from '../../base';
+import type { TDragPluginEvents } from './types';
+/**
+ * TDragPlugin — жест перестановки элементов коллекции: нативное
+ * перетаскивание DOM в команду обёртки `DragAndDrop`.
+ *
+ * Слушает `dragstart`, `dragover`, `drop` и `dragend` на корневом DOM-элементе
+ * компонента. Переставляет не плагин: на каждый `dragover` над другим
+ * элементом он зовёт команду обёртки (`IDragAndDrop.move`), а та шлёт свои
+ * события и переставляет элемент в движке. Место взятого плагин не помнит —
+ * оно в составе коллекции: отменённую перестановку и место, подменённое хуком
+ * движка, он не пересчитывает сам. Перестановка живая — элемент встаёт на
+ * место под указателем по ходу жеста.
+ *
+ * - **Взять** можно то, что разрешает обёртка (`IDragAndDrop.canMove`):
+ *   `dragstart` выключенного элемента отменён, и жеста нет вовсе.
+ * - **Место спрашивается, когда указатель пришёл на другой элемент**, а не на
+ *   каждый `dragover`: он идёт непрерывно, пока указатель стоит, и отменённое
+ *   место иначе переспрашивалось бы без конца.
+ * - **Принимает плагин только свой жест**: `dragover` и `drop` чужого
+ *   перетаскивания — файла, текста — идут как без него, и курсора
+ *   «переместить» над списком у них нет. Свой `drop` — без действия браузера
+ *   по умолчанию: перестановка уже сделана.
+ * - **Пальцем элемент берёт долгое нажатие** (`LONG_PRESS`), событиями
+ *   указателя: нативного перетаскивания у касания на телефонах нет или оно
+ *   спорит с прокруткой. Палец, ушедший за порог (`TOUCH_SLOP`) раньше, —
+ *   прокрутка. Взятый несут — `touchmove` отменён, и страница стоит; узел
+ *   под пальцем — точкой документа. Пока палец держит элемент, меню и
+ *   выделение долгого нажатия и нативный `dragstart` отменены. Шаги жеста —
+ *   взять, прийти на элемент, кончить — у мыши и пальца общие.
+ *
+ * Зависит от плагинов, которые должны присутствовать в том же бандле:
+ * - {@link TElementPlugin} — корневой DOM-элемент компонента;
+ * - {@link TCollectionElements} — доступ к DOM-элементам элементов коллекции;
+ * - {@link TCollectionBundlesPlugin} — реестр bundles (для отслеживания новых элементов).
+ *
+ * Коллекцию и обёртку передаёт {@link activate} (вызывает adapter-слой).
+ *
+ * @fires drag:start — свой жест начался, передаёт `{ index, uid }` взятого элемента.
+ * @fires drag:end   — свой жест кончился.
+ */
+export declare class TDragPlugin extends TBasePlugin<any, TDragPluginEvents> {
+    /** CSS-класс визуального состояния перетаскиваемого элемента. */
+    private static readonly DRAGGING_CLASS;
+    /**
+     * Долгое нажатие пальцем, после которого элемент взят, мс. Около таймаута
+     * долгого нажатия у Android: раньше палец, который начал прокрутку, не
+     * успевает уйти за порог, позже — нажатие кажется зависшим.
+     */
+    private static readonly LONG_PRESS;
+    /** Сдвиг пальца до долгого нажатия, за которым касание — прокрутка, px. */
+    private static readonly TOUCH_SLOP;
+    /** Коллекция, элементы которой переставляют; `null` — перетаскивание не включено. */
+    private _engine;
+    /** Обёртка, командой которой коллекция переставляется. */
+    private _dragAndDrop;
+    /** Корневой DOM-элемент, на котором висят обработчики drag-событий. */
+    private _element;
+    /** Ссылка на плагин, предоставляющий корневой DOM-элемент. */
+    private _elementPlugin;
+    /** Ссылка на плагин доступа к DOM-элементам элементов коллекции. */
+    private _collectionElements;
+    /** Ссылка на реестр bundles (для отслеживания новых элементов коллекции). */
+    private _bundles;
+    /** Функция очистки: снимает слушателей событий и атрибуты draggable. */
+    private _cleanup;
+    install(ctx: IPluginContext): void;
+    /**
+     * Включает перетаскивание элементов коллекции командой обёртки.
+     * Если DOM-элемент уже готов, немедленно навешивает обработчики; включённое
+     * раньше — с другой коллекцией или обёрткой — снимается.
+     */
+    activate(engine: TCollectionEngine<any, any>, dragAndDrop: IDragAndDrop): void;
+    /**
+     * Деактивирует перетаскивание: снимает обработчики и сбрасывает состояние.
+     */
+    deactivate(): void;
+    /**
+     * Навешивает нативные drag-обработчики на корневой DOM-элемент и помечает
+     * каждый DOM-узел элемента коллекции атрибутом `draggable="true"`.
+     */
+    private _setup;
+    private _teardown;
+    destroy(): void;
+}