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

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

@@ -0,0 +1,46 @@
+import { TBasePlugin } from "../../../base/base.class.js";
+//#region src/custom/list/item/item.plugin.ts
+/**
+* TListItemPlugin — состояние подсветки элемента списка (клавиатурная навигация).
+*
+* Не управляет выбором: выбор элемента выполняется selection-расширением коллекции.
+* Плагин лишь хранит флаг `highlighted`, которым управляет TListKeyboardPlugin.
+*
+* Подсветку отдаёт теме сам — через `data-highlighted`. Раньше это делал
+* шаблон, и два компонента успели разойтись: ListBox отдавал значение сырым,
+* Select приводил его через `String(!!value)`. Оба варианта работали по
+* случайности; здесь преобразование одно и живёт рядом с состоянием.
+*
+* В DOM плагин не ходит — пишет в набор, а раскладывает его шаблон, синхронно.
+*/
+var TListItemPlugin = class extends TBasePlugin {
+	_instance = null;
+	_highlighted = false;
+	install(ctx, options) {
+		super.install(ctx, options);
+		this._instance = ctx.getInstance();
+		this._apply();
+	}
+	get highlighted() {
+		return this._highlighted;
+	}
+	set highlighted(value) {
+		const oldHighlighted = this.highlighted;
+		if (this._highlighted === value) return;
+		this._highlighted = value;
+		this._apply();
+		this.events.emit("change:highlighted", {
+			newValue: value,
+			oldValue: oldHighlighted
+		});
+	}
+	_apply() {
+		this._instance?.dataset.add("highlighted", this._highlighted);
+	}
+	destroy() {
+		this._instance = null;
+		super.destroy();
+	}
+};
+//#endregion
+export { TListItemPlugin };

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

@@ -0,0 +1,5 @@
+import type { TValuePayload } from '@soxa-ui/core';
+import type { TPluginEvents } from '../../../base';
+export type TListItemPluginEvents = TPluginEvents & {
+    'change:highlighted': (payload: TValuePayload<boolean>) => void;
+};

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

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

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

@@ -0,0 +1,133 @@
+import type { IListBoxItem, TCollectionEngine } from '@soxa-ui/core';
+import type { IPluginContext } from '../../../base';
+import { TListNavigationPlugin } from '../navigation';
+import type { TListKeyboardPluginEvents } from './types';
+/**
+ * TListKeyboardPlugin — клавиатура самостоятельного списка (ListBox).
+ *
+ * Общая механика — подписка на `keydown`, привязка к коллекции, учёт
+ * подсветки, циклический сдвиг, пропуск недоступных элементов — в
+ * `TListNavigationPlugin`. Здесь только то, чем список отличается: набор
+ * клавиш, смысл активации и модель фокуса.
+ *
+ * `ListBox` фокусируется сам: остановка Tab — узел списка внутри корня
+ * (`tabindex="0"`, на нём же роль `listbox`), а шапка и подвал стоят рядом с
+ * ним. DOM-фокус держит узел списка — кольцо темы у него, — а элемент под
+ * стрелками показывает подсветка (`data-highlighted`). Enter и Space
+ * переключают выбор подсвеченного через расширение списка
+ * (`list.chooseItem`), как и клик по строке.
+ *
+ * **Элемент под стрелками скринридеру называет `aria-activedescendant` узла
+ * списка** (APG Listbox): фокус по строкам не ходит, и без ссылки стрелки были
+ * бы для скринридера немыми. Ссылку плагин пишет в набор `aria` списка — его
+ * разметка кладёт на узел списка, — на `id` подсвеченного элемента
+ * (`TOptionIdsPlugin`), и она повторяет экран: есть, пока у элемента видна
+ * отметка и он в документе (`highlightedId` навигации). Позиция без отметки —
+ * за выбором или на строке, с которой пришла клавиша, — ссылкой не
+ * становится. В окне (`Virtual`) ссылка ждёт, когда окно дорисует
+ * подсвеченный элемент (`onHighlightedMounted`), а элемент, ушедший из
+ * документа, — из коллекции или со снятым монтированием, — её снимает. `id`
+ * элемента — свой, если его задали, и ссылка идёт за его сменой у
+ * подсвеченного (`onHighlightedAriaChanged`).
+ *
+ * Слушатель висит на корне, но клавишу список берёт только с узла списка
+ * (`listOf`) и со строки показанного элемента. До корня всплывают и клавиши
+ * полей и кнопок из шапки, подвала и слотов элемента — что с ними делать, эти
+ * элементы знают сами: поле печатает пробел, кнопка делает из Enter и пробела
+ * клик. Правило отвечает на вопрос «чья клавиша», а не «какая», исключений
+ * нет: из поля в шапке не работают и стрелки.
+ *
+ * **Строка держит фокус после клика только до первой клавиши.** У строки
+ * `tabindex="-1"`, и фокус на неё ставят клик и запись `focused = true`
+ * элемента. Клавиша с неё — клавиша списка с места этой строки: позиция
+ * встаёт на элемент строки, фокус возвращается узлу списка, и дальше клавиша
+ * идёт так же, как с узла (`_fromRow`). Останься фокус на строке, после
+ * клавиши браузер включил бы ей `:focus-visible`, и кольцо строки висело бы до
+ * ухода из списка, пока подсветка ходит по другим элементам. Правило — для
+ * любой клавиши, а не только для стрелок, Enter и пробела: Tab со строки идёт
+ * от узла списка, и Shift+Tab выводит из ListBox одним нажатием, а не
+ * останавливается на самом узле — предке строки.
+ *
+ * Цель сравнивается со строкой на равенство, а не через `contains`, как у
+ * табов (`TTabsKeyboardPlugin`): там кнопка закрытия — часть таба, а в строке
+ * ListBox лежат только слоты потребителя, и их клавиши принадлежат им. Проверка
+ * цели — здесь, а не в `TListNavigationPlugin`: база общая с Select, у которого
+ * своё правило — клавиши только с поля.
+ */
+export declare class TListKeyboardPlugin extends TListNavigationPlugin<TListKeyboardPluginEvents, IListBoxItem> {
+    /** Список: в его набор `aria` — ссылка на подсвеченный элемент. */
+    private _owner;
+    /**
+     * Узлы элементов — по ним ищется строка, с которой пришла клавиша. Без
+     * этого плагина строку не узнать, и список берёт клавиши только с узла
+     * списка.
+     */
+    private _elements;
+    install(ctx: IPluginContext, options?: unknown): void;
+    destroy(): void;
+    /** Видимая подсветка сменилась — ссылка за ней. */
+    protected onHighlightChanged(_uid: string | number | null): void;
+    /** Окно дорисовало подсвеченный элемент: у него появился `id` — на него ссылка. */
+    protected onHighlightedMounted(_uid: string | number): void;
+    /**
+     * Набор подсвеченного сменился — с ним мог смениться его `id` (`id` элемента
+     * в `TIdPlugin` задали, сменили или сняли): ссылка за ним.
+     */
+    protected onHighlightedAriaChanged(_uid: string | number): void;
+    /** `aria-activedescendant` списка — на подсвеченный элемент, пока он на экране. */
+    private _refer;
+    /**
+     * Позиция встаёт на выбранный элемент, когда появилась коллекция, а дальше
+     * следует за выбором — на элемент, который стал выбранным (`newlySelected`):
+     * кликом, клавишей или значением снаружи. Снятие выбора её не трогает.
+     *
+     * Enter и пробел выбирают подсвеченный элемент, и позиция с отметкой
+     * остаются на нём: следующая стрелка ведёт к его соседу. Раньше позиция шла
+     * за первым выбранным, и в `multiple` выбор клавишей снимал отметку и уводил
+     * позицию к нему.
+     *
+     * Позиция, которую выбор перенёс на другой элемент, запоминается без
+     * визуальной отметки: список ещё не в навигации.
+     */
+    protected onEngineBound(engine: TCollectionEngine<any, any>): void;
+    protected onKeyDown(e: KeyboardEvent): void;
+    /**
+     * Показанный элемент, со строки которого пришла клавиша, — в том числе
+     * недоступный. Навигация его пропускает, но фокус на его строке бывает:
+     * элемент могли выключить, пока фокус на ней, а если тема не глушит мышь на
+     * выключенной строке, фокус на неё ставит и клик, хоть и не выбирает. Если
+     * искать строку только среди доступных, клавиши с неё не работали бы.
+     *
+     * `null` — клавиша не со строки: из содержимого слотов или с самого корня.
+     * Корень — рамка вокруг шапки, списка и подвала, и остановкой Tab его
+     * делает только атрибут потребителя.
+     */
+    private _rowItemOf;
+    /**
+     * Клавиша со строки: позиция — на элемент строки, без отметки, как за
+     * выбором, фокус — узлу списка. Дальше клавиша идёт так же, как с узла:
+     * стрелка шагает от строки, а не от прежней позиции (клик, снявший выбор со
+     * строки, и запись `focused = true` позицию не двигают), Enter и пробел
+     * переключают элемент строки, Tab уходит от узла.
+     *
+     * Позиция — раньше фокуса: окно (`Virtual`) держит строку под фокусом
+     * нарисованной, и уход фокуса это закрепление снимает, а позиция к тому
+     * времени уже закрепила элемент строки сама.
+     *
+     * Фокус переходит во время нажатия клавиши, поэтому `:focus-visible`
+     * браузер включает узлу списка, как после Tab, а кольцо строки гаснет
+     * вместе с её фокусом. Без прокрутки: строка, с которой пришла клавиша, на
+     * экране, а докрутка к узлу списка сдвинула бы страницу. Узла нет —
+     * фокус остаётся на месте, но клавиша всё равно идёт от строки.
+     */
+    private _fromRow;
+    /**
+     * Выбор идёт через расширение списка, тем же путём, что клик по строке:
+     * выключенному элементу оно отказывает. `selection.toggle` выключенность
+     * не проверяет — выбрать выключенный элемент из кода вправе приложение.
+     *
+     * Подсвеченный элемент ищется среди доступных (`items()`), поэтому
+     * выключенный или скрытый после подсветки до расширения и не доходит.
+     */
+    private _toggleHighlighted;
+}

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

@@ -0,0 +1,199 @@
+import { TCollectionElements } from "../../collection/collection-elements.plugin.js";
+import { isFocusableElement } from "../../../utils/isFocusableElement.js";
+import { listOf as listOf$1, rowOf } from "../row.js";
+import { TListNavigationPlugin } from "../navigation/navigation.plugin.js";
+import { newlySelected } from "../newly-selected.js";
+import { listOf, selectionOf } from "@soxa-ui/core";
+//#region src/custom/list/keyboard/keyboard.plugin.ts
+/**
+* TListKeyboardPlugin — клавиатура самостоятельного списка (ListBox).
+*
+* Общая механика — подписка на `keydown`, привязка к коллекции, учёт
+* подсветки, циклический сдвиг, пропуск недоступных элементов — в
+* `TListNavigationPlugin`. Здесь только то, чем список отличается: набор
+* клавиш, смысл активации и модель фокуса.
+*
+* `ListBox` фокусируется сам: остановка Tab — узел списка внутри корня
+* (`tabindex="0"`, на нём же роль `listbox`), а шапка и подвал стоят рядом с
+* ним. DOM-фокус держит узел списка — кольцо темы у него, — а элемент под
+* стрелками показывает подсветка (`data-highlighted`). Enter и Space
+* переключают выбор подсвеченного через расширение списка
+* (`list.chooseItem`), как и клик по строке.
+*
+* **Элемент под стрелками скринридеру называет `aria-activedescendant` узла
+* списка** (APG Listbox): фокус по строкам не ходит, и без ссылки стрелки были
+* бы для скринридера немыми. Ссылку плагин пишет в набор `aria` списка — его
+* разметка кладёт на узел списка, — на `id` подсвеченного элемента
+* (`TOptionIdsPlugin`), и она повторяет экран: есть, пока у элемента видна
+* отметка и он в документе (`highlightedId` навигации). Позиция без отметки —
+* за выбором или на строке, с которой пришла клавиша, — ссылкой не
+* становится. В окне (`Virtual`) ссылка ждёт, когда окно дорисует
+* подсвеченный элемент (`onHighlightedMounted`), а элемент, ушедший из
+* документа, — из коллекции или со снятым монтированием, — её снимает. `id`
+* элемента — свой, если его задали, и ссылка идёт за его сменой у
+* подсвеченного (`onHighlightedAriaChanged`).
+*
+* Слушатель висит на корне, но клавишу список берёт только с узла списка
+* (`listOf`) и со строки показанного элемента. До корня всплывают и клавиши
+* полей и кнопок из шапки, подвала и слотов элемента — что с ними делать, эти
+* элементы знают сами: поле печатает пробел, кнопка делает из Enter и пробела
+* клик. Правило отвечает на вопрос «чья клавиша», а не «какая», исключений
+* нет: из поля в шапке не работают и стрелки.
+*
+* **Строка держит фокус после клика только до первой клавиши.** У строки
+* `tabindex="-1"`, и фокус на неё ставят клик и запись `focused = true`
+* элемента. Клавиша с неё — клавиша списка с места этой строки: позиция
+* встаёт на элемент строки, фокус возвращается узлу списка, и дальше клавиша
+* идёт так же, как с узла (`_fromRow`). Останься фокус на строке, после
+* клавиши браузер включил бы ей `:focus-visible`, и кольцо строки висело бы до
+* ухода из списка, пока подсветка ходит по другим элементам. Правило — для
+* любой клавиши, а не только для стрелок, Enter и пробела: Tab со строки идёт
+* от узла списка, и Shift+Tab выводит из ListBox одним нажатием, а не
+* останавливается на самом узле — предке строки.
+*
+* Цель сравнивается со строкой на равенство, а не через `contains`, как у
+* табов (`TTabsKeyboardPlugin`): там кнопка закрытия — часть таба, а в строке
+* ListBox лежат только слоты потребителя, и их клавиши принадлежат им. Проверка
+* цели — здесь, а не в `TListNavigationPlugin`: база общая с Select, у которого
+* своё правило — клавиши только с поля.
+*/
+var TListKeyboardPlugin = class extends TListNavigationPlugin {
+	/** Список: в его набор `aria` — ссылка на подсвеченный элемент. */
+	_owner = null;
+	/**
+	* Узлы элементов — по ним ищется строка, с которой пришла клавиша. Без
+	* этого плагина строку не узнать, и список берёт клавиши только с узла
+	* списка.
+	*/
+	_elements = null;
+	install(ctx, options) {
+		super.install(ctx, options);
+		this._owner = ctx.getInstance();
+		this._elements = ctx.get(TCollectionElements) ?? null;
+		this._bundles?.events.on("bundle:unregistered", ({ uid }) => {
+			if (uid === this._highlightedUid) this._refer();
+		});
+	}
+	destroy() {
+		super.destroy();
+		this._owner = null;
+		this._elements = null;
+	}
+	/** Видимая подсветка сменилась — ссылка за ней. */
+	onHighlightChanged(_uid) {
+		this._refer();
+	}
+	/** Окно дорисовало подсвеченный элемент: у него появился `id` — на него ссылка. */
+	onHighlightedMounted(_uid) {
+		this._refer();
+	}
+	/**
+	* Набор подсвеченного сменился — с ним мог смениться его `id` (`id` элемента
+	* в `TIdPlugin` задали, сменили или сняли): ссылка за ним.
+	*/
+	onHighlightedAriaChanged(_uid) {
+		this._refer();
+	}
+	/** `aria-activedescendant` списка — на подсвеченный элемент, пока он на экране. */
+	_refer() {
+		this._owner?.aria.add("aria-activedescendant", this.highlightedId());
+	}
+	/**
+	* Позиция встаёт на выбранный элемент, когда появилась коллекция, а дальше
+	* следует за выбором — на элемент, который стал выбранным (`newlySelected`):
+	* кликом, клавишей или значением снаружи. Снятие выбора её не трогает.
+	*
+	* Enter и пробел выбирают подсвеченный элемент, и позиция с отметкой
+	* остаются на нём: следующая стрелка ведёт к его соседу. Раньше позиция шла
+	* за первым выбранным, и в `multiple` выбор клавишей снимал отметку и уводил
+	* позицию к нему.
+	*
+	* Позиция, которую выбор перенёс на другой элемент, запоминается без
+	* визуальной отметки: список ещё не в навигации.
+	*/
+	onEngineBound(engine) {
+		const selection = selectionOf(engine);
+		const selected = selection?.selected ?? [];
+		if (selected.length > 0) this.trackHighlight(selected[0].uid);
+		this._listenTo(selection?.events, "change:selection", (items, changed) => {
+			const item = newlySelected(items, changed);
+			if (item) this.trackHighlight(item.uid);
+		});
+	}
+	onKeyDown(e) {
+		const root = e.currentTarget;
+		const list = root instanceof Element ? listOf$1(root) : null;
+		if (e.target !== list) {
+			const item = this._rowItemOf(e.target);
+			if (!item) return;
+			this._fromRow(item, list);
+		}
+		if (!this._engine) return;
+		if (this.items().length === 0) return;
+		switch (e.key) {
+			case "ArrowDown":
+				e.preventDefault();
+				this.move(1);
+				return;
+			case "ArrowUp":
+				e.preventDefault();
+				this.move(-1);
+				return;
+			case "Enter":
+			case " ":
+				e.preventDefault();
+				this._toggleHighlighted();
+				return;
+		}
+	}
+	/**
+	* Показанный элемент, со строки которого пришла клавиша, — в том числе
+	* недоступный. Навигация его пропускает, но фокус на его строке бывает:
+	* элемент могли выключить, пока фокус на ней, а если тема не глушит мышь на
+	* выключенной строке, фокус на неё ставит и клик, хоть и не выбирает. Если
+	* искать строку только среди доступных, клавиши с неё не работали бы.
+	*
+	* `null` — клавиша не со строки: из содержимого слотов или с самого корня.
+	* Корень — рамка вокруг шапки, списка и подвала, и остановкой Tab его
+	* делает только атрибут потребителя.
+	*/
+	_rowItemOf(target) {
+		return this.shown().find((item) => rowOf(this._elements, item.uid) === target) ?? null;
+	}
+	/**
+	* Клавиша со строки: позиция — на элемент строки, без отметки, как за
+	* выбором, фокус — узлу списка. Дальше клавиша идёт так же, как с узла:
+	* стрелка шагает от строки, а не от прежней позиции (клик, снявший выбор со
+	* строки, и запись `focused = true` позицию не двигают), Enter и пробел
+	* переключают элемент строки, Tab уходит от узла.
+	*
+	* Позиция — раньше фокуса: окно (`Virtual`) держит строку под фокусом
+	* нарисованной, и уход фокуса это закрепление снимает, а позиция к тому
+	* времени уже закрепила элемент строки сама.
+	*
+	* Фокус переходит во время нажатия клавиши, поэтому `:focus-visible`
+	* браузер включает узлу списка, как после Tab, а кольцо строки гаснет
+	* вместе с её фокусом. Без прокрутки: строка, с которой пришла клавиша, на
+	* экране, а докрутка к узлу списка сдвинула бы страницу. Узла нет —
+	* фокус остаётся на месте, но клавиша всё равно идёт от строки.
+	*/
+	_fromRow(item, list) {
+		this.trackHighlight(item.uid);
+		if (isFocusableElement(list)) list.focus({ preventScroll: true });
+	}
+	/**
+	* Выбор идёт через расширение списка, тем же путём, что клик по строке:
+	* выключенному элементу оно отказывает. `selection.toggle` выключенность
+	* не проверяет — выбрать выключенный элемент из кода вправе приложение.
+	*
+	* Подсвеченный элемент ищется среди доступных (`items()`), поэтому
+	* выключенный или скрытый после подсветки до расширения и не доходит.
+	*/
+	_toggleHighlighted() {
+		if (this._highlightedUid == null) return;
+		const item = this.itemByUid(this._highlightedUid);
+		if (item) listOf(this._engine)?.chooseItem(item);
+	}
+};
+//#endregion
+export { TListKeyboardPlugin };

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

@@ -0,0 +1,3 @@
+import type { TListNavigationPluginEvents } from '../navigation';
+export type { THighlightPayload } from '../navigation';
+export type TListKeyboardPluginEvents = TListNavigationPluginEvents;

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

@@ -0,0 +1,2 @@
+export { TListNavigationPlugin } from './navigation.plugin';
+export type { THighlightPayload, TListNavigationPluginEvents, TListEdge } from './types';