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

package/dist/utils/tabStopsBefore.js

@@ -0,0 +1,17 @@
+import { tabStops } from "./tabStops.js";
+//#region src/utils/tabStopsBefore.ts
+/**
+* Остановки перед узлом в порядке документа — без его потомков: Shift+Tab из
+* виджета, который водит Tab сам, ведёт к тому, что стоит в документе перед
+* ним. Предок узла с остановкой — тоже перед ним: в порядке Tab он раньше
+* своих потомков.
+*
+* Пара к `tabStopsAfter`, и список остановок тот же — у `tabStops`: второй
+* набор селекторов разошёлся бы с первым. Спрашивает сетка таблицы: её Tab —
+* одна остановка, и уходит он из неё сам.
+*/
+function tabStopsBefore(node) {
+	return tabStops(node.ownerDocument).filter((stop) => !node.contains(stop) && (node.compareDocumentPosition(stop) & Node.DOCUMENT_POSITION_PRECEDING) !== 0);
+}
+//#endregion
+export { tabStopsBefore };

package/dist/utils/toCssValue.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Приводит значение к CSS-строке.
+ * - Число → `${value}px`
+ * - Строка-число (например `'100'`) → `'100px'`
+ * - Строка с единицей (например `'50%'`, `'1rem'`) → как есть
+ * - `'auto'` → как есть
+ */
+export declare function toCssValue(value: string | number): string;

package/dist/utils/toCssValue.js

@@ -0,0 +1,17 @@
+//#region src/utils/toCssValue.ts
+var CSS_UNIT_RE = /^-?\d+(\.\d+)?$/u;
+/**
+* Приводит значение к CSS-строке.
+* - Число → `${value}px`
+* - Строка-число (например `'100'`) → `'100px'`
+* - Строка с единицей (например `'50%'`, `'1rem'`) → как есть
+* - `'auto'` → как есть
+*/
+function toCssValue(value) {
+	if (value === "auto") return value;
+	if (typeof value === "number") return `${value}px`;
+	if (CSS_UNIT_RE.test(value)) return `${value}px`;
+	return value;
+}
+//#endregion
+export { toCssValue };

package/dist/utils/trapTab.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Tab по кругу внутри панели — ловушка модального оверлея.
+ *
+ * С последней остановки панели Tab ведёт на первую, а Shift+Tab с первой — на
+ * последнюю. Панель без единой остановки держит фокус на себе
+ * (`tabindex="-1"`), и Tab с неё никуда не уводит. Порядок остановок внутри
+ * ведёт браузер — ловушка вмешивается только на краях. Фокус увели из панели
+ * мимо неё (`focus()` со стороны, нажатие в поле владельца) — Tab возвращает
+ * его в панель, а не гадает, откуда он ушёл.
+ *
+ * Живёт в общих утилитах, а не у модальной модели фокуса: Tab замыкают и
+ * модальное окно с выезжающей панелью (`TModalFocusPlugin`), и панель
+ * DatePicker (`TDatePickerFocusPlugin`), у которой остальная модель своя.
+ * Вторая копия правила разошлась бы с первой.
+ */
+export declare function trapTab(event: KeyboardEvent, panel: Element): void;

package/dist/utils/trapTab.js

@@ -0,0 +1,36 @@
+import { tabStops } from "./tabStops.js";
+import { focusFirst } from "./focusFirst.js";
+//#region src/utils/trapTab.ts
+/**
+* Tab по кругу внутри панели — ловушка модального оверлея.
+*
+* С последней остановки панели Tab ведёт на первую, а Shift+Tab с первой — на
+* последнюю. Панель без единой остановки держит фокус на себе
+* (`tabindex="-1"`), и Tab с неё никуда не уводит. Порядок остановок внутри
+* ведёт браузер — ловушка вмешивается только на краях. Фокус увели из панели
+* мимо неё (`focus()` со стороны, нажатие в поле владельца) — Tab возвращает
+* его в панель, а не гадает, откуда он ушёл.
+*
+* Живёт в общих утилитах, а не у модальной модели фокуса: Tab замыкают и
+* модальное окно с выезжающей панелью (`TModalFocusPlugin`), и панель
+* DatePicker (`TDatePickerFocusPlugin`), у которой остальная модель своя.
+* Вторая копия правила разошлась бы с первой.
+*/
+function trapTab(event, panel) {
+	const active = panel.ownerDocument.activeElement;
+	if (!active) return;
+	if (!panel.contains(active)) {
+		if (focusFirst([...tabStops(panel), panel])) event.preventDefault();
+		return;
+	}
+	const stops = tabStops(panel);
+	if (stops.length === 0) {
+		event.preventDefault();
+		return;
+	}
+	if (active !== (event.shiftKey ? stops[0] : stops[stops.length - 1]) && active !== panel) return;
+	const wrapped = event.shiftKey ? [...stops].reverse() : stops;
+	if (focusFirst(wrapped)) event.preventDefault();
+}
+//#endregion
+export { trapTab };

package/dist/utils/types.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Узел как источник DOM-событий — с полной их картой.
+ *
+ * `Element.addEventListener` типизирован картой `ElementEventMap`, а в ней
+ * два fullscreen-события: полную карту (`GlobalEventHandlersEventMap`)
+ * lib.dom даёт только `HTMLElement` и `SVGElement`. Узел плагину приходит как
+ * `Element` (см. `TElementPlugin`), и неточность тут в карте, а не в узле: на
+ * любом элементе `click` придёт `MouseEvent`, `keydown` — `KeyboardEvent`.
+ *
+ * Поэтому пробел закрывается объявлением, а не приведением обработчика к
+ * `EventListener` и не сужением узла: методы интерфейса сверяются бивариантно,
+ * и `Element` подходит под него как есть. Сужать узел `instanceof`-ом нельзя —
+ * ветка никогда не ложна, зато на неучтённом виде узла слушатель молча не
+ * повесился бы.
+ *
+ * Плагину, который от узла больше ничего не хочет, этот тип и объявляют полем
+ * — как `TAnchorPlugin` объявляет якорь `Element`. Кому нужен и сам узел,
+ * берёт локальный псевдоним на время подписки.
+ */
+export interface IDomEventTarget {
+    addEventListener<K extends keyof GlobalEventHandlersEventMap>(type: K, listener: (event: GlobalEventHandlersEventMap[K]) => void, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener<K extends keyof GlobalEventHandlersEventMap>(type: K, listener: (event: GlobalEventHandlersEventMap[K]) => void, options?: boolean | EventListenerOptions): void;
+}
+/**
+ * Отрезок по строке: левый и правый край в координатах окна браузера — как их
+ * отдаёт `getBoundingClientRect()`.
+ *
+ * Края физические. Где у строки начало, решает направление письма, а не
+ * отрезок: в RTL начало — правый край.
+ */
+export type TInlineSpan = {
+    left: number;
+    right: number;
+};
+/**
+ * Прямоугольник в координатах окна браузера — левый верхний угол и размер,
+ * как их отдаёт `getBoundingClientRect()`.
+ */
+export type TBox = {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+};
+/**
+ * Что нужно доводке элемента под фокусом (`nearestShift`) — всё отрезками по
+ * строке.
+ */
+export type TNearestShiftOptions = {
+    /**
+     * Окно области прокрутки — паддинг-бокс области без `scroll-padding` с
+     * каждой стороны (`scrollWindowOf`). Окно задаёт тема: у ленты это её
+     * чистая часть между подсказками, у ряда тегов — место с запасом под
+     * кольцо фокуса.
+     */
+    scrollWindow: TInlineSpan;
+    /** Элемент под фокусом. */
+    focused: TInlineSpan;
+    /**
+     * Элемент области, в котором он лежит, — прямой ребёнок области
+     * (`itemOf`). Без него в окно доводится один элемент под фокусом.
+     */
+    item?: TInlineSpan;
+};

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@soxa-ui/plugins",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0-beta.1",
+  "description": "Плагины поведения в рантайме, ставятся в TPluginBundle: DOM, фокус, клавиатура, оверлей",
+  "keywords": [
+    "soxa",
+    "headless",
+    "ui",
+    "plugins"
+  ],
+  "license": "MIT",
+  "author": "Yuri Soldatov",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/youra-h/soxa-ui.git",
+    "directory": "packages/plugins"
+  },
+  "homepage": "https://github.com/youra-h/soxa-ui",
+  "bugs": {
+    "url": "https://github.com/youra-h/soxa-ui/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@soxa-ui/core": "0.3.0-beta.1"
+  },
+  "scripts": {
+    "build": "vite build -c vite.lib.config.ts && tsc -p tsconfig.build.json",
+    "test": "vitest run"
+  }
+}