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

package/dist/custom/toasts/removal/removal.plugin.js

@@ -0,0 +1,69 @@
+import { TBasePlugin } from "../../../base/base.class.js";
+import { TCollectionBundlesPlugin } from "../../collection/bundles.plugin.js";
+import { TCollectionElements } from "../../collection/collection-elements.plugin.js";
+import { afterTransitions } from "../../../utils/afterTransitions.js";
+//#region src/custom/toasts/removal/removal.plugin.ts
+/**
+* TToastsRemovalPlugin — закрытый тост уходит из коллекции, когда догас.
+*
+* Закрытый тост из разметки не прячется: тема ведёт его переходом по
+* `data-open="false"` — он гаснет, уезжает к стороне жеста, а место его
+* схлопывается, — и коллекция держит его, пока переходы его узла не
+* доиграли (`afterTransitions`), а потом удаляет (`plain.remove`). Сними его
+* сразу — узел ушёл бы из документа посреди исчезания. Чисел темы плагин не
+* знает: сколько ждать, решает переход; без движения и без переходов (jsdom)
+* — тем же кадром.
+*
+* Узла у тоста нет — он не нарисован (вытеснен за предел видимых, региона нет
+* или его ещё не отрисовали) — гаснуть нечему, и тост удаляется сразу.
+*
+* Закрытые до привязки движка — тосты, закрытые, пока компонента не было, —
+* удаляются при привязке: их узлов в этом монтировании нет. Набор уничтожают,
+* пока тост гаснет, — ожидание снимается, а тост удаляется сразу: он закрыт, а
+* движок снаружи переживает компонент.
+*/
+var TToastsRemovalPlugin = class extends TBasePlugin {
+	_engine = null;
+	_elements = null;
+	/** Тосты, которые гаснут: отмена ожидания — по тосту. */
+	_fading = /* @__PURE__ */ new Map();
+	install(ctx) {
+		super.install(ctx);
+		this._elements = ctx.get(TCollectionElements) ?? null;
+		ctx.get(TCollectionBundlesPlugin)?.events.on("engine:bound", (engine) => this._bindEngine(engine));
+	}
+	destroy() {
+		const fading = [...this._fading];
+		this._fading.clear();
+		for (const [toast, cancel] of fading) {
+			cancel();
+			this._remove(toast);
+		}
+		this._engine = null;
+		this._elements = null;
+		super.destroy();
+	}
+	_bindEngine(engine) {
+		this._engine = engine;
+		this._listenTo(engine.extensions.toasts.events, "item:close", (toast) => this._fade(toast));
+		for (const toast of engine.extensions.batch.items) if (!toast.open) this._remove(toast);
+	}
+	/** Закрытый тост: дождаться, пока его узел догаснет, и удалить. */
+	_fade(toast) {
+		const node = this._elements?.getElementByItem(toast);
+		if (!node) {
+			this._remove(toast);
+			return;
+		}
+		this._fading.get(toast)?.();
+		this._fading.set(toast, afterTransitions(node, () => {
+			this._fading.delete(toast);
+			this._remove(toast);
+		}));
+	}
+	_remove(toast) {
+		this._engine?.extensions.plain.remove(toast);
+	}
+};
+//#endregion
+export { TToastsRemovalPlugin };

package/dist/custom/toasts/removal/types.d.ts

@@ -0,0 +1,6 @@
+import type { TPluginEvents } from '../../../base';
+/**
+ * Своих событий у плагина нет: удаление видно через коллекцию —
+ * `item:removed`.
+ */
+export type TToastsRemovalPluginEvents = TPluginEvents;

package/dist/custom/toasts/timer/index.d.ts

@@ -0,0 +1,2 @@
+export { TToastsTimerPlugin } from './timer.plugin';
+export type { TToastCountdown, TToastsTimerPluginEvents } from './types';

package/dist/custom/toasts/timer/timer.plugin.d.ts

@@ -0,0 +1,71 @@
+import type { IToasts } from '@soxa-ui/core';
+import { TBasePlugin } from '../../../base';
+import type { IPluginContext } from '../../../base';
+import type { TToastsTimerPluginEvents } from './types';
+/**
+ * TToastsTimerPlugin — отсчёт тостов: время вышло — тост закрывается.
+ *
+ * **Кого считает** — показанные открытые тосты (`batch.shown`) с длительностью
+ * (`durationOf` расширения `toasts`): своя у тоста, иначе владельца. `0` —
+ * тост держится, пока его не закроют, и отсчёта у него нет; так и у тоста,
+ * который ждёт (`loading`), — это итог расширения, а не правило плагина.
+ * Вытесненный за предел видимых тост ждёт места с оставшимся временем: время
+ * идёт только у того, кого видно. Смена длительности (`item:duration`) — и
+ * снятое ожидание тоже — начинает отсчёт заново.
+ *
+ * **Пауза — для всех разом**, пока указатель или фокус в регионе и пока
+ * вкладка скрыта: читающий тост не должен исчезнуть у него из-под указателя, а
+ * уведомление, пришедшее в скрытую вкладку, — истечь, пока его никто не видел.
+ * Уход указателя снимает паузу с задержкой (`RESUME_DELAY`).
+ *
+ * Таймеры и слушатели — только пока есть узел региона: на сервере и до первой
+ * отрисовки считать некому и показывать нечего. Узел ушёл — отсчёт стоит,
+ * оставшееся время сохраняется.
+ *
+ * Время вышло — `close()` тоста: тот же путь, что крестик и Escape, а убирает
+ * закрытый тост из коллекции плагин удаления, когда тот догаснет.
+ */
+export declare class TToastsTimerPlugin extends TBasePlugin<IToasts, TToastsTimerPluginEvents> {
+    private _engine;
+    /** Узел региона; `null` — считать некому. */
+    private _region;
+    private _document;
+    private readonly _countdowns;
+    /** Указатель над тостами. */
+    private _hovered;
+    /** Фокус в регионе. */
+    private _focused;
+    /** Вкладка скрыта. */
+    private _hidden;
+    /** Отложенное снятие паузы после ухода указателя. */
+    private _resumeTimer;
+    private readonly _sync;
+    install(ctx: IPluginContext): void;
+    destroy(): void;
+    private _bindEngine;
+    private _attach;
+    private _detach;
+    /** Отсчёт стоит: указатель или фокус в регионе, вкладка скрыта. */
+    private get _paused();
+    /**
+     * Отсчёт идёт у показанных открытых тостов с длительностью, пока есть узел
+     * региона и нет паузы. Остальные стоят: тост ушёл из коллекции, закрыт или
+     * больше не закрывается сам — его отсчёт забыт; вытесненный за предел
+     * ждёт места с оставшимся временем.
+     */
+    private _resync;
+    /** Длительность тоста сменилась — отсчёт заново, с новой длительности. */
+    private _restart;
+    /** Отсчёт тоста больше не нужен: тост закрыт или его длительность сменилась. */
+    private _drop;
+    private _run;
+    /** Остановить отсчёт и запомнить, сколько осталось. */
+    private _stop;
+    private readonly _onPointerEnter;
+    private readonly _onPointerLeave;
+    private readonly _onFocusIn;
+    /** Фокус ушёл — пауза снимается, только если он ушёл из региона. */
+    private readonly _onFocusOut;
+    private readonly _onVisibilityChange;
+    private _cancelResume;
+}

package/dist/custom/toasts/timer/timer.plugin.js

@@ -0,0 +1,213 @@
+import { TBasePlugin } from "../../../base/base.class.js";
+import { TCollectionBundlesPlugin } from "../../collection/bundles.plugin.js";
+import { TElementPlugin } from "../../element/element.plugin.js";
+//#region src/custom/toasts/timer/timer.plugin.ts
+/**
+* Сколько ждать, прежде чем снять паузу, когда указатель ушёл из региона, мс.
+*
+* Указатель берут только тосты: регион нажатий мимо них не ловит. Закрытый
+* тост указатель отпускает сразу, и уход с него — не уход пользователя:
+* сосед за ним через миг встанет на его место под тот же указатель. Без
+* задержки отсчёт остальных тостов дёргался бы на каждое закрытие под
+* указателем. Время — с запасом на смыкание соседей в теме.
+*/
+var RESUME_DELAY = 400;
+/**
+* TToastsTimerPlugin — отсчёт тостов: время вышло — тост закрывается.
+*
+* **Кого считает** — показанные открытые тосты (`batch.shown`) с длительностью
+* (`durationOf` расширения `toasts`): своя у тоста, иначе владельца. `0` —
+* тост держится, пока его не закроют, и отсчёта у него нет; так и у тоста,
+* который ждёт (`loading`), — это итог расширения, а не правило плагина.
+* Вытесненный за предел видимых тост ждёт места с оставшимся временем: время
+* идёт только у того, кого видно. Смена длительности (`item:duration`) — и
+* снятое ожидание тоже — начинает отсчёт заново.
+*
+* **Пауза — для всех разом**, пока указатель или фокус в регионе и пока
+* вкладка скрыта: читающий тост не должен исчезнуть у него из-под указателя, а
+* уведомление, пришедшее в скрытую вкладку, — истечь, пока его никто не видел.
+* Уход указателя снимает паузу с задержкой (`RESUME_DELAY`).
+*
+* Таймеры и слушатели — только пока есть узел региона: на сервере и до первой
+* отрисовки считать некому и показывать нечего. Узел ушёл — отсчёт стоит,
+* оставшееся время сохраняется.
+*
+* Время вышло — `close()` тоста: тот же путь, что крестик и Escape, а убирает
+* закрытый тост из коллекции плагин удаления, когда тот догаснет.
+*/
+var TToastsTimerPlugin = class extends TBasePlugin {
+	_engine = null;
+	/** Узел региона; `null` — считать некому. */
+	_region = null;
+	_document = null;
+	_countdowns = /* @__PURE__ */ new Map();
+	/** Указатель над тостами. */
+	_hovered = false;
+	/** Фокус в регионе. */
+	_focused = false;
+	/** Вкладка скрыта. */
+	_hidden = false;
+	/** Отложенное снятие паузы после ухода указателя. */
+	_resumeTimer = null;
+	_sync = () => this._resync();
+	install(ctx) {
+		super.install(ctx);
+		const element = ctx.get(TElementPlugin);
+		element?.events.on("ready", (node) => this._attach(node));
+		element?.events.on("removed", () => this._detach());
+		ctx.get(TCollectionBundlesPlugin)?.events.on("engine:bound", (engine) => this._bindEngine(engine));
+	}
+	destroy() {
+		this._detach();
+		for (const countdown of this._countdowns.values()) this._stop(countdown);
+		this._countdowns.clear();
+		this._engine = null;
+		super.destroy();
+	}
+	_bindEngine(engine) {
+		this._engine = engine;
+		this._listenTo(engine.extensions.batch.events, "change:shown", this._sync);
+		this._listenTo(engine.extensions.toasts.events, "item:close", (toast) => this._drop(toast));
+		this._listenTo(engine.extensions.toasts.events, "item:duration", (toast) => this._restart(toast));
+		this._resync();
+	}
+	_attach(node) {
+		this._detach();
+		const region = node;
+		const document = node.ownerDocument;
+		region.addEventListener("pointerenter", this._onPointerEnter);
+		region.addEventListener("pointerleave", this._onPointerLeave);
+		region.addEventListener("focusin", this._onFocusIn);
+		region.addEventListener("focusout", this._onFocusOut);
+		document.addEventListener("visibilitychange", this._onVisibilityChange);
+		this._region = region;
+		this._document = document;
+		this._hidden = document.hidden;
+		this._focused = document.activeElement !== null && node.contains(document.activeElement);
+		this._resync();
+	}
+	_detach() {
+		const region = this._region;
+		this._cancelResume();
+		if (region) {
+			region.removeEventListener("pointerenter", this._onPointerEnter);
+			region.removeEventListener("pointerleave", this._onPointerLeave);
+			region.removeEventListener("focusin", this._onFocusIn);
+			region.removeEventListener("focusout", this._onFocusOut);
+		}
+		this._document?.removeEventListener("visibilitychange", this._onVisibilityChange);
+		this._region = null;
+		this._document = null;
+		this._hovered = false;
+		this._focused = false;
+		this._hidden = false;
+		this._resync();
+	}
+	/** Отсчёт стоит: указатель или фокус в регионе, вкладка скрыта. */
+	get _paused() {
+		return this._hovered || this._focused || this._hidden;
+	}
+	/**
+	* Отсчёт идёт у показанных открытых тостов с длительностью, пока есть узел
+	* региона и нет паузы. Остальные стоят: тост ушёл из коллекции, закрыт или
+	* больше не закрывается сам — его отсчёт забыт; вытесненный за предел
+	* ждёт места с оставшимся временем.
+	*/
+	_resync() {
+		const engine = this._engine;
+		const counting = /* @__PURE__ */ new Set();
+		if (engine && this._region) {
+			const running = !this._paused;
+			for (const toast of engine.extensions.batch.shown) {
+				if (!toast.open) continue;
+				const duration = engine.extensions.toasts.durationOf(toast);
+				if (duration <= 0) continue;
+				counting.add(toast);
+				let countdown = this._countdowns.get(toast);
+				if (!countdown) {
+					countdown = {
+						remaining: duration,
+						started: null,
+						timer: null
+					};
+					this._countdowns.set(toast, countdown);
+				}
+				if (running) this._run(toast, countdown);
+				else this._stop(countdown);
+			}
+		}
+		for (const [toast, countdown] of this._countdowns) {
+			if (counting.has(toast)) continue;
+			this._stop(countdown);
+			if (!(toast.open && engine !== null && engine.extensions.batch.items.includes(toast) && engine.extensions.toasts.durationOf(toast) > 0)) this._countdowns.delete(toast);
+		}
+	}
+	/** Длительность тоста сменилась — отсчёт заново, с новой длительности. */
+	_restart(toast) {
+		this._drop(toast);
+		this._resync();
+	}
+	/** Отсчёт тоста больше не нужен: тост закрыт или его длительность сменилась. */
+	_drop(toast) {
+		const countdown = this._countdowns.get(toast);
+		if (!countdown) return;
+		this._stop(countdown);
+		this._countdowns.delete(toast);
+	}
+	_run(toast, countdown) {
+		if (countdown.timer !== null) return;
+		countdown.started = Date.now();
+		countdown.timer = setTimeout(() => {
+			countdown.timer = null;
+			this._countdowns.delete(toast);
+			toast.close();
+		}, countdown.remaining);
+	}
+	/** Остановить отсчёт и запомнить, сколько осталось. */
+	_stop(countdown) {
+		if (countdown.timer === null) return;
+		clearTimeout(countdown.timer);
+		countdown.remaining = Math.max(0, countdown.remaining - (Date.now() - (countdown.started ?? 0)));
+		countdown.started = null;
+		countdown.timer = null;
+	}
+	_onPointerEnter = () => {
+		this._cancelResume();
+		if (this._hovered) return;
+		this._hovered = true;
+		this._resync();
+	};
+	_onPointerLeave = () => {
+		this._cancelResume();
+		this._resumeTimer = setTimeout(() => {
+			this._resumeTimer = null;
+			this._hovered = false;
+			this._resync();
+		}, RESUME_DELAY);
+	};
+	_onFocusIn = () => {
+		if (this._focused) return;
+		this._focused = true;
+		this._resync();
+	};
+	/** Фокус ушёл — пауза снимается, только если он ушёл из региона. */
+	_onFocusOut = (event) => {
+		const next = event.relatedTarget;
+		if (next instanceof Node && this._region !== null && this._region.contains(next) || !this._focused) return;
+		this._focused = false;
+		this._resync();
+	};
+	_onVisibilityChange = () => {
+		const hidden = this._document?.hidden ?? false;
+		if (hidden === this._hidden) return;
+		this._hidden = hidden;
+		this._resync();
+	};
+	_cancelResume() {
+		if (this._resumeTimer === null) return;
+		clearTimeout(this._resumeTimer);
+		this._resumeTimer = null;
+	}
+};
+//#endregion
+export { TToastsTimerPlugin };

package/dist/custom/toasts/timer/types.d.ts

@@ -0,0 +1,15 @@
+import type { TPluginEvents } from '../../../base';
+/**
+ * Своих событий у плагина нет: истёкшее время видно через тост — он
+ * закрывается (`change:open`), а коллекция сообщает об этом `item:close`.
+ */
+export type TToastsTimerPluginEvents = TPluginEvents;
+/** Отсчёт одного тоста. */
+export type TToastCountdown = {
+    /** Сколько тосту осталось, мс */
+    remaining: number;
+    /** Когда отсчёт пошёл (`Date.now()`); `null` — стоит */
+    started: number | null;
+    /** Таймер истечения; `null` — отсчёт стоит */
+    timer: ReturnType<typeof setTimeout> | null;
+};

package/dist/custom/tooltip/ids/ids.plugin.d.ts

@@ -0,0 +1,22 @@
+import { TBasePlugin } from '../../../base';
+import type { IPluginContext } from '../../../base';
+/**
+ * TTooltipIdsPlugin — связка «триггер ↔ панель» подсказки в документе.
+ *
+ * `id` панели — в `aria` подсказки, который разметка раскладывает на панель,
+ * а ссылка триггера на него — в `triggerAria`: `aria-describedby`, в режиме
+ * `label` — `aria-labelledby`. Ссылка одна, не обе: подсказка-имя,
+ * повторённая описанием, прозвучала бы дважды. Сменился режим (`change:type`)
+ * — прежняя ссылка снимается, новая ставится.
+ *
+ * `id` — от монтирования (`createId`), а не от экземпляра: он нужен только
+ * документу, и на сервере и в браузере обязан совпасть. Пишется при
+ * установке, синхронно: панель не размонтируется, и описание или имя есть уже
+ * в первой (и серверной) отрисовке.
+ */
+export declare class TTooltipIdsPlugin extends TBasePlugin {
+    private _panelId;
+    install(ctx: IPluginContext): void;
+    /** Ссылка триггера по режиму: ровно одна из двух. */
+    private _link;
+}

package/dist/custom/tooltip/ids/ids.plugin.js

@@ -0,0 +1,42 @@
+import { TBasePlugin } from "../../../base/base.class.js";
+//#region src/custom/tooltip/ids/ids.plugin.ts
+/**
+* Атрибут, которым триггер ссылается на панель, — по режиму. Словарь по
+* union, а не условие: режим без своей ссылки не скомпилируется.
+*/
+var TRIGGER_RELATION = {
+	description: "aria-describedby",
+	label: "aria-labelledby"
+};
+/**
+* TTooltipIdsPlugin — связка «триггер ↔ панель» подсказки в документе.
+*
+* `id` панели — в `aria` подсказки, который разметка раскладывает на панель,
+* а ссылка триггера на него — в `triggerAria`: `aria-describedby`, в режиме
+* `label` — `aria-labelledby`. Ссылка одна, не обе: подсказка-имя,
+* повторённая описанием, прозвучала бы дважды. Сменился режим (`change:type`)
+* — прежняя ссылка снимается, новая ставится.
+*
+* `id` — от монтирования (`createId`), а не от экземпляра: он нужен только
+* документу, и на сервере и в браузере обязан совпасть. Пишется при
+* установке, синхронно: панель не размонтируется, и описание или имя есть уже
+* в первой (и серверной) отрисовке.
+*/
+var TTooltipIdsPlugin = class extends TBasePlugin {
+	_panelId = "";
+	install(ctx) {
+		super.install(ctx);
+		const tooltip = ctx.getInstance();
+		if (!tooltip) return;
+		this._panelId = ctx.createId("panel");
+		tooltip.aria.add("id", this._panelId);
+		this._link(tooltip, tooltip.type);
+		this._listenTo(tooltip.events, "change:type", ({ newValue: type }) => this._link(tooltip, type));
+	}
+	/** Ссылка триггера по режиму: ровно одна из двух. */
+	_link(tooltip, type) {
+		for (const [mode, relation] of Object.entries(TRIGGER_RELATION)) tooltip.triggerAria.add(relation, mode === type ? this._panelId : null);
+	}
+};
+//#endregion
+export { TTooltipIdsPlugin };

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

@@ -0,0 +1 @@
+export * from './ids.plugin';

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

@@ -0,0 +1,2 @@
+export * from './trigger';
+export * from './ids';

package/dist/custom/tooltip/trigger/document-state.d.ts

@@ -0,0 +1,42 @@
+import type { ITooltipEntry } from './types';
+/**
+ * Подсказки документа: какая открыта и можно ли показать следующую без
+ * задержки.
+ *
+ * Подсказка на экране одна. Открывшаяся сразу закрывает прежнюю: у соседних
+ * кнопок две плашки встали бы рядом или друг на друга, и какая к чему
+ * относится, было бы не понять. Прежнюю при этом может ещё держать фокус с
+ * клавиатуры — показывает всё равно новая: её вызвал последний жест.
+ *
+ * Задержка показа нужна, чтобы подсказки не вспыхивали у всего, над чем
+ * курсор просто прошёл. Но пользователь, который уже читает подсказки —
+ * ведёт курсор вдоль ряда кнопок, — ждать её у каждой соседней не должен.
+ * Поэтому, пока другая подсказка открыта или закрылась меньше
+ * `TOOLTIP_SKIP_DELAY_MS` назад, следующая показывается сразу.
+ *
+ * Оба факта — о документе, а не о подсказке: флагом на плагине их не
+ * выразить, соседка о нём не знает. Поэтому состояние одно на документ, как
+ * замок прокрутки (`overlay/scroll-lock/lock.ts`), и документ берётся у
+ * корня, а не из `globalThis`: подсказка живёт и в `iframe`.
+ *
+ * Окно — константа, а не проп: оно про то, как человек ведёт курсор по
+ * странице, а не про одну подсказку, и у двух соседок с разными окнами
+ * правило стало бы несимметричным.
+ */
+/** Сколько после закрытия подсказки следующая показывается без задержки, мс. */
+export declare const TOOLTIP_SKIP_DELAY_MS = 300;
+/**
+ * Подсказка открылась: прежняя закрывается, окно без задержки больше не
+ * нужно — пока эта открыта, соседка и так покажется сразу.
+ *
+ * Прежняя закрывается после того, как открытой записана новая: закрываясь,
+ * она сообщит об этом (`tooltipClosed`), и запись новой не должна пропасть.
+ */
+export declare function tooltipOpened(doc: Document, entry: ITooltipEntry): void;
+/**
+ * Подсказка закрылась: окно без задержки открывается для следующей. Закрытие
+ * подсказки, которую уже сменила другая, ничего не меняет.
+ */
+export declare function tooltipClosed(doc: Document, entry: ITooltipEntry): void;
+/** Показывать ли без задержки: другая подсказка открыта или закрылась только что. */
+export declare function tooltipSkipsDelay(doc: Document): boolean;

package/dist/custom/tooltip/trigger/document-state.js

@@ -0,0 +1,50 @@
+var STATES = /* @__PURE__ */ new WeakMap();
+function stateOf(doc) {
+	const known = STATES.get(doc);
+	if (known) return known;
+	const state = {
+		open: null,
+		warm: null
+	};
+	STATES.set(doc, state);
+	return state;
+}
+/**
+* Подсказка открылась: прежняя закрывается, окно без задержки больше не
+* нужно — пока эта открыта, соседка и так покажется сразу.
+*
+* Прежняя закрывается после того, как открытой записана новая: закрываясь,
+* она сообщит об этом (`tooltipClosed`), и запись новой не должна пропасть.
+*/
+function tooltipOpened(doc, entry) {
+	const state = stateOf(doc);
+	const previous = state.open;
+	state.open = entry;
+	stopWarm(state);
+	if (previous && previous !== entry) previous.close();
+}
+/**
+* Подсказка закрылась: окно без задержки открывается для следующей. Закрытие
+* подсказки, которую уже сменила другая, ничего не меняет.
+*/
+function tooltipClosed(doc, entry) {
+	const state = STATES.get(doc);
+	if (!state || state.open !== entry) return;
+	state.open = null;
+	stopWarm(state);
+	state.warm = setTimeout(() => {
+		state.warm = null;
+	}, 300);
+}
+/** Показывать ли без задержки: другая подсказка открыта или закрылась только что. */
+function tooltipSkipsDelay(doc) {
+	const state = STATES.get(doc);
+	return !!state && (state.open !== null || state.warm !== null);
+}
+function stopWarm(state) {
+	if (state.warm === null) return;
+	clearTimeout(state.warm);
+	state.warm = null;
+}
+//#endregion
+export { tooltipClosed, tooltipOpened, tooltipSkipsDelay };

package/dist/custom/tooltip/trigger/index.d.ts

@@ -0,0 +1,2 @@
+export { TTooltipTriggerPlugin } from './trigger.plugin';
+export type { TTooltipTriggerPluginEvents } from './types';