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

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

@@ -0,0 +1,206 @@
+import { TBasePlugin } from "../../../base/base.class.js";
+import { TCollectionBundlesPlugin } from "../../collection/bundles.plugin.js";
+import { TElementPlugin } from "../../element/element.plugin.js";
+import { TCollectionElements } from "../../collection/collection-elements.plugin.js";
+import { isFocusableElement } from "../../../utils/isFocusableElement.js";
+import { tabStopsAfter } from "../../../utils/tabStopsAfter.js";
+import { focusFirst } from "../../../utils/focusFirst.js";
+import { listOf } from "../parts.js";
+import { TLeavingFocus } from "../../collection/leaving-focus.js";
+import { tabOf } from "../tab.js";
+//#region src/custom/tabs/keyboard/keyboard.plugin.ts
+/** Стрелки «к предыдущему» и «к следующему» — на оси ориентации списка. */
+var AXIS_KEYS = {
+	horizontal: ["ArrowLeft", "ArrowRight"],
+	vertical: ["ArrowUp", "ArrowDown"]
+};
+/**
+* TTabsKeyboardPlugin — клавиатура Tabs по паттерну APG Tabs и фокус после
+* закрытия таба.
+*
+* Стрелки по оси списка (у горизонтального ←/→, у вертикального ↑/↓) ведут к
+* соседнему табу по кругу, `Home`/`End` — к первому и последнему. Табы, на
+* которые нельзя перейти (`TTabsExtension.isEnabledTab`), пропускаются.
+* `Delete` закрывает таб, если его можно закрыть.
+*
+* **Активация автоматическая**: переход сразу активирует таб. APG советует
+* так, когда панель показывается без задержки, а `Tabs.Content` рисуется
+* локально. Поэтому фокус и активный таб не расходятся, и остановка Tab —
+* активный таб — считается в коллекции без знания о фокусе. `Enter` и пробел
+* здесь не обрабатываются: таб — нативная `<button>`, и активирует её клик.
+*
+* **Закрытый таб отдаёт фокус остановке Tab** — любым закрытием: клавишей,
+* крестиком, из кода. Крестик фокус от клика принимает, и узел таба уходит из
+* документа вместе с ним: фокус ушёл бы на страницу, и следующий Tab начинал
+* бы обход заново. Переносится только фокус из узла закрываемого таба — на
+* таб-остановку после удаления (`tabStop`): закрыли активный — это сосед,
+* которого уже активировал `TTabsExtension`; закрыли неактивный — прежний
+* активный, соседа такое закрытие не активирует. Остановки нет — к первой
+* остановке Tab после списка; нет и её — фокус не трогается.
+*
+* Когда переносить фокус, решает помощник коллекции (`TLeavingFocus`), общий с
+* Tags: таб бывает снят ещё до того, как закрытие дойдёт до плагина, —
+* подписчиком `item:close`, который стоит раньше, например приложением в
+* обработчике события фасада. Удаление, отменённое в `item:remove:before`, и
+* уход таба без закрытия фокус не трогают. Закрыть таб из кода можно и на
+* сервере, поэтому фокус читается только при узле корня.
+*
+* Сами `tabindex` плагин не пишет: roving tabindex ставит `TTabsExtension`,
+* потому что атрибут обязан стоять с первой отрисовки, включая серверную.
+* Здесь только то, что требует DOM: слушатель клавиш и перенос фокуса.
+*
+* От `TListNavigationPlugin` не наследуется: там модель подсветки при фокусе
+* на контейнере, а у табов по APG фокус ходит по самим табам (см. AGENTS.md,
+* «Граница переиспользования между похожими компонентами»).
+*/
+var TTabsKeyboardPlugin = class extends TBasePlugin {
+	_owner = null;
+	/** Корень: на нём слушатель, по нему же направление письма. */
+	_element = null;
+	_elements = null;
+	_engine = null;
+	/** Фокус закрываемого таба — ждёт, пока таб закроют и он уйдёт из списка. */
+	_leaving = null;
+	install(ctx) {
+		super.install(ctx);
+		this._owner = ctx.getInstance();
+		this._elements = ctx.get(TCollectionElements) ?? null;
+		this._leaving = new TLeavingFocus(this._elements, {
+			root: () => this._element,
+			place: () => void 0,
+			pass: (root) => this._pass(root)
+		});
+		const elementPlugin = ctx.get(TElementPlugin);
+		elementPlugin?.events.on("ready", (element) => this._attach(element));
+		elementPlugin?.events.on("removed", () => {
+			this._detach();
+			this._leaving?.reset();
+		});
+		ctx.get(TCollectionBundlesPlugin)?.events.on("engine:bound", (engine) => this._bindEngine(engine));
+	}
+	destroy() {
+		this._detach();
+		this._bindEngine(null);
+		this._owner = null;
+		this._elements = null;
+		this._leaving = null;
+		super.destroy();
+	}
+	_attach(element) {
+		this._detach();
+		this._element = element;
+		element.addEventListener("keydown", this._onKeyDown);
+	}
+	_detach() {
+		this._element?.removeEventListener("keydown", this._onKeyDown);
+		this._element = null;
+	}
+	/** Движок сменился — закрытие табов и их уход слушаются у нового. */
+	_bindEngine(engine) {
+		this._engine?.extensions.tabs.events.off("item:close", this._onClose);
+		this._engine = engine;
+		engine?.extensions.tabs.events.on("item:close", this._onClose);
+		this._leaving?.bind(engine?.extensions.plain ?? null);
+	}
+	_onKeyDown = (event) => {
+		if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return;
+		const engine = this._engine;
+		if (!engine) return;
+		const tab = this._tabOf(engine, event.target);
+		if (!tab) return;
+		if (event.key === "Delete") {
+			if (engine.extensions.tabs.closeTab(tab)) event.preventDefault();
+			return;
+		}
+		const candidates = this._candidates(engine, event.key, tab);
+		if (candidates.length === 0) return;
+		event.preventDefault();
+		const next = candidates.find((item) => engine.extensions.activation.activate(item));
+		if (next) this._focus(next);
+	};
+	/**
+	* Таб, с которого пришла клавиша, — тот, чей узел содержит цель события.
+	*
+	* Слушатель висит на корне, и до него всплывают клавиши панелей, слотов
+	* списка и вложенных Tabs: их перехватывать нельзя. Кнопка закрытия лежит
+	* внутри узла таба и считается его частью.
+	*/
+	_tabOf(engine, target) {
+		if (!(target instanceof Node)) return void 0;
+		return engine.extensions.batch.shown.find((item) => this._elements?.getElementByUid(item.uid)?.contains(target));
+	}
+	/**
+	* Куда ведёт клавиша — табы по порядку, от первого кандидата; пусто —
+	* клавиша не наша или перейти некуда. `Home` идёт от первого вперёд,
+	* `End` — от последнего назад, стрелка — от соседа в своём направлении.
+	*/
+	_candidates(engine, key, tab) {
+		if (key === "Home") return this._available(engine);
+		if (key === "End") return this._available(engine).reverse();
+		const step = this._step(key);
+		return step === null ? [] : this._neighbours(engine, tab, step);
+	}
+	/**
+	* Шаг по списку от стрелки; клавиши чужой оси не перехватываются. В RTL
+	* горизонтальный список идёт справа налево, и ←/→ меняются местами.
+	*/
+	_step(key) {
+		const orientation = this._owner?.orientation ?? "horizontal";
+		const [back, forward] = AXIS_KEYS[orientation];
+		const step = key === forward ? 1 : key === back ? -1 : null;
+		if (step === null || orientation === "vertical") return step;
+		return this._rtl ? -step : step;
+	}
+	/**
+	* Направление письма берётся вычисленным: `direction` компонента бывает
+	* `inherit`, и тогда его задаёт предок.
+	*/
+	get _rtl() {
+		return this._element !== null && getComputedStyle(this._element).direction === "rtl";
+	}
+	/** Табы в порядке списка, на которые можно перейти. */
+	_available(engine) {
+		return engine.extensions.batch.shown.filter((item) => engine.extensions.tabs.isEnabledTab(item));
+	}
+	/**
+	* Табы в направлении шага, по кругу, от ближайшего: с последнего вперёд —
+	* на первый. Отсчёт от позиции таба в списке, а не среди доступных: таб
+	* могли выключить, пока на нём фокус.
+	*/
+	_neighbours(engine, tab, step) {
+		const shown = engine.extensions.batch.shown;
+		const count = shown.length;
+		const from = shown.indexOf(tab);
+		const neighbours = [];
+		for (let offset = 1; offset <= count; offset++) {
+			const candidate = shown[((from + step * offset) % count + count) % count];
+			if (engine.extensions.tabs.isEnabledTab(candidate)) neighbours.push(candidate);
+		}
+		return neighbours;
+	}
+	/** Фокус на узел таба с ролью. Гард нужен: узел плагину приходит `Element`. */
+	_focus(item) {
+		const tab = tabOf(this._elements, item.uid);
+		if (isFocusableElement(tab)) tab.focus();
+	}
+	/**
+	* Таб закрывают — любым путём: клавишей, крестиком, из кода. Переносить
+	* ли фокус, решает помощник: фокус мог стоять и не в этом табе.
+	*/
+	_onClose = (tab) => this._leaving?.close(tab);
+	/**
+	* Фокус закрытого таба — на таб-остановку. Остановка берётся по модели
+	* (`tabStop`), а не по `[tabindex="0"]`: в такте закрытия разметка ещё
+	* старая. Остановки нет — на первую остановку Tab после списка: за ним
+	* слот `trailing` и панели; нет и её — фокус остаётся, где был.
+	*/
+	_pass(root) {
+		const stop = this._engine?.extensions.tabs.tabStop;
+		const tab = stop ? tabOf(this._elements, stop.uid) : null;
+		if (tab && focusFirst([tab])) return;
+		const list = this._owner ? listOf(this._owner, root) : null;
+		if (list) focusFirst(tabStopsAfter(list, null));
+	}
+};
+//#endregion
+export { TTabsKeyboardPlugin };

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

@@ -0,0 +1,6 @@
+import type { TPluginEvents } from '../../../base';
+/**
+ * Своих событий у плагина нет: результат нажатия виден и так — активацию
+ * сообщает коллекция (`change:activation`), фокус — DOM.
+ */
+export type TTabsKeyboardPluginEvents = TPluginEvents;

package/dist/custom/tabs/layout/index.d.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './layout.plugin';

package/dist/custom/tabs/layout/layout.plugin.d.ts

@@ -0,0 +1,37 @@
+import type { ITabs } from '@soxa-ui/core';
+import { TBasePlugin } from '../../../base';
+import type { IPluginContext } from '../../../base';
+import type { TTabsLayoutPluginEvents } from './types';
+/**
+ * TTabsLayoutPlugin — отслеживает изменения размеров табов через ResizeObserver.
+ *
+ * Наблюдает:
+ * - корень набора;
+ * - свой список табов — ребёнка своего ряда. При выравнивании `center` и `end`
+ *   слот ряда меняет ширину, и табы сдвигаются, а размеры табов и корня — нет:
+ *   меняется только место, которое список забирает между слотами;
+ * - DOM-элементы каждого таба (через реестр bundles + TElementPlugin).
+ *
+ * Эмитит change:layout при изменении размеров — нужно для обновления позиции/размера
+ * активного таба, по которым тема рисует его отметку, и при переносе табов на
+ * другую строку.
+ *
+ * Все наблюдатели смотрят border-box: наблюдать надо ровно то, что меряется
+ * по `change:layout`, — `TTabsActiveTabPlugin` берёт позицию и размер таба из
+ * `offsetLeft`/`offsetTop` и `offsetWidth`/`offsetHeight`. Умолчание
+ * `content-box` пропустило бы смену одного паддинга или рамки таба (паддинг
+ * по размеру, толщина рамки по состоянию), и геометрия активного таба
+ * держалась бы по старому размеру до ближайшего пересчёта по другой причине.
+ */
+export declare class TTabsLayoutPlugin extends TBasePlugin<ITabs, TTabsLayoutPluginEvents> {
+    private _tabs;
+    private _rootObserver;
+    private _listObserver;
+    private readonly _itemObservers;
+    install(ctx: IPluginContext): void;
+    destroy(): void;
+    /** Наблюдатель размеров узла по border-box (см. шапку). */
+    private _observe;
+    /** Снять наблюдение за корнем и списком: узел снят, заменён или плагин уничтожен. */
+    private _disconnect;
+}

package/dist/custom/tabs/layout/layout.plugin.js

@@ -0,0 +1,81 @@
+import { TBasePlugin } from "../../../base/base.class.js";
+import { TCollectionBundlesPlugin } from "../../collection/bundles.plugin.js";
+import { TElementPlugin } from "../../element/element.plugin.js";
+import { listOf } from "../parts.js";
+//#region src/custom/tabs/layout/layout.plugin.ts
+/**
+* TTabsLayoutPlugin — отслеживает изменения размеров табов через ResizeObserver.
+*
+* Наблюдает:
+* - корень набора;
+* - свой список табов — ребёнка своего ряда. При выравнивании `center` и `end`
+*   слот ряда меняет ширину, и табы сдвигаются, а размеры табов и корня — нет:
+*   меняется только место, которое список забирает между слотами;
+* - DOM-элементы каждого таба (через реестр bundles + TElementPlugin).
+*
+* Эмитит change:layout при изменении размеров — нужно для обновления позиции/размера
+* активного таба, по которым тема рисует его отметку, и при переносе табов на
+* другую строку.
+*
+* Все наблюдатели смотрят border-box: наблюдать надо ровно то, что меряется
+* по `change:layout`, — `TTabsActiveTabPlugin` берёт позицию и размер таба из
+* `offsetLeft`/`offsetTop` и `offsetWidth`/`offsetHeight`. Умолчание
+* `content-box` пропустило бы смену одного паддинга или рамки таба (паддинг
+* по размеру, толщина рамки по состоянию), и геометрия активного таба
+* держалась бы по старому размеру до ближайшего пересчёта по другой причине.
+*/
+var TTabsLayoutPlugin = class extends TBasePlugin {
+	_tabs = null;
+	_rootObserver = null;
+	_listObserver = null;
+	_itemObservers = /* @__PURE__ */ new Map();
+	install(ctx) {
+		super.install(ctx);
+		this._tabs = ctx.getInstance();
+		ctx.get(TElementPlugin)?.events.on("ready", (element) => {
+			this._disconnect();
+			this._rootObserver = this._observe(element);
+			const list = this._tabs ? listOf(this._tabs, element) : null;
+			this._listObserver = list ? this._observe(list) : null;
+		});
+		ctx.get(TElementPlugin)?.events.on("removed", () => this._disconnect());
+		const bundles = ctx.get(TCollectionBundlesPlugin);
+		bundles?.events.on("bundle:registered", ({ uid, bundle }) => {
+			const elementPlugin = bundle.get(TElementPlugin);
+			elementPlugin?.events.on("ready", (element) => {
+				this._itemObservers.get(uid)?.disconnect();
+				this._itemObservers.set(uid, this._observe(element));
+			});
+			elementPlugin?.events.on("removed", () => {
+				this._itemObservers.get(uid)?.disconnect();
+				this._itemObservers.delete(uid);
+			});
+		});
+		bundles?.events.on("bundle:unregistered", ({ uid }) => {
+			this._itemObservers.get(uid)?.disconnect();
+			this._itemObservers.delete(uid);
+		});
+	}
+	destroy() {
+		this._disconnect();
+		this._tabs = null;
+		for (const observer of this._itemObservers.values()) observer.disconnect();
+		this._itemObservers.clear();
+		super.destroy();
+	}
+	/** Наблюдатель размеров узла по border-box (см. шапку). */
+	_observe(element) {
+		const observer = new ResizeObserver(() => this.events.emit("change:layout"));
+		observer.observe(element, { box: "border-box" });
+		return observer;
+	}
+	/** Снять наблюдение за корнем и списком: узел снят, заменён или плагин уничтожен. */
+	_disconnect() {
+		this._rootObserver?.disconnect();
+		this._rootObserver = null;
+		this._listObserver?.disconnect();
+		this._listObserver = null;
+	}
+};
+//#endregion
+export { TTabsLayoutPlugin };

package/dist/custom/tabs/layout/types.d.ts

@@ -0,0 +1,4 @@
+import type { TPluginEvents } from '../../../base';
+export type TTabsLayoutPluginEvents = TPluginEvents & {
+    'change:layout': () => void;
+};

package/dist/custom/tabs/parts.d.ts

@@ -0,0 +1,15 @@
+import type { ITabs } from '@soxa-ui/core';
+/**
+ * Узлы набора — один поиск на плагины раскладки Tabs: место активного таба
+ * меряется от ряда (`TTabsActiveTabPlugin`), а сдвиг табов без смены их
+ * размеров ловит наблюдатель списка (`TTabsLayoutPlugin`).
+ *
+ * Узлы находят по классам владельца (`classes.resolve`), а не строкой в
+ * плагине, и прямым путём от корня: Tabs бывают вложены — в слот ряда или в
+ * панель других, — и поиск по потомкам нашёл бы чужой узел первым: слот
+ * `leading` стоит в ряду раньше списка.
+ */
+/** Ряд набора — ребёнок корня: список табов и слоты по его краям. */
+export declare function barOf(owner: ITabs, root: Element): Element | null;
+/** Список табов набора — ребёнок его ряда, `[role=tablist]`. */
+export declare function listOf(owner: ITabs, root: Element): Element | null;

package/dist/custom/tabs/parts.js

@@ -0,0 +1,21 @@
+//#region src/custom/tabs/parts.ts
+/**
+* Узлы набора — один поиск на плагины раскладки Tabs: место активного таба
+* меряется от ряда (`TTabsActiveTabPlugin`), а сдвиг табов без смены их
+* размеров ловит наблюдатель списка (`TTabsLayoutPlugin`).
+*
+* Узлы находят по классам владельца (`classes.resolve`), а не строкой в
+* плагине, и прямым путём от корня: Tabs бывают вложены — в слот ряда или в
+* панель других, — и поиск по потомкам нашёл бы чужой узел первым: слот
+* `leading` стоит в ряду раньше списка.
+*/
+/** Ряд набора — ребёнок корня: список табов и слоты по его краям. */
+function barOf(owner, root) {
+	return root.querySelector(`:scope > ${owner.classes.resolve("__bar", { point: true })}`);
+}
+/** Список табов набора — ребёнок его ряда, `[role=tablist]`. */
+function listOf(owner, root) {
+	return barOf(owner, root)?.querySelector(`:scope > ${owner.classes.resolve("__list", { point: true })}`) ?? null;
+}
+//#endregion
+export { barOf, listOf };

package/dist/custom/tabs/tab.d.ts

@@ -0,0 +1,29 @@
+import type { IPluginContext } from '../../base';
+import { TCollectionElements } from '../collection';
+/**
+ * Узел таба — строка с ролью `tab` внутри узла элемента. `null` — элемента нет
+ * в документе.
+ *
+ * Одна на клавиатуру Tabs (куда перевести фокус стрелкой) и фокус набора
+ * (`tabStopOf`): узел таба оба ищут одним правилом.
+ */
+export declare function tabOf(elements: TCollectionElements | null, uid: string | number): Element | null;
+/**
+ * Узел таба внутри узла элемента — тем же правилом, что `tabOf`, когда узел
+ * уже на руках. `null` — узла нет или таба в нём нет.
+ *
+ * Он же узел фокуса `Tabs.Item` (`focusTarget` плагина действия): запись
+ * `focused = true` ставит фокус на строку таба, а не на обёртку элемента.
+ */
+export declare function tabIn(node: Element | null): Element | null;
+/**
+ * Таб-остановка — узел таба, который держит остановку Tab. `null` — табов, на
+ * которые можно перейти, нет, или узла таба нет в документе.
+ *
+ * Узел фокуса Tabs (`focusTarget` плагина действия): запись `focused = true`
+ * ставит фокус туда же, куда ведёт Tab, а не на кнопку в слоте `leading`.
+ * Таб берётся по модели — `tabStop` расширения табов, — а не по
+ * `[tabindex="0"]` в разметке: в такте смены активного таба разметка ещё
+ * старая, и фокус ушёл бы на прежний таб.
+ */
+export declare function tabStopOf(_root: Element, ctx: IPluginContext): Element | null;

package/dist/custom/tabs/tab.js

@@ -0,0 +1,44 @@
+import { TCollectionElements } from "../collection/collection-elements.plugin.js";
+//#region src/custom/tabs/tab.ts
+/**
+* Узел таба внутри узла элемента. Корень элемента — обёртка для темы, а табом
+* со своей ролью является вложенная строка: на неё и уходит фокус.
+*/
+var TAB_SELECTOR = "[role=\"tab\"]";
+/**
+* Узел таба — строка с ролью `tab` внутри узла элемента. `null` — элемента нет
+* в документе.
+*
+* Одна на клавиатуру Tabs (куда перевести фокус стрелкой) и фокус набора
+* (`tabStopOf`): узел таба оба ищут одним правилом.
+*/
+function tabOf(elements, uid) {
+	return tabIn(elements?.getElementByUid(uid) ?? null);
+}
+/**
+* Узел таба внутри узла элемента — тем же правилом, что `tabOf`, когда узел
+* уже на руках. `null` — узла нет или таба в нём нет.
+*
+* Он же узел фокуса `Tabs.Item` (`focusTarget` плагина действия): запись
+* `focused = true` ставит фокус на строку таба, а не на обёртку элемента.
+*/
+function tabIn(node) {
+	return node?.querySelector(TAB_SELECTOR) ?? null;
+}
+/**
+* Таб-остановка — узел таба, который держит остановку Tab. `null` — табов, на
+* которые можно перейти, нет, или узла таба нет в документе.
+*
+* Узел фокуса Tabs (`focusTarget` плагина действия): запись `focused = true`
+* ставит фокус туда же, куда ведёт Tab, а не на кнопку в слоте `leading`.
+* Таб берётся по модели — `tabStop` расширения табов, — а не по
+* `[tabindex="0"]` в разметке: в такте смены активного таба разметка ещё
+* старая, и фокус ушёл бы на прежний таб.
+*/
+function tabStopOf(_root, ctx) {
+	const elements = ctx.get(TCollectionElements) ?? null;
+	const stop = (elements?.engine ?? null)?.extensions.tabs.tabStop;
+	return stop ? tabOf(elements, stop.uid) : null;
+}
+//#endregion
+export { tabIn, tabOf, tabStopOf };

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

@@ -0,0 +1,4 @@
+export * from './keyboard';
+export * from './scroll';
+export * from './item-names';
+export { tagStopIn, tagStopOf } from './tag';

package/dist/custom/tags/item-names/index.d.ts

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

package/dist/custom/tags/item-names/item-names.plugin.d.ts

@@ -0,0 +1,12 @@
+import type { ITagsItem } from '@soxa-ui/core';
+import { TNamesPlugin } from '../../../locale/names.plugin';
+import type { TTranslations } from '../../../locale/types';
+/**
+ * TTagsItemNamesPlugin — имя кнопки закрытия тега от локали: в `closeAria`,
+ * вместе с текстом тега, как у таба (`TTabsItemNamesPlugin`). `tabindex` того
+ * же набора пишет коллекция, а не плагин.
+ */
+export declare class TTagsItemNamesPlugin extends TNamesPlugin<ITagsItem> {
+    protected _name(owner: ITagsItem, translations: TTranslations): void;
+    protected _watch(owner: ITagsItem, name: () => void): void;
+}

package/dist/custom/tags/item-names/item-names.plugin.js

@@ -0,0 +1,18 @@
+import { formatName } from "../../../locale/locale.js";
+import { TNamesPlugin } from "../../../locale/names.plugin.js";
+//#region src/custom/tags/item-names/item-names.plugin.ts
+/**
+* TTagsItemNamesPlugin — имя кнопки закрытия тега от локали: в `closeAria`,
+* вместе с текстом тега, как у таба (`TTabsItemNamesPlugin`). `tabindex` того
+* же набора пишет коллекция, а не плагин.
+*/
+var TTagsItemNamesPlugin = class extends TNamesPlugin {
+	_name(owner, translations) {
+		owner.closeAria.add("aria-label", formatName(translations.tags.close, owner.text));
+	}
+	_watch(owner, name) {
+		this._listenTo(owner.events, "change:text", name);
+	}
+};
+//#endregion
+export { TTagsItemNamesPlugin };

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

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './keyboard.plugin';

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

@@ -0,0 +1,133 @@
+import type { ITags } from '@soxa-ui/core';
+import { TBasePlugin } from '../../../base';
+import type { IPluginContext } from '../../../base';
+import type { TTagsKeyboardPluginEvents } from './types';
+/**
+ * TTagsKeyboardPlugin — клавиатура Tags с выбором по паттерну APG Listbox и
+ * фокус после закрытия тега в любом режиме.
+ *
+ * Весь набор — одна остановка Tab (roving tabindex), по тегам ходят стрелки:
+ * ←/→ (в RTL наоборот) и ↑/↓ — к соседнему тегу по кругу, `Home`/`End` — к
+ * крайним. Теги, на которые нельзя перейти (`TTagsExtension.isEnabledTag`),
+ * пропускаются. `Delete` и `Backspace` закрывают тег, если его можно закрыть.
+ *
+ * **Фокус и выбор расходятся**, в отличие от Tabs: стрелка переносит только
+ * фокус, выбирает пробел. `Enter` и пробел здесь не обрабатываются — строку
+ * под фокусом переключает её собственный `press` (`TActionPlugin`). Поэтому
+ * остановку Tab коллекция не может посчитать по одному выбору: `focusin` на
+ * корне сообщает ей тег под фокусом (`notifyFocus`) — и от стрелок, и от
+ * клика, и от `focus()` из кода.
+ *
+ * Слушатели клавиш висят, пока у набора включён выбор. В `none` строка —
+ * `listitem` без действия, остановкой она не бывает, и перехватывать клавиши
+ * незачем. Режим выражен подпиской на `change:mode`, а не проверкой в
+ * обработчике.
+ *
+ * **Закрытый тег отдаёт фокус соседу** — в любом режиме и любым закрытием:
+ * клавишей, крестиком, из кода. Узел тега уходит из документа, и фокус,
+ * стоявший в нём, ушёл бы на страницу: следующий Tab начинал бы обход
+ * заново, а в поле Select стрелки прокручивали бы страницу. Переносится
+ * только фокус из узла закрываемого тега — к следующему соседу, у последнего
+ * к предыдущему, недоступные и без остановки пропускаются, — на его остановку
+ * (`tagStopIn`): с выбором — строку, без выбора — крестик. Соседа нет — к
+ * первой остановке Tab после ряда и вне его: в поле Select ряд стоит перед
+ * полем ввода, и фокус встаёт в поле без своего правила Select. Нет и её —
+ * фокус не трогается.
+ *
+ * Где фокус и кто соседи, видно только до удаления: после него узла тега нет
+ * в реестре, а места — в наборе. Когда переносить фокус, решает помощник
+ * коллекции (`TLeavingFocus`), общий с Tabs: он снимает фокус и соседей и на
+ * закрытии, и в хуке удаления, а переносит тем из фактов «закрыли» и «ушёл»,
+ * что пришёл вторым. Порядок у них разный: набор удаляет тег сам, следом за
+ * `item:close`, а поле Select снимает выбор с опции ещё в своём обработчике
+ * `item:close`, раньше плагина, — и её тег уходит до того, как закрытие
+ * дойдёт сюда. Удаление, отменённое в `item:remove:before`, фокус не трогает.
+ * Тег, ушедший без закрытия, — снятый из данных или размонтированный, — фокус
+ * не переносит: иначе ряд, который снимают целиком, гонял бы фокус по своим
+ * уходящим тегам. Здесь — только кто соседи и куда идёт фокус.
+ *
+ * Сами `tabindex` плагин не пишет: их ставит `TTagsExtension`, потому что
+ * атрибут обязан стоять с первой отрисовки, включая серверную. Здесь только
+ * то, что требует DOM: слушатели и перенос фокуса. Тег, на который ушёл
+ * фокус, в окно ряда `scroll` доводит `TTagsScrollPlugin` по `focusin`,
+ * который даёт и `focus()` этого плагина. Закрыть тег из кода можно и на
+ * сервере, поэтому фокус читается только при узле корня.
+ *
+ * От `TListNavigationPlugin` не наследуется: там фокус на контейнере и
+ * подсветка через `aria-activedescendant`, а здесь фокус ходит по самим
+ * тегам — у каждого свой крестик (см. AGENTS.md, «Граница переиспользования
+ * между похожими компонентами»).
+ */
+export declare class TTagsKeyboardPlugin extends TBasePlugin<ITags, TTagsKeyboardPluginEvents> {
+    /** Корень: на нём слушатели, по нему же направление письма. */
+    private _element;
+    /** Узел, на котором слушатели висят сейчас; `null` — не висят. */
+    private _listening;
+    private _elements;
+    private _engine;
+    /** Фокус закрываемого тега — ждёт, пока тег закроют и он уйдёт из набора. */
+    private _leaving;
+    install(ctx: IPluginContext): void;
+    destroy(): void;
+    /**
+     * Движок сменился — подписки на режим выбора, закрытие и удаление тегов
+     * переезжают вместе с ним. Закрытие и удаление слушаются в любом режиме:
+     * фокус после закрытия переносится и без выбора.
+     */
+    private _bindEngine;
+    private readonly _onModeChange;
+    /** Слушатели висят на корне, пока узел есть и у набора включён выбор. */
+    private _syncListeners;
+    private readonly _onKeyDown;
+    /**
+     * Фокус пришёл на тег — остановка Tab переходит к нему. Один путь для
+     * стрелок (их `focus()` тоже даёт `focusin`), клика и фокуса из кода.
+     */
+    private readonly _onFocusIn;
+    /**
+     * Тег, с которого пришло событие, — тот, чей узел содержит его цель.
+     *
+     * Слушатель висит на корне, и до него всплывают события содержимого слота
+     * набора (поле ввода нового тега и т. п.): их перехватывать нельзя. Кнопка
+     * закрытия лежит внутри узла тега и считается его частью.
+     */
+    private _tagOf;
+    /** Куда ведёт клавиша; `undefined` — клавиша не наша. */
+    private _target;
+    /**
+     * Шаг по набору от стрелки. Теги идут в ряд с переносом, поэтому ↑/↓ —
+     * тоже шаг по порядку. В RTL ряд идёт справа налево, и ←/→ меняются
+     * местами.
+     */
+    private _step;
+    /**
+     * Направление письма берётся вычисленным: `direction` компонента бывает
+     * `inherit`, и тогда его задаёт предок.
+     */
+    private get _rtl();
+    /** Теги в порядке набора, на которые можно перейти. */
+    private _available;
+    /**
+     * Ближайший тег в направлении шага, по кругу: с последнего вперёд — на
+     * первый. Отсчёт от позиции тега в наборе, а не среди доступных: тег могли
+     * выключить, пока на нём фокус.
+     */
+    private _neighbour;
+    /** Фокус на строку тега с ролью. Гард нужен: узел плагину приходит `Element`. */
+    private _focus;
+    /**
+     * Тег закрывают — любым путём: клавишей, крестиком, из кода. Переносить
+     * ли фокус, решает помощник: фокус мог стоять и не в этом теге.
+     */
+    private readonly _onClose;
+    /**
+     * Соседи тега в порядке, в котором им отдаётся фокус: следующие за ним в
+     * наборе от ближнего, затем предыдущие от ближнего.
+     */
+    private _neighbours;
+    /**
+     * Фокус — на остановку ближайшего соседа, на которого можно перейти, а
+     * нет такого — на первую остановку Tab после ряда.
+     */
+    private _pass;
+}