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

package/dist/custom/list/navigation/navigation.plugin.js

@@ -0,0 +1,402 @@
+import { TBasePlugin } from "../../../base/base.class.js";
+import { TCollectionBundlesPlugin } from "../../collection/bundles.plugin.js";
+import { TElementPlugin } from "../../element/element.plugin.js";
+import { TListItemPlugin } from "../item/item.plugin.js";
+import { batchOf, drawOf } from "@soxa-ui/core";
+//#region src/custom/list/navigation/navigation.plugin.ts
+/**
+* Можно ли подсветить элемент: он доступен и виден. Подсветить то, что нельзя
+* выбрать, значит завести пользователя в тупик. `disabled` — итог, в нём учтён
+* и выключенный владелец.
+*/
+var isNavigable = (item) => !item.disabled && item.rendered && item.visible;
+/** Причина закрепления элемента в окне коллекции — на нём подсветка. */
+var HIGHLIGHT = "highlight";
+/**
+* TListNavigationPlugin — общая механика навигации по коллекции с клавиатуры.
+*
+* Здесь всё, что не зависит от роли элемента и модели фокуса: подписка на
+* `keydown`, привязка к движку коллекции, учёт подсвеченного элемента,
+* циклический сдвиг и пропуск недоступных элементов. Что делают конкретные
+* клавиши и что означает активация — дело наследника.
+*
+* Граница проведена именно так не из аккуратности. `ListBox` — самостоятельный
+* фокусируемый виджет: фокус держит узел списка. `Select` — combobox, у
+* которого фокус не уходит с поля. Элемент под стрелками оба объявляют через
+* `aria-activedescendant` узла с фокусом, но узел, роли (`option` против
+* `option` в другом контейнере), набор клавиш и смысл активации у них разные,
+* и попытка выразить это режимами одного плагина заставила бы его тесты
+* охранять два поведения сразу.
+*
+* Подсветка — не выбор. Она визуальна, живёт только во время навигации и в
+* значение не попадает; хранится в `TListItemPlugin` каждого элемента.
+*
+* **Позиция и видимая подсветка — разные вещи.** Позиция встаёт на элемент и
+* без отметки: за выбором и на строку, с которой пришла клавиша
+* (`trackHighlight`). О том, что видно на экране, навигация сообщает одним
+* приватным методом сразу двоим: событием `change:highlight` — тем, кто
+* слушает снаружи (прокрутка списка `TListScrollPlugin`, разметка Select), —
+* и хуком `onHighlightChanged` — наследнику. Элемент — когда отметка встала,
+* в том числе на месте, где позиция уже стояла без неё; `null` — когда
+* видимая отметка ушла: подсветку сняли или позиция ушла без отметки. Позиция
+* без отметки переезжает молча: экран не меняется, и прокручивать к ней
+* нечего. У Select и меню позиция всегда с отметкой — для них событие одно с
+* переездом позиции.
+*
+* **Ссылка на подсвеченный элемент** (`aria-activedescendant`) повторяет
+* экран: она есть, пока у элемента видна отметка и он в документе. `id` для
+* ссылки отдаёт `highlightedId()`, а куда её писать, решает наследник по хуку:
+* туда, где фокус. `id` подсвеченного бывает и новым при той же подсветке —
+* `id` элемента от приложения (`TIdPlugin`) задали, сменили или сняли, — и об
+* этом наследник узнаёт своим хуком (`onHighlightedAriaChanged`): база следит
+* за набором `aria` элемента на позиции, пока она на нём.
+*
+* **В окне** (обёртка `Virtual`) в документе только видимые элементы, и у
+* ненарисованного нет ни узла, ни `TListItemPlugin`. Поэтому элемент позиции
+* навигация закрепляет в рисовании коллекции (`draw.pin`): окно рисует его на
+* месте, даже когда стрелка увела подсветку за видимую полосу, и до кадра, в
+* котором его прокручивают к глазу. Отметку заново
+* смонтированному элементу навигация возвращает при регистрации его набора:
+* прежний набор ушёл вместе с узлом. Тогда же наследник узнаёт, что
+* подсвеченный элемент вошёл в документ (`onHighlightedMounted`): то, что есть
+* только у смонтированного элемента, — `id` и узел — появилось у него только
+* сейчас.
+*
+* Элемент списка — `TItem`. Навигации хватает `IControl`, а наследник
+* называет элемент своего списка: этим типом подсвеченный ждёт расширение,
+* через которое идёт выбор (`list.chooseItem` у ListBox, `select.chooseItem`
+* у Select). `any` в констрейнте — карта событий элемента инвариантна, и
+* точный `IControl` не принял бы элемент со своими событиями.
+*/
+var TListNavigationPlugin = class extends TBasePlugin {
+	/** Узел нужен только под слушатель клавиш — отсюда и тип. */
+	_element = null;
+	_bundles = null;
+	_engine = null;
+	_highlightedUid = null;
+	/** Подсветка видна: у подсвеченного элемента стоит отметка, а не одна позиция. */
+	_marked = false;
+	/**
+	* Шина элемента на позиции — за его набором `aria` база следит, пока
+	* позиция на нём: в наборе `id`, на который ведёт ссылка наследника.
+	* Подписка своя, а не `_listenTo`: элемент сменяется с позицией, и прежнего
+	* база отпускает сразу, а не при уничтожении.
+	*/
+	_watched = null;
+	install(ctx, options) {
+		super.install(ctx, options);
+		this._bundles = ctx.get(TCollectionBundlesPlugin) ?? null;
+		this._bundles?.events.on("bundle:registered", ({ uid, bundle }) => {
+			if (!this._marked || uid !== this._highlightedUid) return;
+			const plugin = bundle.get(TListItemPlugin);
+			if (plugin) plugin.highlighted = true;
+			this.onHighlightedMounted(uid);
+		});
+		ctx.get(TElementPlugin)?.events.on("ready", (element) => {
+			this._element = element;
+			element.addEventListener("keydown", this._onKeyDown);
+		});
+		ctx.get(TElementPlugin)?.events.on("removed", () => {
+			this._element?.removeEventListener("keydown", this._onKeyDown);
+			this._element = null;
+		});
+		this._bundles?.events.on("engine:bound", (engine) => {
+			this._engine = engine;
+			this.onEngineBound(engine);
+		});
+	}
+	/**
+	* Эмит собственных событий навигации — без приведения `this.events` к
+	* конкретной карте (см. `TEventSink` в `@soxa-ui/core`).
+	*
+	* Перекрывает сток базы, потому что у `TBasePlugin._sink` карта
+	* `TPluginEvents`, а `change:highlight` объявлен здесь: через базовый сток
+	* это имя не пройдёт. Свой сток заводит каждый уровень иерархии, который
+	* добавил событие; `TListKeyboardPlugin` и `TSelectKeyboardPlugin` к механике
+	* навигации ничего не добавляют и пользуются этим.
+	*
+	* Дженерик карту не заменяет. На `TEventSink<TEvents>` эмит упирается в
+	* `Parameters<TEvents['change:highlight']>` — тип, который на
+	* непроинстанцированном дженерике не разрешается. Вынести карту отдельным
+	* параметром базы тоже не выход: ошибка переезжает в базу, где этот параметр
+	* снова дженерик. Сток обязан назвать карту точно — тем он и отличается от
+	* `this.events`.
+	*
+	* Расширять карту базы безопасно: наследник не может сузить обработчик
+	* (`TEvents extends TListNavigationPluginEvents` сверяется контравариантно по
+	* аргументам), поэтому эмит базы через расширенный сток звучит.
+	*/
+	get _sink() {
+		return this.events;
+	}
+	destroy() {
+		this._element?.removeEventListener("keydown", this._onKeyDown);
+		this.clearHighlight();
+		this._watch(void 0);
+		this._element = null;
+		this._bundles = null;
+		this._engine = null;
+		super.destroy();
+	}
+	/** Элемент, на котором сейчас подсветка. */
+	get highlightedUid() {
+		return this._highlightedUid;
+	}
+	/** Коллекция появилась — можно синхронизировать начальное состояние. */
+	onEngineBound(_engine) {}
+	/**
+	* Видимая подсветка сменилась — тем же сообщением, что `change:highlight`.
+	* Здесь наследник ведёт ссылку `aria-activedescendant` или фокус; прокрутку
+	* к подсвеченному ведёт `TListScrollPlugin` по событию.
+	*
+	* `uid` — элемент, который получил отметку. Переход с элемента на элемент —
+	* один вызов, с новым: прежняя отметка снимается молча, а `null` между ними
+	* у меню увёл бы фокус на панель. `null` — отметки больше нет: подсветку
+	* сняли (`clearHighlight`) или позиция ушла без отметки (`trackHighlight`).
+	* Без отметки позиция переезжает молча: экран при этом не меняется.
+	*/
+	onHighlightChanged(_uid) {}
+	/**
+	* Подсвеченный элемент вошёл в документ — его набор зарегистрирован, а
+	* отметка ему возвращена. Так бывает в окне: подсветка ушла к элементу,
+	* которого окно не рисовало, и окно дорисовало его уже после
+	* `onHighlightChanged`. Здесь наследник берёт то, что есть только у
+	* смонтированного элемента: `id` для ссылки на него. Прокрутка к нему ждёт
+	* его набор сама (`TListScrollPlugin`).
+	*/
+	onHighlightedMounted(_uid) {}
+	/**
+	* Набор `aria` подсвеченного элемента сменился, пока отметка видна, — и
+	* вместе с ним мог смениться `id`, на который ведёт ссылка: `id` элемента в
+	* `TIdPlugin` задали, сменили или сняли. Здесь наследник, который ссылается
+	* на подсвеченный (`aria-activedescendant`), переписывает ссылку.
+	*
+	* Отдельный хук, а не повтор `onHighlightChanged`: подсветка не сменилась,
+	* и наследник не должен снова переносить фокус, а список — прокручивать к
+	* элементу. База следит за набором, а не за `change:id` `TIdPlugin`
+	* элемента: `id` в набор пишет плагин связок своим подписчиком того же
+	* события, и подписчик, пришедший раньше него, прочёл бы прежний.
+	*/
+	onHighlightedAriaChanged(_uid) {}
+	/**
+	* Показанные элементы — `batch.shown`, а не `batch.items`: ходить
+	* стрелками по тому, что отбор скрыл, нельзя. Среди них и недоступные: по
+	* ним наследник узнаёт, с чьей строки пришла клавиша, а `move` — откуда
+	* шагать.
+	*
+	* Тип — элемент списка наследника (`TItem`), а база опирается только на
+	* `IControl`: навигации нужны `uid`, `disabled`, `rendered` и `visible`.
+	* Элементы ListBox и опции Select общего предка ниже `IControl` не имеют, и
+	* раньше здесь стоял `IListItem` от несуществующего теперь компонента
+	* `TList`. Массив — только для чтения: это сама выборка коллекции, у
+	* коллекции с памятью выборки — запомненная.
+	*/
+	shown() {
+		return batchOf(this._engine)?.shown ?? [];
+	}
+	/**
+	* Элементы, по которым идёт навигация: показанные и доступные. Недоступные
+	* пропускаются у ListBox и у Select одинаково — правило не зависит ни от
+	* роли элемента, ни от модели фокуса.
+	*/
+	items() {
+		return this.shown().filter(isNavigable);
+	}
+	indexOf(uid) {
+		if (uid == null) return -1;
+		return this.items().findIndex((item) => item.uid === uid);
+	}
+	itemAt(index) {
+		return this.items()[index] ?? null;
+	}
+	itemByUid(uid) {
+		return this.items().find((item) => item.uid === uid) ?? null;
+	}
+	/**
+	* `id` подсвеченного элемента для ссылки `aria-activedescendant`, пока она
+	* повторяет экран: у элемента видна отметка и он в документе — его набор
+	* зарегистрирован. Иначе — `null`: позиция без отметки ссылкой не
+	* становится, а у элемента вне окна (`Virtual`) своего `id` нет, и
+	* оставшийся от прошлого монтирования указывал бы в пустоту.
+	*
+	* `id` — из набора `aria` элемента, а не с DOM-узла: узел, который знает
+	* реестр, — корень элемента, а `id` вместе со всей ARIA стоит на его строке.
+	* В набор его пишет `TOptionIdsPlugin` элемента, и ссылка берёт ровно то,
+	* что окажется в разметке. Куда её писать, решает наследник — туда, где
+	* фокус.
+	*/
+	highlightedId() {
+		const uid = this._highlightedUid;
+		if (uid === null || !this._marked) return null;
+		if (this._bundles?.getByUid(uid) === void 0) return null;
+		return this.itemByUid(uid)?.aria.get("id") ?? null;
+	}
+	/**
+	* Сдвигает подсветку к ближайшему доступному элементу в направлении шага.
+	* Навигация зациклена: с последнего элемента `↓` уводит на первый — так
+	* принято в списках и так делают Ark и Radix.
+	*
+	* Шаг отсчитывается от места подсветки среди показанных, а не среди
+	* доступных: подсвеченный элемент могли выключить, а ListBox ставит позицию
+	* и на выбранный элемент, который бывает выключен. Среди доступных такого
+	* нет, и стрелка увела бы на край списка. Так же ищут соседа
+	* `TTabsKeyboardPlugin` и `TTagsKeyboardPlugin`. Подсветки нет или её
+	* элемент не показан — шаг начинается с края.
+	*/
+	move(step) {
+		const shown = this.shown();
+		const from = shown.findIndex((item) => item.uid === this._highlightedUid);
+		if (from === -1) {
+			this.highlightEdge(step > 0 ? "first" : "last");
+			return;
+		}
+		const count = shown.length;
+		for (let offset = 1; offset <= count; offset++) {
+			const candidate = shown[((from + step * offset) % count + count) % count];
+			if (isNavigable(candidate)) {
+				this.highlight(candidate.uid);
+				return;
+			}
+		}
+	}
+	highlightEdge(edge) {
+		const items = this.items();
+		if (items.length === 0) return;
+		this.highlight(items[edge === "first" ? 0 : items.length - 1].uid);
+	}
+	/**
+	* Подсветить элемент: позиция плюс визуальная отметка — и сообщение о
+	* ней: `change:highlight` с элементом и соседями и хук наследника
+	* (`_announce`).
+	*
+	* Позиция может уже стоять на элементе без отметки — её ставит
+	* `trackHighlight` за выбором и со строки, с которой пришла клавиша. Тогда
+	* отметка встаёт на месте, и сообщение уходит так же: на экране подсветка
+	* появилась, хоть позиция и не сменилась. Так стрелка отмечает
+	* единственный доступный элемент — шаг по кругу приводит к нему же, — и
+	* список докручивает к нему. Подсвечивать нечего, только когда у элемента
+	* и позиция, и отметка: повтор молчит.
+	*/
+	highlight(uid) {
+		if (this._highlightedUid === uid && this._marked) return;
+		const oldValue = this._highlightPayload(this._marked ? this._highlightedUid : null);
+		if (this._highlightedUid !== uid) this._moveTo(uid);
+		const plugin = this.itemPlugin(uid);
+		if (plugin) plugin.highlighted = true;
+		this._marked = true;
+		this._announce(uid, oldValue);
+	}
+	/**
+	* Запомнить позицию, не отмечая элемент визуально.
+	*
+	* Нужно при синхронизации с выбором: список открылся на выбранном
+	* элементе, но подсветка навигации ещё не должна быть видна. Отметка, которая
+	* была видна, снимается, и об этом уходит сообщение с `null`
+	* (`change:highlight` и `onHighlightChanged(null)`): позиция осталась, а
+	* подсветки на экране нет. Без отметки позиция переезжает молча — ни
+	* события, ни хука: на экране ничего не сменилось.
+	*/
+	trackHighlight(uid) {
+		if (this._highlightedUid === uid) return;
+		const oldValue = this._highlightPayload(this._marked ? this._highlightedUid : null);
+		const marked = this._marked;
+		this._moveTo(uid);
+		if (marked) this._announce(null, oldValue);
+	}
+	/**
+	* Снять подсветку: позиции больше нет. Сообщение с `null` — только если
+	* отметка была видна: позиция без отметки уходит молча, как и переезжает.
+	*/
+	clearHighlight() {
+		if (this._highlightedUid == null) return;
+		const oldValue = this._highlightPayload(this._marked ? this._highlightedUid : null);
+		const marked = this._marked;
+		this.unmarkCurrent();
+		this._highlightedUid = null;
+		this._followPosition();
+		if (marked) this._announce(null, oldValue);
+	}
+	itemPlugin(uid) {
+		return this._bundles?.getByUid(uid)?.get(TListItemPlugin);
+	}
+	/**
+	* Позиция — на элемент: прежняя отметка снята, элемент закреплён в окне, и
+	* база следит за его набором. Событий здесь нет: ставить ли отметку и
+	* сообщать ли о ней, решает тот, кто позицию перенёс, — `highlight` или
+	* `trackHighlight`.
+	*/
+	_moveTo(uid) {
+		this.unmarkCurrent();
+		this._highlightedUid = uid;
+		this._followPosition();
+	}
+	/**
+	* За позицией — её элемент среди показанных: он закреплён в окне, и база
+	* следит за его набором `aria`. Позиции нет — закрепление снято, следить
+	* не за чем.
+	*/
+	_followPosition() {
+		const uid = this._highlightedUid;
+		const item = uid === null ? void 0 : this.shown().find((candidate) => candidate.uid === uid);
+		this._pin(item);
+		this._watch(item);
+	}
+	/**
+	* Видимая подсветка сменилась — одним сообщением обоим слушателям:
+	* `change:highlight` тем, кто слушает снаружи, и `onHighlightChanged`
+	* наследнику. Элемент — с соседями среди доступных; `null` — отметки
+	* больше нет, и соседей тоже.
+	*/
+	_highlightPayload(uid) {
+		const items = this.items();
+		const index = uid === null ? -1 : items.findIndex((item) => item.uid === uid);
+		const item = items[index] ?? null;
+		return {
+			item,
+			prevItem: item && (items[index - 1] ?? null),
+			nextItem: item && (items[index + 1] ?? null)
+		};
+	}
+	_announce(uid, oldValue) {
+		this._sink.emit("change:highlight", {
+			newValue: this._highlightPayload(uid),
+			oldValue
+		});
+		this.onHighlightChanged(uid);
+	}
+	/** Снимает визуальную отметку с текущего элемента. */
+	unmarkCurrent() {
+		this._marked = false;
+		if (this._highlightedUid == null) return;
+		const plugin = this.itemPlugin(this._highlightedUid);
+		if (plugin) plugin.highlighted = false;
+	}
+	/**
+	* Закрепить элемент позиции в окне коллекции, если оно есть: окно рисует
+	* его на месте, и подсветка, уведённая стрелкой за видимую полосу, не
+	* теряет узел. Позиции нет — закрепление снять.
+	*/
+	_pin(item) {
+		drawOf(this._engine)?.pin(HIGHLIGHT, item);
+	}
+	/**
+	* Следить за набором `aria` элемента на позиции, а прежнего — отпустить.
+	* Элемента нет — не следить ни за чьим.
+	*/
+	_watch(item) {
+		const bus = item?.events ?? null;
+		if (bus === this._watched) return;
+		this._watched?.off("change:aria", this._onHighlightedAria);
+		this._watched = bus;
+		bus?.on("change:aria", this._onHighlightedAria);
+	}
+	/** Набор элемента на позиции сменился: ссылке он важен, только пока отметка видна. */
+	_onHighlightedAria = () => {
+		if (this._marked && this._highlightedUid !== null) this.onHighlightedAriaChanged(this._highlightedUid);
+	};
+	_onKeyDown = (event) => {
+		this.onKeyDown(event);
+	};
+};
+//#endregion
+export { TListNavigationPlugin };

package/dist/custom/list/navigation/types.d.ts

@@ -0,0 +1,25 @@
+import type { TValuePayload } from '@soxa-ui/core';
+import type { IControl } from '@soxa-ui/core';
+import type { TPluginEvents } from '../../../base';
+/**
+ * Видимая подсветка списка — аргумент `change:highlight`.
+ *
+ * `item` — элемент, на котором встала отметка, в том числе на месте, где
+ * позиция уже стояла без неё; `null` — видимой отметки больше нет: подсветку
+ * сняли или позиция ушла без отметки. Позиция без отметки события не шлёт.
+ *
+ * Соседи — доступные элементы до и после подсвеченного, тем порядком, каким по
+ * ним ходят стрелки; у края и без подсветки — `null`. Навигации и прокрутке
+ * они не нужны: это данные подписчику снаружи, который знает о подсветке
+ * только из события (`keyboard:change:highlight` у Select).
+ */
+export type THighlightPayload = {
+    item: IControl | null;
+    prevItem: IControl | null;
+    nextItem: IControl | null;
+};
+export type TListNavigationPluginEvents = TPluginEvents & {
+    'change:highlight': (payload: TValuePayload<THighlightPayload>) => void;
+};
+/** Край списка для `highlightEdge`. */
+export type TListEdge = 'first' | 'last';

package/dist/custom/list/newly-selected.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Элемент, за которым список следует после смены выбора, — тот, что стал
+ * выбранным: первый из выбранных (`selected`, по порядку выбора), чья отметка
+ * сменилась (`changed` — второй аргумент `change:selection`). `undefined` —
+ * выбранным не стал никто: выбор сняли или только переставили, и следовать не
+ * за чем.
+ *
+ * Не первый выбранный: в `multiple` выбранных несколько, и выбор клавишей или
+ * кликом уводил бы подсветку и прокрутку к первому из них, а не к элементу,
+ * который выбрали сейчас. В `single` выбранный один — он и стал выбранным.
+ * Значение снаружи — по тому же правилу: список встаёт на новый выбранный.
+ *
+ * Одно на клавиатуру ListBox (`TListKeyboardPlugin`) и прокрутку списка
+ * (`TListScrollPlugin`): элемент оба ищут одним правилом, и подсветка не
+ * встанет на одном элементе, пока прокрутка уезжает к другому.
+ */
+export declare function newlySelected<TItem>(selected: readonly TItem[], changed: ReadonlySet<TItem>): TItem | undefined;

package/dist/custom/list/newly-selected.js

@@ -0,0 +1,22 @@
+//#region src/custom/list/newly-selected.ts
+/**
+* Элемент, за которым список следует после смены выбора, — тот, что стал
+* выбранным: первый из выбранных (`selected`, по порядку выбора), чья отметка
+* сменилась (`changed` — второй аргумент `change:selection`). `undefined` —
+* выбранным не стал никто: выбор сняли или только переставили, и следовать не
+* за чем.
+*
+* Не первый выбранный: в `multiple` выбранных несколько, и выбор клавишей или
+* кликом уводил бы подсветку и прокрутку к первому из них, а не к элементу,
+* который выбрали сейчас. В `single` выбранный один — он и стал выбранным.
+* Значение снаружи — по тому же правилу: список встаёт на новый выбранный.
+*
+* Одно на клавиатуру ListBox (`TListKeyboardPlugin`) и прокрутку списка
+* (`TListScrollPlugin`): элемент оба ищут одним правилом, и подсветка не
+* встанет на одном элементе, пока прокрутка уезжает к другому.
+*/
+function newlySelected(selected, changed) {
+	return selected.find((item) => changed.has(item));
+}
+//#endregion
+export { newlySelected };

package/dist/custom/list/option-ids/index.d.ts

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

package/dist/custom/list/option-ids/option-ids.plugin.d.ts

@@ -0,0 +1,29 @@
+import { TBasePlugin } from '../../../base';
+import type { IPluginContext } from '../../../base';
+/**
+ * TOptionIdsPlugin — `id` элемента списка в документе: опции Select и элемента
+ * ListBox. На него ссылается `aria-activedescendant` узла с фокусом, пока
+ * элемент подсвечен: у Select — поля комбобокса, у ListBox — узла списка.
+ *
+ * Плагин один на оба списка: `id` от роли элемента и модели фокуса не зависит,
+ * а копия под каждый компонент стала бы вторым путём к тому же знанию. Чей
+ * узел ссылается на элемент, решает клавиатура списка — наследник
+ * `TListNavigationPlugin`.
+ *
+ * Пишется в `aria` элемента — набор его строки, — и клавиатура списка берёт
+ * его оттуда же (`highlightedId` навигации): ссылка получает ровно то, что
+ * стоит в разметке.
+ *
+ * `id`, заданный приложением (`TIdPlugin` элемента), главнее: он и встаёт на
+ * строку, и на него ведёт ссылка. Сменили — плагин переписывает набор, и
+ * клавиатура списка ведёт ссылку за ним (она следит за набором подсвеченного
+ * элемента). Сняли — снова `id` от монтирования.
+ *
+ * Без него — `id` от монтирования элемента (`createId`), а не от экземпляра.
+ * Элемент из данных рисуется с готовым экземпляром (`ctrl`), и его конструктор
+ * адаптер не зовёт, а монтирование у него своё. Пишется при установке,
+ * синхронно, — `id` есть уже в первой (и серверной) отрисовке.
+ */
+export declare class TOptionIdsPlugin extends TBasePlugin {
+    install(ctx: IPluginContext): void;
+}

package/dist/custom/list/option-ids/option-ids.plugin.js

@@ -0,0 +1,43 @@
+import { TBasePlugin } from "../../../base/base.class.js";
+import { TIdPlugin } from "../../id/id.plugin.js";
+//#region src/custom/list/option-ids/option-ids.plugin.ts
+/**
+* TOptionIdsPlugin — `id` элемента списка в документе: опции Select и элемента
+* ListBox. На него ссылается `aria-activedescendant` узла с фокусом, пока
+* элемент подсвечен: у Select — поля комбобокса, у ListBox — узла списка.
+*
+* Плагин один на оба списка: `id` от роли элемента и модели фокуса не зависит,
+* а копия под каждый компонент стала бы вторым путём к тому же знанию. Чей
+* узел ссылается на элемент, решает клавиатура списка — наследник
+* `TListNavigationPlugin`.
+*
+* Пишется в `aria` элемента — набор его строки, — и клавиатура списка берёт
+* его оттуда же (`highlightedId` навигации): ссылка получает ровно то, что
+* стоит в разметке.
+*
+* `id`, заданный приложением (`TIdPlugin` элемента), главнее: он и встаёт на
+* строку, и на него ведёт ссылка. Сменили — плагин переписывает набор, и
+* клавиатура списка ведёт ссылку за ним (она следит за набором подсвеченного
+* элемента). Сняли — снова `id` от монтирования.
+*
+* Без него — `id` от монтирования элемента (`createId`), а не от экземпляра.
+* Элемент из данных рисуется с готовым экземпляром (`ctrl`), и его конструктор
+* адаптер не зовёт, а монтирование у него своё. Пишется при установке,
+* синхронно, — `id` есть уже в первой (и серверной) отрисовке.
+*/
+var TOptionIdsPlugin = class extends TBasePlugin {
+	install(ctx) {
+		super.install(ctx);
+		const item = ctx.getInstance();
+		if (!item) return;
+		const idPlugin = ctx.get(TIdPlugin);
+		const mountId = ctx.createId("option");
+		const write = () => {
+			item.aria.add("id", idPlugin?.id ?? mountId);
+		};
+		write();
+		idPlugin?.events.on("change:id", write);
+	}
+};
+//#endregion
+export { TOptionIdsPlugin };

package/dist/custom/list/row.d.ts

@@ -0,0 +1,50 @@
+import type { TCollectionElements } from '../collection';
+/**
+ * Строка элемента коллекции — узел, который держит фокус внутри узла
+ * элемента. `null` — элемента нет в документе.
+ *
+ * Одна на клавиатуру ListBox (с чьей строки пришла клавиша) и меню (куда
+ * ставить фокус подсвеченному пункту): строку оба ищут одним правилом.
+ */
+export declare function rowOf(elements: TCollectionElements | null, uid: string | number): Element | null;
+/**
+ * Строка внутри узла элемента — тем же правилом, что `rowOf`, когда узел уже
+ * на руках: свой корень у пункта с подменю — узел пункта в меню над ним.
+ *
+ * Она же узел фокуса элемента — ListBox.Item и пунктов меню (`focusTarget`
+ * плагина действия в дескрипторе): запись `focused = true` ставит фокус на
+ * строку, а не на обёртку элемента. Опции Select её не дают: у комбобокса
+ * фокус остаётся на поле. Tags.Item — тоже: у строки тега без выбора
+ * `tabindex` нет, и узел фокуса тега — его остановка (`tagStopIn`).
+ */
+export declare function rowIn(node: Element | null): Element | null;
+/**
+ * Узел списка ListBox — ребёнок его корня с ролью `listbox`. `null` — корня
+ * нет или узла списка в нём нет.
+ *
+ * Он же узел фокуса ListBox: запись `focused = true` ставит фокус на него, а
+ * не на поле или кнопку шапки (`focusTarget` плагина действия в дескрипторе).
+ */
+export declare function listOf(root: Element | null): Element | null;
+/**
+ * Узел списка, в котором стоит элемент, — ближайший предок с ролью
+ * `listbox`: узел списка ListBox и список панели Select. `null` — элемент не в
+ * списке.
+ *
+ * Не родитель элемента: у элемента группы (`ListBox.Group`, `Select.Group`)
+ * родитель — группа, а предел строк держит список вокруг групп.
+ */
+export declare function closestList(element: Element): Element | null;
+/**
+ * Прокрутка списка, в котором стоит элемент, — ближайший предок его узла,
+ * который прокручивается по вертикали, не выше узла с ролью списка (`listbox`,
+ * `menu`). `null` — своей прокрутки у списка нет: элементы помещаются, список
+ * скрыт или прокручивает его только страница.
+ *
+ * У ListBox и Select это сам узел с ролью `listbox` — ему предел строк ставит
+ * `TListHeightPlugin`. У меню прокручивается список пунктов внутри панели с
+ * ролью `menu` (`.so-menu__list`), и `closestList` его не находит. Не
+ * родитель элемента: у элемента группы родитель — группа, а прокручивается
+ * список вокруг групп.
+ */
+export declare function scrollContainerOf(element: Element): HTMLElement | null;