@advdominion/tooltip@7.2.0

packages/tooltip/CHANGELOG.md

@@ -1,3 +1,9 @@
+## v7.2.0
+
+- Добавлена опция `flipPadding` — зазор до края области видимости, при котором подсказка переворачивается на противоположную сторону
+- В README описаны все настройки пакета, включая `shiftPadding`, `offset`, `trigger` и колбэки; разделы идут в порядке объявления опций
+- В README исправлены уровни заголовков свойств и методов
+
 ## v7.1.1
 
 - Позиция при прокрутке обновляется без принудительного reflow: все измерения геометрии выполняются до записи стилей

packages/tooltip/README.md

@@ -37,6 +37,7 @@ createTooltip(document.querySelector('button'), 'Подсказка', {
     delay: [0, 0],
     duration: [0, 0],
     easing: ['linear', 'linear'],
+    flipPadding: 0,
     hideOnClick: true,
     interactive: true,
     offset: [0, 8],
@@ -56,11 +57,34 @@ createTooltip(document.querySelector('button'), 'Подсказка', {
 });
 ```
 
-#### hideOnClick
+Любую настройку можно задать через data-атрибут: имя опции в kebab-case с префиксом `data-tooltip-`. Значение парсится как JSON, а если разобрать не удалось — используется как строка.
 
-- `true` (по умолчанию) — всплывающая подсказка скрывается при клике по любому элементу на странице (**кроме** самой всплывающей подсказки).
+```html
-- `'all'` — всплывающая подсказка скрывается при клике по любому элементу на странице (**включая** саму всплывающую подсказку).
+<button type="button" data-tooltip-placement="bottom" data-tooltip-offset="[0, 12]">Кнопка</button>
-- `'toggle'` — всплывающая подсказка скрывается только при клике по элементу, который её вызывает.
+```
+
+#### animation
+
+Две последовательности keyframes для `Element.animate`: первая проигрывается при появлении, вторая — при скрытии.
+
+```js
+createTooltip(document.querySelector('button'), 'Подсказка', {
+    animation: [
+        [
+            { opacity: 0, transform: 'translateY(-5px)' },
+            { opacity: 1, transform: 'translateY(0)' },
+        ],
+        [
+            { opacity: 1, transform: 'translateY(0)' },
+            { opacity: 0, transform: 'translateY(-5px)' },
+        ],
+    ],
+});
+```
+
+#### appendTo
+
+Элемент, в который вставляется подсказка перед показом. По умолчанию `document.body`. Значение `'parent'` вставляет подсказку в родителя опорного элемента — это нужно, когда её обрезает или перекрывает контейнер.
 
 #### arrow
 
@@ -76,13 +100,93 @@ createTooltip(document.querySelector('button'), 'Подсказка', {
 });
 ```
 
+#### delay
+
+Задержка перед появлением и перед скрытием в миллисекундах: `[появление, скрытие]`. Методы `show({ immediately: true })` и `hide({ immediately: true })` отключают задержку и анимацию.
+
+#### duration
+
+Длительность анимации появления и скрытия в миллисекундах: `[появление, скрытие]`.
+
+#### easing
+
+Функция плавности анимации появления и скрытия: `[появление, скрытие]`. Принимает значения CSS, например `ease-out` или `cubic-bezier(0.4, 0, 0.2, 1)`.
+
+#### flipPadding
+
+Минимальный зазор между подсказкой и краем области видимости, при котором подсказка переворачивается на противоположную сторону. По умолчанию `0`: переворот происходит, только если подсказка не помещается целиком.
+
+Переворот наступает, когда подсказка, её зазор `offset` и `flipPadding` вместе не помещаются с выбранной стороны. Например, при `flipPadding: 60` подсказка над элементом перевернётся вниз, если сверху останется меньше 60 px свободного места.
+
+Значение передаётся в middleware `flip` из Floating UI: число либо объект со сторонами `top`, `right`, `bottom`, `left`.
+
+```js
+createTooltip(document.querySelector('button'), 'Подсказка', {
+    flipPadding: 60,
+});
+```
+
 Так же настраивается через data-атрибут:
 
 ```html
-<button type="button" data-tooltip-arrow='{"centered":true}'>Кнопка</button>
+<button type="button" data-tooltip-flip-padding="60">Кнопка</button>
 ```
 
-##### virtualReference
+#### hideOnClick
+
+- `true` (по умолчанию) — всплывающая подсказка скрывается при клике по любому элементу на странице (**кроме** самой всплывающей подсказки).
+- `'all'` — всплывающая подсказка скрывается при клике по любому элементу на странице (**включая** саму всплывающую подсказку).
+- `'toggle'` — всплывающая подсказка скрывается только при клике по элементу, который её вызывает.
+
+Настройка работает только с `trigger`, включающим `click` или `manual`.
+
+#### interactive
+
+`true` (по умолчанию) — курсор можно перевести с элемента на подсказку и взаимодействовать с её содержимым. Невидимая зона перекрывает зазор `offset` между элементом и подсказкой, чтобы подсказка не скрылась по пути курсора.
+
+`false` — подсказка скрывается сразу, как только курсор уходит с элемента.
+
+#### offset
+
+Зазор между элементом и подсказкой: `[поперёк основной оси, вдоль основной оси]`. Для `top` и `bottom` первое значение сдвигает подсказку по горизонтали, второе задаёт зазор по вертикали. По умолчанию `[0, 8]` — 8 px между элементом и подсказкой.
+
+#### placement
+
+Сторона размещения: `top`, `right`, `bottom`, `left`. Выравнивание задаётся суффиксом `-start` или `-end`, например `bottom-start`. Если места с выбранной стороны не хватает, подсказка переворачивается (см. `flipPadding`).
+
+#### shiftPadding
+
+Отступ от края области видимости, на который подсказка сдвигается вдоль оси, чтобы полностью поместиться на экране: `[по горизонтали, по вертикали]`. Для `top` и `bottom` работает по горизонтали, для `left` и `right` — по вертикали.
+
+По умолчанию `[8, 0]`. Пример с отступом 12 px от краёв экрана на мобильных:
+
+```js
+createTooltip(document.querySelector('button'), 'Подсказка', {
+    shiftPadding: [12, 0],
+});
+```
+
+#### theme
+
+Тема оформления. Значение подставляется в класс `tooltip_theme_<theme>` — стили для каждой темы задаёт потребитель. По умолчанию `light`.
+
+#### trigger
+
+События, по которым показывается и скрывается подсказка: строка со списком через пробел. По умолчанию `mouseenter click`.
+
+- `mouseenter` — по наведению курсора (только мышь);
+- `click` — по клику;
+- `focus` — по получению фокуса;
+- `blur` — скрытие по потере фокуса;
+- `manual` — без обработчиков: показ и скрытие только через `show()` и `hide()`.
+
+```js
+createTooltip(document.querySelector('button'), 'Подсказка', {
+    trigger: 'click',
+});
+```
+
+#### virtualReference
 
 Настройка используется для кастомного позиционирования, ожидает объект с методом `getBoundingClientRect`.
 
@@ -107,7 +211,22 @@ createTooltip(document.querySelector('button'), 'Подсказка', {
 });
 ```
 
-#### Свойства
+#### zIndex
+
+Значение для свойства `z-index` подсказки. По умолчанию пустая строка — `z-index` не задаётся, работает значение из CSS.
+
+#### Колбэки
+
+Каждый колбэк получает экземпляр подсказки (`instance` — то же, что `$el._tooltip`).
+
+- `onCreate` — после создания экземпляра, до первого показа. Здесь уже доступны `show()` и `hide()`.
+- `onMount` — при первом показе, после создания DOM подсказки и до её вставки в документ. Удобно для инициализации вложенных компонентов.
+- `onShow` — после вставки в документ, перед анимацией появления.
+- `onShown` — после анимации появления.
+- `onHide` — перед анимацией скрытия.
+- `onHidden` — после анимации скрытия, когда подсказка уже удалена из документа.
+
+### Свойства
 
 #### $tooltip
 
@@ -121,39 +240,33 @@ DOM-элемент всплывающей подсказки (имеет сво
 
 Видимость всплывающей подсказки - `true`/`false`
 
-#### Методы
+### Методы
 
-##### show
+#### show
 
 ```js
 document.querySelector('button')._tooltip.show();
 ```
 
-##### hide
+#### hide
 
 ```js
 document.querySelector('button')._tooltip.hide();
 ```
 
-##### setContent
+#### setContent
 
 ```js
 document.querySelector('button')._tooltip.setContent('Новая подсказка');
 ```
 
-##### updateOptions
+#### updateOptions
 
 ```js
 document.querySelector('button')._tooltip.updateOptions({ placement: 'bottom' });
 ```
 
-Настройки так же можно переназначать, используя data-атрибуты:
+#### destroy
-
-```html
-<button type="button" data-tooltip-placement="bottom">Кнопка</button>
-```
-
-##### destroy
 
 ```js
 document.querySelector('button')._tooltip.destroy();

packages/tooltip/index.js

@@ -59,6 +59,7 @@ export const createTooltip = ($el, initialContent, initialOptions) => {
         delay: [0, 0],
         duration: [0, 0],
         easing: ['linear', 'linear'],
+        flipPadding: 0,
         hideOnClick: true, // Возможные значения: true, 'all', 'toggle'
         interactive: true,
         offset: [0, 8],
@@ -204,6 +205,7 @@ export const createTooltip = ($el, initialContent, initialOptions) => {
 
             if (
                 updatedOptions.offset !== undefined ||
+                updatedOptions.flipPadding !== undefined ||
                 updatedOptions.shiftPadding !== undefined ||
                 updatedOptions.arrow !== undefined
             ) {
@@ -337,7 +339,7 @@ export const createTooltip = ($el, initialContent, initialOptions) => {
                 const arrowSize = $el._tooltip.$arrow?.offsetWidth ?? 0;
                 return [
                     offset({ mainAxis: options.offset[1], crossAxis: options.offset[0] }),
-                    flip(),
+                    flip({ padding: options.flipPadding }),
                     shift({
                         padding: {
                             top: options.shiftPadding[1],

packages/tooltip/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@advdominion/tooltip",
-  "version": "7.1.1",
+  "version": "7.2.0",
   "type": "module",
   "main": "index.js",
   "repository": {