@brandup/ui-kit 1.0.45 → 1.0.48

package/README.md

@@ -55,8 +55,45 @@ PopupManager.close();
 
 // Проверить, открыт ли какой-либо попап
 PopupManager.isOpened(); // boolean
+
+// ...или именно этот — так после open() узнают, открылся попап или закрылся повторным нажатием
+PopupManager.isOpened(popupElem); // boolean
 ```
 
+### Состояния
+
+Пока попап открыт, классы расставлены так:
+
+| Элемент   | Класс               | Константа                 |
+| --------- | ------------------- | ------------------------- |
+| Попап     | `opened`            | `POPUP_OPENED_CLASS`      |
+| Инициатор | `ui-popup-expanded` | `POPUP_EXPANDED_CLASS`    |
+| `body`    | `ui-popup-opened`   | `POPUP_OPENED_BODY_CLASS` |
+
+Класс на `body` — точка расширения для страницы: например, чтобы придержать фон, пока попап открыт.
+
+### Закрытие
+
+Попап закрывается кликом мимо себя, повторным кликом по инициатору, клавишей `Escape` и навигацией
+приложения. Свои обработчики `Escape` компоненту не нужны — менеджер снимает попап сам; если нужно
+вернуть фокус на инициатор, делайте это в `onClose`.
+
+### Узкий экран
+
+До `@adaptive-tablet-small` (850px) попап позиционируется относительно инициатора. Ниже этой ширины
+рядом с кнопкой места уже нет, поэтому попап отрывается от неё и показывается окном по центру экрана
+с затемнением — `position: fixed`, ширина по экрану до `--popup-window-max-width`, прокрутка страницы
+под ним придержана через `body.ui-popup-opened`. Собственные `top` / `left` / `width` попапа в этом
+режиме перекрываются: правила кита идут с `body` в селекторе и весят больше, чем два класса.
+
+Настраивается переменными `--popup-backdrop`, `--popup-window-inset`, `--popup-window-max-width`.
+
+Ловушки фокуса в этом режиме нет: за экраном попапа остаются достижимые с клавиатуры элементы
+страницы. Если попап — полноценный диалог, берите `Modal`.
+
+Прокрутку держит `overflow: hidden` на `body` — в Safari на iOS этого не всегда достаточно, страница
+под попапом может тянуться. Оговорка общая для попапа, модального окна и списка дропдауна.
+
 ## Modal
 
 Базовое модальное окно: затемнение, шапка с заголовком и крестиком, тело. Наследник наполняет `body` в своём конструкторе и живёт до `close()`; само окно знает только про рамку, слои и закрытие.
@@ -99,6 +136,20 @@ const list = DOM.tag("div", { class: SCROLLABLE_CLASS });
 
 Оформление держится на `::-webkit-scrollbar`: стандартные `scrollbar-width`/`scrollbar-color` не задаются намеренно — Blink при них отдаёт системную полосу со стрелками. Браузерам без `::-webkit-scrollbar` (Firefox) стандартные свойства выдаются отдельным правилом.
 
+### Полоса прокрутки страницы
+
+Место под полосой прокрутки страницы зарезервировано всегда — `scrollbar-gutter: stable` на `html` и `body`. Без этого страница дёргается по ширине каждый раз, когда прокрутку придерживают (`ui-popup-opened`, `ui-modal-opened`) или контент перестаёт её требовать: полоса пропадает, вьюпорт становится шире на её толщину.
+
+Ценой этого на странице, которой прокрутка не нужна, остаётся пустая полоса. Если такое поведение не нужно, выключите резерв переменной:
+
+```css
+:root {
+    --scrollbar-gutter: auto;
+}
+```
+
+Браузеры без поддержки `scrollbar-gutter` (Safari до 18.2) объявление игнорируют, но там, где полосы накладные (iOS, Android), ширина и так не прыгает.
+
 ## Утилиты
 
 ```typescript

package/package.json

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

package/source/common.less

@@ -38,23 +38,25 @@
 	--svg-fill: @svg-fill;
 	--svg-stroke: @svg-stroke;
 
-	// popup
-	--popup-fill: @popup-fill;
-	--popup-color: @popup-color;
-	--popup-border-style: @popup-border-style;
-	--popup-border-width: @popup-border-width;
-	--popup-border-color: @popup-border-color;
-	--popup-border-radius: @popup-border-radius;
-	--popup-box-shadow: @popup-box-shadow;
-
 	// scrollable
 	--scrollbar-size: @scrollbar-size;
 	--scrollbar-thumb: @scrollbar-thumb;
 	--scrollbar-thumb-radius: @scrollbar-thumb-radius;
+	--scrollbar-gutter: @scrollbar-gutter;
 }
 
 // Body styles
 
+// Место под полосой прокрутки держим занятым всегда. Иначе страница дёргается по ширине каждый
+// раз, когда прокрутку придерживают (попап-окно, модальное окно): полоса пропадает, вьюпорт
+// становится шире на её толщину, и весь контент уезжает вбок. Свойство пишем на обоих элементах:
+// полосу вьюпорта задаёт то из них, чей overflow до вьюпорта доехал (у нас это body), но движки
+// читают gutter с корня. Отключается переменной: --scrollbar-gutter: auto.
+html,
+body {
+	scrollbar-gutter: var(--scrollbar-gutter);
+}
+
 body {
 	-webkit-font-smoothing: antialiased;
 	-moz-osx-font-smoothing: grayscale;
@@ -127,31 +129,6 @@ svg {
 	box-sizing: border-box;
 }
 
-// Popup styles
-
-.ui-popup {
-	position: absolute;
-	box-sizing: border-box;
-	z-index: 1000;
-	background: var(--popup-fill);
-	color: var(--popup-color);
-	border-style: var(--popup-border-style);
-	border-color: var(--popup-border-color);
-	border-width: var(--popup-border-width);
-	border-radius: var(--popup-border-radius);
-	box-shadow: var(--popup-box-shadow);
-	visibility: collapse;
-
-	&.opened {
-		visibility: visible;
-	}
-}
-
-.ui-popup-expanded {
-	& ~ .ui-popup {
-		visibility: visible;
-	}
-}
 // Scrollable styles
 
 // Прокручиваемая область с оформленной полосой: везде в ките она выглядит одинаково,

package/source/modal.less

@@ -8,7 +8,7 @@
 	--modal-color: var(--popup-color);
 	--modal-border-radius: var(--popup-border-radius);
 	--modal-box-shadow: var(--popup-box-shadow);
-	--modal-backdrop: rgba(0, 0, 0, 0.45);
+	--modal-backdrop: var(--popup-backdrop);
 	--modal-width: 480px;
 	--modal-padding: 20px;
 	--modal-z-index: 2000; // выше popup (1000): окно перекрывает и его

package/source/popup.less

@@ -0,0 +1,81 @@
+@import (reference) "../vars.less";
+@import (reference) "adaptive.less";
+
+// Всплывающая поверхность: позиционируется рядом с инициатором и показывается по классу.
+
+:root {
+	--popup-fill: @popup-fill;
+	--popup-color: @popup-color;
+	--popup-border-style: @popup-border-style;
+	--popup-border-width: @popup-border-width;
+	--popup-border-color: @popup-border-color;
+	--popup-border-radius: @popup-border-radius;
+	--popup-box-shadow: @popup-box-shadow;
+
+	// попап, оторванный от инициатора на узком экране: отступ от краёв экрана и предел ширины
+	--popup-backdrop: rgba(0, 0, 0, 0.45);
+	--popup-window-inset: 20px;
+	--popup-window-max-width: 540px;
+}
+
+.ui-popup {
+	position: absolute;
+	box-sizing: border-box;
+	z-index: 1000;
+	background: var(--popup-fill);
+	color: var(--popup-color);
+	border-style: var(--popup-border-style);
+	border-color: var(--popup-border-color);
+	border-width: var(--popup-border-width);
+	border-radius: var(--popup-border-radius);
+	box-shadow: var(--popup-box-shadow);
+	visibility: collapse;
+
+	&.opened {
+		visibility: visible;
+	}
+}
+
+.ui-popup-expanded {
+	& ~ .ui-popup {
+		visibility: visible;
+	}
+}
+
+// На узком экране попап отрывается от инициатора и показывается окном по центру с затемнением:
+// места рядом с кнопкой уже нет, а попап у края экрана уезжает за него. Так же ведёт себя popup
+// dropdown, только у него подложка — отдельный элемент разметки.
+.adaptive-tablet-small({
+	// Селектор с body намеренно: потребитель позиционирует попап вложенным правилом вида
+	// `.ui-messageeditor .ui-richeditor-emoji` — это два класса, столько же, сколько у пары
+	// `.ui-popup.opened`, и при равной специфичности исход решал бы порядок стилей в сборке.
+	// Элемент в селекторе даёт тот вес, которого паре классов не хватает.
+	body .ui-popup.opened,
+	body .ui-popup-expanded ~ .ui-popup {
+		position: fixed;
+		inset: 0;
+		margin: auto;
+		width: calc(100% - var(--popup-window-inset) * 2);
+		max-width: var(--popup-window-max-width);
+		// Браузер без fit-content отбросит свойство, и при inset: 0 окно растянется на всю
+		// высоту экрана — режим сохраняется, теряется только подгонка под содержимое.
+		height: fit-content;
+		max-height: calc(100% - var(--popup-window-inset) * 2);
+		overflow: auto;
+
+		// Затемнение — тенью с растяжкой на весь экран: отдельной подложки в разметке нет,
+		// а псевдоэлемент пришлось бы уводить под фон самого попапа (z-index: -1), где он
+		// перекрыл бы фон, но не текст. Собственную тень попапа не подмешиваем: поверх
+		// затемнения её всё равно не видно, а список с `none` (--popup-box-shadow может быть
+		// и таким) невалиден — декларация отвалилась бы целиком вместе с затемнением.
+		// Клик по тени не ловится и уходит на страницу — то есть закрывает попап, как и любой
+		// клик снаружи.
+		box-shadow: 0 0 0 100vmax var(--popup-backdrop);
+	}
+
+	// Класс ставит PopupManager: пока открыт попап-окно, страница под ним не прокручивается.
+	// По ширине она при этом не дёргается — место под полосой держит --scrollbar-gutter (common.less).
+	body.ui-popup-opened {
+		overflow: hidden;
+	}
+});

package/source/popup.ts

@@ -1,5 +1,11 @@
+import "./popup.less"; // стили всплывающей поверхности
+
 export const POPUP_CLASS = "ui-popup";
+/** Ставится на сам попап, пока он открыт. */
+export const POPUP_OPENED_CLASS = "opened";
 export const POPUP_EXPANDED_CLASS = "ui-popup-expanded";
+/** Ставится на body, пока открыт попап: страница может подстроиться под него (см. popup.less). */
+export const POPUP_OPENED_BODY_CLASS = "ui-popup-opened";
 export const POPUP_COMMAND = "ui-popup-toggle";
 
 type CurrentPopup = {
@@ -27,17 +33,28 @@ const closePopupEventHandler = (e: MouseEvent) => {
 	}
 };
 
+// Escape закрывает попап — это ожидание от любого всплывающего слоя, и держать свой обработчик
+// каждому компоненту незачем. Слушатель не перехватывающий: обработчики на самом попапе получают
+// клавишу первыми и успевают сделать своё (вернуть фокус, отменить ввод).
+const closePopupKeyHandler = (e: KeyboardEvent) => {
+	if (e.key !== "Escape") return;
+
+	close();
+};
+
 const close = () => {
 	if (current) {
 		if (current.closeCallback) current.closeCallback();
 
 		current.initiator?.classList.remove(POPUP_EXPANDED_CLASS); // закрываем последнее открытое контекстное меню
-		current.popup.classList.remove("opened");
+		current.popup.classList.remove(POPUP_OPENED_CLASS);
 
 		current = null;
 	}
 
+	document.body.classList.remove(POPUP_OPENED_BODY_CLASS);
 	document.body.removeEventListener("click", closePopupEventHandler);
+	document.removeEventListener("keydown", closePopupKeyHandler);
 };
 
 const open = (popupElem: HTMLElement, options?: PopupOptions) => {
@@ -50,12 +67,14 @@ const open = (popupElem: HTMLElement, options?: PopupOptions) => {
 
 	newPopup.closeCallback = options?.onClose;
 
-	if (newPopup.popup.classList.toggle("opened")) {
+	if (newPopup.popup.classList.toggle(POPUP_OPENED_CLASS)) {
 		// это новый popup, открываем его
 
 		newPopup.initiator?.classList.add(POPUP_EXPANDED_CLASS);
+		document.body.classList.add(POPUP_OPENED_BODY_CLASS);
 
 		document.body.addEventListener("click", closePopupEventHandler);
+		document.addEventListener("keydown", closePopupKeyHandler);
 
 		current = newPopup;
 	} else {
@@ -67,13 +86,14 @@ const open = (popupElem: HTMLElement, options?: PopupOptions) => {
 export const PopupManager: IPopupManager = {
 	open,
 	close,
-	isOpened: () => !!current,
+	isOpened: (popupElem?: HTMLElement) => (popupElem ? current?.popup === popupElem : !!current),
 };
 
 interface IPopupManager {
 	open: (popupElem: HTMLElement, options?: PopupOptions) => void;
 	close: () => void;
-	isOpened: () => boolean;
+	/** Без аргумента — открыт ли хоть один попап; с аргументом — открыт ли именно этот. */
+	isOpened: (popupElem?: HTMLElement) => boolean;
 }
 
 interface PopupOptions {

package/vars.less

@@ -51,6 +51,7 @@
 @scrollbar-size: 6px;
 @scrollbar-thumb: #8696a0;
 @scrollbar-thumb-radius: 3px;
+@scrollbar-gutter: stable;
 
 // inputs