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

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

@@ -0,0 +1,262 @@
+import type { IControl, TCollectionEngine, TEventSink } from '@soxa-ui/core';
+import { TBasePlugin } from '../../../base';
+import type { IPluginContext } from '../../../base';
+import { TCollectionBundlesPlugin } from '../../collection';
+import type { IDomEventTarget } from '../../../utils';
+import { TListItemPlugin } from '../item';
+import type { TListEdge, TListNavigationPluginEvents } from './types';
+/**
+ * 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` не принял бы элемент со своими событиями.
+ */
+export declare abstract class TListNavigationPlugin<TEvents extends TListNavigationPluginEvents = TListNavigationPluginEvents, TItem extends IControl<any, any> = IControl> extends TBasePlugin<any, TEvents> {
+    /** Узел нужен только под слушатель клавиш — отсюда и тип. */
+    protected _element: IDomEventTarget | null;
+    protected _bundles: TCollectionBundlesPlugin | null;
+    protected _engine: TCollectionEngine<any, any> | null;
+    protected _highlightedUid: string | number | null;
+    /** Подсветка видна: у подсвеченного элемента стоит отметка, а не одна позиция. */
+    private _marked;
+    /**
+     * Шина элемента на позиции — за его набором `aria` база следит, пока
+     * позиция на нём: в наборе `id`, на который ведёт ссылка наследника.
+     * Подписка своя, а не `_listenTo`: элемент сменяется с позицией, и прежнего
+     * база отпускает сразу, а не при уничтожении.
+     */
+    private _watched;
+    install(ctx: IPluginContext, options?: unknown): void;
+    /**
+     * Эмит собственных событий навигации — без приведения `this.events` к
+     * конкретной карте (см. `TEventSink` в `@soxa-ui/core`).
+     *
+     * Перекрывает сток базы, потому что у `TBasePlugin._sink` карта
+     * `TPluginEvents`, а `change:highlight` объявлен здесь: через базовый сток
+     * это имя не пройдёт. Свой сток заводит каждый уровень иерархии, который
+     * добавил событие; `TListKeyboardPlugin` и `TSelectKeyboardPlugin` к механике
+     * навигации ничего не добавляют и пользуются этим.
+     *
+     * Дженерик карту не заменяет. На `TEventSink<TEvents>` эмит упирается в
+     * `Parameters<TEvents['change:highlight']>` — тип, который на
+     * непроинстанцированном дженерике не разрешается. Вынести карту отдельным
+     * параметром базы тоже не выход: ошибка переезжает в базу, где этот параметр
+     * снова дженерик. Сток обязан назвать карту точно — тем он и отличается от
+     * `this.events`.
+     *
+     * Расширять карту базы безопасно: наследник не может сузить обработчик
+     * (`TEvents extends TListNavigationPluginEvents` сверяется контравариантно по
+     * аргументам), поэтому эмит базы через расширенный сток звучит.
+     */
+    protected get _sink(): TEventSink<TListNavigationPluginEvents>;
+    destroy(): void;
+    /** Элемент, на котором сейчас подсветка. */
+    get highlightedUid(): string | number | null;
+    /** Что делают клавиши. */
+    protected abstract onKeyDown(event: KeyboardEvent): void;
+    /** Коллекция появилась — можно синхронизировать начальное состояние. */
+    protected onEngineBound(_engine: TCollectionEngine<any, any>): void;
+    /**
+     * Видимая подсветка сменилась — тем же сообщением, что `change:highlight`.
+     * Здесь наследник ведёт ссылку `aria-activedescendant` или фокус; прокрутку
+     * к подсвеченному ведёт `TListScrollPlugin` по событию.
+     *
+     * `uid` — элемент, который получил отметку. Переход с элемента на элемент —
+     * один вызов, с новым: прежняя отметка снимается молча, а `null` между ними
+     * у меню увёл бы фокус на панель. `null` — отметки больше нет: подсветку
+     * сняли (`clearHighlight`) или позиция ушла без отметки (`trackHighlight`).
+     * Без отметки позиция переезжает молча: экран при этом не меняется.
+     */
+    protected onHighlightChanged(_uid: string | number | null): void;
+    /**
+     * Подсвеченный элемент вошёл в документ — его набор зарегистрирован, а
+     * отметка ему возвращена. Так бывает в окне: подсветка ушла к элементу,
+     * которого окно не рисовало, и окно дорисовало его уже после
+     * `onHighlightChanged`. Здесь наследник берёт то, что есть только у
+     * смонтированного элемента: `id` для ссылки на него. Прокрутка к нему ждёт
+     * его набор сама (`TListScrollPlugin`).
+     */
+    protected onHighlightedMounted(_uid: string | number): void;
+    /**
+     * Набор `aria` подсвеченного элемента сменился, пока отметка видна, — и
+     * вместе с ним мог смениться `id`, на который ведёт ссылка: `id` элемента в
+     * `TIdPlugin` задали, сменили или сняли. Здесь наследник, который ссылается
+     * на подсвеченный (`aria-activedescendant`), переписывает ссылку.
+     *
+     * Отдельный хук, а не повтор `onHighlightChanged`: подсветка не сменилась,
+     * и наследник не должен снова переносить фокус, а список — прокручивать к
+     * элементу. База следит за набором, а не за `change:id` `TIdPlugin`
+     * элемента: `id` в набор пишет плагин связок своим подписчиком того же
+     * события, и подписчик, пришедший раньше него, прочёл бы прежний.
+     */
+    protected onHighlightedAriaChanged(_uid: string | number): void;
+    /**
+     * Показанные элементы — `batch.shown`, а не `batch.items`: ходить
+     * стрелками по тому, что отбор скрыл, нельзя. Среди них и недоступные: по
+     * ним наследник узнаёт, с чьей строки пришла клавиша, а `move` — откуда
+     * шагать.
+     *
+     * Тип — элемент списка наследника (`TItem`), а база опирается только на
+     * `IControl`: навигации нужны `uid`, `disabled`, `rendered` и `visible`.
+     * Элементы ListBox и опции Select общего предка ниже `IControl` не имеют, и
+     * раньше здесь стоял `IListItem` от несуществующего теперь компонента
+     * `TList`. Массив — только для чтения: это сама выборка коллекции, у
+     * коллекции с памятью выборки — запомненная.
+     */
+    protected shown(): readonly TItem[];
+    /**
+     * Элементы, по которым идёт навигация: показанные и доступные. Недоступные
+     * пропускаются у ListBox и у Select одинаково — правило не зависит ни от
+     * роли элемента, ни от модели фокуса.
+     */
+    protected items(): TItem[];
+    protected indexOf(uid: string | number | null): number;
+    protected itemAt(index: number): TItem | null;
+    protected itemByUid(uid: string | number): TItem | null;
+    /**
+     * `id` подсвеченного элемента для ссылки `aria-activedescendant`, пока она
+     * повторяет экран: у элемента видна отметка и он в документе — его набор
+     * зарегистрирован. Иначе — `null`: позиция без отметки ссылкой не
+     * становится, а у элемента вне окна (`Virtual`) своего `id` нет, и
+     * оставшийся от прошлого монтирования указывал бы в пустоту.
+     *
+     * `id` — из набора `aria` элемента, а не с DOM-узла: узел, который знает
+     * реестр, — корень элемента, а `id` вместе со всей ARIA стоит на его строке.
+     * В набор его пишет `TOptionIdsPlugin` элемента, и ссылка берёт ровно то,
+     * что окажется в разметке. Куда её писать, решает наследник — туда, где
+     * фокус.
+     */
+    protected highlightedId(): string | null;
+    /**
+     * Сдвигает подсветку к ближайшему доступному элементу в направлении шага.
+     * Навигация зациклена: с последнего элемента `↓` уводит на первый — так
+     * принято в списках и так делают Ark и Radix.
+     *
+     * Шаг отсчитывается от места подсветки среди показанных, а не среди
+     * доступных: подсвеченный элемент могли выключить, а ListBox ставит позицию
+     * и на выбранный элемент, который бывает выключен. Среди доступных такого
+     * нет, и стрелка увела бы на край списка. Так же ищут соседа
+     * `TTabsKeyboardPlugin` и `TTagsKeyboardPlugin`. Подсветки нет или её
+     * элемент не показан — шаг начинается с края.
+     */
+    protected move(step: number): void;
+    protected highlightEdge(edge: TListEdge): void;
+    /**
+     * Подсветить элемент: позиция плюс визуальная отметка — и сообщение о
+     * ней: `change:highlight` с элементом и соседями и хук наследника
+     * (`_announce`).
+     *
+     * Позиция может уже стоять на элементе без отметки — её ставит
+     * `trackHighlight` за выбором и со строки, с которой пришла клавиша. Тогда
+     * отметка встаёт на месте, и сообщение уходит так же: на экране подсветка
+     * появилась, хоть позиция и не сменилась. Так стрелка отмечает
+     * единственный доступный элемент — шаг по кругу приводит к нему же, — и
+     * список докручивает к нему. Подсвечивать нечего, только когда у элемента
+     * и позиция, и отметка: повтор молчит.
+     */
+    protected highlight(uid: string | number): void;
+    /**
+     * Запомнить позицию, не отмечая элемент визуально.
+     *
+     * Нужно при синхронизации с выбором: список открылся на выбранном
+     * элементе, но подсветка навигации ещё не должна быть видна. Отметка, которая
+     * была видна, снимается, и об этом уходит сообщение с `null`
+     * (`change:highlight` и `onHighlightChanged(null)`): позиция осталась, а
+     * подсветки на экране нет. Без отметки позиция переезжает молча — ни
+     * события, ни хука: на экране ничего не сменилось.
+     */
+    protected trackHighlight(uid: string | number): void;
+    /**
+     * Снять подсветку: позиции больше нет. Сообщение с `null` — только если
+     * отметка была видна: позиция без отметки уходит молча, как и переезжает.
+     */
+    protected clearHighlight(): void;
+    protected itemPlugin(uid: string | number): TListItemPlugin | undefined;
+    /**
+     * Позиция — на элемент: прежняя отметка снята, элемент закреплён в окне, и
+     * база следит за его набором. Событий здесь нет: ставить ли отметку и
+     * сообщать ли о ней, решает тот, кто позицию перенёс, — `highlight` или
+     * `trackHighlight`.
+     */
+    private _moveTo;
+    /**
+     * За позицией — её элемент среди показанных: он закреплён в окне, и база
+     * следит за его набором `aria`. Позиции нет — закрепление снято, следить
+     * не за чем.
+     */
+    private _followPosition;
+    /**
+     * Видимая подсветка сменилась — одним сообщением обоим слушателям:
+     * `change:highlight` тем, кто слушает снаружи, и `onHighlightChanged`
+     * наследнику. Элемент — с соседями среди доступных; `null` — отметки
+     * больше нет, и соседей тоже.
+     */
+    private _highlightPayload;
+    private _announce;
+    /** Снимает визуальную отметку с текущего элемента. */
+    private unmarkCurrent;
+    /**
+     * Закрепить элемент позиции в окне коллекции, если оно есть: окно рисует
+     * его на месте, и подсветка, уведённая стрелкой за видимую полосу, не
+     * теряет узел. Позиции нет — закрепление снять.
+     */
+    private _pin;
+    /**
+     * Следить за набором `aria` элемента на позиции, а прежнего — отпустить.
+     * Элемента нет — не следить ни за чьим.
+     */
+    private _watch;
+    /** Набор элемента на позиции сменился: ссылке он важен, только пока отметка видна. */
+    private readonly _onHighlightedAria;
+    private readonly _onKeyDown;
+}