From f97680e7dbb015c90c52bf3a2589733212fd2feb Mon Sep 17 00:00:00 2001 From: Valentin Silyutin Date: Tue, 27 Oct 2026 13:05:22 +0400 Subject: [PATCH] @advdominion/tooltip@7.2.0 --- packages/tooltip/CHANGELOG.md | 6 ++ packages/tooltip/README.md | 151 +++++++++++++++++++++++++++++----- packages/tooltip/index.js | 4 +- packages/tooltip/package.json | 2 +- 4 files changed, 142 insertions(+), 21 deletions(-) diff --git a/packages/tooltip/CHANGELOG.md b/packages/tooltip/CHANGELOG.md index cb3dbee..8ddec72 100644 --- a/packages/tooltip/CHANGELOG.md +++ b/packages/tooltip/CHANGELOG.md @@ -1,3 +1,9 @@ +## v7.2.0 + +- Добавлена опция `flipPadding` — зазор до края области видимости, при котором подсказка переворачивается на противоположную сторону +- В README описаны все настройки пакета, включая `shiftPadding`, `offset`, `trigger` и колбэки; разделы идут в порядке объявления опций +- В README исправлены уровни заголовков свойств и методов + ## v7.1.1 - Позиция при прокрутке обновляется без принудительного reflow: все измерения геометрии выполняются до записи стилей diff --git a/packages/tooltip/README.md b/packages/tooltip/README.md index 6e5d1f0..4eeb71b 100644 --- a/packages/tooltip/README.md +++ b/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` (по умолчанию) — всплывающая подсказка скрывается при клике по любому элементу на странице (**кроме** самой всплывающей подсказки). -- `'all'` — всплывающая подсказка скрывается при клике по любому элементу на странице (**включая** саму всплывающую подсказку). -- `'toggle'` — всплывающая подсказка скрывается только при клике по элементу, который её вызывает. +```html + +``` + +#### 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 - + ``` -##### 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_` — стили для каждой темы задаёт потребитель. По умолчанию `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-атрибуты: - -```html - -``` - -##### destroy +#### destroy ```js document.querySelector('button')._tooltip.destroy(); diff --git a/packages/tooltip/index.js b/packages/tooltip/index.js index 5eed4a2..5b06aae 100644 --- a/packages/tooltip/index.js +++ b/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], diff --git a/packages/tooltip/package.json b/packages/tooltip/package.json index 52f3953..ef3e683 100644 --- a/packages/tooltip/package.json +++ b/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": {