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

package/dist/custom/scroller/viewport/viewport.plugin.js

@@ -0,0 +1,352 @@
+import { TBasePlugin } from "../../../base/base.class.js";
+import { TElementPlugin } from "../../element/element.plugin.js";
+import { isFocusableElement } from "../../../utils/isFocusableElement.js";
+import { tabStops } from "../../../utils/tabStops.js";
+import { itemOf, scrollWindowOf } from "../../../utils/scrollWindow.js";
+import { smoothScrollBehavior } from "../../../motion/motion.js";
+import { resolveEdges } from "./edges.js";
+import { resolveFocusShift } from "./focus.js";
+import { viewportOf } from "./stop.js";
+//#region src/custom/scroller/viewport/viewport.plugin.ts
+/** Часть разметки — кнопка, которая листает в эту сторону. */
+var BUTTON_PART = {
+	prev: "__prev",
+	next: "__next"
+};
+/** Сторона напротив. */
+var OPPOSITE = {
+	prev: "next",
+	next: "prev"
+};
+/**
+* TScrollerViewportPlugin — вьюпорт ленты: замер краёв, само листание,
+* доводка элемента под фокусом в окно снапа и фокус кнопки, выключенной у
+* края.
+*
+* Плагин, а не расширение или разметка: и то, и другое здесь — операции над
+* DOM. Где сейчас лента, сколько у неё содержимого и есть ли внутри свои
+* остановки Tab, знает только живой узел; результат уходит в ядро одним
+* вызовом (`IScroller.notifyViewport`) — тем же приёмом, каким клавиатура
+* тегов сообщает тег под фокусом (`notifyFocus`).
+*
+* Клики по кнопкам плагин ловит сам, слушателем на корне, и зовёт команды
+* ядра (приём `TSelectPointerPlugin` → `owner.toggleOpen()`). В разметке
+* обработчиков нет: связка «нажали ⇄ листаем» повторялась бы в каждом из
+* шести адаптеров.
+*
+* Поводов пересчитать четыре — размер вьюпорта, размер его детей, смена
+* состава и прокрутка, — и все они сводятся в **один проход раз в кадр**.
+* Писать в DOM прямо из колбэка наблюдателя нельзя: петля
+* `ResizeObserver loop completed with undelivered notifications` роняет
+* браузерный прогон (сторож `playground/vue/browser/setup.ts`).
+*
+* **Фокус.** Элемент под фокусом браузер докручивает, только если тот целиком
+* ушёл из окна снапа, а частично видимый оставляет на месте — у края, под
+* подсказкой темы. Поэтому по `focusin` плагин доводит элемент в окно сам
+* (счёт — `resolveFocusShift`). Окно — паддинг-бокс вьюпорта без
+* `scroll-padding`: ширину подсказки знает только тема, и она же делает окно
+* чистой частью ленты. Замер окна и доводка без снапа — общие с рядом тегов
+* `scroll` (`scrollWindowOf`, `nearestShift`). Три решения:
+* - только фокус с клавиатуры (`:focus-visible`). Фокус от нажатия мышью
+*   браузер сам не докручивает, и правильно: сдвинься лента между нажатием и
+*   отпусканием, под указателем оказался бы другой элемент, и `click` не
+*   дошёл бы;
+* - сдвиг синхронный, прямо в обработчике, и мгновенный (`instant`). Фокус
+*   браузер докручивает и сам, тоже мгновенно: после `focus()` — сразу за
+*   `focusin`, и плавную анимацию он бы перебил, а после нашего сдвига ему уже
+*   нечего делать. При переходе Tab он докручивает ещё до `focusin`, и
+*   элемент, целиком ушедший из окна, плагин застаёт уже в окне;
+* - в окно встаёт элемент ленты (прямой ребёнок вьюпорта), а не только
+*   элемент под фокусом: не шире окна — целиком, к своей точке снапа; шире —
+*   к ближайшей точке, где он накрывает окно, а элемент под фокусом в окне.
+*   Элемент — потому что снап выравнивает элементы, а не их части: докрутку
+*   до конца окна (фокусом браузера или чужим `scrollIntoView`) он вернул бы
+*   к соседней точке, и элемент остался бы у края, — а крестик тега без
+*   подписи не скажет, какой тег он закроет. Точка — потому что снап
+*   действует и на программную прокрутку; ближайшая — потому что с одним
+*   «начало к началу» крестик в конце длинного тега остался бы за краем.
+*
+* **Фокус у края.** Когда лента доезжает до края, кнопка этой стороны
+* выключается нативным `disabled`, и если фокус был на ней, браузер
+* сбрасывает его на страницу: пользователь клавиатуры и скринридера теряет
+* место и кольцо фокуса. Поэтому плагин отдаёт такой фокус кнопке напротив.
+* Край, от которого ушли, к этому моменту уже открыт: пользователь остаётся у
+* ленты, и прокрутка не меняется. Отдаёт кадром позже: в одном замере один
+* край закрывается, а другой открывается, и кнопку напротив включает только
+* перерисовка адаптера. Фокус, который за этот кадр увели на другой элемент,
+* плагин не трогает, а у выключенной ленты отдать его некому.
+*
+* Не режим `Button` «выключена, но фокусируема» (`aria-disabled` вместо
+* нативного `disabled`): это новая поверхность общего компонента ради правила
+* фокуса одной ленты. И не элемент ленты: остановка ряда тегов бывает за
+* краем, и фокус на ней прокрутил бы ленту обратно.
+*/
+var TScrollerViewportPlugin = class extends TBasePlugin {
+	_owner = null;
+	_root = null;
+	_viewport = null;
+	_resize = null;
+	_mutation = null;
+	_frame = null;
+	/** Кадр, в котором фокус уйдёт от выключенной кнопки к кнопке напротив. */
+	_handoverFrame = null;
+	/**
+	* Узлы под наблюдением размера — вьюпорт и его прямые дети.
+	*
+	* Список, а не «отключить и наблюдать заново каждый проход»: свежая
+	* подписка `ResizeObserver` сразу шлёт уведомление, и переподписка на
+	* каждом проходе гоняла бы проход по кругу кадр за кадром. Здесь новый
+	* узел даёт одно лишнее уведомление, а следующий проход состава уже не
+	* меняет.
+	*/
+	_observed = /* @__PURE__ */ new Set();
+	install(ctx) {
+		super.install(ctx);
+		this._owner = ctx.getInstance() ?? null;
+		const element = ctx.get(TElementPlugin);
+		element?.events.on("ready", (node) => this._bind(node));
+		element?.events.on("removed", () => this._bind(null));
+		this._listenTo(this._owner?.events, "scroll:request", (direction) => this._scroll(direction));
+		this._listenTo(this._owner?.events, "change:canPrev", ({ newValue: open }) => {
+			if (!open) this._onEdgeClosed("prev");
+		});
+		this._listenTo(this._owner?.events, "change:canNext", ({ newValue: open }) => {
+			if (!open) this._onEdgeClosed("next");
+		});
+	}
+	destroy() {
+		this._unlisten();
+		this._disconnect();
+		this._cancel();
+		this._cancelHandover();
+		this._resize?.disconnect();
+		this._resize = null;
+		this._mutation = null;
+		this._root = null;
+		this._viewport = null;
+		this._owner = null;
+		super.destroy();
+	}
+	/** Корень сменился — вместе с ним переезжают вьюпорт, слушатели и наблюдатели. */
+	_bind(root) {
+		this._unlisten();
+		this._disconnect();
+		this._cancel();
+		this._cancelHandover();
+		this._root = root;
+		this._viewport = root && this._owner ? viewportOf(this._owner, root) : null;
+		this._listen();
+		if (this._viewport) this._schedule();
+	}
+	_listen() {
+		const root = this._root;
+		const viewport = this._viewport;
+		root?.addEventListener("click", this._onClick);
+		viewport?.addEventListener("scroll", this._onSchedule);
+		viewport?.addEventListener("focusin", this._onFocusIn);
+		if (this._viewport) {
+			this._mutation ??= new MutationObserver(this._onSchedule);
+			this._mutation.observe(this._viewport, {
+				childList: true,
+				subtree: true
+			});
+		}
+	}
+	_unlisten() {
+		const root = this._root;
+		const viewport = this._viewport;
+		root?.removeEventListener("click", this._onClick);
+		viewport?.removeEventListener("scroll", this._onSchedule);
+		viewport?.removeEventListener("focusin", this._onFocusIn);
+		this._mutation?.disconnect();
+	}
+	/** Снимает наблюдение размеров: узлы старого корня нас больше не касаются. */
+	_disconnect() {
+		for (const node of this._observed) this._resize?.unobserve(node);
+		this._observed.clear();
+	}
+	/** Проход — раз в кадр: подряд идущие поводы схлопываются в один замер. */
+	_onSchedule = () => this._schedule();
+	_schedule() {
+		if (this._frame !== null) return;
+		this._frame = requestAnimationFrame(() => {
+			this._frame = null;
+			this._observe();
+			this._measure();
+		});
+	}
+	_cancel() {
+		if (this._frame === null) return;
+		cancelAnimationFrame(this._frame);
+		this._frame = null;
+	}
+	/**
+	* Под наблюдением вьюпорт и его прямые дети: лента меняет края и когда ей
+	* самой сменили ширину, и когда вырос любой элемент внутри.
+	*
+	* `border-box`: у вьюпорта есть паддинг (запас под кольцо фокуса
+	* содержимого), и `content-box` пропустил бы его смену вместе со сменой
+	* размера.
+	*/
+	_observe() {
+		const observer = this._resize ??= new ResizeObserver(this._onSchedule);
+		const current = /* @__PURE__ */ new Set();
+		if (this._viewport) {
+			current.add(this._viewport);
+			for (const child of this._viewport.children) current.add(child);
+		}
+		for (const node of this._observed) {
+			if (current.has(node)) continue;
+			observer.unobserve(node);
+			this._observed.delete(node);
+		}
+		for (const node of current) {
+			if (this._observed.has(node)) continue;
+			observer.observe(node, { box: "border-box" });
+			this._observed.add(node);
+		}
+	}
+	/** Три числа вьюпорта плюс остановки Tab внутри — весь замер ленты. */
+	_measure() {
+		const viewport = this._viewport;
+		if (!this._owner || !viewport) return;
+		this._owner.notifyViewport({
+			...resolveEdges({
+				scrollLeft: viewport.scrollLeft,
+				clientWidth: viewport.clientWidth,
+				scrollWidth: viewport.scrollWidth
+			}),
+			hasTabStops: tabStops(viewport).length > 0
+		});
+	}
+	/**
+	* Шаг — видимая ширина вьюпорта, то есть страница; до границы элемента
+	* страницу доводит снап темы, и границы элементов считать не нужно —
+	* в этом и была ставка на слот вместо коллекции.
+	*
+	* Знак — по вычисленному направлению письма: в RTL начало строки справа,
+	* и «вперёд» уводит ленту влево.
+	*
+	* Листает плавно, если движение не убрано (`smoothScrollBehavior`): по
+	* умолчанию — пока система о движении не просила, а режим движения
+	* библиотеки может задать приложение. Плавность — в вызове, а не проп
+	* ядра: из трёх значений `TScrollBehavior` у ленты осмысленны два, и
+	* третье было бы мёртвым значением в перечислении. Правило темы с этим не
+	* спорит — `scroll-behavior` она не объявляет.
+	*/
+	_scroll(direction) {
+		const viewport = this._viewport;
+		if (!viewport) return;
+		const rtl = getComputedStyle(viewport).direction === "rtl";
+		const forward = direction === "next" ? 1 : -1;
+		viewport.scrollBy({
+			left: (rtl ? -forward : forward) * viewport.clientWidth,
+			behavior: smoothScrollBehavior(viewport)
+		});
+	}
+	/**
+	* Нажатие по кнопке ленты. Кнопки стоят снаружи вьюпорта, поэтому чужая
+	* лента внутри содержимого своими кнопками нашу не двигает: её кнопки
+	* лежат в нашем вьюпорте.
+	*/
+	_onClick = (event) => {
+		const target = event.target;
+		if (!(target instanceof Element)) return;
+		if (this._owns(target.closest(this._selector("__prev")))) {
+			this._owner?.scrollPrev();
+			return;
+		}
+		if (this._owns(target.closest(this._selector("__next")))) this._owner?.scrollNext();
+	};
+	/**
+	* Фокус с клавиатуры пришёл в ленту — довести элемент под ним в окно
+	* снапа (почему так — в описании плагина).
+	*
+	* Сам вьюпорт — остановка Tab ленты без своих остановок: он и есть окно, и
+	* доводить его некуда.
+	*/
+	_onFocusIn = (event) => {
+		const viewport = this._viewport;
+		const target = event.target;
+		if (!viewport || !(target instanceof Element) || target === viewport) return;
+		if (!target.matches(":focus-visible")) return;
+		const style = getComputedStyle(viewport);
+		const shift = resolveFocusShift({
+			snapport: scrollWindowOf(viewport, style),
+			focused: target.getBoundingClientRect(),
+			item: itemOf(target, viewport).getBoundingClientRect(),
+			rtl: style.direction === "rtl"
+		});
+		if (shift !== null) viewport.scrollBy({
+			left: shift,
+			behavior: "instant"
+		});
+	};
+	/**
+	* Край закрылся. Если фокус на кнопке этого края, её выключит перерисовка,
+	* и браузер сбросит фокус на страницу, — кадром позже его заберёт кнопка
+	* напротив (почему так — в описании плагина).
+	*/
+	_onEdgeClosed(edge) {
+		const button = (this._root?.ownerDocument.activeElement ?? null)?.closest(this._selector(BUTTON_PART[edge])) ?? null;
+		if (button === null || !this._owns(button)) return;
+		this._cancelHandover();
+		this._handoverFrame = requestAnimationFrame(() => {
+			this._handoverFrame = null;
+			this._handOver(edge, button);
+		});
+	}
+	/**
+	* Отдать фокус кнопке напротив, если у него не осталось места.
+	*
+	* Без места он в двух случаях: браузер сбросил его на страницу или оставил
+	* на выключенной кнопке. Если же край за кадр открылся снова, кнопка жива,
+	* и фокус на ней остаётся.
+	*/
+	_handOver(edge, stranded) {
+		const owner = this._owner;
+		const root = this._root;
+		if (!owner || !root) return;
+		const doc = root.ownerDocument;
+		const active = doc.activeElement;
+		if (stranded.contains(active)) {
+			if (!isButtonDisabled(owner, edge)) return;
+		} else if (active !== null && active !== doc.body && active !== doc.documentElement) return;
+		const opposite = OPPOSITE[edge];
+		if (isButtonDisabled(owner, opposite)) return;
+		const button = this._button(opposite);
+		if (isFocusableElement(button)) button.focus();
+	}
+	_cancelHandover() {
+		if (this._handoverFrame === null) return;
+		cancelAnimationFrame(this._handoverFrame);
+		this._handoverFrame = null;
+	}
+	/**
+	* Кнопка этой ленты, а не первая по селектору: у вложенной ленты кнопки с
+	* тем же классом, и лежат они в нашем вьюпорте.
+	*/
+	_button(side) {
+		const selector = this._selector(BUTTON_PART[side]);
+		for (const node of this._root?.querySelectorAll(selector) ?? []) if (this._owns(node)) return node;
+		return null;
+	}
+	_owns(node) {
+		if (node === null) return false;
+		return this._root?.contains(node) === true && this._viewport?.contains(node) !== true;
+	}
+	/** Селектор части — из классов инстанса, а не строкой в плагине. */
+	_selector(part) {
+		return this._owner?.classes.resolve(part, { point: true }) ?? "";
+	}
+};
+/**
+* Выключена ли кнопка этой стороны — правилом ядра: выключена лента или
+* упёрлись в край. Своего правила у плагина нет: второй экземпляр однажды
+* разошёлся бы с тем, по которому кнопку выключает разметка.
+*/
+function isButtonDisabled(owner, side) {
+	return side === "prev" ? owner.prevDisabled : owner.nextDisabled;
+}
+//#endregion
+export { TScrollerViewportPlugin };

package/dist/custom/select/backspace/backspace.plugin.d.ts

@@ -0,0 +1,50 @@
+import { TBasePlugin } from '../../../base';
+import type { IPluginContext } from '../../../base';
+import type { TSelectBackspacePluginEvents } from './types';
+/**
+ * TSelectBackspacePlugin — удаление выбранных тегов по `Backspace` в пустом
+ * поле Select (`editable` + `multiple`).
+ *
+ * Отдельный плагин, не ветка в `TSelectKeyboardPlugin`: удаление тега не
+ * влияет ни на подсветку, ни на `aria-activedescendant`, которыми владеет
+ * клавиатурная стратегия, а смешивать их значило бы решать, чья стратегия
+ * первой увидит `Backspace`.
+ *
+ * Слушатель, как и у `TEditablePlugin`, вешается подпиской на условия, а не
+ * проверкой внутри обработчика: нужны сразу три — включённое свойство
+ * `owner.removeOnBackspace`, `editable: true` и `selection.mode === 'multiple'`.
+ * Ни одно из них само по себе не значит, что клавиатуре есть что удалять.
+ *
+ * Правило взвода: первое нажатие `Backspace` в пустом поле только взводит
+ * счётчик, второе и каждое следующее подряд удаляет по одному тегу. Любая
+ * другая клавиша, `Backspace` при непустом поле и снятие слушателя сбрасывают
+ * счётчик. Автоповтор (`KeyboardEvent.repeat`) не учитывается вовсе — ни
+ * взводит, ни сбрасывает.
+ *
+ * Что считается «последним» — последний тег, а не последний элемент
+ * `selection.selected`: пользователь видит теги, не порядок выбора в
+ * коллекции (на практике они совпадают, но знание об этом не должно жить в
+ * плагине). Тег ищется через расширение тегов (`tags`), снимается выбор — через
+ * `selection.deselect`, а не через driver: плагину сама коллекция опций
+ * недоступна на уровне хранилища, только через расширения.
+ */
+export declare class TSelectBackspacePlugin extends TBasePlugin<any, TSelectBackspacePluginEvents> {
+    private _owner;
+    private _input;
+    private _engine;
+    private _listening;
+    private _armed;
+    private readonly _onKeyDown;
+    install(ctx: IPluginContext): void;
+    destroy(): void;
+    private get _selectionExtension();
+    private get _tagsExtension();
+    /** Слушаем `keydown`, только пока все три условия выполнены разом. */
+    private _needed;
+    private _syncListener;
+    private _listen;
+    private _unlisten;
+    private _handleKeyDown;
+    /** Снимает выбор с опции, чей тег стоит последним в поле. */
+    private _removeLastTag;
+}

package/dist/custom/select/backspace/backspace.plugin.js

@@ -0,0 +1,125 @@
+import { TBasePlugin } from "../../../base/base.class.js";
+import { TCollectionBundlesPlugin } from "../../collection/bundles.plugin.js";
+import { TElementPlugin } from "../../element/element.plugin.js";
+import { fieldOf } from "../../input/field.js";
+import { batchOf, selectionOf, tagsOf } from "@soxa-ui/core";
+//#region src/custom/select/backspace/backspace.plugin.ts
+/**
+* TSelectBackspacePlugin — удаление выбранных тегов по `Backspace` в пустом
+* поле Select (`editable` + `multiple`).
+*
+* Отдельный плагин, не ветка в `TSelectKeyboardPlugin`: удаление тега не
+* влияет ни на подсветку, ни на `aria-activedescendant`, которыми владеет
+* клавиатурная стратегия, а смешивать их значило бы решать, чья стратегия
+* первой увидит `Backspace`.
+*
+* Слушатель, как и у `TEditablePlugin`, вешается подпиской на условия, а не
+* проверкой внутри обработчика: нужны сразу три — включённое свойство
+* `owner.removeOnBackspace`, `editable: true` и `selection.mode === 'multiple'`.
+* Ни одно из них само по себе не значит, что клавиатуре есть что удалять.
+*
+* Правило взвода: первое нажатие `Backspace` в пустом поле только взводит
+* счётчик, второе и каждое следующее подряд удаляет по одному тегу. Любая
+* другая клавиша, `Backspace` при непустом поле и снятие слушателя сбрасывают
+* счётчик. Автоповтор (`KeyboardEvent.repeat`) не учитывается вовсе — ни
+* взводит, ни сбрасывает.
+*
+* Что считается «последним» — последний тег, а не последний элемент
+* `selection.selected`: пользователь видит теги, не порядок выбора в
+* коллекции (на практике они совпадают, но знание об этом не должно жить в
+* плагине). Тег ищется через расширение тегов (`tags`), снимается выбор — через
+* `selection.deselect`, а не через driver: плагину сама коллекция опций
+* недоступна на уровне хранилища, только через расширения.
+*/
+var TSelectBackspacePlugin = class extends TBasePlugin {
+	_owner = null;
+	_input = null;
+	_engine = null;
+	_listening = false;
+	_armed = false;
+	_onKeyDown = this._handleKeyDown.bind(this);
+	install(ctx) {
+		super.install(ctx);
+		this._owner = ctx.getInstance() ?? null;
+		const elementPlugin = ctx.get(TElementPlugin);
+		elementPlugin?.events.on("ready", (element) => {
+			const field = fieldOf(element);
+			this._input = field instanceof HTMLInputElement ? field : null;
+			this._syncListener();
+		});
+		elementPlugin?.events.on("removed", () => {
+			this._unlisten();
+			this._input = null;
+		});
+		const sync = () => this._syncListener();
+		ctx.get(TCollectionBundlesPlugin)?.events.on("engine:bound", (engine) => {
+			this._engine = engine;
+			this._listenTo(this._selectionExtension?.events, "change:mode", sync);
+			this._syncListener();
+		});
+		this._listenTo(this._owner?.events, "change:removeOnBackspace", sync);
+		this._listenTo(this._owner?.events, "change:editable", sync);
+	}
+	destroy() {
+		this._unlisten();
+		this._input = null;
+		this._owner = null;
+		this._engine = null;
+		super.destroy();
+	}
+	get _selectionExtension() {
+		return selectionOf(this._engine);
+	}
+	get _tagsExtension() {
+		return tagsOf(this._engine);
+	}
+	/** Слушаем `keydown`, только пока все три условия выполнены разом. */
+	_needed() {
+		const owner = this._owner;
+		return Boolean(owner?.removeOnBackspace) && Boolean(owner?.editable) && Boolean(this._selectionExtension?.multiple);
+	}
+	_syncListener() {
+		if (this._needed()) this._listen();
+		else this._unlisten();
+	}
+	_listen() {
+		if (this._listening || !this._input) return;
+		this._input.addEventListener("keydown", this._onKeyDown);
+		this._listening = true;
+	}
+	_unlisten() {
+		this._armed = false;
+		if (!this._listening) return;
+		this._input?.removeEventListener("keydown", this._onKeyDown);
+		this._listening = false;
+	}
+	_handleKeyDown(event) {
+		if (event.repeat) return;
+		if (event.key !== "Backspace") {
+			this._armed = false;
+			return;
+		}
+		if (this._input?.value ?? "") {
+			this._armed = false;
+			return;
+		}
+		if (!this._armed) {
+			this._armed = true;
+			return;
+		}
+		this._removeLastTag();
+	}
+	/** Снимает выбор с опции, чей тег стоит последним в поле. */
+	_removeLastTag() {
+		const selection = this._selectionExtension;
+		const tags = this._tagsExtension;
+		if (!selection || !tags) return;
+		const tagItems = tags.engine?.extensions.batch.items;
+		const lastTag = tagItems?.[tagItems.length - 1];
+		if (!lastTag) return;
+		const item = batchOf(this._engine)?.items.find((candidate) => candidate.value === lastTag.value);
+		if (item) selection.deselect(item);
+	}
+};
+//#endregion
+export { TSelectBackspacePlugin };

package/dist/custom/select/backspace/index.d.ts

@@ -0,0 +1,2 @@
+export { TSelectBackspacePlugin } from './backspace.plugin';
+export type { TSelectBackspacePluginEvents } from './types';

package/dist/custom/select/backspace/types.d.ts

@@ -0,0 +1,2 @@
+import type { TPluginEvents } from '../../../base';
+export type TSelectBackspacePluginEvents = TPluginEvents;