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

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

@@ -0,0 +1,271 @@
+import { TBasePlugin } from "../../../base/base.class.js";
+import { TElementPlugin } from "../../element/element.plugin.js";
+import { isMeasurableElement } from "../../../utils/isMeasurableElement.js";
+import { arrowStep, slideDirection } from "../../slide/direction.js";
+//#region src/custom/table/column-resize/column-resize.plugin.ts
+/** Шаг стрелки и жеста скринридера, px, — пока опция не задана. */
+var STEP = 10;
+/** Крупный шаг, px, — пока опция не задана: десять шагов. */
+var LARGE_STEP = 100;
+/**
+* Ось ручки: ширина колонки растёт вдоль строки, к её концу, — горизонталь без
+* разворота. По ней направление письма сводится в сторону роста
+* (`slideDirection`), как у ползунка: от неё зависят и протяжка, и стрелки.
+*/
+var AXIS = {
+	orientation: "horizontal",
+	inverted: false
+};
+/** Сдвиг призрака от края колонки, px по оси окна: плюс — вправо. */
+var GHOST_VARIABLE = "--so-table-column-ghost";
+/** Высота призрака, px: от верха заголовка до низа таблицы в видимой части окна. */
+var GHOST_SIZE_VARIABLE = "--so-table-column-ghost-size";
+/**
+* Полоса ручки — ребёнок корня с классом `__resizer` владельца, по классу, а не
+* строкой в плагине. Только прямые дети: в заголовке может лежать что угодно,
+* вплоть до другой таблицы, и поиск вглубь нашёл бы её ручку.
+*/
+function resizerOf(column, root) {
+	const className = column.classes.resolve("__resizer");
+	return Array.from(root.children).find((child) => child.classList.contains(className)) ?? null;
+}
+/** Поле ручки — ребёнок полосы `input`. */
+function fieldOf(resizer) {
+	if (!resizer) return null;
+	return Array.from(resizer.children).find((child) => child instanceof HTMLInputElement) ?? null;
+}
+/**
+* TTableColumnResizePlugin — ручка ширины колонки: указатель, клавиши и жест
+* скринридера.
+*
+* Операции над DOM — здесь, ширина — у колонки: плагин переводит указатель и
+* клавиши в px и зовёт её команды (`grab`, `drag`, `release`, `shift`,
+* `moveToEdge`). Какой станет ширина, в каких пределах и когда слать `commit`,
+* решает колонка, и жест она ведёт от своего итога ширины: ширины колонок
+* раскладывает ядро, и итог — та ширина, что видна. Сторону, куда колонка
+* растёт, плагин берёт у вычисленного направления письма (`slideDirection`):
+* ручка стоит у конца строки, и в RTL колонку расширяет движение влево.
+*
+* **Указатель** — на полосе ручки: нажатие с её захватом начинает жест,
+* протяжка двигает край, отпускание или отнятый указатель жест заканчивают.
+* Своих действий у нажатия нет (`preventDefault`): ни выделения текста, ни
+* своего фокуса браузера. Слушает корень, а не полосу: полосу разметка рисует
+* и убирает, а корень — заголовок — живёт всё монтирование, и захват
+* указателя держится на нём.
+*
+* **Отложенный жест** (`resizePreview: 'deferred'` таблицы) ширину до
+* отпускания не меняет: её будущую границу показывает призрак, которого
+* рисует тема по `data-resize-ghost` заголовка. Плагин пишет заголовку его
+* сдвиг от края колонки (`--so-table-column-ghost`, по оси окна, на каждый
+* шаг, если сменился) и высоту (`--so-table-column-ghost-size`, один раз на
+* нажатии: от верха заголовка до низа таблицы в окне браузера) и снимает их
+* в конце жеста. Переменные — на заголовке, а не на корне: запись на корень
+* пересчитала бы стиль каждой ячейки тела. Escape посреди жеста — отмена в
+* обоих режимах (`cancel` колонки).
+*
+* **Клавиши и жест скринридера** — у поля ручки, как у поля ползунка
+* (`TSlideKeyboardPlugin`): стрелки — шаг по стороне роста, Shift со стрелкой,
+* PageUp и PageDown — крупный шаг, Home и End — края хода. Поле браузер сдвинул
+* бы своим шагом, поэтому клавиши плагин берёт себе. Мобильный скринридер
+* клавиш не шлёт: свайп двигает поле и сообщает событием `input`, а плагин
+* переводит направление правки в шаг колонки и возвращает полю её ширину.
+* Шаги — опции установки.
+*/
+var TTableColumnResizePlugin = class extends TBasePlugin {
+	_column = null;
+	_root = null;
+	_gesture = null;
+	_step = STEP;
+	_largeStep = LARGE_STEP;
+	install(ctx, options) {
+		super.install(ctx, options);
+		this._step = options?.step ?? this._step;
+		this._largeStep = options?.largeStep ?? this._largeStep;
+		this._column = ctx.getInstance();
+		const element = ctx.get(TElementPlugin);
+		element?.events.on("ready", (node) => this._attach(node));
+		element?.events.on("removed", () => this._detach());
+	}
+	destroy() {
+		this._detach();
+		this._column = null;
+		super.destroy();
+	}
+	_attach(root) {
+		this._detach();
+		this._root = root;
+		const target = root;
+		target.addEventListener("pointerdown", this._onPointerDown);
+		target.addEventListener("pointermove", this._onPointerMove);
+		target.addEventListener("pointerup", this._onPointerUp);
+		target.addEventListener("pointercancel", this._onPointerUp);
+		target.addEventListener("lostpointercapture", this._onPointerUp);
+		target.addEventListener("keydown", this._onKeyDown);
+		target.addEventListener("input", this._onInput);
+	}
+	_detach() {
+		this._end();
+		const target = this._root;
+		target?.removeEventListener("pointerdown", this._onPointerDown);
+		target?.removeEventListener("pointermove", this._onPointerMove);
+		target?.removeEventListener("pointerup", this._onPointerUp);
+		target?.removeEventListener("pointercancel", this._onPointerUp);
+		target?.removeEventListener("lostpointercapture", this._onPointerUp);
+		target?.removeEventListener("keydown", this._onKeyDown);
+		target?.removeEventListener("input", this._onInput);
+		this._root = null;
+	}
+	_onPointerDown = (event) => {
+		const column = this._column;
+		const root = this._root;
+		if (!column || !root || this._gesture || event.button !== 0) return;
+		const resizer = resizerOf(column, root);
+		if (!resizer || !(event.target instanceof Node) || !resizer.contains(event.target)) return;
+		const sign = slideDirection(AXIS, root) === "from-left" ? 1 : -1;
+		const ghostSize = column.resizePreview === "deferred" ? this._ghostSize(root) : 0;
+		if (!column.grab()) return;
+		event.preventDefault();
+		this._gesture = {
+			pointer: event.pointerId,
+			origin: event.clientX,
+			sign,
+			ghost: void 0
+		};
+		if (column.resizeGhost !== void 0 && isMeasurableElement(root)) {
+			root.style.setProperty(GHOST_SIZE_VARIABLE, `${ghostSize}px`);
+			this._moveGhost(column, root);
+		}
+		if ("setPointerCapture" in root) root.setPointerCapture(event.pointerId);
+		this._focus(fieldOf(resizer));
+	};
+	_onPointerMove = (event) => {
+		const gesture = this._gesture;
+		if (!gesture || event.pointerId !== gesture.pointer) return;
+		const column = this._column;
+		if (!column) return;
+		column.drag((event.clientX - gesture.origin) * gesture.sign);
+		if (this._root) this._moveGhost(column, this._root);
+	};
+	/**
+	* Призрак — на ширину, которую запишет отложенный жест: сдвиг от края
+	* колонки по оси окна. Ход колонка уже учла, поэтому за границы колонки
+	* призрак не уходит. Тот же сдвиг не пишется: переменная на заголовке
+	* пересчитывает его стиль. В живом жесте призрака нет.
+	*/
+	_moveGhost(column, root) {
+		const gesture = this._gesture;
+		const ghost = column.resizeGhost;
+		const width = column.width;
+		if (!gesture || ghost === void 0 || width === void 0) return;
+		const offset = (ghost - width) * gesture.sign;
+		if (offset === gesture.ghost || !isMeasurableElement(root)) return;
+		gesture.ghost = offset;
+		root.style.setProperty(GHOST_VARIABLE, `${offset}px`);
+	}
+	/**
+	* Высота призрака: от верха заголовка до низа таблицы, но не ниже окна
+	* браузера — таблица в тысячи строк дала бы линию в сотни тысяч px.
+	*/
+	_ghostSize(root) {
+		const table = root.closest("table") ?? root;
+		const view = root.ownerDocument.defaultView;
+		const bottom = table.getBoundingClientRect().bottom;
+		const top = root.getBoundingClientRect().top;
+		return Math.max(0, Math.min(bottom, view?.innerHeight ?? bottom) - top);
+	}
+	/** Снять переменные призрака: жест закончен. */
+	_clearGhost() {
+		const root = this._root;
+		if (!isMeasurableElement(root)) return;
+		root.style.removeProperty(GHOST_VARIABLE);
+		root.style.removeProperty(GHOST_SIZE_VARIABLE);
+	}
+	_onPointerUp = (event) => {
+		const gesture = this._gesture;
+		if (!gesture || event.pointerId !== gesture.pointer) return;
+		this._end();
+	};
+	/** Закончить жест: отпустили, браузер отнял указатель или корень ушёл. */
+	_end() {
+		const gesture = this._gesture;
+		if (!gesture) return;
+		this._gesture = null;
+		if (gesture.ghost !== void 0) this._clearGhost();
+		this._column?.release();
+	}
+	/**
+	* Escape посреди жеста — отмена: ширина нажатия, без `commit`. Захват
+	* указателя плагин отпускает сам: протяжка дальше ширину не двигает.
+	*/
+	_cancel() {
+		const gesture = this._gesture;
+		const root = this._root;
+		if (!gesture) return;
+		this._gesture = null;
+		if (gesture.ghost !== void 0) this._clearGhost();
+		this._column?.cancel();
+		if (root && "releasePointerCapture" in root && root.hasPointerCapture(gesture.pointer)) root.releasePointerCapture(gesture.pointer);
+	}
+	/**
+	* Фокус — полю ручки, как у ползунка: клавиши продолжают с той ширины, на
+	* которой отпустили указатель. Без прокрутки: страница не должна прыгать к
+	* ручке, которую пользователь и так держит.
+	*
+	* И без кольца (`focusVisible: false`). Фокус ставит скрипт, а видимость
+	* такого фокуса браузер берёт у прошлого: пришёл тот не от мыши — свежая
+	* страница, Tab, — и нажатие мышью зажгло бы линию ручки, которую держит
+	* только фокус с клавиатуры.
+	*/
+	_focus(field) {
+		if (field && field.ownerDocument.activeElement !== field) field.focus({
+			preventScroll: true,
+			focusVisible: false
+		});
+	}
+	_onKeyDown = (event) => {
+		if (this._gesture && event.key === "Escape") {
+			event.preventDefault();
+			this._cancel();
+			return;
+		}
+		if (event.altKey || event.ctrlKey || event.metaKey) return;
+		const column = this._column;
+		const root = this._root;
+		if (!column || !root || event.target !== fieldOf(resizerOf(column, root))) return;
+		const action = this._actionOf(column, root, event);
+		if (!action) return;
+		event.preventDefault();
+		action();
+	};
+	/** Что клавиша делает с шириной; не наша клавиша — `null`, её обработает браузер. */
+	_actionOf(column, root, event) {
+		switch (event.key) {
+			case "Home": return () => column.moveToEdge("start");
+			case "End": return () => column.moveToEdge("end");
+			case "PageUp": return () => column.shift(this._largeStep);
+			case "PageDown": return () => column.shift(-this._largeStep);
+		}
+		const step = arrowStep(slideDirection(AXIS, root), event.key);
+		if (step === null) return null;
+		const size = event.shiftKey ? this._largeStep : this._step;
+		return () => column.shift(step * size);
+	}
+	/**
+	* Правка поля не клавишей — жестом скринридера. Колонка делает шаг в ту же
+	* сторону, а поле показывает её ширину: и когда шаг сделан, и когда упёрся в
+	* край хода.
+	*/
+	_onInput = (event) => {
+		const column = this._column;
+		const root = this._root;
+		const field = event.target;
+		if (!column || !root || !(field instanceof HTMLInputElement)) return;
+		if (field !== fieldOf(resizerOf(column, root))) return;
+		const direction = Math.sign(Number(field.value) - column.resizer.value);
+		if (direction) column.shift(direction * this._step);
+		const value = String(column.resizer.value);
+		if (field.value !== value) field.value = value;
+	};
+};
+//#endregion
+export { TTableColumnResizePlugin };

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

@@ -0,0 +1,2 @@
+export { TTableColumnResizePlugin } from './column-resize.plugin';
+export type { ITableColumnResizePluginOptions, TTableColumnResizePluginEvents, TTableColumnResizeGesture, } from './types';

package/dist/custom/table/column-resize/types.d.ts

@@ -0,0 +1,38 @@
+import type { TPluginEvents } from '../../../base';
+/**
+ * Своих событий у плагина нет: результат жеста и клавиш виден через колонку —
+ * ширину, `data-resizing` и `commit` сообщает она, а таблица отдаёт наружу
+ * `column:resize`. Второй путь к тем же фактам через события плагина
+ * разошёлся бы с первым.
+ */
+export type TTableColumnResizePluginEvents = TPluginEvents;
+export interface ITableColumnResizePluginOptions {
+    /**
+     * Шаг стрелки и жеста скринридера, px. По умолчанию — 10: заметно глазу и
+     * не требует десятков нажатий, чтобы сдвинуть колонку на слово.
+     */
+    step?: number;
+    /**
+     * Крупный шаг — Shift со стрелкой, PageUp и PageDown, px. По умолчанию —
+     * 100, десять шагов, как крупный шаг ползунка.
+     */
+    largeStep?: number;
+}
+/** Жест, который ведёт плагин: от нажатия до отпускания. */
+export type TTableColumnResizeGesture = {
+    /** `pointerId` указателя жеста: чужие указатели его не двигают */
+    pointer: number;
+    /** Точка нажатия по строке — `clientX` */
+    origin: number;
+    /**
+     * Знак роста ширины по оси окна: `1` — вправо, `-1` — влево. Ручка стоит у
+     * конца строки, и в RTL колонку расширяет движение влево. Вычислен при
+     * нажатии — на весь жест
+     */
+    sign: 1 | -1;
+    /**
+     * Сдвиг призрака, px по оси окна, который плагин записал последним, —
+     * только в отложенном жесте: тот же сдвиг второй раз не пишется
+     */
+    ghost: number | undefined;
+};

package/dist/custom/table/grid/grid.plugin.d.ts

@@ -0,0 +1,119 @@
+import type { ITable } from '@soxa-ui/core';
+import { TBasePlugin } from '../../../base';
+import type { IPluginContext } from '../../../base';
+import type { ITableGridPluginOptions, TTableGridPluginEvents } from './types';
+/**
+ * TTableGridPlugin — сетка таблицы в документе (APG Data Grid): клавиши,
+ * выбор строки нажатием и DOM-фокус за фокусом сетки.
+ *
+ * Операции над DOM — здесь, фокус и выбор — у расширения `grid` коллекции
+ * строк: плагин переводит клавиши и нажатия в его команды (`focusCell`,
+ * `moveFocus`, `moveFocusToEdge`, `chooseRow`). Какая ячейка под фокусом,
+ * решает расширение, а плагин ставит на неё DOM-фокус. Движок плагин узнаёт
+ * от реестра bundles, узлы строк — от реестра узлов. Вне сетки плагин не
+ * делает ничего.
+ *
+ * **Ячейки** плагин находит по строкам: шапка — строка шапки своей таблицы
+ * (прямыми детьми, по классам владельца), строка тела — узел строки
+ * коллекции. Ячейки строки идут по колонкам сетки: колонка выбора и
+ * показанные колонки, — как их рисует таблица. Ячейки вложенной таблицы не
+ * её: строк этой таблицы у них нет.
+ *
+ * **Остановка Tab — сама таблица.** Фокус, пришедший на корень, — Tab в
+ * таблицу или нажатие мимо ячеек — плагин переводит на ячейку под фокусом
+ * сетки. Пришедший с клавиатуры снаружи на виджет внутри ячейки (Shift+Tab
+ * из-за таблицы) — тоже: у сетки одна остановка. Tab с ячейки уводит фокус
+ * из таблицы — к остановке за ней или, с Shift, перед ней: внутри у ячеек
+ * бывают свои поля и кнопки, и браузер повёл бы по ним.
+ *
+ * **Клавиши** — только с самой ячейки: ←/→ (по вычисленному направлению
+ * письма), ↑/↓, Home/End — края строки, Ctrl+Home/End — края сетки,
+ * PageUp/PageDown — на `pageStep` строк. Пробел (и Shift+пробел) на строке —
+ * её выбор, на ячейке колонки выбора шапки — все показанные строки или
+ * снять их; Ctrl/Cmd+A в `multiple` — выбрать все. Enter на заголовке
+ * сортируемой колонки сортирует, на остальных ячейках, как и F2, уводит
+ * фокус к первой остановке внутри ячейки. Там клавиши принадлежат виджетам,
+ * а сетке — только Escape и F2 (обратно на ячейку) и Tab (по кругу остановок
+ * ячейки). Ctrl+Shift+←/→ — перестановка колонки, её ведёт свой плагин.
+ *
+ * **Нажатие** по строке — где угодно, кроме контролов внутри ячейки, —
+ * выбор строки, как у строки ListBox. Фокус на ячейку ставит сам браузер
+ * (`tabindex="-1"`), а плагин сообщает его сетке (`focusin`).
+ */
+export declare class TTableGridPlugin extends TBasePlugin<ITable, TTableGridPluginEvents> {
+    private _owner;
+    private _root;
+    private _engine;
+    private _elements;
+    private _pageStep;
+    /** Фокус придёт от нажатия указателя, а не с клавиатуры. */
+    private _pointer;
+    private _frame;
+    install(ctx: IPluginContext, options?: ITableGridPluginOptions): void;
+    destroy(): void;
+    private _attach;
+    private _detach;
+    /** Расширение сетки, пока таблица в сетке. */
+    private get _grid();
+    private _headRow;
+    private _body;
+    /** Строка сетки, чей узел — `line`; чужой узел — `undefined`. */
+    private _rowOf;
+    /** Узел строки сетки — пока он в теле своей таблицы. */
+    private _lineOf;
+    /**
+     * Ячейка сетки, в которой лежит цель, — её строка, колонка и узел. Ячейки
+     * строки идут по колонкам сетки; строка ещё не дорисовала смену колонок —
+     * ячейки нет: место в строке не совпало бы с колонкой.
+     */
+    private _cellOf;
+    /** Узел ячейки сетки — пока её строка дорисована по колонкам сетки. */
+    private _cellElement;
+    /**
+     * Фокус сетки перешёл — DOM-фокус за ним, если он в сетке: на корне или на
+     * ячейке. Фокус на виджете внутри ячейки плагин не трогает: там с
+     * клавишами работает виджет. Вне таблицы фокус сетка помнит до Tab в неё.
+     */
+    private readonly _follow;
+    /**
+     * DOM-фокус — на узел ячейки. Узла ещё нет — строку перерисовывают после
+     * смены, которая её показала, — ждём кадр.
+     */
+    private _focus;
+    private _focusNow;
+    private _cancelFrame;
+    private readonly _onPointerDown;
+    private readonly _onFocusIn;
+    private readonly _onKeyDown;
+    /** Клавиша с самой ячейки — ходьба по сетке, выбор и вход в ячейку. */
+    private _navigate;
+    /** Что клавиша на ячейке делает; не наша клавиша — `null`. */
+    private _actionOf;
+    /**
+     * Пробел: на строке — её выбор, на ячейке колонки выбора шапки — все
+     * показанные строки или снять их, как её чекбокс. Остальным ячейкам шапки
+     * пробел ничего не делает, но страницу не листает.
+     */
+    private _choose;
+    /** Enter: заголовок сортируемой колонки сортирует, остальные ячейки — вход в ячейку. */
+    private _activate;
+    /** Фокус — к первой остановке внутри ячейки: дальше клавиши принадлежат её виджетам. */
+    private _enter;
+    /**
+     * Tab с ячейки — из таблицы: к остановке за ней, с Shift — перед ней.
+     * Остановки нет — фокус снимается, и следующий Tab начнёт с края
+     * документа: внутри таблицы браузер повёл бы по полям ячеек.
+     */
+    private _leave;
+    /**
+     * Клавиша с виджета внутри ячейки. Escape и F2 возвращают фокус на ячейку,
+     * Tab ходит по кругу остановок ячейки: из сетки уводит Tab только с самой
+     * ячейки. Остальное — виджета.
+     */
+    private _interact;
+    /**
+     * Нажатие по строке — её выбор, как у строки ListBox. Контролы внутри
+     * ячейки — чекбокс строки, кнопки и поля слота — нажимаются сами.
+     */
+    private readonly _onClick;
+}