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

package/dist/custom/slide/pointer/strategies/points.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Доля в пределах хода: за краем — край. Указатель за краем дорожки ведёт
+ * ручку за край хода (`fractionAt` долю не прижимает), но стоит она на краю.
+ */
+export declare function withinTravel(fraction: number): number;
+/**
+ * Ближайшая к `target` точка не дальше `radius`; поровну от двух — меньшая.
+ * Такой нет — `undefined`.
+ */
+export declare function nearestPoint(points: readonly number[], target: number, radius: number): number | undefined;
+/**
+ * Первая точка на пути ручки от `from` к `to` — пройденная или достигнутая.
+ * Точка, от которой путь начался, не в счёт: ручка с неё уходит. Пути нет
+ * или точек на нём нет — `undefined`.
+ */
+export declare function crossedPoint(points: readonly number[], from: number, to: number): number | undefined;

package/dist/custom/slide/pointer/strategies/points.js

@@ -0,0 +1,32 @@
+//#region src/custom/slide/pointer/strategies/points.ts
+/**
+* Доля в пределах хода: за краем — край. Указатель за краем дорожки ведёт
+* ручку за край хода (`fractionAt` долю не прижимает), но стоит она на краю.
+*/
+function withinTravel(fraction) {
+	return Math.min(1, Math.max(0, fraction));
+}
+/**
+* Ближайшая к `target` точка не дальше `radius`; поровну от двух — меньшая.
+* Такой нет — `undefined`.
+*/
+function nearestPoint(points, target, radius) {
+	let nearest;
+	for (const point of points) {
+		const distance = Math.abs(point - target);
+		if (distance > radius) continue;
+		if (nearest === void 0 || distance < Math.abs(nearest - target)) nearest = point;
+	}
+	return nearest;
+}
+/**
+* Первая точка на пути ручки от `from` к `to` — пройденная или достигнутая.
+* Точка, от которой путь начался, не в счёт: ручка с неё уходит. Пути нет
+* или точек на нём нет — `undefined`.
+*/
+function crossedPoint(points, from, to) {
+	if (to > from) return points.find((point) => point > from && point <= to);
+	return points.filter((point) => point < from && point >= to).at(-1);
+}
+//#endregion
+export { crossedPoint, nearestPoint, withinTravel };

package/dist/custom/slide/pointer/strategies/settle.strategy.d.ts

@@ -0,0 +1,11 @@
+import { TSlideSnapStrategy } from './base.strategy';
+/**
+ * TSettleSnapStrategy — доводка (`settle`): пока тянут, ручка идёт за
+ * указателем; отпустили в радиусе метки — ручка доезжает до неё.
+ *
+ * Доводит уже не жест: владелец снимает перетаскивание и ставит ручку на
+ * метку (`ISlidable.settle`), и тема довозит её своим переходом.
+ */
+export declare class TSettleSnapStrategy extends TSlideSnapStrategy {
+    release(target: number): number | undefined;
+}

package/dist/custom/slide/pointer/strategies/settle.strategy.js

@@ -0,0 +1,17 @@
+import { TSlideSnapStrategy } from "./base.strategy.js";
+import { nearestPoint } from "./points.js";
+//#region src/custom/slide/pointer/strategies/settle.strategy.ts
+/**
+* TSettleSnapStrategy — доводка (`settle`): пока тянут, ручка идёт за
+* указателем; отпустили в радиусе метки — ручка доезжает до неё.
+*
+* Доводит уже не жест: владелец снимает перетаскивание и ставит ручку на
+* метку (`ISlidable.settle`), и тема довозит её своим переходом.
+*/
+var TSettleSnapStrategy = class extends TSlideSnapStrategy {
+	release(target) {
+		return nearestPoint(this._points, target, this._radius);
+	}
+};
+//#endregion
+export { TSettleSnapStrategy };

package/dist/custom/slide/pointer/strategies/types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Что стратегия щелчка знает о жесте. Всё — доли хода ручки в направлении
+ * роста, как у владельца (`ISlidable`): 0 — у `min`, 1 — у `max`.
+ */
+export type TSlideSnapContext = {
+    /** Точки щелчка — доли меток по возрастанию, без повторов */
+    readonly points: readonly number[];
+    /** Радиус щелчка — доля хода: радиус в px на длину дорожки */
+    readonly radius: number;
+    /**
+     * Где ручка в начале жеста: у захвата — где она стоит, у нажатия мимо
+     * ручек — точка нажатия
+     */
+    readonly anchor: number;
+    /** Сколько мс ручка стоит на пересечённой метке — у задержки (`hold`) */
+    readonly holdDelay: number;
+};
+/**
+ * Стратегия щелчка — одна на режим (`TSlideSnap`) и новая на каждый жест:
+ * у плато и задержки есть память жеста.
+ *
+ * Стратегия видит ручку, а не указатель. На входе — куда встала бы ручка без
+ * щелчка: указатель со смещением захвата. На выходе — куда ей встать. Не
+ * вмешалась — отдаёт вход как есть.
+ */
+export interface ISlideSnapStrategy {
+    /**
+     * Когда стратегии снова нужна ручка, хотя указатель стоит на месте, — конец
+     * стоянки на метке, мс по часам `performance.now()`. Ждать нечего —
+     * `undefined`
+     */
+    readonly wakeAt: number | undefined;
+    /**
+     * Куда встать ручке. `target` — где она была бы без щелчка, `now` — время,
+     * мс по часам `performance.now()`
+     */
+    follow(target: number, now: number): number;
+    /**
+     * Ручку отпустили там, где без щелчка она стояла бы в `target`: куда её
+     * довести. Оставить, где отпустили, — `undefined`
+     */
+    release(target: number): number | undefined;
+}
+/** Конструктор стратегии: плагин заводит по нему стратегию на каждый жест. */
+export type TSlideSnapStrategyCtor = new (context: TSlideSnapContext) => ISlideSnapStrategy;
+/**
+ * Узел ломаной плато: где ручка была бы без щелчка → где она встаёт. Между
+ * узлами — прямая, на плато у двух соседних узлов одно и то же «встаёт».
+ */
+export type TPlateauKnot = readonly [target: number, placed: number];
+/** Стоянка ручки на метке — у задержки. */
+export type THoldStop = {
+    /** Метка, на которой стоит ручка */
+    readonly point: number;
+    /** До какого времени, мс по часам `performance.now()` */
+    readonly until: number;
+};

package/dist/custom/slide/pointer/types.d.ts

@@ -0,0 +1,46 @@
+import type { TPluginEvents } from '../../../base';
+import type { TSlideDirection } from '../types';
+import type { ISlideSnapStrategy } from './strategies';
+/**
+ * Своих событий у плагина нет: результат жеста виден через владельца —
+ * значение, `dragging` и `commit` сообщает он. Второй путь к тем же фактам
+ * через события плагина разошёлся бы с первым.
+ */
+export type TSlidePointerPluginEvents = TPluginEvents;
+export interface ISlidePointerPluginOptions {
+    /**
+     * Сколько мс ручка стоит на пересечённой метке в режиме щелчка `hold`,
+     * прежде чем догнать указатель. По умолчанию — 250: столько хватает, чтобы
+     * заметить остановку и отпустить ручку на метке, а тянуть дальше ещё не
+     * мешает.
+     */
+    holdDelay?: number;
+}
+/** Жест, который ведёт плагин: от нажатия до отпускания. */
+export type TSlidePointerGesture = {
+    /** `pointerId` указателя жеста: чужие указатели его не двигают */
+    pointer: number;
+    /** Дорожка: по её коробке указатель переводится в долю хода */
+    track: Element;
+    /** Направление роста — на весь жест, вычислено при нажатии */
+    direction: TSlideDirection;
+    /** Стратегия щелчка — по режиму владельца на момент нажатия */
+    snap: ISlideSnapStrategy;
+    /** Доля указателя при нажатии */
+    origin: number;
+    /**
+     * Доля ручки при нажатии: у захвата — где она стоит, у нажатия мимо ручек —
+     * точка нажатия. Без щелчка ручка сдвигается на столько же, на сколько
+     * указатель от `origin`
+     */
+    anchor: number;
+    /** Последняя доля указателя */
+    at: number;
+    /**
+     * Куда плагин поставил ручку последним шагом. Щелчок отдал ту же долю —
+     * ядру сообщать нечего
+     */
+    placed: number;
+};
+/** Начало жеста — то, что известно до того, как владелец его принял. */
+export type TSlidePointerStart = Pick<TSlidePointerGesture, 'pointer' | 'track' | 'direction' | 'origin'>;

package/dist/custom/slide/types.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Откуда растёт значение — сторона хода, у которой `min`.
+ *
+ * Одно понятие на указатель и клавиатуру (`SlideDirection` у Radix): ось,
+ * вычисленное направление письма и `inverted` сводятся в него один раз, и
+ * дальше плагины о них не спрашивают. По нему указатель переводит точку в
+ * долю хода, а клавиатура решает, какая стрелка ведёт к `min`.
+ */
+export type TSlideDirection = 'from-left' | 'from-right' | 'from-bottom' | 'from-top';
+/** Точка указателя в координатах окна — то, что есть у `PointerEvent`. */
+export type TSlidePoint = {
+    clientX: number;
+    clientY: number;
+};

package/dist/custom/table/column-ids/column-ids.plugin.d.ts

@@ -0,0 +1,26 @@
+import { TBasePlugin } from '../../../base';
+import type { IPluginContext } from '../../../base';
+/**
+ * TTableColumnIdsPlugin — имя заголовка колонки и её ручки в документе.
+ *
+ * Своё имя у заголовка браузер собрал бы из всего содержимого ячейки, а в ней
+ * стоят поле ручки ширины (`input type="range"`) и кнопка сортировки:
+ * значение встроенного контрола входит в имя (accname 1.2), и заголовок
+ * звался бы «Имя 150», а имя кнопки дописало бы к нему «Sort by Имя».
+ * Поэтому заголовок назван подписью явно — ссылкой на неё, — и той же
+ * ссылкой назван ползунок ручки: имя у обоих — ровно подпись колонки, без
+ * строк библиотеки.
+ *
+ * Всё — в наборах колонки: `id` — в `textAria` (он стоит на подписи), ссылка —
+ * в `aria` (на заголовке) и в `resizerAria` (на поле ручки). Формула одна,
+ * здесь.
+ *
+ * `id` — от монтирования заголовка (`createId`), а не от экземпляра: он нужен
+ * только документу, и на сервере и в браузере обязан совпасть. Колонку таблица
+ * рисует с готовым экземпляром (`ctrl`), и его конструктор адаптер не зовёт, а
+ * монтирование у неё своё. Пишется при установке, синхронно, — имя есть уже в
+ * первой (и серверной) отрисовке.
+ */
+export declare class TTableColumnIdsPlugin extends TBasePlugin {
+    install(ctx: IPluginContext): void;
+}

package/dist/custom/table/column-ids/column-ids.plugin.js

@@ -0,0 +1,36 @@
+import { TBasePlugin } from "../../../base/base.class.js";
+//#region src/custom/table/column-ids/column-ids.plugin.ts
+/**
+* TTableColumnIdsPlugin — имя заголовка колонки и её ручки в документе.
+*
+* Своё имя у заголовка браузер собрал бы из всего содержимого ячейки, а в ней
+* стоят поле ручки ширины (`input type="range"`) и кнопка сортировки:
+* значение встроенного контрола входит в имя (accname 1.2), и заголовок
+* звался бы «Имя 150», а имя кнопки дописало бы к нему «Sort by Имя».
+* Поэтому заголовок назван подписью явно — ссылкой на неё, — и той же
+* ссылкой назван ползунок ручки: имя у обоих — ровно подпись колонки, без
+* строк библиотеки.
+*
+* Всё — в наборах колонки: `id` — в `textAria` (он стоит на подписи), ссылка —
+* в `aria` (на заголовке) и в `resizerAria` (на поле ручки). Формула одна,
+* здесь.
+*
+* `id` — от монтирования заголовка (`createId`), а не от экземпляра: он нужен
+* только документу, и на сервере и в браузере обязан совпасть. Колонку таблица
+* рисует с готовым экземпляром (`ctrl`), и его конструктор адаптер не зовёт, а
+* монтирование у неё своё. Пишется при установке, синхронно, — имя есть уже в
+* первой (и серверной) отрисовке.
+*/
+var TTableColumnIdsPlugin = class extends TBasePlugin {
+	install(ctx) {
+		super.install(ctx);
+		const column = ctx.getInstance();
+		if (!column) return;
+		const textId = ctx.createId("text");
+		column.textAria.add("id", textId);
+		column.aria.add("aria-labelledby", textId);
+		column.resizerAria.add("aria-labelledby", textId);
+	}
+};
+//#endregion
+export { TTableColumnIdsPlugin };

package/dist/custom/table/column-ids/index.d.ts

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

package/dist/custom/table/column-names/column-names.plugin.d.ts

@@ -0,0 +1,18 @@
+import type { ITableColumn } from '@soxa-ui/core';
+import { TNamesPlugin } from '../../../locale/names.plugin';
+import type { TTranslations } from '../../../locale/types';
+/**
+ * TTableColumnNamesPlugin — имя кнопки сортировки в заголовке колонки от
+ * локали: в `sortAria`, вместе с подписью колонки, как у крестика тега
+ * (`TTagsItemNamesPlugin`).
+ *
+ * Текста у кнопки нет — в ней одна стрелка, — а подпись колонки стоит рядом,
+ * вне кнопки: заголовок назван подписью (`TTableColumnIdsPlugin`), и имя
+ * кнопки в имя заголовка не входит. Ссылкой на подпись кнопку не называют:
+ * своя кнопка потребителя в слоте заголовка с тем же текстом дала бы два
+ * одинаковых имени.
+ */
+export declare class TTableColumnNamesPlugin extends TNamesPlugin<ITableColumn> {
+    protected _name(owner: ITableColumn, translations: TTranslations): void;
+    protected _watch(owner: ITableColumn, name: () => void): void;
+}

package/dist/custom/table/column-names/column-names.plugin.js

@@ -0,0 +1,24 @@
+import { formatName } from "../../../locale/locale.js";
+import { TNamesPlugin } from "../../../locale/names.plugin.js";
+//#region src/custom/table/column-names/column-names.plugin.ts
+/**
+* TTableColumnNamesPlugin — имя кнопки сортировки в заголовке колонки от
+* локали: в `sortAria`, вместе с подписью колонки, как у крестика тега
+* (`TTagsItemNamesPlugin`).
+*
+* Текста у кнопки нет — в ней одна стрелка, — а подпись колонки стоит рядом,
+* вне кнопки: заголовок назван подписью (`TTableColumnIdsPlugin`), и имя
+* кнопки в имя заголовка не входит. Ссылкой на подпись кнопку не называют:
+* своя кнопка потребителя в слоте заголовка с тем же текстом дала бы два
+* одинаковых имени.
+*/
+var TTableColumnNamesPlugin = class extends TNamesPlugin {
+	_name(owner, translations) {
+		owner.sortAria.add("aria-label", formatName(translations.table.sort, owner.text));
+	}
+	_watch(owner, name) {
+		this._listenTo(owner.events, "change:text", name);
+	}
+};
+//#endregion
+export { TTableColumnNamesPlugin };

package/dist/custom/table/column-names/index.d.ts

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

package/dist/custom/table/column-reorder/column-reorder.plugin.d.ts

@@ -0,0 +1,169 @@
+import type { ITable } from '@soxa-ui/core';
+import { TBasePlugin } from '../../../base';
+import type { IPluginContext } from '../../../base';
+import type { TTableColumnReorderPluginEvents } from './types';
+/**
+ * TTableColumnReorderPlugin — перестановка колонок пользователем: заголовок
+ * тащат указателем или сдвигают Ctrl+Shift+←/→.
+ *
+ * Операции над DOM — здесь, место колонки — у расширения `columns` коллекции
+ * строк: плагин переводит указатель и клавиши в его команды (`dragStart`,
+ * `dragOver`, `dragDrop`, `dragEnd`, `dragCancel`, `moveColumn`). Какую
+ * колонку можно взять, куда она встанет, какие метки получат колонки и что
+ * сообщить приложению, решает расширение. Движок плагин узнаёт от реестра
+ * bundles (`engine:bound`).
+ *
+ * **Заголовки** плагин находит в шапке своей таблицы — прямыми детьми, по
+ * классам владельца и колонки: заголовков таблица рисует по одному на
+ * показанную колонку и в её порядке, поэтому место заголовка в строке шапки —
+ * место колонки среди показанных. Колонку выбора и шапки вложенных таблиц
+ * поиск не видит.
+ *
+ * **Указатель** — на корне: нажатие на заголовке колонки, которую можно
+ * взять, становится жестом, когда указатель ушёл по строке дальше порога, —
+ * до этого оно остаётся нажатием, и кнопка сортировки сортирует. Нажатие,
+ * которое уже взяли (ручка ширины гасит своё), не наше. Жест захватывает
+ * указатель на корне: протяжка за таблицей и отпускание где угодно приходят
+ * сюда, а `click` отпускания до кнопки сортировки не доходит. Касание, в
+ * отличие от мыши, браузер с нажатия сам захватывает за узлом заголовка под
+ * пальцем, и начало жеста, перенося захват на корень, этот узел захвата
+ * лишает: его `lostpointercapture` всплывает до корня. Отнятым указатель
+ * считается, только когда захват потерял сам корень.
+ *
+ * Взяв колонку, плагин снимает коробки заголовков — относительно корня, один
+ * раз — и направление строки, а потом пишет ширину взятого
+ * (`--so-table-column-shift`) туда, где её читает тема: в `head` — шапке, в
+ * `column` — корню. На неё тема сдвигает соседей, которым расширение
+ * поставило `data-shift`. Место, куда колонка встанет, плагин считает по
+ * серединам остальных заголовков из снимка, а не из документа: сдвинутые
+ * соседи не двигают пороги, и место не прыгает, а прокрутку посреди жеста
+ * учитывает коробка корня. Взятый заголовок идёт за указателем — переменная
+ * сдвига на нём.
+ *
+ * В обработчике указателя — сначала чтения, потом записи: снимок,
+ * направление и место считаются, пока стиль и раскладка те, что в кадре.
+ * Чтение после записи заставило бы браузер пересчитать стиль синхронно,
+ * прямо в обработчике, а в кадре — ещё раз. Направление строки — из снимка:
+ * стиль на шагах жеста плагин не читает.
+ *
+ * **Шапка стоит** — таблица в `none` (`dragPreview` расширения на старте
+ * жеста): ширину взятого плагин не пишет никуда, а отпускание переставляет
+ * колонку сразу, `dragEnd` (отмена — `dragCancel`), без приземления — как
+ * до живого жеста. Остальное то же: снимок, место, заголовок за указателем.
+ *
+ * **Отпустили** — колонка не переставляется сразу: расширение замораживает
+ * место (`dragDrop`, `data-landing`), а кадром позже, когда метка уже в
+ * разметке, заголовок получает сдвиг до места, где встанет, и тема довозит
+ * его переходом. Доиграл переход заголовка — `dragEnd`: перестановка и снятие
+ * меток одной операцией, и переменные сняты тут же. К этому времени заголовки
+ * и ячейки стоят там, где их поставит новая раскладка, а переходы тема
+ * выключает вместе с жестом, — ничего не отъезжает. Без движения переходов
+ * нет, и колонка встаёт через кадр. Отнятый указатель (`pointercancel` или
+ * захват, потерянный корнем) и Escape — то же приземление на своё место и
+ * `dragCancel`. Сколько ждать, решает тема — плагин режима движения не читает.
+ *
+ * Нажатие и Ctrl+Shift+←/→, пришедшие, пока заголовок приземляется,
+ * доводят приземление сразу: следующее действие видит модель и шапку в одном
+ * порядке. Заголовок под ними плагин находит до доводки — после неё модель
+ * уже в новом порядке, а шапка ещё нет.
+ *
+ * **Клавиши** — Ctrl+Shift+←/→ на заголовке под фокусом (на кнопке
+ * сортировки и поле ручки, а в Grid — на самой ячейке): шаг к началу или к
+ * концу строки по вычисленному направлению письма, в RTL ← — к концу.
+ * Таблица перерисовывает шапку, и узел под фокусом браузер при переносе мог
+ * потерять — плагин возвращает ему фокус кадром позже.
+ */
+export declare class TTableColumnReorderPlugin extends TBasePlugin<ITable, TTableColumnReorderPluginEvents> {
+    private _owner;
+    private _root;
+    private _engine;
+    private _press;
+    private _landing;
+    private _frame;
+    install(ctx: IPluginContext): void;
+    destroy(): void;
+    private _attach;
+    private _detach;
+    /** Показанные колонки — по ним разложены заголовки шапки. */
+    private get _shown();
+    /** Шапка своей таблицы — прямой ребёнок корня: у вложенной таблицы своя. */
+    private _head;
+    /**
+     * Заголовки шапки своей таблицы — по одному на показанную колонку, в её
+     * порядке. Шапка ещё не дорисовала смену колонок — заголовков нет: место
+     * в строке не совпало бы с местом колонки.
+     */
+    private _headers;
+    /** Заголовок, в котором лежит цель события, и его колонка. */
+    private _hit;
+    /** Коробки заголовков по строке — относительно корня: снимок на старте жеста. */
+    private _boxes;
+    /**
+     * Место среди показанных, куда встанет взятая колонка, — сколько остальных
+     * заголовков серединой стоят раньше указателя по строке. Середины — из
+     * снимка на старте жеста, от нынешнего края корня: заголовки, которые тема
+     * сдвинула, порогов не двигают. Свой заголовок не в счёт: он идёт за
+     * указателем. Направление строки — тоже из снимка: стиль здесь не читается.
+     */
+    private _placeAt;
+    private readonly _onPointerDown;
+    private readonly _onPointerMove;
+    /**
+     * Колонку взяли. Сначала чтения — коробки заголовков (до сдвига взятого),
+     * направление строки и место под указателем, — потом записи: жест у
+     * расширения и ширина взятого там, где её читает тема (`_shiftHolder`).
+     * Шапка стоит (`still`, таблица в `none`) — ширины нет: соседям сдвигаться
+     * не на что. Заголовков нет или колонку не дали взять — жеста нет.
+     */
+    private _takeGesture;
+    /**
+     * Узел для ширины взятого — там, где её читает тема: в `head` — шапка, в
+     * `column` — корень, от которого её наследует и тело. На корне большой
+     * таблицы запись пересчитала бы стиль каждой ячейке тела, а в `head` тело
+     * стоит. В `none` соседям сдвигаться не на что — узла нет.
+     */
+    private _shiftHolder;
+    private readonly _onPointerUp;
+    /** Браузер отнял указатель — колонка возвращается на место. */
+    private readonly _onPointerCancel;
+    /**
+     * Захват потерял корень — указатель у него отняли, и жест кончен, как от
+     * `pointercancel`. Узел под пальцем теряет захват и посреди жеста: касание
+     * браузер сам захватывает за ним, а начало жеста переносит захват на
+     * корень. Это событие всплывает до корня, но жест не кончает — указатель
+     * по-прежнему у корня.
+     */
+    private readonly _onLostCapture;
+    /** Escape посреди жеста — отмена. Слушается на документе: фокус бывает вне таблицы. */
+    private readonly _onEscape;
+    /**
+     * Закончить нажатие: отпустили — заголовок приземляется на место, куда
+     * колонку принесли, отмена — на своё, и соседи возвращаются. Коллекцию
+     * переставит конец приземления.
+     */
+    private _release;
+    /**
+     * Заголовок — на место: кадром позже, когда `data-landing` уже в разметке
+     * и тема ведёт его переходом, — так же сдвиг отпущенной панели снимает
+     * `TSwipePlugin`. Конец — когда заголовок доиграл свои переходы.
+     */
+    private _land;
+    /** Заголовок встал: колонка — на место, метки и переменные сняты. */
+    private _landed;
+    /** Довести приземление сразу — без кадра и без ожидания переходов. */
+    private _finishLanding;
+    /**
+     * Корень ушёл: жест и приземление — прочь без перестановки, ожидания и
+     * кадры сняты.
+     */
+    private _abort;
+    /** Снять сдвиги жеста: у взятого заголовка и ширину взятого — с узла, которому её записали. */
+    private _clearVariables;
+    private readonly _onKeyDown;
+    /**
+     * Фокус — тому же узлу после перерисовки шапки: переставленный заголовок
+     * браузер переносит в документе, и узел под фокусом при этом его теряет.
+     */
+    private _keepFocus;
+    private _cancelFrame;
+}