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

package/dist/custom/calendar/ids/ids.plugin.d.ts

@@ -0,0 +1,25 @@
+import { TBasePlugin } from '../../../base';
+import type { IPluginContext } from '../../../base';
+/**
+ * TCalendarIdsPlugin — имена сеток календаря в документе: сетку называет её
+ * заголовок, панель выбора месяца и года — её шапка.
+ *
+ * На каждом месте сетки пишет `id` заголовка и ссылку на него
+ * `aria-labelledby` у таблицы — в наборы места (`gridSets` вида), которые вид
+ * раскладывает в `grids`. Место, а не месяц: листание меняет месяц сетки, а
+ * заголовок, его `id` и живая область остаются. Месяцев стало больше —
+ * новым местам пишется то же (`change:months`).
+ *
+ * Там же — `id` шапки панели выбора (`pickerSets` расширения `picker`).
+ * Ссылку на шапку панель и список получают пропом `aria_labelledBy` из
+ * выхода `pickers`, а не записью в их наборы: их имя пишет их собственный
+ * `TAriaPlugin` и снял бы чужую запись.
+ *
+ * `id` — от монтирования календаря (`createId`), а не от экземпляра: он нужен
+ * только документу, и на сервере и в браузере обязан совпасть. Движок
+ * привязывается при сборке (`engine:bound`), до первой отрисовки, — имена
+ * сеток есть уже в серверной разметке.
+ */
+export declare class TCalendarIdsPlugin extends TBasePlugin {
+    install(ctx: IPluginContext): void;
+}

package/dist/custom/calendar/ids/ids.plugin.js

@@ -0,0 +1,44 @@
+import { TBasePlugin } from "../../../base/base.class.js";
+import { TCollectionBundlesPlugin } from "../../collection/bundles.plugin.js";
+//#region src/custom/calendar/ids/ids.plugin.ts
+/**
+* TCalendarIdsPlugin — имена сеток календаря в документе: сетку называет её
+* заголовок, панель выбора месяца и года — её шапка.
+*
+* На каждом месте сетки пишет `id` заголовка и ссылку на него
+* `aria-labelledby` у таблицы — в наборы места (`gridSets` вида), которые вид
+* раскладывает в `grids`. Место, а не месяц: листание меняет месяц сетки, а
+* заголовок, его `id` и живая область остаются. Месяцев стало больше —
+* новым местам пишется то же (`change:months`).
+*
+* Там же — `id` шапки панели выбора (`pickerSets` расширения `picker`).
+* Ссылку на шапку панель и список получают пропом `aria_labelledBy` из
+* выхода `pickers`, а не записью в их наборы: их имя пишет их собственный
+* `TAriaPlugin` и снял бы чужую запись.
+*
+* `id` — от монтирования календаря (`createId`), а не от экземпляра: он нужен
+* только документу, и на сервере и в браузере обязан совпасть. Движок
+* привязывается при сборке (`engine:bound`), до первой отрисовки, — имена
+* сеток есть уже в серверной разметке.
+*/
+var TCalendarIdsPlugin = class extends TBasePlugin {
+	install(ctx) {
+		super.install(ctx);
+		ctx.get(TCollectionBundlesPlugin)?.events.on("engine:bound", (engine) => {
+			const { view, picker } = engine.extensions;
+			const name = () => {
+				view.months.forEach((_, index) => {
+					const titleId = ctx.createId(`title-${index}`);
+					const sets = view.gridSets(index);
+					sets.title.add("id", titleId);
+					sets.grid.add("aria-labelledby", titleId);
+					picker.pickerSets(index).heading.add("id", ctx.createId(`picker-${index}`));
+				});
+			};
+			name();
+			this._listenTo(view.events, "change:months", name);
+		});
+	}
+};
+//#endregion
+export { TCalendarIdsPlugin };

package/dist/custom/calendar/ids/index.d.ts

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

package/dist/custom/calendar/index.d.ts

@@ -0,0 +1,5 @@
+export * from './ids';
+export * from './keyboard';
+export * from './pointer';
+export * from './names';
+export { gridStopOf } from './stop';

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

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

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

@@ -0,0 +1,114 @@
+import type { ICalendar } from '@soxa-ui/core';
+import { TBasePlugin } from '../../../base';
+import type { IPluginContext } from '../../../base';
+import type { TCalendarKeyboardPluginEvents } from './types';
+/**
+ * TCalendarKeyboardPlugin — клавиатура календаря по APG (Date Picker Dialog)
+ * и DOM-фокус, который идёт за фокусом коллекции.
+ *
+ * Все сетки — одна остановка Tab (roving tabindex): `tabindex` дней пишет
+ * расширение фокуса коллекции, потому что атрибут обязан стоять с первой
+ * отрисовки, включая серверную. Здесь только то, что требует DOM: слушатели
+ * на корне и перенос фокуса.
+ *
+ * **Клавиши** берутся только с самой ячейки дня: у содержимого слота дня свои
+ * клавиши. Переходы (`MOVES`) — команды расширения фокуса, Enter и пробел —
+ * выбор дня, Escape — отмена начатого диапазона, и только когда якорь стоит:
+ * без него клавиша не наша, её ждёт панель DatePicker. Обработанная клавиша
+ * гасится `preventDefault`, а не `stopPropagation`. Перед переходом плагин
+ * снимает день под указателем: предпросмотр диапазона идёт за клавишами, а не
+ * за указателем, который остался где был.
+ *
+ * Enter и пробел на ячейке — только здесь: `click` из них браузер у `td` не
+ * делает, а плагин указателя слушает нажатия, так что день выбирается один раз.
+ *
+ * **Фокус.** `focusin` на дне сообщает фокусу коллекции день — от клавиш,
+ * нажатия и `focus()` из кода, одним путём. Обратно — `change:focusedDate`:
+ * если DOM-фокус стоял на дне, он переходит на день новой даты. Узла этого
+ * дня может ещё не быть — PageDown увёл сетку в новый месяц, а разметка его
+ * ещё не нарисовала. Тогда плагин ждёт узла помощником реестра узлов
+ * (`TCollectionElements.waitFor`): на регистрацию дня в коллекции и на
+ * `ready` его узла. Ждёт он день с фокусом коллекции на момент прихода узла,
+ * а не дату, запомненную заранее: ожидание одно, и фокус, сменившийся за
+ * время ожидания, его заменяет. Снимают ожидание фокус, ушедший из
+ * календаря, фокус на не-дне и `destroy()`.
+ *
+ * Фокус на кнопке листания остаётся на ней: листание двигает фокус коллекции
+ * вместе с сеткой, но не DOM. Кроме случая, когда кнопка погасла у края под
+ * фокусом (`change:paging`): выключенная кнопка фокус теряет, и он упал бы на
+ * страницу, поэтому плагин переводит его на остановку сетки, как React Aria.
+ *
+ * То же у стрелок панели выбора месяца и года (`change:pickers`): стрелка
+ * погасла у границы лет под фокусом — фокус на список той же панели. Решает
+ * выход расширения, а не атрибут: разметка выключит кнопку позже, а фокус
+ * должен уйти с неё раньше.
+ */
+export declare class TCalendarKeyboardPlugin extends TBasePlugin<ICalendar, TCalendarKeyboardPluginEvents> {
+    private _owner;
+    /** Корень: на нём слушатели, по нему же направление письма. */
+    private _root;
+    private _elements;
+    private _engine;
+    /**
+     * Снять ожидание узла дня с фокусом коллекции; `null` — DOM-фокус узла не
+     * ждёт.
+     */
+    private _waiting;
+    install(ctx: IPluginContext): void;
+    destroy(): void;
+    private _bindEngine;
+    /** Корень сменился — слушатели переезжают, ожидание узла прежнего корня снимается. */
+    private _bind;
+    private readonly _onKeyDown;
+    /**
+     * Фокус пришёл на день — фокус коллекции переходит к нему: один путь для
+     * клавиш (их `focus()` тоже даёт `focusin`), нажатия и `focus()` из кода.
+     * Фокус пришёл не на день — ожидание узла больше не нужно: пользователь
+     * уже там, куда ушёл.
+     */
+    private readonly _onFocusIn;
+    /**
+     * Фокус ушёл из календаря — ожидание снимается. Без `relatedTarget` фокус
+     * ушёл «никуда»: узел дня с фокусом убрала разметка или кнопка погасла под
+     * фокусом, — тогда ожидание как раз и нужно.
+     */
+    private readonly _onFocusOut;
+    /**
+     * Фокус коллекции перешёл — DOM-фокус идёт за ним, если стоял на дне или
+     * уже ждал узла: тогда он ждёт уже новый день. Без корня — выход: до узла
+     * DOM-фокуса нет, а ожидание снимает `_bind`. Событие приходит и при сборке
+     * на сервере — смена месяцев и границ двигает фокус, — а проверке узла там
+     * не на что опереться: в Node типов DOM нет.
+     */
+    private readonly _onFocusedDate;
+    /**
+     * Кнопка листания погасла, пока на ней фокус, — фокус на остановку сетки.
+     * У выключенного календаря остановки нет, и переносить некуда.
+     */
+    private readonly _onPaging;
+    /**
+     * Стрелка панели выбора погасла, пока на ней фокус, — фокус на список панели.
+     * Список — ListBox, и остановка Tab у него — узел списка (`pickerListOf`),
+     * а не корень с классом части календаря. Без корня — выход, как у листания:
+     * `change:pickers` приходит уже при сборке — плагины связок и имён пишут
+     * наборы мест, — а DOM-фокуса до узла нет.
+     */
+    private readonly _onPickers;
+    /**
+     * DOM-фокус — на день с фокусом коллекции; узла ещё нет — ждать его
+     * помощником реестра узлов: день войдёт в коллекцию, и его узел объявят.
+     */
+    private _follow;
+    /**
+     * Узел дня с фокусом коллекции в документе — ожидание снято, фокус на нём.
+     * Нашёлся ли узел — ответ для помощника ожидания: `false` — ждать дальше.
+     */
+    private _focusFollowed;
+    private _stopFollowing;
+    private get _activeElement();
+    /**
+     * Направление письма берётся вычисленным: `direction` компонента бывает
+     * `inherit`, и тогда его задаёт предок.
+     */
+    private get _rtl();
+}

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

@@ -0,0 +1,249 @@
+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 { isFocusableElement } from "../../../utils/isFocusableElement.js";
+import { dayElementOf, dayOf, pagerOf, pickerListOf, pickerPartOf } from "../parts.js";
+//#region src/custom/calendar/keyboard/keyboard.plugin.ts
+/**
+* Переходы фокуса по клавишам — APG, Date Picker Dialog: ←/→ — день, ↑/↓ —
+* неделя, Home/End — края недели, PageUp/PageDown — месяц, с Shift — год.
+* Даты считает расширение фокуса, клавиша только называет команду.
+*/
+var MOVES = {
+	ArrowLeft: (focus, { rtl }) => focus.shiftFocus("day", rtl ? 1 : -1),
+	ArrowRight: (focus, { rtl }) => focus.shiftFocus("day", rtl ? -1 : 1),
+	ArrowUp: (focus) => focus.shiftFocus("week", -1),
+	ArrowDown: (focus) => focus.shiftFocus("week", 1),
+	Home: (focus) => focus.moveFocusToEdge("start"),
+	End: (focus) => focus.moveFocusToEdge("end"),
+	PageUp: (focus, { shift }) => focus.shiftFocus(shift ? "year" : "month", -1),
+	PageDown: (focus, { shift }) => focus.shiftFocus(shift ? "year" : "month", 1)
+};
+/** Клавиши выбора дня под фокусом. */
+var CHOOSE_KEYS = /* @__PURE__ */ new Set(["Enter", " "]);
+/** Погасла ли кнопка листания — по выходу вида коллекции. */
+var PAGER_OFF = {
+	prev: (view) => view.prevDisabled,
+	next: (view) => view.nextDisabled
+};
+/**
+* TCalendarKeyboardPlugin — клавиатура календаря по APG (Date Picker Dialog)
+* и DOM-фокус, который идёт за фокусом коллекции.
+*
+* Все сетки — одна остановка Tab (roving tabindex): `tabindex` дней пишет
+* расширение фокуса коллекции, потому что атрибут обязан стоять с первой
+* отрисовки, включая серверную. Здесь только то, что требует DOM: слушатели
+* на корне и перенос фокуса.
+*
+* **Клавиши** берутся только с самой ячейки дня: у содержимого слота дня свои
+* клавиши. Переходы (`MOVES`) — команды расширения фокуса, Enter и пробел —
+* выбор дня, Escape — отмена начатого диапазона, и только когда якорь стоит:
+* без него клавиша не наша, её ждёт панель DatePicker. Обработанная клавиша
+* гасится `preventDefault`, а не `stopPropagation`. Перед переходом плагин
+* снимает день под указателем: предпросмотр диапазона идёт за клавишами, а не
+* за указателем, который остался где был.
+*
+* Enter и пробел на ячейке — только здесь: `click` из них браузер у `td` не
+* делает, а плагин указателя слушает нажатия, так что день выбирается один раз.
+*
+* **Фокус.** `focusin` на дне сообщает фокусу коллекции день — от клавиш,
+* нажатия и `focus()` из кода, одним путём. Обратно — `change:focusedDate`:
+* если DOM-фокус стоял на дне, он переходит на день новой даты. Узла этого
+* дня может ещё не быть — PageDown увёл сетку в новый месяц, а разметка его
+* ещё не нарисовала. Тогда плагин ждёт узла помощником реестра узлов
+* (`TCollectionElements.waitFor`): на регистрацию дня в коллекции и на
+* `ready` его узла. Ждёт он день с фокусом коллекции на момент прихода узла,
+* а не дату, запомненную заранее: ожидание одно, и фокус, сменившийся за
+* время ожидания, его заменяет. Снимают ожидание фокус, ушедший из
+* календаря, фокус на не-дне и `destroy()`.
+*
+* Фокус на кнопке листания остаётся на ней: листание двигает фокус коллекции
+* вместе с сеткой, но не DOM. Кроме случая, когда кнопка погасла у края под
+* фокусом (`change:paging`): выключенная кнопка фокус теряет, и он упал бы на
+* страницу, поэтому плагин переводит его на остановку сетки, как React Aria.
+*
+* То же у стрелок панели выбора месяца и года (`change:pickers`): стрелка
+* погасла у границы лет под фокусом — фокус на список той же панели. Решает
+* выход расширения, а не атрибут: разметка выключит кнопку позже, а фокус
+* должен уйти с неё раньше.
+*/
+var TCalendarKeyboardPlugin = class extends TBasePlugin {
+	_owner = null;
+	/** Корень: на нём слушатели, по нему же направление письма. */
+	_root = null;
+	_elements = null;
+	_engine = null;
+	/**
+	* Снять ожидание узла дня с фокусом коллекции; `null` — DOM-фокус узла не
+	* ждёт.
+	*/
+	_waiting = null;
+	install(ctx) {
+		super.install(ctx);
+		this._owner = ctx.getInstance() ?? null;
+		this._elements = ctx.get(TCollectionElements) ?? null;
+		const elementPlugin = ctx.get(TElementPlugin);
+		elementPlugin?.events.on("ready", (element) => this._bind(element));
+		elementPlugin?.events.on("removed", () => this._bind(null));
+		ctx.get(TCollectionBundlesPlugin)?.events.on("engine:bound", (engine) => this._bindEngine(engine));
+	}
+	destroy() {
+		this._bind(null);
+		this._owner = null;
+		this._elements = null;
+		this._engine = null;
+		super.destroy();
+	}
+	_bindEngine(engine) {
+		this._engine = engine;
+		this._listenTo(engine.extensions.focus.events, "change:focusedDate", this._onFocusedDate);
+		this._listenTo(engine.extensions.view.events, "change:paging", this._onPaging);
+		this._listenTo(engine.extensions.picker.events, "change:pickers", this._onPickers);
+	}
+	/** Корень сменился — слушатели переезжают, ожидание узла прежнего корня снимается. */
+	_bind(root) {
+		const previous = this._root;
+		previous?.removeEventListener("keydown", this._onKeyDown);
+		previous?.removeEventListener("focusin", this._onFocusIn);
+		previous?.removeEventListener("focusout", this._onFocusOut);
+		this._stopFollowing();
+		this._root = root;
+		const target = root;
+		target?.addEventListener("keydown", this._onKeyDown);
+		target?.addEventListener("focusin", this._onFocusIn);
+		target?.addEventListener("focusout", this._onFocusOut);
+	}
+	_onKeyDown = (event) => {
+		if (event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey) return;
+		const engine = this._engine;
+		const day = engine ? dayOf(engine, this._elements, event.target) : void 0;
+		if (!engine || !day || day.element !== event.target) return;
+		const { focus, selection } = engine.extensions;
+		if (CHOOSE_KEYS.has(event.key)) {
+			event.preventDefault();
+			selection.chooseDate(day.item.date);
+			return;
+		}
+		if (event.key === "Escape") {
+			if (selection.anchor === void 0) return;
+			event.preventDefault();
+			selection.cancelRange();
+			return;
+		}
+		const move = MOVES[event.key];
+		if (!move) return;
+		event.preventDefault();
+		selection.notifyHover(void 0);
+		move(focus, {
+			rtl: this._rtl,
+			shift: event.shiftKey
+		});
+	};
+	/**
+	* Фокус пришёл на день — фокус коллекции переходит к нему: один путь для
+	* клавиш (их `focus()` тоже даёт `focusin`), нажатия и `focus()` из кода.
+	* Фокус пришёл не на день — ожидание узла больше не нужно: пользователь
+	* уже там, куда ушёл.
+	*/
+	_onFocusIn = (event) => {
+		const engine = this._engine;
+		if (!engine) return;
+		const day = dayOf(engine, this._elements, event.target);
+		if (!day) {
+			this._stopFollowing();
+			return;
+		}
+		engine.extensions.focus.focusDate(day.item.date);
+	};
+	/**
+	* Фокус ушёл из календаря — ожидание снимается. Без `relatedTarget` фокус
+	* ушёл «никуда»: узел дня с фокусом убрала разметка или кнопка погасла под
+	* фокусом, — тогда ожидание как раз и нужно.
+	*/
+	_onFocusOut = (event) => {
+		const next = event.relatedTarget;
+		if (next instanceof Node && !this._root?.contains(next)) this._stopFollowing();
+	};
+	/**
+	* Фокус коллекции перешёл — DOM-фокус идёт за ним, если стоял на дне или
+	* уже ждал узла: тогда он ждёт уже новый день. Без корня — выход: до узла
+	* DOM-фокуса нет, а ожидание снимает `_bind`. Событие приходит и при сборке
+	* на сервере — смена месяцев и границ двигает фокус, — а проверке узла там
+	* не на что опереться: в Node типов DOM нет.
+	*/
+	_onFocusedDate = () => {
+		const engine = this._engine;
+		if (!engine || !this._root) return;
+		if (this._waiting || dayOf(engine, this._elements, this._activeElement)) this._follow();
+	};
+	/**
+	* Кнопка листания погасла, пока на ней фокус, — фокус на остановку сетки.
+	* У выключенного календаря остановки нет, и переносить некуда.
+	*/
+	_onPaging = () => {
+		const engine = this._engine;
+		const owner = this._owner;
+		const root = this._root;
+		if (!engine || !owner || !root || owner.disabled) return;
+		const pager = pagerOf(owner, root, this._activeElement);
+		if (pager && PAGER_OFF[pager](engine.extensions.view)) this._follow();
+	};
+	/**
+	* Стрелка панели выбора погасла, пока на ней фокус, — фокус на список панели.
+	* Список — ListBox, и остановка Tab у него — узел списка (`pickerListOf`),
+	* а не корень с классом части календаря. Без корня — выход, как у листания:
+	* `change:pickers` приходит уже при сборке — плагины связок и имён пишут
+	* наборы мест, — а DOM-фокуса до узла нет.
+	*/
+	_onPickers = () => {
+		const engine = this._engine;
+		const owner = this._owner;
+		if (!engine || !owner || !this._root) return;
+		const pickers = engine.extensions.picker.pickers;
+		const hit = pickerPartOf(owner, pickers, this._activeElement);
+		const picker = hit ? pickers[hit.index] : void 0;
+		if (!hit || !picker || hit.part === "heading") return;
+		if (!(hit.part === "prev" ? picker.prevDisabled : picker.nextDisabled)) return;
+		const list = pickerListOf(owner, hit.panel);
+		if (isFocusableElement(list)) list.focus();
+	};
+	/**
+	* DOM-фокус — на день с фокусом коллекции; узла ещё нет — ждать его
+	* помощником реестра узлов: день войдёт в коллекцию, и его узел объявят.
+	*/
+	_follow() {
+		this._stopFollowing();
+		if (this._focusFollowed()) return;
+		this._waiting = this._elements?.waitFor(() => this._focusFollowed()) ?? null;
+	}
+	/**
+	* Узел дня с фокусом коллекции в документе — ожидание снято, фокус на нём.
+	* Нашёлся ли узел — ответ для помощника ожидания: `false` — ждать дальше.
+	*/
+	_focusFollowed() {
+		const engine = this._engine;
+		const element = engine ? dayElementOf(engine, this._elements, engine.extensions.focus.focusedDate) : null;
+		if (!element) return false;
+		this._stopFollowing();
+		if (!element.contains(this._activeElement) && isFocusableElement(element)) element.focus();
+		return true;
+	}
+	_stopFollowing() {
+		const stop = this._waiting;
+		this._waiting = null;
+		stop?.();
+	}
+	get _activeElement() {
+		return this._root?.ownerDocument.activeElement ?? null;
+	}
+	/**
+	* Направление письма берётся вычисленным: `direction` компонента бывает
+	* `inherit`, и тогда его задаёт предок.
+	*/
+	get _rtl() {
+		return this._root !== null && getComputedStyle(this._root).direction === "rtl";
+	}
+};
+//#endregion
+export { TCalendarKeyboardPlugin };

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

@@ -0,0 +1,16 @@
+import type { ICalendarFocusExtension } from '@soxa-ui/core';
+import type { TPluginEvents } from '../../../base';
+/**
+ * Своих событий у плагина нет: результат нажатия виден и так — фокус сообщает
+ * DOM, выбор и фокус сетки — расширения коллекции.
+ */
+export type TCalendarKeyboardPluginEvents = TPluginEvents;
+/** Что клавише нужно знать, кроме фокуса: направление письма и Shift. */
+export type TCalendarMoveContext = {
+    /** Правое-левое письмо: ←/→ меняются местами */
+    rtl: boolean;
+    /** С Shift PageUp/PageDown листают год, а не месяц */
+    shift: boolean;
+};
+/** Переход фокуса сетки по клавише — команда расширения фокуса. */
+export type TCalendarMove = (focus: ICalendarFocusExtension, context: TCalendarMoveContext) => void;

package/dist/custom/calendar/names/index.d.ts

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

package/dist/custom/calendar/names/names.plugin.d.ts

@@ -0,0 +1,24 @@
+import type { ICalendar } from '@soxa-ui/core';
+import { TNamesPlugin } from '../../../locale/names.plugin';
+import type { IPluginContext } from '../../../base';
+import type { TTranslations } from '../../../locale/types';
+/**
+ * TCalendarNamesPlugin — имена кнопок календаря от локали.
+ *
+ * Кнопки листания месяцев — в наборы календаря (`prevAria`, `nextAria`).
+ * Стрелки панели выбора месяца и года — в наборы мест панели
+ * (`pickerSets` расширения `picker`), по уровню места: на месяцах стрелка
+ * листает год, на годах — страницу из 12 лет. Уровень сменился, мест стало
+ * больше (`change:pickers`) — имена переписываются; та же строка в наборе
+ * ничего не меняет, поэтому запись из этого события в него же не
+ * возвращается.
+ *
+ * Движок привязывается при сборке (`engine:bound`), до первой отрисовки, —
+ * имена стрелок есть уже в серверной разметке.
+ */
+export declare class TCalendarNamesPlugin extends TNamesPlugin<ICalendar> {
+    private _engine;
+    protected _name(owner: ICalendar, translations: TTranslations): void;
+    protected _watch(_owner: ICalendar, name: () => void, ctx: IPluginContext): void;
+    destroy(): void;
+}

package/dist/custom/calendar/names/names.plugin.js

@@ -0,0 +1,45 @@
+import { TCollectionBundlesPlugin } from "../../collection/bundles.plugin.js";
+import { TNamesPlugin } from "../../../locale/names.plugin.js";
+//#region src/custom/calendar/names/names.plugin.ts
+/**
+* TCalendarNamesPlugin — имена кнопок календаря от локали.
+*
+* Кнопки листания месяцев — в наборы календаря (`prevAria`, `nextAria`).
+* Стрелки панели выбора месяца и года — в наборы мест панели
+* (`pickerSets` расширения `picker`), по уровню места: на месяцах стрелка
+* листает год, на годах — страницу из 12 лет. Уровень сменился, мест стало
+* больше (`change:pickers`) — имена переписываются; та же строка в наборе
+* ничего не меняет, поэтому запись из этого события в него же не
+* возвращается.
+*
+* Движок привязывается при сборке (`engine:bound`), до первой отрисовки, —
+* имена стрелок есть уже в серверной разметке.
+*/
+var TCalendarNamesPlugin = class extends TNamesPlugin {
+	_engine = null;
+	_name(owner, translations) {
+		const names = translations.calendar;
+		owner.prevAria.add("aria-label", names.prevMonth);
+		owner.nextAria.add("aria-label", names.nextMonth);
+		const picker = this._engine?.extensions.picker;
+		picker?.pickers.forEach(({ level }, index) => {
+			const sets = picker.pickerSets(index);
+			const months = level === "months";
+			sets.prev.add("aria-label", months ? names.prevYear : names.prevYears);
+			sets.next.add("aria-label", months ? names.nextYear : names.nextYears);
+		});
+	}
+	_watch(_owner, name, ctx) {
+		ctx.get(TCollectionBundlesPlugin)?.events.on("engine:bound", (engine) => {
+			this._engine = engine;
+			name();
+			this._listenTo(engine.extensions.picker.events, "change:pickers", name);
+		});
+	}
+	destroy() {
+		this._engine = null;
+		super.destroy();
+	}
+};
+//#endregion
+export { TCalendarNamesPlugin };

package/dist/custom/calendar/parts.d.ts

@@ -0,0 +1,58 @@
+import type { ICalendar, TCalendarCollection, TCalendarDate, TCalendarPicker } from '@soxa-ui/core';
+import type { TCollectionElements } from '../collection';
+import type { TCalendarDay, TCalendarPager, TCalendarPickerHit } from './types';
+/**
+ * День календаря, в узле которого лежит `target`, — один поиск на оба плагина
+ * календаря: клавиша, фокус, нажатие и наведение находят день одинаково.
+ *
+ * Узел дня — его корень, ячейка сетки; внутри неё плитка и содержимое слота,
+ * и событие с них — тоже событие дня. Кому нужна сама ячейка (клавиши берутся
+ * только с неё), сверяет `element` с целью события. Заполнитель соседнего
+ * месяца днём не бывает: элемента коллекции у него нет, и узла среди узлов
+ * дней — тоже.
+ */
+export declare function dayOf(engine: TCalendarCollection, elements: TCollectionElements | null, target: EventTarget | null): TCalendarDay | undefined;
+/** Узел дня с такой датой, пока он в документе. */
+export declare function dayElementOf(engine: TCalendarCollection, elements: TCollectionElements | null, date: TCalendarDate): Element | null;
+/**
+ * Кнопка шапки панели выбора месяца и года, в которой лежит `target`, панель
+ * этой кнопки и место панели среди `pickers` — один поиск на оба плагина
+ * календаря.
+ *
+ * Своей панель делает шапка места (`holdsHeading`). Части находят по классам
+ * владельца (`classes.resolve`), как кнопки листания.
+ */
+export declare function pickerPartOf(owner: ICalendar, pickers: readonly TCalendarPicker[], target: EventTarget | null): TCalendarPickerHit | undefined;
+/**
+ * Карточка панели выбора места `picker` в корне — ту же карточку отдаёт
+ * `pickerPartOf` от кнопки её шапки. Своей её делает шапка места
+ * (`holdsHeading`), часть находят по классу владельца (`classes.resolve`).
+ * `null` — карточки в документе нет: содержимое поповера не смонтировано до
+ * первого открытия.
+ */
+export declare function pickerPanelOf(owner: ICalendar, root: Element, picker: TCalendarPicker): Element | null;
+/**
+ * Список карточки панели выбора — узел списка ListBox (`listOf`): остановка
+ * Tab у списка — он, а не корень ListBox с классом части календаря. `null` —
+ * карточки или списка в ней нет.
+ *
+ * Один на клавиатуру календаря (кому отдать фокус со стрелки, погасшей у
+ * границы лет) и остановку календаря, пока панель открыта (`gridStopOf`).
+ */
+export declare function pickerListOf(owner: ICalendar, panel: Element | null): Element | null;
+/**
+ * Место, чья подложка — `target`; `target` не подложка — `undefined`.
+ *
+ * Подложка — сама панель поповера места, а не узел в ней: панель накрывает
+ * календарь, а выбирают в её содержимом, и у нажатия мимо содержимого цель —
+ * панель. Псевдоэлемент панели — тоже панель: у нажатия по нему та же цель.
+ * Панель находят по классу её поповера (`classes.resolve`), своей её делает
+ * шапка места (`holdsHeading`).
+ */
+export declare function pickerBackdropOf(pickers: readonly TCalendarPicker[], target: EventTarget | null): number | undefined;
+/**
+ * Кнопка листания, в которой лежит `target`. Кнопки находят по классам
+ * владельца (`classes.resolve`), а не строкой в плагине, и только внутри его
+ * корня.
+ */
+export declare function pagerOf(owner: ICalendar, root: Element, target: EventTarget | null): TCalendarPager | undefined;