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

package/dist/utils/isAppleTouch.js

@@ -0,0 +1,17 @@
+//#region src/utils/isAppleTouch.ts
+/**
+* Сенсорное устройство Apple — iPhone, iPod или iPad. iPadOS называет себя
+* `MacIntel`, как Mac, и отличает его сенсорный экран: у Mac точек касания нет.
+*
+* Общее у полей, которым VoiceOver на iOS не даёт счётчик (`spinbutton`): там
+* он его не фокусирует, и поле даты и поле числа отдают роль `textbox`.
+* Устройство узнают у документа узла, а не у `globalThis`: поле живёт и в
+* iframe.
+*/
+function isAppleTouch(navigator) {
+	if (!navigator) return false;
+	const { platform, maxTouchPoints } = navigator;
+	return /^(iPhone|iPod|iPad)/.test(platform) || /^Mac/.test(platform) && maxTouchPoints > 1;
+}
+//#endregion
+export { isAppleTouch };

package/dist/utils/isFocusableElement.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Узел, которому можно дать и снять фокус: `focus()` и `blur()` есть у
+ * `HTMLElement` и у `SVGElement`.
+ *
+ * `SVGElement` здесь не для полноты: корнем компонента бывает `svg`, и
+ * сужение до одного `HTMLElement` молча отняло бы у него фокус.
+ */
+export declare function isFocusableElement(el: unknown): el is HTMLElement | SVGElement;

package/dist/utils/isFocusableElement.js

@@ -0,0 +1,13 @@
+//#region src/utils/isFocusableElement.ts
+/**
+* Узел, которому можно дать и снять фокус: `focus()` и `blur()` есть у
+* `HTMLElement` и у `SVGElement`.
+*
+* `SVGElement` здесь не для полноты: корнем компонента бывает `svg`, и
+* сужение до одного `HTMLElement` молча отняло бы у него фокус.
+*/
+function isFocusableElement(el) {
+	return el instanceof HTMLElement || el instanceof SVGElement;
+}
+//#endregion
+export { isFocusableElement };

package/dist/utils/isMeasurableElement.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Узел с layout-боксом: `offsetWidth`/`offsetHeight`/`offsetTop`/`offsetLeft`
+ * и инлайновый `style`.
+ *
+ * Узел плагину приходит как `Element` (см. `TElementPlugin`) — корнем
+ * компонента может оказаться `svg`. Там, где меряется бокс или пишется
+ * инлайновый стиль, узел сужается этим гардом, а не приведением: у
+ * `SVGElement` нет `offset*`, и приведение отдало бы `undefined` в
+ * арифметику.
+ */
+export declare function isMeasurableElement(el: unknown): el is HTMLElement;

package/dist/utils/isMeasurableElement.js

@@ -0,0 +1,16 @@
+//#region src/utils/isMeasurableElement.ts
+/**
+* Узел с layout-боксом: `offsetWidth`/`offsetHeight`/`offsetTop`/`offsetLeft`
+* и инлайновый `style`.
+*
+* Узел плагину приходит как `Element` (см. `TElementPlugin`) — корнем
+* компонента может оказаться `svg`. Там, где меряется бокс или пишется
+* инлайновый стиль, узел сужается этим гардом, а не приведением: у
+* `SVGElement` нет `offset*`, и приведение отдало бы `undefined` в
+* арифметику.
+*/
+function isMeasurableElement(el) {
+	return el instanceof HTMLElement;
+}
+//#endregion
+export { isMeasurableElement };

package/dist/utils/isPrintableKey.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Печатный символ, а не сочетание с модификатором.
+ *
+ * В общих утилитах, а не у клавиатуры Select: набор по первым буквам ведут и
+ * комбобокс, и меню (`packages/plugins/src/custom/list/typeahead.ts`).
+ */
+export declare function isPrintableKey(e: KeyboardEvent): boolean;

package/dist/utils/isPrintableKey.js

@@ -0,0 +1,12 @@
+//#region src/utils/isPrintableKey.ts
+/**
+* Печатный символ, а не сочетание с модификатором.
+*
+* В общих утилитах, а не у клавиатуры Select: набор по первым буквам ведут и
+* комбобокс, и меню (`packages/plugins/src/custom/list/typeahead.ts`).
+*/
+function isPrintableKey(e) {
+	return e.key.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey;
+}
+//#endregion
+export { isPrintableKey };

package/dist/utils/layerOf.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Номер слоя узла (`data-layer`); `null` — узла нет или слоя у него нет.
+ *
+ * Номер пишет показанный слой (`TLayer` — Frame и модальное окно,
+ * `FRAME_LAYER_ATTRIBUTE`): больше номер — выше слой, открытый позже.
+ *
+ * Живёт в общих утилитах, а не у `TDismissPlugin`: по слоям решают двое —
+ * «нажали мимо» и то, что прячет фон модального слоя от скринридера
+ * (`THideOutsidePlugin`). Своё чтение атрибута у второго разошлось бы с
+ * первым.
+ */
+export declare function layerOf(element: Element | null): number | null;

package/dist/utils/layerOf.js

@@ -0,0 +1,21 @@
+import { FRAME_LAYER_ATTRIBUTE } from "@soxa-ui/core";
+//#region src/utils/layerOf.ts
+/**
+* Номер слоя узла (`data-layer`); `null` — узла нет или слоя у него нет.
+*
+* Номер пишет показанный слой (`TLayer` — Frame и модальное окно,
+* `FRAME_LAYER_ATTRIBUTE`): больше номер — выше слой, открытый позже.
+*
+* Живёт в общих утилитах, а не у `TDismissPlugin`: по слоям решают двое —
+* «нажали мимо» и то, что прячет фон модального слоя от скринридера
+* (`THideOutsidePlugin`). Своё чтение атрибута у второго разошлось бы с
+* первым.
+*/
+function layerOf(element) {
+	const value = element?.getAttribute(FRAME_LAYER_ATTRIBUTE);
+	if (value === null || value === void 0) return null;
+	const layer = Number(value);
+	return Number.isFinite(layer) ? layer : null;
+}
+//#endregion
+export { layerOf };

package/dist/utils/nearestShift.d.ts

@@ -0,0 +1,19 @@
+import type { TNearestShiftOptions } from './types';
+/**
+ * На сколько сдвинуть область, чтобы элемент под фокусом встал в окно, — или
+ * `null`, если он уже там.
+ *
+ * С элементом области (`item`) в окно встаёт и он. Не шире окна — целиком: у
+ * тега в ряду кольцо фокуса рисует пилюля, а крестик без подписи не скажет,
+ * какой тег он закроет. Шире окна — накрывает его, а элемент под фокусом
+ * лежит в окне: так крестик в конце длинного тега виден, хотя начало тега за
+ * краем.
+ *
+ * Из всех таких сдвигов берётся ближайший: область уезжает не дальше, чем
+ * нужно, и то, что было в окне, по возможности в нём и остаётся.
+ *
+ * Элемент под фокусом шире окна в него не встанет ни при каком сдвиге и
+ * доводится до ближайшего положения, где накрывает окно: больше окна от него
+ * всё равно не увидеть.
+ */
+export declare function nearestShift({ scrollWindow, focused, item, }: TNearestShiftOptions): number | null;

package/dist/utils/nearestShift.js

@@ -0,0 +1,58 @@
+//#region src/utils/nearestShift.ts
+/**
+* Доводка элемента под фокусом в окно области прокрутки — чистая функция,
+* без DOM: область и её элементы сюда приходят отрезками по строке. Отсюда и
+* проверяемость: субпиксели, элемент шире окна и оба края проверяются
+* числами, а не настоящей раскладкой.
+*
+* Живёт в общих утилитах, а не у ленты: доводят двое — вьюпорт ленты
+* (`TScrollerViewportPlugin`) и ряд тегов `scroll` (`TTagsScrollPlugin`).
+* Своя арифметика у второго разошлась бы с первой: допуск, элемент шире окна
+* и «накрывает окно» пришлось бы писать дважды. У ленты сверх этого есть
+* снап, и он остаётся у неё (`resolveFocusShift`).
+*
+* Направление письма здесь не нужно: ближайший сдвиг одинаков в обе стороны,
+* а сдвиг — физический, как у `scrollBy`.
+*/
+/**
+* Допуск на субпиксельное округление: край, вышедший из окна на полпикселя, —
+* ещё в окне. Область встаёт на целый пиксель, а края элементов дробные.
+*/
+var TOLERANCE = .5;
+/**
+* Сдвиги области, при которых отрезок лежит в окне, а если он шире окна —
+* накрывает его: больше окна от него не увидеть. Сдвиг — как у `scrollBy`: на
+* сколько содержимое области уезжает влево.
+*/
+function fitting(span, scrollWindow) {
+	const left = span.left - scrollWindow.left;
+	const right = span.right - scrollWindow.right;
+	return [Math.min(left, right), Math.max(left, right)];
+}
+/**
+* На сколько сдвинуть область, чтобы элемент под фокусом встал в окно, — или
+* `null`, если он уже там.
+*
+* С элементом области (`item`) в окно встаёт и он. Не шире окна — целиком: у
+* тега в ряду кольцо фокуса рисует пилюля, а крестик без подписи не скажет,
+* какой тег он закроет. Шире окна — накрывает его, а элемент под фокусом
+* лежит в окне: так крестик в конце длинного тега виден, хотя начало тега за
+* краем.
+*
+* Из всех таких сдвигов берётся ближайший: область уезжает не дальше, чем
+* нужно, и то, что было в окне, по возможности в нём и остаётся.
+*
+* Элемент под фокусом шире окна в него не встанет ни при каком сдвиге и
+* доводится до ближайшего положения, где накрывает окно: больше окна от него
+* всё равно не увидеть.
+*/
+function nearestShift({ scrollWindow, focused, item = focused }) {
+	const [focusFrom, focusTo] = fitting(focused, scrollWindow);
+	const [itemFrom, itemTo] = fitting(item, scrollWindow);
+	const from = Math.max(focusFrom, itemFrom);
+	const to = Math.min(focusTo, itemTo);
+	if (from - TOLERANCE <= 0 && to + TOLERANCE >= 0) return null;
+	return Math.min(Math.max(0, from), to);
+}
+//#endregion
+export { nearestShift };

package/dist/utils/positionOrigin.d.ts

@@ -0,0 +1,34 @@
+/** Позиционирование, от которого зависит блок отсчёта: `fixed` или `absolute`. */
+export type TPositionStrategy = 'fixed' | 'absolute';
+/** Точка в координатах окна. */
+export type TPoint = {
+    readonly x: number;
+    readonly y: number;
+};
+/**
+ * Угол блока, от которого браузер отсчитывает `left`/`top` узла с этим
+ * позиционированием, — в координатах окна.
+ *
+ * Блок — ближайший предок, который держит такие потомки: для `fixed` — только
+ * трансформацией, фильтром и сдерживанием (`holdsFixed`), для `absolute` — ещё
+ * и любым `position`, кроме `static`. Отсчёт идёт от края его паддинга — за
+ * рамкой (`clientLeft`/`clientTop`) — и едет с его прокруткой. У корня
+ * документа прокрутку не вычитаем: она — прокрутка окна, и в его
+ * прямоугольнике уже учтена.
+ *
+ * Такого предка нет — для `fixed` это окно (`0, 0`), для `absolute` — начало
+ * документа, то есть точка окна `-scrollX, -scrollY`.
+ *
+ * Узла ещё нет — блок не найти, и отсчёт тот же, что без предка.
+ */
+export declare function positionOriginOf(node: Element | null, strategy: TPositionStrategy): TPoint;
+/**
+ * Узел стоит в окне, а не в документе: он сам или его предок —
+ * `position: fixed`, или `sticky`, который липнет к окну, — у него нет
+ * прокручиваемого предка (`scrollParentOf`). Прокрутка окна такой узел не
+ * двигает.
+ *
+ * `sticky` во внутренней прокрутке с окном не стоит: окно везёт его вместе с
+ * контейнером.
+ */
+export declare function isPinnedToViewport(node: Element): boolean;

package/dist/utils/positionOrigin.js

@@ -0,0 +1,71 @@
+import { scrollParentOf } from "./scrollParent.js";
+//#region src/utils/positionOrigin.ts
+/**
+* Значение свойства, которое делает узел блоком отсчёта и для `fixed`, и для
+* `absolute` потомков: трансформация, фильтр, сдерживание. Пустая строка —
+* свойство браузер не знает (jsdom, старый движок), и блока оно не даёт.
+*/
+var sets = (value) => !!value && value !== "none";
+/**
+* Узел — блок отсчёта для потомка с `position: fixed`, а значит и с
+* `absolute`: так его делают трансформация и отдельные `translate`, `rotate`,
+* `scale`, перспектива, фильтры, сдерживание раскладки и отрисовки, контейнер
+* размера и `will-change` любого из них. Тот же список у Floating UI.
+*/
+function holdsFixed(style) {
+	return sets(style.transform) || sets(style.translate) || sets(style.rotate) || sets(style.scale) || sets(style.perspective) || sets(style.filter) || sets(style.backdropFilter) || /paint|layout|strict|content/.test(style.contain ?? "") || /transform|translate|rotate|scale|perspective|filter/.test(style.willChange ?? "") || !!style.containerType && style.containerType !== "normal";
+}
+/**
+* Угол блока, от которого браузер отсчитывает `left`/`top` узла с этим
+* позиционированием, — в координатах окна.
+*
+* Блок — ближайший предок, который держит такие потомки: для `fixed` — только
+* трансформацией, фильтром и сдерживанием (`holdsFixed`), для `absolute` — ещё
+* и любым `position`, кроме `static`. Отсчёт идёт от края его паддинга — за
+* рамкой (`clientLeft`/`clientTop`) — и едет с его прокруткой. У корня
+* документа прокрутку не вычитаем: она — прокрутка окна, и в его
+* прямоугольнике уже учтена.
+*
+* Такого предка нет — для `fixed` это окно (`0, 0`), для `absolute` — начало
+* документа, то есть точка окна `-scrollX, -scrollY`.
+*
+* Узла ещё нет — блок не найти, и отсчёт тот же, что без предка.
+*/
+function positionOriginOf(node, strategy) {
+	for (let current = node?.parentElement ?? null; current; current = current.parentElement) {
+		const style = getComputedStyle(current);
+		if (!holdsFixed(style) && (strategy === "fixed" || style.position === "static")) continue;
+		const rect = current.getBoundingClientRect();
+		const root = current === current.ownerDocument.documentElement;
+		return {
+			x: rect.left + current.clientLeft - (root ? 0 : current.scrollLeft),
+			y: rect.top + current.clientTop - (root ? 0 : current.scrollTop)
+		};
+	}
+	return strategy === "fixed" ? {
+		x: 0,
+		y: 0
+	} : {
+		x: -window.scrollX,
+		y: -window.scrollY
+	};
+}
+/**
+* Узел стоит в окне, а не в документе: он сам или его предок —
+* `position: fixed`, или `sticky`, который липнет к окну, — у него нет
+* прокручиваемого предка (`scrollParentOf`). Прокрутка окна такой узел не
+* двигает.
+*
+* `sticky` во внутренней прокрутке с окном не стоит: окно везёт его вместе с
+* контейнером.
+*/
+function isPinnedToViewport(node) {
+	for (let current = node; current; current = current.parentElement) {
+		const position = getComputedStyle(current).position;
+		if (position === "fixed") return true;
+		if (position === "sticky" && !scrollParentOf(current, "y")) return true;
+	}
+	return false;
+}
+//#endregion
+export { isPinnedToViewport, positionOriginOf };

package/dist/utils/scrollParent.d.ts

@@ -0,0 +1,12 @@
+/** Ось прокрутки: `x` — вдоль строки, `y` — вдоль страницы. */
+export type TScrollAxis = 'x' | 'y';
+/**
+ * Прокручивается ли узел вдоль оси: стиль разрешает прокрутку (`auto`,
+ * `scroll`), и содержимое в окно узла не помещается.
+ */
+export declare function isScrollable(element: Element, axis: TScrollAxis): boolean;
+/**
+ * Ближайший предок узла, который прокручивается вдоль оси. Такого нет —
+ * `null`: узел прокручивает страница.
+ */
+export declare function scrollParentOf(node: Element, axis: TScrollAxis): HTMLElement | null;

package/dist/utils/scrollParent.js

@@ -0,0 +1,23 @@
+import { isMeasurableElement } from "./isMeasurableElement.js";
+//#region src/utils/scrollParent.ts
+/**
+* Прокручивается ли узел вдоль оси: стиль разрешает прокрутку (`auto`,
+* `scroll`), и содержимое в окно узла не помещается.
+*/
+function isScrollable(element, axis) {
+	if (!isMeasurableElement(element)) return false;
+	const style = getComputedStyle(element);
+	const overflow = axis === "y" ? style.overflowY : style.overflowX;
+	const overflows = axis === "y" ? element.scrollHeight > element.clientHeight : element.scrollWidth > element.clientWidth;
+	return (overflow === "auto" || overflow === "scroll") && overflows;
+}
+/**
+* Ближайший предок узла, который прокручивается вдоль оси. Такого нет —
+* `null`: узел прокручивает страница.
+*/
+function scrollParentOf(node, axis) {
+	for (let current = node.parentElement; current; current = current.parentElement) if (isScrollable(current, axis)) return current;
+	return null;
+}
+//#endregion
+export { isScrollable, scrollParentOf };

package/dist/utils/scrollWindow.d.ts

@@ -0,0 +1,27 @@
+import type { TInlineSpan } from './types';
+/**
+ * Замер области прокрутки для доводки элемента под фокусом (`nearestShift`):
+ * окно области и элемент области, в котором лежит узел.
+ *
+ * Живёт в общих утилитах, а не у ленты: мерят двое — вьюпорт ленты
+ * (`TScrollerViewportPlugin`) и ряд тегов `scroll` (`TTagsScrollPlugin`).
+ * Свой замер у второго разошёлся бы с первым — например, в том, чем считать
+ * процент у `scroll-padding` и что делать с `auto`.
+ */
+/**
+ * Окно области по строке: паддинг-бокс (`clientLeft`, `clientWidth` — без
+ * рамки и полосы прокрутки) без вычисленного `scroll-padding` с каждой
+ * стороны. Стороны физические: логический `scroll-padding-inline` браузер
+ * отдаёт уже разложенным по ним.
+ *
+ * Отступ окна задаёт тема, и только она знает, сколько места держать у края:
+ * ширину подсказки ленты, запас под кольцо фокуса. До того же окна докручивает
+ * и сам браузер (`scrollIntoView`, фокус), поэтому доводка с ним не спорит.
+ */
+export declare function scrollWindowOf(area: Element, style: CSSStyleDeclaration): TInlineSpan;
+/**
+ * Элемент области, в котором лежит узел, — его предок, который прямой ребёнок
+ * области. Содержимое лежит в области без обёрток: у ленты это элементы, на
+ * которых тема ставит точки снапа, у ряда тегов — пилюли.
+ */
+export declare function itemOf(node: Element, area: Element): Element;

package/dist/utils/scrollWindow.js

@@ -0,0 +1,50 @@
+//#region src/utils/scrollWindow.ts
+/**
+* Замер области прокрутки для доводки элемента под фокусом (`nearestShift`):
+* окно области и элемент области, в котором лежит узел.
+*
+* Живёт в общих утилитах, а не у ленты: мерят двое — вьюпорт ленты
+* (`TScrollerViewportPlugin`) и ряд тегов `scroll` (`TTagsScrollPlugin`).
+* Свой замер у второго разошёлся бы с первым — например, в том, чем считать
+* процент у `scroll-padding` и что делать с `auto`.
+*/
+/**
+* Окно области по строке: паддинг-бокс (`clientLeft`, `clientWidth` — без
+* рамки и полосы прокрутки) без вычисленного `scroll-padding` с каждой
+* стороны. Стороны физические: логический `scroll-padding-inline` браузер
+* отдаёт уже разложенным по ним.
+*
+* Отступ окна задаёт тема, и только она знает, сколько места держать у края:
+* ширину подсказки ленты, запас под кольцо фокуса. До того же окна докручивает
+* и сам браузер (`scrollIntoView`, фокус), поэтому доводка с ним не спорит.
+*/
+function scrollWindowOf(area, style) {
+	const left = area.getBoundingClientRect().left + area.clientLeft;
+	const width = area.clientWidth;
+	return {
+		left: left + insetOf(style.scrollPaddingLeft, width),
+		right: left + width - insetOf(style.scrollPaddingRight, width)
+	};
+}
+/**
+* Отступ окна с одной стороны, в px. Процент считается от ширины области
+* прокрутки. `auto` спецификация оставляет браузеру и советует ноль — ноль и
+* считается.
+*/
+function insetOf(value, width) {
+	const length = parseFloat(value);
+	if (!Number.isFinite(length)) return 0;
+	return value.endsWith("%") ? length * width / 100 : length;
+}
+/**
+* Элемент области, в котором лежит узел, — его предок, который прямой ребёнок
+* области. Содержимое лежит в области без обёрток: у ленты это элементы, на
+* которых тема ставит точки снапа, у ряда тегов — пилюли.
+*/
+function itemOf(node, area) {
+	let item = node;
+	while (item.parentElement !== null && item.parentElement !== area) item = item.parentElement;
+	return item;
+}
+//#endregion
+export { itemOf, scrollWindowOf };

package/dist/utils/tabStops.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Остановки Tab — элементы, на которые браузер ставит фокус клавишей Tab, в
+ * порядке документа.
+ *
+ * Браузер этот порядок наружу не отдаёт, поэтому он восстанавливается по
+ * разметке: что фокусируется само, что получило `tabindex`, что выключено.
+ * Раскладку поиск не проверяет — в jsdom её нет, а в браузере скрытый
+ * элемент сам не примет фокус: кандидатов перебирают по очереди, пока один
+ * не примет (`focusFirst`). Положительный `tabindex` порядок не меняет: он
+ * ломает порядок обхода и в APG не рекомендован.
+ *
+ * Живёт в общих утилитах, а не у модели фокуса Popover: спрашивают об этом
+ * поповер (куда уводить фокус), лента (становиться ли ей самой остановкой
+ * Tab), поле Select (не остановка ли под указателем, `closestTabStop`), а не
+ * контрол ли под указателем (`closestControl`), — жест выезжающей панели и
+ * сетка таблицы. Свой список селекторов у любого из них был бы вторым путём к
+ * тому же знанию.
+ */
+/** Остановки Tab внутри узла или документа, в порядке документа. */
+export declare function tabStops(scope: ParentNode): Element[];
+/**
+ * Контрол, в котором лежит узел, — ближайший кандидат в остановки Tab между
+ * узлом и `scope` (сам `scope` не в счёт): поле, кнопка, ссылка, всё с
+ * `tabindex`. `null` — узел лежит в разметке без контрола.
+ *
+ * Кандидат, а не остановка: выключенное поле, радио не первое в группе и
+ * строка с `tabindex="-1"` в roving tabindex остановками не бывают, но с ними
+ * работают указателем. Об этом спрашивают жест выезжающей панели — тянуть её
+ * можно за любое место, кроме контролов, — и сетка таблицы — нажатие по
+ * контролу ячейки строку не выбирает. Список тот же, что у остановок: свой
+ * набор селекторов разошёлся бы с ним.
+ */
+export declare function closestControl(node: Element, scope: Element): Element | null;
+/**
+ * Остановка Tab, в которой лежит узел, — ближайший к нему кандидат между узлом
+ * и `scope` (сам `scope` не в счёт), который и есть остановка. Кандидаты по
+ * дороге, которые остановками не бывают — `tabindex="-1"`, выключенное поле, —
+ * пропускаются. `null` — остановки нет ни на узле, ни над ним до `scope`.
+ *
+ * Об этом спрашивает поле Select (`TSelectPointerPlugin`): нажатие мимо его
+ * остановок гасится, и фокус остаётся в поле. Кандидаты и правило остановки —
+ * те же, что у `tabStops`.
+ */
+export declare function closestTabStop(node: Element, scope: Element): Element | null;

package/dist/utils/tabStops.js

@@ -0,0 +1,102 @@
+//#region src/utils/tabStops.ts
+/**
+* Остановки Tab — элементы, на которые браузер ставит фокус клавишей Tab, в
+* порядке документа.
+*
+* Браузер этот порядок наружу не отдаёт, поэтому он восстанавливается по
+* разметке: что фокусируется само, что получило `tabindex`, что выключено.
+* Раскладку поиск не проверяет — в jsdom её нет, а в браузере скрытый
+* элемент сам не примет фокус: кандидатов перебирают по очереди, пока один
+* не примет (`focusFirst`). Положительный `tabindex` порядок не меняет: он
+* ломает порядок обхода и в APG не рекомендован.
+*
+* Живёт в общих утилитах, а не у модели фокуса Popover: спрашивают об этом
+* поповер (куда уводить фокус), лента (становиться ли ей самой остановкой
+* Tab), поле Select (не остановка ли под указателем, `closestTabStop`), а не
+* контрол ли под указателем (`closestControl`), — жест выезжающей панели и
+* сетка таблицы. Свой список селекторов у любого из них был бы вторым путём к
+* тому же знанию.
+*/
+/** Элементы, которые встают в порядок Tab сами, без `tabindex`. */
+var NATIVE_STOPS = [
+	"a[href]",
+	"area[href]",
+	"button",
+	"input:not([type=\"hidden\"])",
+	"select",
+	"textarea",
+	"iframe",
+	"audio[controls]",
+	"video[controls]",
+	"summary",
+	"[contenteditable]:not([contenteditable=\"false\"])"
+].join(",");
+var CANDIDATES = `${NATIVE_STOPS},[tabindex]`;
+/** Остановки Tab внутри узла или документа, в порядке документа. */
+function tabStops(scope) {
+	return [...scope.querySelectorAll(CANDIDATES)].filter(isTabStop);
+}
+/**
+* Контрол, в котором лежит узел, — ближайший кандидат в остановки Tab между
+* узлом и `scope` (сам `scope` не в счёт): поле, кнопка, ссылка, всё с
+* `tabindex`. `null` — узел лежит в разметке без контрола.
+*
+* Кандидат, а не остановка: выключенное поле, радио не первое в группе и
+* строка с `tabindex="-1"` в roving tabindex остановками не бывают, но с ними
+* работают указателем. Об этом спрашивают жест выезжающей панели — тянуть её
+* можно за любое место, кроме контролов, — и сетка таблицы — нажатие по
+* контролу ячейки строку не выбирает. Список тот же, что у остановок: свой
+* набор селекторов разошёлся бы с ним.
+*/
+function closestControl(node, scope) {
+	const control = node.closest(CANDIDATES);
+	return control && control !== scope && scope.contains(control) ? control : null;
+}
+/**
+* Остановка Tab, в которой лежит узел, — ближайший к нему кандидат между узлом
+* и `scope` (сам `scope` не в счёт), который и есть остановка. Кандидаты по
+* дороге, которые остановками не бывают — `tabindex="-1"`, выключенное поле, —
+* пропускаются. `null` — остановки нет ни на узле, ни над ним до `scope`.
+*
+* Об этом спрашивает поле Select (`TSelectPointerPlugin`): нажатие мимо его
+* остановок гасится, и фокус остаётся в поле. Кандидаты и правило остановки —
+* те же, что у `tabStops`.
+*/
+function closestTabStop(node, scope) {
+	let candidate = node.closest(CANDIDATES);
+	while (candidate && candidate !== scope && scope.contains(candidate)) {
+		if (isTabStop(candidate)) return candidate;
+		candidate = candidate.parentElement?.closest(CANDIDATES) ?? null;
+	}
+	return null;
+}
+function isTabStop(element) {
+	const tabindex = explicitTabIndex(element);
+	if (tabindex === null ? !element.matches(NATIVE_STOPS) : tabindex < 0) return false;
+	if (element.matches(":disabled") || element.closest("[inert]")) return false;
+	return isRadioStop(element);
+}
+/** Значение атрибута `tabindex`; `null` — атрибута нет или он не число. */
+function explicitTabIndex(element) {
+	const value = element.getAttribute("tabindex");
+	if (value === null) return null;
+	const parsed = Number.parseInt(value, 10);
+	return Number.isNaN(parsed) ? null : parsed;
+}
+/**
+* Группа радио с общим `name` — одна остановка: выбранное радио, а если
+* выбранного нет — первое. По остальным ходят стрелки. Без этого последним в
+* панели считалось бы последнее радио группы, и Tab с выбранного первого
+* уводил бы фокус мимо правила «из панели — к тому, что за триггером».
+*/
+function isRadioStop(element) {
+	if (!(element instanceof HTMLInputElement) || element.type !== "radio" || !element.name) return true;
+	const group = radioGroup(element);
+	const checked = group.find((radio) => radio.checked);
+	return checked ? checked === element : group[0] === element;
+}
+function radioGroup(radio) {
+	return [...(radio.form ?? radio.ownerDocument).querySelectorAll("input[type=\"radio\"]")].filter((candidate) => candidate instanceof HTMLInputElement && candidate.name === radio.name && candidate.form === radio.form);
+}
+//#endregion
+export { closestControl, closestTabStop, tabStops };

package/dist/utils/tabStopsAfter.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Остановки после узла в порядке документа — без его потомков и без
+ * `exclude`: Tab из телепортированной панели ведёт к тому, что стоит в
+ * документе за триггером, а сама панель лежит в конце `body`.
+ *
+ * Спрашивает об этом немодальный оверлей: у модального Tab замкнут в панели,
+ * и что стоит за ней, его не касается. Список остановок берётся у `tabStops`
+ * — второй набор селекторов разошёлся бы с первым.
+ */
+export declare function tabStopsAfter(node: Element, exclude: Element | null): Element[];

package/dist/utils/tabStopsAfter.js

@@ -0,0 +1,16 @@
+import { tabStops } from "./tabStops.js";
+//#region src/utils/tabStopsAfter.ts
+/**
+* Остановки после узла в порядке документа — без его потомков и без
+* `exclude`: Tab из телепортированной панели ведёт к тому, что стоит в
+* документе за триггером, а сама панель лежит в конце `body`.
+*
+* Спрашивает об этом немодальный оверлей: у модального Tab замкнут в панели,
+* и что стоит за ней, его не касается. Список остановок берётся у `tabStops`
+* — второй набор селекторов разошёлся бы с первым.
+*/
+function tabStopsAfter(node, exclude) {
+	return tabStops(node.ownerDocument).filter((stop) => !node.contains(stop) && !exclude?.contains(stop) && (node.compareDocumentPosition(stop) & Node.DOCUMENT_POSITION_FOLLOWING) !== 0);
+}
+//#endregion
+export { tabStopsAfter };

package/dist/utils/tabStopsBefore.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Остановки перед узлом в порядке документа — без его потомков: Shift+Tab из
+ * виджета, который водит Tab сам, ведёт к тому, что стоит в документе перед
+ * ним. Предок узла с остановкой — тоже перед ним: в порядке Tab он раньше
+ * своих потомков.
+ *
+ * Пара к `tabStopsAfter`, и список остановок тот же — у `tabStops`: второй
+ * набор селекторов разошёлся бы с первым. Спрашивает сетка таблицы: её Tab —
+ * одна остановка, и уходит он из неё сам.
+ */
+export declare function tabStopsBefore(node: Element): Element[];