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

package/dist/custom/list/row.js

@@ -0,0 +1,99 @@
+import { isScrollable } from "../../utils/scrollParent.js";
+//#region src/custom/list/row.ts
+/**
+* Строка элемента внутри его узла. Корень элемента — обёртка для темы, а фокус
+* держит вложенная строка: на ней набор `aria` элемента, и в него коллекция
+* пишет `tabindex="-1"` (ListBox, меню). Из-за этого атрибута строка и может
+* держать фокус. Строка — первый узел элемента с этим атрибутом: роль у неё
+* своя у каждого списка (`option` против `menuitem`), а `tabindex` — общий.
+*/
+var ROW_SELECTOR = "[tabindex]";
+/**
+* Узел списка ListBox внутри его корня. Корень — рамка для темы: в нём рядом
+* со списком стоят шапка и подвал, а в `listbox` ARIA пускает только опции.
+* Фокус, клавиатуру и набор `aria` списка держит его узел — ребёнок корня с
+* ролью из этого набора.
+*
+* По роли, а не по `tabindex`, как строка: шапка и подвал — тоже дети корня, и
+* в них бывают свои остановки Tab (кнопка на `div` пишет себе `tabindex`), а
+* роль `listbox` среди детей корня — только у узла списка. И не по классу
+* темы: правило одно на клавиатуру списка (с чьего узла пришла клавиша),
+* календарь (куда ставить фокус списку панели выбора), узел фокуса ListBox
+* (`focusTarget` плагина действия), предел строк (`closestList`) и границу
+* прокрутки списка (`scrollContainerOf`): у ListBox и у Select блок класса
+* свой, а роль списка одна.
+*/
+var LIST_SELECTOR = "[role=\"listbox\"]";
+/**
+* Граница прокрутки списка — узел с ролью списка: `listbox` у ListBox и
+* Select, `menu` у панели меню и подменю. Выше него прокрутка списку не
+* принадлежит: там панель, страница или меню над подменю.
+*/
+var LIST_BOUNDARY_SELECTOR = `${LIST_SELECTOR}, [role="menu"]`;
+/**
+* Строка элемента коллекции — узел, который держит фокус внутри узла
+* элемента. `null` — элемента нет в документе.
+*
+* Одна на клавиатуру ListBox (с чьей строки пришла клавиша) и меню (куда
+* ставить фокус подсвеченному пункту): строку оба ищут одним правилом.
+*/
+function rowOf(elements, uid) {
+	return rowIn(elements?.getElementByUid(uid) ?? null);
+}
+/**
+* Строка внутри узла элемента — тем же правилом, что `rowOf`, когда узел уже
+* на руках: свой корень у пункта с подменю — узел пункта в меню над ним.
+*
+* Она же узел фокуса элемента — ListBox.Item и пунктов меню (`focusTarget`
+* плагина действия в дескрипторе): запись `focused = true` ставит фокус на
+* строку, а не на обёртку элемента. Опции Select её не дают: у комбобокса
+* фокус остаётся на поле. Tags.Item — тоже: у строки тега без выбора
+* `tabindex` нет, и узел фокуса тега — его остановка (`tagStopIn`).
+*/
+function rowIn(node) {
+	return node?.querySelector(ROW_SELECTOR) ?? null;
+}
+/**
+* Узел списка ListBox — ребёнок его корня с ролью `listbox`. `null` — корня
+* нет или узла списка в нём нет.
+*
+* Он же узел фокуса ListBox: запись `focused = true` ставит фокус на него, а
+* не на поле или кнопку шапки (`focusTarget` плагина действия в дескрипторе).
+*/
+function listOf(root) {
+	if (!root) return null;
+	for (const child of root.children) if (child.matches(LIST_SELECTOR)) return child;
+	return null;
+}
+/**
+* Узел списка, в котором стоит элемент, — ближайший предок с ролью
+* `listbox`: узел списка ListBox и список панели Select. `null` — элемент не в
+* списке.
+*
+* Не родитель элемента: у элемента группы (`ListBox.Group`, `Select.Group`)
+* родитель — группа, а предел строк держит список вокруг групп.
+*/
+function closestList(element) {
+	return element.closest(LIST_SELECTOR);
+}
+/**
+* Прокрутка списка, в котором стоит элемент, — ближайший предок его узла,
+* который прокручивается по вертикали, не выше узла с ролью списка (`listbox`,
+* `menu`). `null` — своей прокрутки у списка нет: элементы помещаются, список
+* скрыт или прокручивает его только страница.
+*
+* У ListBox и Select это сам узел с ролью `listbox` — ему предел строк ставит
+* `TListHeightPlugin`. У меню прокручивается список пунктов внутри панели с
+* ролью `menu` (`.so-menu__list`), и `closestList` его не находит. Не
+* родитель элемента: у элемента группы родитель — группа, а прокручивается
+* список вокруг групп.
+*/
+function scrollContainerOf(element) {
+	for (let current = element.parentElement; current; current = current.parentElement) {
+		if (isScrollable(current, "y")) return current;
+		if (current.matches(LIST_BOUNDARY_SELECTOR)) return null;
+	}
+	return null;
+}
+//#endregion
+export { closestList, listOf, rowIn, rowOf, scrollContainerOf };

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

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

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

@@ -0,0 +1,132 @@
+import { TBasePlugin } from '../../../base';
+import type { IPluginContext } from '../../../base';
+import type { IListScrollPluginOptions, TListScrollPluginEvents } from './types';
+/**
+ * TListScrollPlugin — прокрутка списка к элементу: ListBox, Select, меню и
+ * подменю (и всего, что построено на них, — панели выбора месяца и года
+ * Calendar это ListBox).
+ *
+ * **Список докручивает к элементу ровно за двумя фактами** — элементу задали
+ * значение и на элементе встала видимая подсветка. Источник механизму
+ * безразличен: клик по строке, Enter и пробел, значение снаружи и
+ * монтирование — значение; стрелки, Home и End, буквы, наведение в меню и
+ * открытие с клавиатуры — подсветка. Флагов «откуда пришло» нет.
+ *
+ * - **Значение** — `change:selection` расширения выбора: к элементу, который
+ *   стал выбранным (`newlySelected`), тем же правилом, что позиция клавиатуры
+ *   ListBox. Не к первому выбранному: в `multiple` выбор видимого элемента
+ *   уводил бы список к первому выбранному. Снятие выбора не крутит, а цель,
+ *   с которой значение сняли до кадра, отменяет. У меню выбор — отметка
+ *   флажков и переключателей. Двигается только сам список (`revealValue`):
+ *   страница от смены значения не прыгает.
+ * - **Подсветка** — `change:highlight` навигации списка, класс которой задаёт
+ *   опция `navigation` (`IListScrollPluginOptions`): событие сообщает о видимой
+ *   отметке, и позиция без неё — за выбором, на строке, с которой ушёл Tab, —
+ *   список не двигает. Подсвеченный элемент встаёт ближайшим краем
+ *   (`scrollIntoView` с `block: 'nearest'`), как от фокуса: при нужде и
+ *   страница. Подсветку сняли — её ждущая цель отменена, цель значения нет.
+ *
+ * Центр всегда не годится — клик тоже значение, и срезанная строка уехала бы
+ * из-под курсора; край всегда — тоже: дальний выбранный терял бы контекст.
+ *
+ * **Цель одна — последняя**, и прокрутка к ней — в следующем кадре: узел
+ * элемента, который окно дорисовывает, и панель, открытую той же клавишей,
+ * адаптер рисует после обработчика. Кадр свой и отменяемый: новая цель, снятая
+ * подсветка, снятие корня и уничтожение плагина отменяют его. Кадр
+ * планируется, только пока у плагина есть узел корня (`ready` … `removed`):
+ * сборка вместе с подписками идёт и на сервере, где нет ни узла, ни
+ * `requestAnimationFrame`.
+ *
+ * **Начальная прокрутка** — список открывается на первом выбранном. Ей нужны
+ * и узел корня, и движок, а приходят они порознь: движок привязывают при
+ * сборке, узел корня плагин получает кадром после монтирования (`ready`).
+ * Поэтому её зовут оба события, а срабатывает то, что пришло вторым, — в
+ * жизни это `ready`. Попытка — сразу, без кадра: к `ready` узлы элементов уже
+ * привязаны, а строки измерены и предел строк поставлен (`TListHeightPlugin`
+ * мерит их на том же `ready` и стоит в наборе раньше). Она мгновенная и при
+ * `smooth`: анимировать не от чего, а плавный проход перерисовывал бы окно на
+ * каждом кадре. Список скрыт — попытка ждёт его показа (ниже, «Скрытый
+ * список»).
+ *
+ * **Скрытый список** — закрытая панель Select, ListBox в скрытой вкладке или
+ * поповере — не меряется: у строк нет высоты, а у списка своей прокрутки.
+ * Поэтому, пока строки не измерены (`measured` плагина высоты), любая цель
+ * закреплена в окне и ждёт, а дождавшаяся идёт мгновенно, как начальная:
+ * анимировать не от чего. Строки измерились — ждущая цель сразу, в том же
+ * колбэке (`change:measured`): плагин высоты сообщает о замере после записи
+ * предела, и список встаёт уже в пределе строк. Список спрятали, а цели нет —
+ * её место занимает первый выбранный: при каждом показе список открывается на
+ * нём, как нативный `<select>`, с окном и без. Так же при показе, если цель,
+ * ждавшую его, сняли: с элемента сняли выбор или подсветку. Панель, открытую с
+ * клавиатуры, ведёт подсветка — она новее, а цель одна, последняя. Показ — факт
+ * раскладки, а не открытия панели: он общий у Select и ListBox в скрытой
+ * вкладке, и ни подписки на `open`, ни веток «клик или клавиша» здесь нет. Без
+ * плагина высоты (меню) строки считаются измеренными, и закрытое меню
+ * открывается сверху.
+ *
+ * **Цели нет в документе** — окно (обёртка `Virtual`) её не нарисовало. Тогда
+ * плагин закрепляет её своей причиной в рисовании коллекции (`draw.pin`), и
+ * окно дорисовывает её после замера, а прокрутка ждёт, когда набор цели
+ * зарегистрируют, и идёт кадром позже: узел адаптер привязывает после
+ * регистрации. Закрепление снимает следующая цель или отмена, а не сама
+ * прокрутка: окно перемеряется кадром позже, и без закрепления оно на этот
+ * кадр убрало бы цель, к которой только что прокрутили, — список мигнул бы
+ * распорками. Скрытый список окно не мерит, и цель в нём ждёт и замера строк,
+ * и своего набора — в каком порядке они ни придут.
+ *
+ * Как прокручивать, решает `scrollBehavior` владельца (`IList`): свойством
+ * владеет ядро, плагин его только читает, в момент прокрутки. У меню свойства
+ * нет — умолчание списков. `none` — прокрутки нет, `instant` — сразу,
+ * `smooth` — плавно, только пока режим движения библиотеки движение не убрал
+ * (`smoothScrollBehavior`).
+ */
+export declare class TListScrollPlugin extends TBasePlugin<any, TListScrollPluginEvents> {
+    /** Узел корня: без него крутить нечего — на сервере, до `ready`, после `removed`. */
+    private _root;
+    private _owner;
+    private _bundles;
+    private _elements;
+    /** Плагин высоты: измерены ли строки. У меню его нет. */
+    private _height;
+    /** Куда прокрутить — одна цель, последняя; `null` — некуда. */
+    private _target;
+    /** Кадр с прокруткой к цели; `null` — кадр не запланирован. */
+    private _frame;
+    install(ctx: IPluginContext, options?: IListScrollPluginOptions): void;
+    destroy(): void;
+    /**
+     * Значение — к элементу, который стал выбранным (`newlySelected`). Значение
+     * сняли с цели, к которой ещё не прокрутили, — цель отменена: крутить к
+     * невыбранному незачем.
+     */
+    private _subscribeToEngine;
+    /**
+     * Начальная прокрутка к первому выбранному — когда есть и узел корня, и
+     * движок, и когда список спрятали или показали, а цели нет. Попытка сразу и
+     * мгновенно; выбранного нет — прежняя цель отменена: она от прежнего движка.
+     */
+    private _revealSelected;
+    /** Случился факт: цель — его элемент, прокрутка — в следующем кадре. */
+    private _follow;
+    /** Новая цель вместо прежней: кадр и закрепление прежней сняты. */
+    private _aim;
+    /** Цели больше нет: кадр отменён, закрепление снято. */
+    private _drop;
+    /** Прокрутка к цели — в следующем кадре, только при узле корня. */
+    private _schedule;
+    private _cancel;
+    /**
+     * Прокрутить к цели — по правилу её факта. Строки не измерены — список
+     * скрыт или только что показан: закрепить цель, сделать её мгновенной и
+     * ждать замера (`change:measured`). Узла у цели нет — окно её не
+     * нарисовало: закрепить и ждать, когда зарегистрируют её набор.
+     * Прокрутили — цель исполнена, а закрепление остаётся до следующей цели
+     * (см. описание класса).
+     *
+     * `scrollIntoView` вызывается, если он есть: в jsdom его нет. Прокрутка —
+     * удобство, а не часть контракта.
+     */
+    private _attempt;
+    /** Рисование коллекции — у списков в окне; у меню его нет, и закреплять нечего. */
+    private _draw;
+}

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

@@ -0,0 +1,286 @@
+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 { scrollContainerOf } from "../row.js";
+import { TListHeightPlugin } from "../height/height.plugin.js";
+import { newlySelected } from "../newly-selected.js";
+import { smoothScrollBehavior } from "../../../motion/motion.js";
+import { LIST_DEFAULTS, drawOf, selectionOf } from "@soxa-ui/core";
+//#region src/custom/list/scroll/scroll.plugin.ts
+/** Причина закрепления цели в окне коллекции — к ней крутит прокрутка. */
+var SCROLL = "scroll";
+/**
+* Допуск на субпиксельное округление: край, вышедший из окна списка на
+* полпикселя, — ещё в окне. Список встаёт на целый пиксель, а края элементов
+* дробные.
+*/
+var TOLERANCE = .5;
+/**
+* Значение двигает только прокрутку самого списка, страница стоит. Элемент
+* виден целиком — ничего; частью — до ближайшего края окна списка: срезанная
+* строка после клика встаёт целиком и остаётся под курсором; не виден вовсе —
+* в середину окна: дальний выбранный (монтирование, список лет) виден вместе с
+* соседями. Окно — паддинг-бокс прокрутки. Своей прокрутки у списка нет
+* (`scrollContainerOf`) — ничего: элементы помещаются или список скрыт.
+*/
+function revealValue(node, behavior) {
+	const container = scrollContainerOf(node);
+	if (!container) return;
+	const top = container.getBoundingClientRect().top + container.clientTop;
+	const bottom = top + container.clientHeight;
+	const rect = node.getBoundingClientRect();
+	if (rect.top >= top - TOLERANCE && rect.bottom <= bottom + TOLERANCE) return;
+	let shift = rect.top + rect.height / 2 - (top + bottom) / 2;
+	if (rect.bottom > top && rect.top < bottom) shift = rect.top < top ? rect.top - top : rect.bottom - bottom;
+	container.scrollTo({
+		top: container.scrollTop + shift,
+		behavior
+	});
+}
+/**
+* TListScrollPlugin — прокрутка списка к элементу: ListBox, Select, меню и
+* подменю (и всего, что построено на них, — панели выбора месяца и года
+* Calendar это ListBox).
+*
+* **Список докручивает к элементу ровно за двумя фактами** — элементу задали
+* значение и на элементе встала видимая подсветка. Источник механизму
+* безразличен: клик по строке, Enter и пробел, значение снаружи и
+* монтирование — значение; стрелки, Home и End, буквы, наведение в меню и
+* открытие с клавиатуры — подсветка. Флагов «откуда пришло» нет.
+*
+* - **Значение** — `change:selection` расширения выбора: к элементу, который
+*   стал выбранным (`newlySelected`), тем же правилом, что позиция клавиатуры
+*   ListBox. Не к первому выбранному: в `multiple` выбор видимого элемента
+*   уводил бы список к первому выбранному. Снятие выбора не крутит, а цель,
+*   с которой значение сняли до кадра, отменяет. У меню выбор — отметка
+*   флажков и переключателей. Двигается только сам список (`revealValue`):
+*   страница от смены значения не прыгает.
+* - **Подсветка** — `change:highlight` навигации списка, класс которой задаёт
+*   опция `navigation` (`IListScrollPluginOptions`): событие сообщает о видимой
+*   отметке, и позиция без неё — за выбором, на строке, с которой ушёл Tab, —
+*   список не двигает. Подсвеченный элемент встаёт ближайшим краем
+*   (`scrollIntoView` с `block: 'nearest'`), как от фокуса: при нужде и
+*   страница. Подсветку сняли — её ждущая цель отменена, цель значения нет.
+*
+* Центр всегда не годится — клик тоже значение, и срезанная строка уехала бы
+* из-под курсора; край всегда — тоже: дальний выбранный терял бы контекст.
+*
+* **Цель одна — последняя**, и прокрутка к ней — в следующем кадре: узел
+* элемента, который окно дорисовывает, и панель, открытую той же клавишей,
+* адаптер рисует после обработчика. Кадр свой и отменяемый: новая цель, снятая
+* подсветка, снятие корня и уничтожение плагина отменяют его. Кадр
+* планируется, только пока у плагина есть узел корня (`ready` … `removed`):
+* сборка вместе с подписками идёт и на сервере, где нет ни узла, ни
+* `requestAnimationFrame`.
+*
+* **Начальная прокрутка** — список открывается на первом выбранном. Ей нужны
+* и узел корня, и движок, а приходят они порознь: движок привязывают при
+* сборке, узел корня плагин получает кадром после монтирования (`ready`).
+* Поэтому её зовут оба события, а срабатывает то, что пришло вторым, — в
+* жизни это `ready`. Попытка — сразу, без кадра: к `ready` узлы элементов уже
+* привязаны, а строки измерены и предел строк поставлен (`TListHeightPlugin`
+* мерит их на том же `ready` и стоит в наборе раньше). Она мгновенная и при
+* `smooth`: анимировать не от чего, а плавный проход перерисовывал бы окно на
+* каждом кадре. Список скрыт — попытка ждёт его показа (ниже, «Скрытый
+* список»).
+*
+* **Скрытый список** — закрытая панель Select, ListBox в скрытой вкладке или
+* поповере — не меряется: у строк нет высоты, а у списка своей прокрутки.
+* Поэтому, пока строки не измерены (`measured` плагина высоты), любая цель
+* закреплена в окне и ждёт, а дождавшаяся идёт мгновенно, как начальная:
+* анимировать не от чего. Строки измерились — ждущая цель сразу, в том же
+* колбэке (`change:measured`): плагин высоты сообщает о замере после записи
+* предела, и список встаёт уже в пределе строк. Список спрятали, а цели нет —
+* её место занимает первый выбранный: при каждом показе список открывается на
+* нём, как нативный `<select>`, с окном и без. Так же при показе, если цель,
+* ждавшую его, сняли: с элемента сняли выбор или подсветку. Панель, открытую с
+* клавиатуры, ведёт подсветка — она новее, а цель одна, последняя. Показ — факт
+* раскладки, а не открытия панели: он общий у Select и ListBox в скрытой
+* вкладке, и ни подписки на `open`, ни веток «клик или клавиша» здесь нет. Без
+* плагина высоты (меню) строки считаются измеренными, и закрытое меню
+* открывается сверху.
+*
+* **Цели нет в документе** — окно (обёртка `Virtual`) её не нарисовало. Тогда
+* плагин закрепляет её своей причиной в рисовании коллекции (`draw.pin`), и
+* окно дорисовывает её после замера, а прокрутка ждёт, когда набор цели
+* зарегистрируют, и идёт кадром позже: узел адаптер привязывает после
+* регистрации. Закрепление снимает следующая цель или отмена, а не сама
+* прокрутка: окно перемеряется кадром позже, и без закрепления оно на этот
+* кадр убрало бы цель, к которой только что прокрутили, — список мигнул бы
+* распорками. Скрытый список окно не мерит, и цель в нём ждёт и замера строк,
+* и своего набора — в каком порядке они ни придут.
+*
+* Как прокручивать, решает `scrollBehavior` владельца (`IList`): свойством
+* владеет ядро, плагин его только читает, в момент прокрутки. У меню свойства
+* нет — умолчание списков. `none` — прокрутки нет, `instant` — сразу,
+* `smooth` — плавно, только пока режим движения библиотеки движение не убрал
+* (`smoothScrollBehavior`).
+*/
+var TListScrollPlugin = class extends TBasePlugin {
+	/** Узел корня: без него крутить нечего — на сервере, до `ready`, после `removed`. */
+	_root = null;
+	_owner = null;
+	_bundles = null;
+	_elements = null;
+	/** Плагин высоты: измерены ли строки. У меню его нет. */
+	_height = null;
+	/** Куда прокрутить — одна цель, последняя; `null` — некуда. */
+	_target = null;
+	/** Кадр с прокруткой к цели; `null` — кадр не запланирован. */
+	_frame = null;
+	install(ctx, options) {
+		super.install(ctx, options);
+		this._owner = ctx.getInstance();
+		this._bundles = ctx.get(TCollectionBundlesPlugin) ?? null;
+		this._elements = ctx.get(TCollectionElements) ?? null;
+		this._height = ctx.get(TListHeightPlugin) ?? null;
+		const elementPlugin = ctx.get(TElementPlugin);
+		elementPlugin?.events.on("ready", (element) => {
+			this._root = element;
+			this._revealSelected();
+		});
+		elementPlugin?.events.on("removed", () => {
+			this._root = null;
+			this._drop();
+		});
+		this._bundles?.events.on("engine:bound", (engine) => {
+			this._subscribeToEngine(engine);
+			this._revealSelected();
+		});
+		this._bundles?.events.on("bundle:registered", ({ uid }) => {
+			if (uid === this._target?.item.uid) this._schedule();
+		});
+		this._height?.events.on("change:measured", ({ newValue: measured }) => {
+			if (!this._target) this._revealSelected();
+			else if (measured) this._attempt();
+		});
+		(options?.navigation ? ctx.get(options.navigation) : void 0)?.events.on("change:highlight", ({ newValue: { item } }) => {
+			if (item) this._follow(item, "highlight");
+			else if (this._target?.fact === "highlight") this._drop();
+		});
+	}
+	destroy() {
+		this._drop();
+		this._root = null;
+		this._owner = null;
+		this._bundles = null;
+		this._elements = null;
+		this._height = null;
+		super.destroy();
+	}
+	/**
+	* Значение — к элементу, который стал выбранным (`newlySelected`). Значение
+	* сняли с цели, к которой ещё не прокрутили, — цель отменена: крутить к
+	* невыбранному незачем.
+	*/
+	_subscribeToEngine(engine) {
+		this._listenTo(selectionOf(engine)?.events, "change:selection", (items, changed) => {
+			const item = newlySelected(items, changed);
+			const target = this._target;
+			if (item) this._follow(item, "value");
+			else if (target?.fact === "value" && !items.includes(target.item)) this._drop();
+		});
+	}
+	/**
+	* Начальная прокрутка к первому выбранному — когда есть и узел корня, и
+	* движок, и когда список спрятали или показали, а цели нет. Попытка сразу и
+	* мгновенно; выбранного нет — прежняя цель отменена: она от прежнего движка.
+	*/
+	_revealSelected() {
+		const engine = this._bundles?.engine;
+		if (!this._root || !engine) return;
+		const [selected] = selectionOf(engine)?.selected ?? [];
+		if (!selected) {
+			this._drop();
+			return;
+		}
+		this._aim({
+			item: selected,
+			fact: "value",
+			instant: true
+		});
+		this._attempt();
+	}
+	/** Случился факт: цель — его элемент, прокрутка — в следующем кадре. */
+	_follow(item, fact) {
+		if (!this._root) return;
+		this._aim({
+			item,
+			fact,
+			instant: false
+		});
+		this._schedule();
+	}
+	/** Новая цель вместо прежней: кадр и закрепление прежней сняты. */
+	_aim(target) {
+		this._drop();
+		this._target = target;
+	}
+	/** Цели больше нет: кадр отменён, закрепление снято. */
+	_drop() {
+		this._cancel();
+		this._target = null;
+		this._draw()?.pin(SCROLL, void 0);
+	}
+	/** Прокрутка к цели — в следующем кадре, только при узле корня. */
+	_schedule() {
+		this._cancel();
+		if (!this._root) return;
+		this._frame = requestAnimationFrame(() => {
+			this._frame = null;
+			this._attempt();
+		});
+	}
+	_cancel() {
+		if (this._frame === null) return;
+		cancelAnimationFrame(this._frame);
+		this._frame = null;
+	}
+	/**
+	* Прокрутить к цели — по правилу её факта. Строки не измерены — список
+	* скрыт или только что показан: закрепить цель, сделать её мгновенной и
+	* ждать замера (`change:measured`). Узла у цели нет — окно её не
+	* нарисовало: закрепить и ждать, когда зарегистрируют её набор.
+	* Прокрутили — цель исполнена, а закрепление остаётся до следующей цели
+	* (см. описание класса).
+	*
+	* `scrollIntoView` вызывается, если он есть: в jsdom его нет. Прокрутка —
+	* удобство, а не часть контракта.
+	*/
+	_attempt() {
+		const target = this._target;
+		if (!target || !this._root) return;
+		const behavior = this._owner?.scrollBehavior ?? LIST_DEFAULTS.scrollBehavior;
+		if (behavior === "none") {
+			this._drop();
+			return;
+		}
+		if (!(this._height?.measured ?? true)) {
+			this._target = {
+				...target,
+				instant: true
+			};
+			this._draw()?.pin(SCROLL, target.item);
+			return;
+		}
+		const node = this._elements?.getElementByUid(target.item.uid) ?? null;
+		if (!node) {
+			this._draw()?.pin(SCROLL, target.item);
+			return;
+		}
+		this._target = null;
+		const scroll = target.instant || behavior === "instant" ? "instant" : smoothScrollBehavior(node);
+		if (target.fact === "highlight") node.scrollIntoView?.({
+			block: "nearest",
+			behavior: scroll
+		});
+		else revealValue(node, scroll);
+	}
+	/** Рисование коллекции — у списков в окне; у меню его нет, и закреплять нечего. */
+	_draw() {
+		return drawOf(this._bundles?.engine);
+	}
+};
+//#endregion
+export { TListScrollPlugin };

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

@@ -0,0 +1,21 @@
+import type { IPluginConstructor, TPluginEvents } from '../../../base';
+import type { TListNavigationPlugin } from '../navigation';
+export type TListScrollPluginEvents = TPluginEvents & {
+    'change:scroll': () => void;
+};
+export interface IListScrollPluginOptions {
+    /**
+     * Навигация списка — класс плагина, за чьей видимой подсветкой
+     * (`change:highlight`) идёт прокрутка: `TListKeyboardPlugin` у ListBox,
+     * `TSelectKeyboardPlugin` у Select, `TMenuKeyboardPlugin` у меню,
+     * `TMenuSubmenuKeyboardPlugin` у подменю. Стоит в наборе раньше прокрутки.
+     *
+     * Опцией, а не поиском в наборе: набор находит плагин по точному классу
+     * (`ctx.get`), а наследников у базы навигации четыре. Не задана —
+     * прокрутка идёт только за значением.
+     *
+     * `any` — карта событий наследника инвариантна и бывает шире базовой (у
+     * Select — `escape`), а событие подсветки у всех наследников одно.
+     */
+    navigation?: IPluginConstructor<any, any, TListNavigationPlugin<any, any>>;
+}

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

@@ -0,0 +1,53 @@
+/**
+ * Набор по первым буквам (APG, «type-ahead»): буква ведёт подсветку к
+ * элементу, чей текст с неё начинается.
+ *
+ * Правило одно на списки с подсветкой — меню и комбобокс Select. Поэтому оно
+ * — модуль с буфером и поиском, а не метод одного плагина: подсветку и
+ * клавиши каждый плагин держит сам, а что считать набором и куда он ведёт,
+ * решает этот модуль.
+ *
+ * - Буквы, набранные быстрее паузы (`timeout`), — одно слово: «со» ищет
+ *   «Сохранить», а не следующий пункт на «о».
+ * - Поиск идёт по кругу от подсвеченного элемента. Слово ищется с него
+ *   самого: дописанная буква не уводит с элемента, который ещё подходит.
+ *   Одна буква ищется со следующего — так повтор буквы ходит по элементам на
+ *   неё («с», «с», «с» — «Сохранить», «Сохранить как», «Создать»), и
+ *   повторённая буква («ссс») значит то же, что одна.
+ * - Совпадения нет — подсветка остаётся на месте.
+ *
+ * Регистр не важен. Элементы — те, по которым идёт навигация: недоступные
+ * плагин отсеивает сам.
+ */
+/** Пауза, после которой следующая буква начинает новый набор, мс. */
+export declare const TYPEAHEAD_TIMEOUT = 500;
+/**
+ * Текст элемента, по которому идёт набор, — его `text`. У элемента без
+ * текста — пусто, и набор его не находит.
+ */
+export declare const itemText: (item: object) => string;
+export declare class TTypeahead {
+    private readonly _timeout;
+    private _query;
+    private _at;
+    /** @param timeout — пауза, после которой следующая буква начинает новый набор, мс */
+    constructor(_timeout?: number);
+    /**
+     * Идёт ли набор: с последней буквы прошло не больше паузы. Пока он идёт,
+     * пробел — тоже буква («Сохранить как»), а не нажатие элемента.
+     */
+    typing(now?: number): boolean;
+    /**
+     * Буква набора: продолжить слово или начать новое — и найти элемент.
+     *
+     * @param char — набранная буква
+     * @param items — элементы по порядку, по которым идёт навигация
+     * @param current — подсвеченный элемент; `null` — поиск с первого
+     * @param textOf — текст элемента, по которому идёт сравнение
+     * @returns элемент, на который встать, или `null` — совпадения нет, и
+     *   подсветка остаётся на месте
+     */
+    next<TItem>(char: string, items: readonly TItem[], current: TItem | null, textOf: (item: TItem) => string, now?: number): TItem | null;
+    /** Сбросить набор: следующая буква начнёт новый. */
+    reset(): void;
+}