@brandup/ui-kit 1.0.53 → 1.0.54

package/README.md

@@ -173,10 +173,24 @@ const list = DOM.tag("div", { class: SCROLLABLE_CLASS });
 ## Утилиты
 
 ```typescript
-import { IS_TOUCH_DEVICE } from "@brandup/ui-kit";
+import { IS_TOUCH_DEVICE, isCoarsePointer, hasUserScrolled, resetUserScroll } from "@brandup/ui-kit";
 
 // true на touch-устройствах (мобильные, планшеты)
 if (IS_TOUCH_DEVICE) { ... }
+
+// true, когда основной указатель грубый — палец или стилус. В отличие от IS_TOUCH_DEVICE
+// ноутбук с сенсорным экраном сюда не попадает: работают на нём мышью
+if (isCoarsePointer()) { ... }
+
+// true, если пользователь сам прокручивал страницу с момента её показа. Нужно отложенным
+// действиям, которые двигают вид (автофокус контрола ввода). Считаются жесты — колесо, свайп,
+// полоса прокрутки, автопрокрутка средней кнопкой, клавиши прокрутки, действие которых никто
+// не отменил, — а не событие scroll: его поднимает и программная прокрутка
+if (!hasUserScrolled()) { ... }
+
+// забыть прокрутку — показана другая страница. При навигации это делает UiKitMiddleware,
+// перед тем как новую страницу нарисуют: её контролы должны видеть уже чистый признак
+resetUserScroll();
 ```
 
 ## Стили

package/package.json

@@ -25,7 +25,7 @@
   },
   "type": "module",
   "license": "Apache-2.0",
-  "version": "1.0.53",
+  "version": "1.0.54",
   "main": "source/index.ts",
   "types": "source/index.ts",
   "dependencies": {

package/source/index.ts

@@ -8,7 +8,8 @@ export * from "./popup";
 export const SCROLLABLE_CLASS = "ui-scrollable";
 
 export { default as Modal, MODAL_CLASS, MODAL_OPENED_CLASS, MODAL_CLOSE_COMMAND, type ModalOptions } from "./modal";
-export { IS_TOUCH_DEVICE } from "./utils/compatibility";
+export { IS_TOUCH_DEVICE, isCoarsePointer } from "./utils/compatibility";
+export { hasUserScrolled, resetUserScroll } from "./utils/user-scroll";
 export { textTag } from "./utils/text";
 import "./styles.less";
 

package/source/middleware.ts

@@ -1,9 +1,12 @@
 import { Middleware, MiddlewareNext, NavigateContext, StartContext } from "@brandup/ui-app";
 import { PopupManager, POPUP_COMMAND, POPUP_CLASS } from "./popup";
+import { resetUserScroll } from "./utils/user-scroll";
 
 export class UiKitMiddleware implements Middleware {
 	name = "uikit";
 
+	private __navigated = false;
+
 	start(context: StartContext, next: MiddlewareNext) {
 		context.app.registerCommand(POPUP_COMMAND, (context) => {
 			if (!context.target.nextElementSibling?.classList.contains(POPUP_CLASS))
@@ -18,6 +21,19 @@ export class UiKitMiddleware implements Middleware {
 	navigate(_context: NavigateContext, next: MiddlewareNext) {
 		PopupManager.close(); // закрываем открытое контекстное меню при навигации
 
+		// Показана другая страница — прокрутка пользователя по прежней больше ни при чём
+		// (см. resetUserScroll). Первую навигацию пропускаем: она показывает ту же страницу,
+		// с которой приложение стартовало, и прокрутка во время его загрузки остаётся в силе —
+		// именно она и должна отменить автофокус.
+		//
+		// Забываем до next(), а не после: страницу рисуют внутри него, и её контролы обязаны
+		// видеть уже чистый признак. Плата за это — окно, пока новая страница ещё не нарисована:
+		// контрол, доинициализированный на прежней в этот момент, посчитает её непрокрученной.
+		// Возвращать флаг на неудачной навигации нельзя: редирект успевает нарисовать свою
+		// страницу до того, как отмена дойдёт сюда, и она получила бы чужую прокрутку.
+		if (this.__navigated) resetUserScroll();
+		this.__navigated = true;
+
 		return next();
 	}
 }

package/source/utils/compatibility.ts

@@ -1,3 +1,17 @@
-export const IS_TOUCH_DEVICE = window.document.documentElement
-	? "ontouchstart" in window.document.documentElement
-	: false;
+// Признаки окружения читаются при загрузке модуля, поэтому проверяем и само окружение:
+// пакет собирают и там, где DOM появится позже или не появится вовсе (серверный рендер).
+const HAS_DOM = typeof window !== "undefined" && !!window.document?.documentElement;
+
+export const IS_TOUCH_DEVICE = HAS_DOM && "ontouchstart" in window.document.documentElement;
+
+/**
+ * Грубый ли основной указатель — палец или стилус, то есть точного наведения нет, а текст
+ * вводят экранной клавиатурой.
+ *
+ * Не то же, что {@link IS_TOUCH_DEVICE}: тот отвечает «есть ли у устройства сенсор», и ноутбук
+ * с сенсорным экраном попадает в него наравне с телефоном, хотя работают на нём мышью.
+ *
+ * Спрашиваем при каждом вызове, а не один раз при загрузке: на гибридных устройствах ответ
+ * меняется по ходу работы — планшет ставят в док-станцию с мышью и обратно.
+ */
+export const isCoarsePointer = (): boolean => (HAS_DOM && window.matchMedia?.("(pointer: coarse)").matches) ?? false;

package/source/utils/user-scroll.ts

@@ -0,0 +1,82 @@
+/**
+ * Прокручивал ли пользователь страницу сам с момента её показа.
+ *
+ * Нужно отложенным действиям, которые двигают вид: автофокус контрола ввода ставится в конце
+ * его инициализации, а она бывает и отложенной (ленивый content script, вставка разметки
+ * из кода). Если к этому моменту пользователь ушёл смотреть другое место страницы, забирать
+ * у него вид и клавиатуру нельзя.
+ *
+ * Считаем жесты прокрутки, а не событие scroll: scroll поднимает и программная прокрутка,
+ * и восстановление позиции браузером при перезагрузке или возврате назад — намерения
+ * пользователя в них нет.
+ */
+let userScrolled = false;
+
+/** Клавиши, которыми прокручивают страницу. */
+const SCROLL_KEYS = new Set(["PageUp", "PageDown", "Home", "End", "ArrowUp", "ArrowDown"]);
+
+const setScrolled = () => (userScrolled = true);
+
+/**
+ * Попало ли нажатие мимо клиентской области — то есть в саму полосу прокрутки. Нулевые размеры
+ * не проверяем: страницы без разметки (и jsdom) иначе считали бы полосой любое нажатие.
+ */
+function isScrollbarPress(e: MouseEvent): boolean {
+	const root = window.document.documentElement;
+
+	return (
+		(root.clientWidth > 0 && e.clientX >= root.clientWidth) ||
+		(root.clientHeight > 0 && e.clientY >= root.clientHeight)
+	);
+}
+
+// Слушатели живут всё время работы приложения: признак общий на страницу, снимать его вместе
+// с каким-то одним контролом нечего. Пассивные — прокрутку они только замечают, останавливать
+// её не собираются.
+if (typeof window !== "undefined") {
+	// Колесо и свайп — в фазе перехвата: докуда бы событие ни дошло, прокрутка уже случилась.
+	window.addEventListener("wheel", setScrolled, { passive: true, capture: true });
+	window.addEventListener("touchmove", setScrolled, { passive: true, capture: true });
+
+	// Полосу прокрутки и автопрокрутку средней кнопкой ни колесом, ни свайпом не поймать, а
+	// событие scroll поднимает и программная прокрутка. Обе начинаются с нажатия мыши: средняя
+	// кнопка — это автопрокрутка, а нажатие мимо клиентской области попадает в полосу.
+	window.addEventListener(
+		"mousedown",
+		(e: MouseEvent) => {
+			if (e.button === 1 || isScrollbarPress(e)) setScrolled();
+		},
+		{ passive: true, capture: true }
+	);
+
+	// Клавиатуру, в отличие от остального, слушаем на всплытии: страницу двигает только та
+	// клавиша, действие которой никто не отменил. Виджет, которому клавиша своя, — список
+	// dropdown, меню, карусель — гасит её сам, и это работа внутри виджета, а не прокрутка.
+	window.addEventListener("keydown", (e: KeyboardEvent) => {
+		if (e.defaultPrevented || !SCROLL_KEYS.has(e.key)) return;
+
+		// в поле ввода те же клавиши двигают каретку, а не страницу, и отменять их полю незачем
+		const target = e.target as HTMLElement | null;
+		if (
+			target?.isContentEditable ||
+			target instanceof HTMLInputElement ||
+			target instanceof HTMLTextAreaElement ||
+			target instanceof HTMLSelectElement
+		)
+			return;
+
+		setScrolled();
+	});
+}
+
+/** Прокручивал ли пользователь страницу сам с момента её показа. */
+export const hasUserScrolled = (): boolean => userScrolled;
+
+/**
+ * Забыть прокрутку пользователя — показана другая страница. Зовёт {@link UiKitMiddleware}
+ * при навигации; первую навигацию она пропускает: это показ той же страницы, с которой
+ * приложение стартовало, и прокрутка во время его загрузки остаётся в силе.
+ */
+export const resetUserScroll = (): void => {
+	userScrolled = false;
+};