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

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

@@ -0,0 +1,253 @@
+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 { TLeavingFocus } from "../../collection/leaving-focus.js";
+import { tagOf, tagStopIn } from "../tag.js";
+//#region src/custom/tags/keyboard/keyboard.plugin.ts
+/** Клавиши, которые закрывают тег. */
+var CLOSE_KEYS = /* @__PURE__ */ new Set(["Delete", "Backspace"]);
+/**
+* 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, «Граница переиспользования
+* между похожими компонентами»).
+*/
+var TTagsKeyboardPlugin = class extends TBasePlugin {
+	/** Корень: на нём слушатели, по нему же направление письма. */
+	_element = null;
+	/** Узел, на котором слушатели висят сейчас; `null` — не висят. */
+	_listening = null;
+	_elements = null;
+	_engine = null;
+	/** Фокус закрываемого тега — ждёт, пока тег закроют и он уйдёт из набора. */
+	_leaving = null;
+	install(ctx) {
+		super.install(ctx);
+		this._elements = ctx.get(TCollectionElements) ?? null;
+		this._leaving = new TLeavingFocus(this._elements, {
+			root: () => this._element,
+			place: (tag) => this._neighbours(tag),
+			pass: (root, neighbours) => this._pass(root, neighbours)
+		});
+		const elementPlugin = ctx.get(TElementPlugin);
+		elementPlugin?.events.on("ready", (element) => {
+			this._element = element;
+			this._syncListeners();
+		});
+		elementPlugin?.events.on("removed", () => {
+			this._element = null;
+			this._leaving?.reset();
+			this._syncListeners();
+		});
+		ctx.get(TCollectionBundlesPlugin)?.events.on("engine:bound", (engine) => this._bindEngine(engine));
+	}
+	destroy() {
+		this._element = null;
+		this._bindEngine(null);
+		this._elements = null;
+		this._leaving = null;
+		super.destroy();
+	}
+	/**
+	* Движок сменился — подписки на режим выбора, закрытие и удаление тегов
+	* переезжают вместе с ним. Закрытие и удаление слушаются в любом режиме:
+	* фокус после закрытия переносится и без выбора.
+	*/
+	_bindEngine(engine) {
+		const previous = this._engine?.extensions;
+		previous?.selection.events.off("change:mode", this._onModeChange);
+		previous?.tags.events.off("item:close", this._onClose);
+		this._engine = engine;
+		const extensions = engine?.extensions;
+		extensions?.selection.events.on("change:mode", this._onModeChange);
+		extensions?.tags.events.on("item:close", this._onClose);
+		this._leaving?.bind(extensions?.plain ?? null);
+		this._syncListeners();
+	}
+	_onModeChange = () => this._syncListeners();
+	/** Слушатели висят на корне, пока узел есть и у набора включён выбор. */
+	_syncListeners() {
+		const target = (this._engine?.extensions.selection.mode ?? "none") !== "none" ? this._element : null;
+		if (target === this._listening) return;
+		this._listening?.removeEventListener("keydown", this._onKeyDown);
+		this._listening?.removeEventListener("focusin", this._onFocusIn);
+		this._listening = target;
+		target?.addEventListener("keydown", this._onKeyDown);
+		target?.addEventListener("focusin", this._onFocusIn);
+	}
+	_onKeyDown = (event) => {
+		if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return;
+		const engine = this._engine;
+		if (!engine) return;
+		const tag = this._tagOf(engine, event.target);
+		if (!tag) return;
+		if (CLOSE_KEYS.has(event.key)) {
+			if (engine.extensions.tags.closeTag(tag)) event.preventDefault();
+			return;
+		}
+		const next = this._target(engine, event.key, tag);
+		if (!next) return;
+		event.preventDefault();
+		this._focus(next);
+	};
+	/**
+	* Фокус пришёл на тег — остановка Tab переходит к нему. Один путь для
+	* стрелок (их `focus()` тоже даёт `focusin`), клика и фокуса из кода.
+	*/
+	_onFocusIn = (event) => {
+		const engine = this._engine;
+		if (!engine) return;
+		const tag = this._tagOf(engine, event.target);
+		if (tag) engine.extensions.tags.notifyFocus(tag);
+	};
+	/**
+	* Тег, с которого пришло событие, — тот, чей узел содержит его цель.
+	*
+	* Слушатель висит на корне, и до него всплывают события содержимого слота
+	* набора (поле ввода нового тега и т. п.): их перехватывать нельзя. Кнопка
+	* закрытия лежит внутри узла тега и считается его частью.
+	*/
+	_tagOf(engine, target) {
+		if (!(target instanceof Node)) return void 0;
+		return engine.extensions.batch.shown.find((item) => this._elements?.getElementByUid(item.uid)?.contains(target));
+	}
+	/** Куда ведёт клавиша; `undefined` — клавиша не наша. */
+	_target(engine, key, tag) {
+		if (key === "Home") return this._available(engine)[0];
+		if (key === "End") return this._available(engine).at(-1);
+		const step = this._step(key);
+		return step === null ? void 0 : this._neighbour(engine, tag, step);
+	}
+	/**
+	* Шаг по набору от стрелки. Теги идут в ряд с переносом, поэтому ↑/↓ —
+	* тоже шаг по порядку. В RTL ряд идёт справа налево, и ←/→ меняются
+	* местами.
+	*/
+	_step(key) {
+		switch (key) {
+			case "ArrowUp": return -1;
+			case "ArrowDown": return 1;
+			case "ArrowLeft": return this._rtl ? 1 : -1;
+			case "ArrowRight": return this._rtl ? -1 : 1;
+			default: return null;
+		}
+	}
+	/**
+	* Направление письма берётся вычисленным: `direction` компонента бывает
+	* `inherit`, и тогда его задаёт предок.
+	*/
+	get _rtl() {
+		return this._element !== null && getComputedStyle(this._element).direction === "rtl";
+	}
+	/** Теги в порядке набора, на которые можно перейти. */
+	_available(engine) {
+		return engine.extensions.batch.shown.filter((item) => engine.extensions.tags.isEnabledTag(item));
+	}
+	/**
+	* Ближайший тег в направлении шага, по кругу: с последнего вперёд — на
+	* первый. Отсчёт от позиции тега в наборе, а не среди доступных: тег могли
+	* выключить, пока на нём фокус.
+	*/
+	_neighbour(engine, tag, step) {
+		const shown = engine.extensions.batch.shown;
+		const count = shown.length;
+		const from = shown.indexOf(tag);
+		for (let offset = 1; offset <= count; offset++) {
+			const candidate = shown[((from + step * offset) % count + count) % count];
+			if (engine.extensions.tags.isEnabledTag(candidate)) return candidate;
+		}
+	}
+	/** Фокус на строку тега с ролью. Гард нужен: узел плагину приходит `Element`. */
+	_focus(item) {
+		const option = tagOf(this._elements, item.uid);
+		if (isFocusableElement(option)) option.focus();
+	}
+	/**
+	* Тег закрывают — любым путём: клавишей, крестиком, из кода. Переносить
+	* ли фокус, решает помощник: фокус мог стоять и не в этом теге.
+	*/
+	_onClose = (tag) => this._leaving?.close(tag);
+	/**
+	* Соседи тега в порядке, в котором им отдаётся фокус: следующие за ним в
+	* наборе от ближнего, затем предыдущие от ближнего.
+	*/
+	_neighbours(tag) {
+		const shown = this._engine?.extensions.batch.shown ?? [];
+		const index = shown.indexOf(tag);
+		return [...shown.slice(index + 1), ...shown.slice(0, Math.max(index, 0)).reverse()];
+	}
+	/**
+	* Фокус — на остановку ближайшего соседа, на которого можно перейти, а
+	* нет такого — на первую остановку Tab после ряда.
+	*/
+	_pass(root, neighbours) {
+		const engine = this._engine;
+		if (!engine) return;
+		const { batch, tags } = engine.extensions;
+		const present = new Set(batch.items);
+		const stops = [];
+		for (const neighbour of neighbours) {
+			if (!present.has(neighbour) || !tags.isEnabledTag(neighbour)) continue;
+			const stop = tagStopIn(this._elements?.getElementByItem(neighbour) ?? null);
+			if (stop) stops.push(stop);
+		}
+		if (focusFirst(stops)) return;
+		focusFirst(tabStopsAfter(root, null));
+	}
+};
+//#endregion
+export { TTagsKeyboardPlugin };

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

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

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

@@ -0,0 +1,2 @@
+export { TTagsScrollPlugin } from './scroll.plugin';
+export type { TTagsScrollPluginEvents } from './types';

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

@@ -0,0 +1,68 @@
+import type { ITags } from '@soxa-ui/core';
+import { TBasePlugin } from '../../../base';
+import type { IPluginContext } from '../../../base';
+import type { TTagsScrollPluginEvents } from './types';
+/**
+ * TTagsScrollPlugin — brings the focused element of a `scroll` tags row into
+ * view.
+ *
+ * A `scroll` row scrolls by itself, and at its edge the focused element stayed
+ * cut: a partly visible one the browser doesn't scroll to on focus at all, a
+ * fully hidden one it centres — and then its tag stays cut. So on `focusin`
+ * the plugin brings the focused tag into the row's window: the padding box
+ * without `scroll-padding` (`scrollWindowOf`). How much room to keep at the
+ * edge only the theme knows — the focus ring's margin in a standalone row, the
+ * fade's width in a Select field. The arithmetic is shared with the scroller
+ * (`nearestShift`, `TScrollerViewportPlugin`).
+ *
+ * A plugin, not an extension or markup: boxes and scrolling are DOM
+ * operations. Decisions:
+ * - the tag — the row's direct child — goes into the window, not just the
+ *   focused element. Focus lands on the tag's line or its close button, while
+ *   in selection mode the ring is drawn by the pill: with the line in the
+ *   window and the pill past the edge, the ring and the close button stayed
+ *   cut, and a close button without its label doesn't tell which tag it
+ *   closes. A tag wider than the window covers it, with the focused element
+ *   inside;
+ * - the shift is the nearest one that puts the tag in the window, not start to
+ *   start as in the scroller: the row has no snap;
+ * - keyboard focus only (`:focus-visible`). The browser doesn't scroll to the
+ *   focus of a mouse press either, and rightly: had the row moved between the
+ *   press and the release, another tag would be under the pointer, and `click`
+ *   would miss;
+ * - the shift is synchronous, right in the handler, and instant, as in the
+ *   scroller. The browser's own scroll to focus is instant too and would cut a
+ *   smooth one short. On Tab it scrolls before `focusin`, after `focus()` —
+ *   right after it, and after our shift it has nothing left to do.
+ *
+ * The plugin is the only path that brings a tag in: on entering the set by
+ * Tab and after `focus()` of the keyboard plugin (`TTagsKeyboardPlugin`:
+ * arrows, `Home`/`End`, the neighbour of a closed tag). The keyboard plugin
+ * doesn't scroll by itself: `focus()` after a key press the browser counts as
+ * keyboard focus, and `focusin` comes here with `:focus-visible`.
+ *
+ * Listens only while `overflow === 'scroll'`: in `wrap` the row doesn't
+ * scroll. The mode is expressed by the subscription, not by a check in the
+ * handler.
+ */
+export declare class TTagsScrollPlugin extends TBasePlugin<ITags, TTagsScrollPluginEvents> {
+    /** The set's root: in `scroll` it is the scrolling row. */
+    private _root;
+    /** The node the listener is on now; `null` — it isn't on any. */
+    private _listening;
+    private _owner;
+    install(ctx: IPluginContext): void;
+    destroy(): void;
+    private readonly _onOverflowChange;
+    /** The listener is on the root while there is a node and the row scrolls by itself. */
+    private _syncListener;
+    /**
+     * Keyboard focus came into the row — bring its tag into the window (why —
+     * in the class description).
+     *
+     * The row itself is a Tab stop when it has none of its own: the browser
+     * makes one of a scrolling area. It is the window, and there is nowhere to
+     * bring it.
+     */
+    private readonly _onFocusIn;
+}

package/dist/custom/tags/scroll/scroll.plugin.js

@@ -0,0 +1,120 @@
+import { TBasePlugin } from "../../../base/base.class.js";
+import { TElementPlugin } from "../../element/element.plugin.js";
+import { nearestShift } from "../../../utils/nearestShift.js";
+import { itemOf, scrollWindowOf } from "../../../utils/scrollWindow.js";
+//#region src/custom/tags/scroll/scroll.plugin.ts
+/**
+* TTagsScrollPlugin — brings the focused element of a `scroll` tags row into
+* view.
+*
+* A `scroll` row scrolls by itself, and at its edge the focused element stayed
+* cut: a partly visible one the browser doesn't scroll to on focus at all, a
+* fully hidden one it centres — and then its tag stays cut. So on `focusin`
+* the plugin brings the focused tag into the row's window: the padding box
+* without `scroll-padding` (`scrollWindowOf`). How much room to keep at the
+* edge only the theme knows — the focus ring's margin in a standalone row, the
+* fade's width in a Select field. The arithmetic is shared with the scroller
+* (`nearestShift`, `TScrollerViewportPlugin`).
+*
+* A plugin, not an extension or markup: boxes and scrolling are DOM
+* operations. Decisions:
+* - the tag — the row's direct child — goes into the window, not just the
+*   focused element. Focus lands on the tag's line or its close button, while
+*   in selection mode the ring is drawn by the pill: with the line in the
+*   window and the pill past the edge, the ring and the close button stayed
+*   cut, and a close button without its label doesn't tell which tag it
+*   closes. A tag wider than the window covers it, with the focused element
+*   inside;
+* - the shift is the nearest one that puts the tag in the window, not start to
+*   start as in the scroller: the row has no snap;
+* - keyboard focus only (`:focus-visible`). The browser doesn't scroll to the
+*   focus of a mouse press either, and rightly: had the row moved between the
+*   press and the release, another tag would be under the pointer, and `click`
+*   would miss;
+* - the shift is synchronous, right in the handler, and instant, as in the
+*   scroller. The browser's own scroll to focus is instant too and would cut a
+*   smooth one short. On Tab it scrolls before `focusin`, after `focus()` —
+*   right after it, and after our shift it has nothing left to do.
+*
+* The plugin is the only path that brings a tag in: on entering the set by
+* Tab and after `focus()` of the keyboard plugin (`TTagsKeyboardPlugin`:
+* arrows, `Home`/`End`, the neighbour of a closed tag). The keyboard plugin
+* doesn't scroll by itself: `focus()` after a key press the browser counts as
+* keyboard focus, and `focusin` comes here with `:focus-visible`.
+*
+* Listens only while `overflow === 'scroll'`: in `wrap` the row doesn't
+* scroll. The mode is expressed by the subscription, not by a check in the
+* handler.
+*/
+var TTagsScrollPlugin = class extends TBasePlugin {
+	/** The set's root: in `scroll` it is the scrolling row. */
+	_root = null;
+	/** The node the listener is on now; `null` — it isn't on any. */
+	_listening = null;
+	_owner = null;
+	install(ctx) {
+		super.install(ctx);
+		this._owner = ctx.getInstance();
+		const element = ctx.get(TElementPlugin);
+		element?.events.on("ready", (node) => {
+			this._root = node;
+			this._syncListener();
+		});
+		element?.events.on("removed", () => {
+			this._root = null;
+			this._syncListener();
+		});
+		this._listenTo(this._owner?.events, "change:overflow", this._onOverflowChange);
+	}
+	destroy() {
+		this._root = null;
+		this._syncListener();
+		this._owner = null;
+		super.destroy();
+	}
+	_onOverflowChange = () => this._syncListener();
+	/** The listener is on the root while there is a node and the row scrolls by itself. */
+	_syncListener() {
+		const target = this._owner?.overflow === "scroll" ? this._root : null;
+		if (target === this._listening) return;
+		this._listening?.removeEventListener("focusin", this._onFocusIn);
+		this._listening = target;
+		target?.addEventListener("focusin", this._onFocusIn);
+	}
+	/**
+	* Keyboard focus came into the row — bring its tag into the window (why —
+	* in the class description).
+	*
+	* The row itself is a Tab stop when it has none of its own: the browser
+	* makes one of a scrolling area. It is the window, and there is nowhere to
+	* bring it.
+	*/
+	_onFocusIn = (event) => {
+		const root = this._root;
+		const target = event.target;
+		if (!root || !(target instanceof Element) || target === root) return;
+		if (!target.matches(":focus-visible")) return;
+		const shift = nearestShift({
+			scrollWindow: scrollWindowOf(root, getComputedStyle(root)),
+			focused: target.getBoundingClientRect(),
+			item: itemOf(target, root).getBoundingClientRect()
+		});
+		if (shift !== null) root.scrollBy({
+			left: wholePixels(shift),
+			behavior: "instant"
+		});
+	};
+};
+/**
+* The shift in whole pixels, rounded away from zero. WebKit keeps the scroll
+* position in whole pixels and truncates a fractional target toward zero: the
+* tag stopped short of the window by under a pixel, and the row keeps exactly
+* the focus ring's width at its edge, so the ring was cut. From a whole
+* position the target stays whole, and in both engines the row moves no less
+* than the tag needs. The arithmetic (`nearestShift`) stays exact.
+*/
+function wholePixels(shift) {
+	return Math.sign(shift) * Math.ceil(Math.abs(shift));
+}
+//#endregion
+export { TTagsScrollPlugin };

package/dist/custom/tags/scroll/types.d.ts

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

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

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

package/dist/custom/tags/tag.js

@@ -0,0 +1,66 @@
+import { TCollectionElements } from "../collection/collection-elements.plugin.js";
+import { tabStops } from "../../utils/tabStops.js";
+//#region src/custom/tags/tag.ts
+/**
+* Узел опции внутри узла тега. Корень элемента — пилюля для темы, а опцией со
+* своей ролью является вложенная строка: на неё и уходит фокус.
+*/
+var OPTION_SELECTOR = "[role=\"option\"]";
+/**
+* Строка тега с ролью опции — узел, на который уходит фокус тега, пока у
+* набора включён выбор. `null` — элемента нет в документе.
+*
+* Одна на клавиатуру Tags (куда перевести фокус стрелкой) и фокус набора
+* (`tagStopOf`): строку тега оба ищут одним правилом.
+*/
+function tagOf(elements, uid) {
+	return elements?.getElementByUid(uid)?.querySelector(OPTION_SELECTOR) ?? null;
+}
+/**
+* Остановка тега в его узле — узел фокуса `Tags.Item` (`focusTarget` плагина
+* действия): запись `focused = true` ставит фокус туда же, куда ведёт Tab, а
+* не на корень — пилюлю для темы, которая фокус не держит.
+*
+* С выбором — строка с ролью опции, тем же правилом, что `tagOf`: по тегам
+* ходят стрелки, и строка — опция, даже когда остановка набора не у неё. Без
+* выбора у строки нет ни роли опции, ни `tabindex` — она `listitem` без
+* действия, — и остановка тега — первая в его узле, крестик.
+*
+* `null` — узла нет, или в нём нет ни опции, ни остановки: тег без выбора не
+* закрывается.
+*/
+function tagStopIn(node) {
+	if (!node) return null;
+	return node.querySelector(OPTION_SELECTOR) ?? tabStops(node)[0] ?? null;
+}
+/**
+* Остановка набора тегов — узел фокуса Tags (`focusTarget` плагина действия):
+* запись `focused = true` ставит фокус туда же, куда ведёт Tab.
+*
+* С выбором набор — одна остановка (roving tabindex), тег-остановка
+* (`tabStop` расширения тегов). Он берётся по модели, а не по
+* `[tabindex="0"]`: в такте смены остановки разметка ещё старая. Без выбора
+* остановки у строк нет, и у модели — тоже: остановки набора — крестики, и
+* фокус встаёт на первую из них — остановку первого тега, у которого она
+* есть (`tagStopIn`, то же правило, что у `Tags.Item`), по тегам в порядке
+* показа, на которые можно перейти (`isEnabledTag`, то же правило, что у
+* остановки с выбором).
+*
+* `null` — остановок у набора нет (теги не закрываются, или на них нельзя
+* перейти) или узла тега нет в документе.
+*/
+function tagStopOf(_root, ctx) {
+	const elements = ctx.get(TCollectionElements) ?? null;
+	const engine = elements?.engine ?? null;
+	if (!engine) return null;
+	const { batch, tags } = engine.extensions;
+	const stop = tags.tabStop;
+	if (stop) return tagOf(elements, stop.uid);
+	for (const tag of batch.shown) {
+		const first = tags.isEnabledTag(tag) ? tagStopIn(elements?.getElementByItem(tag) ?? null) : null;
+		if (first) return first;
+	}
+	return null;
+}
+//#endregion
+export { tagOf, tagStopIn, tagStopOf };

package/dist/custom/textarea/autoresize/autoresize.plugin.d.ts

@@ -0,0 +1,70 @@
+import type { ITextarea } from '@soxa-ui/core';
+import { TBasePlugin } from '../../../base';
+import type { IPluginContext } from '../../../base';
+import type { TTextareaAutoresizePluginEvents } from './types';
+/**
+ * TTextareaAutoresizePlugin — высота многострочного поля по содержимому: от
+ * `rows` до `maxRows` строк.
+ *
+ * Нативная `<textarea>` не растёт, поэтому авторост — флаг `autoresize`, а
+ * пока он выключен, плагин поле не трогает: высоту дают `rows` и ручка.
+ * Свойства лежат на инстансе (`ITextarea`), плагин их читает — так же, как
+ * `TListHeightPlugin` читает `maxRows` списка: свойство — ядру, применение —
+ * плагину.
+ *
+ * Высота — инлайновый `height` самой `<textarea>` (корень растёт за ней сам:
+ * в нём ещё счётчик), в единицах её `box-sizing`. Строку меряет вычисленный
+ * интерлиньяж поля, к строкам добавляются его поля и рамка по оси блока, а
+ * высоту текста отдаёт `scrollHeight` — на миг сжатого до `rows` поля без
+ * прокрутки: так текст переносится по всей ширине, как после замера.
+ * Прокрутку предков, которую сжатие могло сбить, замер возвращает. Пока
+ * потолок не набран, прокрутки у поля нет (`overflow-y: hidden`): иначе под
+ * курсором мелькала бы полоса, которой вот-вот не станет. На потолке плагин
+ * этот запрет снимает, и поле прокручивается. Ручку (`resize: none`) плагин
+ * гасит на всё время автороста: высоту ведёт он. Выключили авторост — стили
+ * снимает, чужих не трогает. Перехода у высоты нет: поле растёт вместе с
+ * набором.
+ *
+ * **Ввод пользователя — синхронно**, в слушателе `input` поля: значение в
+ * узле уже новое, и высота встаёт до отрисовки. Остальное — значение из кода,
+ * `rows`, `maxRows`, `autoresize`, `size`, ширина поля и подгруженный шрифт
+ * (текст переносится иначе) — **кадром**: значение из кода фреймворк пишет в
+ * узел позже, чем ядро о нём сообщает, а размер меняет поля и кегль через
+ * класс. Ширину сообщает `ResizeObserver` — плагину важна только она: высоту
+ * поля меняет он сам.
+ *
+ * **Кадр — только при узле**: между `ready` и `removed` своего
+ * `TElementPlugin`. Сборка идёт и на сервере, и значение там меняется, а узла
+ * и `requestAnimationFrame` нет. Что сменилось до узла, применяет `ready` —
+ * сразу.
+ */
+export declare class TTextareaAutoresizePlugin extends TBasePlugin<ITextarea, TTextareaAutoresizePluginEvents> {
+    private _owner;
+    /** Поле — `<textarea>` корня, пока узел корня объявлен */
+    private _field;
+    private _observer;
+    /** Ширина поля, о которой уже знает плагин: высоту меняет он сам */
+    private _width;
+    /** Стили поля писал плагин: при выключении автороста есть что снять */
+    private _applied;
+    /** Замер в следующем кадре; прежний отложенный отменяется. */
+    private readonly _fitNextFrame;
+    private readonly _onInput;
+    private readonly _onFonts;
+    constructor();
+    install(ctx: IPluginContext, options?: unknown): void;
+    destroy(): void;
+    private _attach;
+    private _detach;
+    /** Наблюдатель сообщил размер поля: замер нужен, только если сменилась ширина. */
+    private _resized;
+    /**
+     * Замерить кадром позже — пока у плагина есть поле. Без узла повод ничего
+     * не планирует: всё, что сменилось до узла, применит `ready`.
+     */
+    private _schedule;
+    /** Высота поля по тексту — или снять стили, если авторост выключен. */
+    private _fit;
+    /** Авторост выключен — снять то, что писал плагин; без его стилей — ничего. */
+    private _release;
+}