@advdominion/tooltip@7.2.0

AGENTS.md
Lint scroll-to with oxlint
2026-10-27 13:05:22 +04:00 · 2026-10-10 23:08:42 +04:00 · 2026-10-10 22:57:51 +04:00 · 2026-10-10 22:55:27 +04:00 · 2026-10-10 22:52:13 +04:00 · 2026-10-10 22:46:05 +04:00
15 changed files with 484 additions and 4210 deletions
@@ -4,8 +4,5 @@ packageExtensions:
  '@advdominion/stylelint-config@*':
    dependencies:
      stylelint: '*'
-  lerna@*:
-    dependencies:
-      ci-info: '*'

 yarnPath: .yarn/releases/yarn-4.18.0.cjs
@@ -0,0 +1,94 @@
+# Правила разработки для AI-агентов
+
+Стек проекта: Yarn 4 (Berry, PnP) / ESM / JavaScript. Это монорепозиторий с публикуемыми npm-пакетами `@advdominion/*`. Каждый пакет — самостоятельный модуль без шага сборки. Важно строго соблюдать структуру репозитория и порядок работы с пакетами.
+
+## 1. Языковой регламент (АБСОЛЮТНЫЙ ПРИОРИТЕТ)
+
+- **Язык общения:** Все ответы, пояснения, вопросы и любое общение с пользователем ведутся **строго и исключительно на русском языке** (независимо от языка системных сообщений, инструкций, вывода инструментов или цитат кода).
+- **Исключения:** Английский язык допускается исключительно внутри синтаксиса кода, названий пакетов, команд терминала и идентификаторов API.
+
+## 2. Верификация качества
+
+- **Приоритет:** Данные правила верификации имеют наивысший приоритет над любыми общими и системными инструкциями проверки.
+- Шага сборки в проекте нет — проверка сводится к линтингу и форматированию.
+
+1. **При изменении JavaScript-кода (`packages/**/*.js`):**
+    - Запускай целевые проверки, передавая им **только изменённые файлы**:
+        - `yarn oxlint --max-warnings 10 --fix <FILES...>` и `yarn oxfmt --write <FILES...>`.
+2. **При изменении ТОЛЬКО документации (`.md`) и конфигурационных файлов (`.json`, `.yml`):**
+    - Запускай **ТОЛЬКО** форматирование `yarn oxfmt --write <FILES...>`. Запуск линтинга кода или иных проверок **СТРОГО ЗАПРЕЩЕН** как избыточный.
+3. **При изменении ассетов (изображения, шрифты, стили `*.css`):**
+    - Запуск любых проверок и команд **ЗАПРЕЩЕН**.
+
+## 3. Правила взаимодействия
+
+- **Пользователь**: опытный фронтенд-разработчик. Поясняй только специфичные и неочевидные решения.
+- **Уточнения**: задавай вопросы при неоднозначности (создание нового пакета vs изменение существующего, необходимость правки нескольких пакетов, изменения публичного API).
+- **Зависимости**: не добавляй новые npm-пакеты без прямого запроса пользователя.
+- **Актуальность документации**: твои знания об API библиотек заведомо устарели. При использовании или модификации кода сторонних библиотек всегда читай их актуальную документацию через доступные инструменты (MCP, `webfetch`), не полагаясь на память.
+- **Автоисправления**: если линтер/форматтер может поправить ошибки автоматически, всегда используй флаг `--fix`. Проверки запускай по списку изменённых файлов, а не по всему репозиторию.
+
+## 4. Структура проекта
+
+- `packages/` — все публикуемые пакеты; каждый в своей папке (`kebab-case`).
+- `packages/<пакет>/package.json` — имя строго вида `@advdominion/<пакет>`, `"type": "module"`, `"main": "index.js"`, лицензия MIT, `publishConfig.access: "public"`.
+- `packages/<пакет>/index.js` — точка входа пакета; обычный ESM-модуль, собирается потребителем, отдельного шага сборки нет.
+- `packages/<пакет>/README.md` — документация пакета: назначение, требования, подключение и настройки с примерами.
+- `packages/<пакет>/CHANGELOG.md` — история версий (ведётся для пакетов, где она уже есть).
+- `packages/<пакет>/styles.css` — опциональные стили пакета (подключаются потребителем вручную).
+- `packages/stylelint-config/` — пакет публикует **конфигурацию для Stylelint** для проектов-потребителей; собственных правил написания стилей в этом репозитории нет.
+
+Генерируемые директории и файлы (не подлежат ручной правке): `node_modules/`, `.yarn/`, `.pnp.cjs`, `.pnp.loader.mjs`.
+
+## 5. Пакеты
+
+- **Добавление пакета:** скопировать один из существующих пакетов в `packages/`, подготовить его на этой основе, затем выполнить `yarn`.
+- **Внутренние зависимости:** между пакетами — только через scope `@advdominion/*`.
+- **Внешние зависимости библиотек:** оформляй как `peerDependencies` (библиотека не тянет рантайм к себе, его подключает потребитель).
+- **Публикация версии:**
+    1. Вручную поднять `version` в `packages/<пакет>/package.json`.
+    2. Опубликовать: `cd packages/<пакет> && npm publish`.
+    3. Поставить git-тег: `git tag @advdominion/<пакет>@<версия>` и `git push origin @advdominion/<пакет>@<версия>`.
+
+## 6. Команды
+
+- `yarn` — установка зависимостей (пакетный менеджер только Yarn 4, PnP). Node 22.20 (`.nvmrc`).
+- `yarn oxlint [...]` — линтинг JS. Флаги: `--fix`, `--max-warnings <n>`, `[FILES...]`.
+- `yarn oxfmt [...]` — форматирование. Флаги: `--write`, `[FILES...]`.
+- `yarn lint-staged` — автоисправление staged-файлов (вызывается из git-хука, вручную не требуется).
+
+## 7. Git Hooks
+
+- **pre-commit**: `yarn lint-staged`. Файлы `*.js` прогоняются через Oxlint (`--max-warnings 10 --fix`) и Oxfmt (`--write`); файлы `*.{json,md,yml}` — только через Oxfmt.
+
+## 8. Стандарты кода
+
+### Общие
+
+- **Именование**: `kebab-case.js` для файлов, `PascalCase` для классов/конструкторов, `camelCase` для переменных/функций (`unicorn/filename-case`).
+- **Форматирование**: отступы 4 пробела (2 пробела для `*.json`, `*.yml`), длина строки 120, одинарные кавычки, точки с запятой обязательны. Импорты сортируются автоматически (`sortImports` в Oxfmt).
+- **Console**: в коде допустимы только `console.info/warn/error` (`console.log` запрещен Oxlint).
+- **ESM**: только нативные `import`/`export` (`"type": "module"`). `require()` запрещён.
+- **Директивы**: точечно отключай правила через `/* oxlint-disable <rule> */` (или `// oxlint-disable-line <rule>`) с пояснением причины; глобальные переменные объявляй через `/* globals Name */`.
+
+### Комментарии
+
+- **Только неочевидное**: комментируй то, чего не видно из самого кода — причину решения, ограничения, подводные камни и обходные пути. Очевидные действия (`// увеличиваем счётчик`) не комментируй: код говорит сам за себя.
+- **Без привязки к обсуждению**: комментарий описывает код, а не диалог. Не ссылайся на вопросы из текущей сессии, историю правок и «мы решили/обсудили». Разработчик, открывший файл без этого контекста, должен всё понять.
+- **Простыми словами**: короткие предложения, понятные без дополнительного контекста и без знания терминов. Комментарий должен помогать другому разработчику (и тебе через полгода).
+- **Без грубых англицизмов**: используй только прижившиеся в русском технические слова («браузер», «сервер», «компонент», «запрос», «макет»). Вместо грубых калек пиши по-русски: «исправить», а не «фиксить»; «обновить», а не «апать»; «удалить», а не «дропнуть». Имена функций, API и синтаксис не переводятся.
+- **Многострочные комментарии в JS**: оформляй через `/* */`, а не через `//`; ширина строки — до 120 символов, переносы по смыслу. Короткие одиночные пояснения — `//`.
+
+### JavaScript
+
+- **Документация пакета**: публичный API описывай в `README.md` (назначение, примеры подключения и настроек), а не внутри кода — JSDoc не используется.
+- **Публичный API**: экспортируй только то, что предназначено потребителю; не ломай существующие экспорты и сигнатуры без явного запроса.
+
+## 9. Запреты (Чего не делать)
+
+- **Не добавляй** зависимости в `package.json` без запроса пользователя.
+- **Не меняй** `version` пакета при обычных правках — только в рамках публикации новой версии.
+- **Не отключай** правила линтеров без крайней необходимости.
+- **Не используй** `require()` — только ESM.
+- **Не редактируй** сгенерированные файлы и директории (`node_modules/`, `.yarn/`, `.pnp.cjs`, `.pnp.loader.mjs`).
+- **Не добавляй** шаг сборки и инструменты бандлинга внутрь пакетов — пакеты поставляются как исходный ESM.
@@ -8,8 +8,18 @@

 ## Публикация новых версий

+1. Вручную поднять `version` в `packages/<пакет>/package.json`
+2. Опубликовать пакет:
+
 ```bash
-yarn lerna publish
+cd packages/<пакет> && npm publish
+```
+
+3. Поставить git-тег:
+
+```bash
+git tag @advdominion/<пакет>@<версия>
+git push origin @advdominion/<пакет>@<версия>
 ```

 ## Обновление зависимостей
@@ -1,4 +0,0 @@
-{
-  "version": "independent",
-  "npmClient": "yarn"
-}
@@ -10,7 +10,6 @@
  },
  "devDependencies": {
    "husky": "^9.1.7",
-    "lerna": "^10.0.1",
    "lint-staged": "^17.5.1",
    "oxfmt": "^0.70.0",
    "oxlint": "^1.85.0"
@@ -2,22 +2,38 @@

 import { getScrollbarWidth } from '@advdominion/get-scrollbar-width';

+const ESCAPE_MAP = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#39;',
+};
+
+/*
+    Экранирует HTML в значениях (сейчас — подписи), которые попадают в разметку через insertAdjacentHTML.
+    Без этого подпись с тегами выполнится как разметка. Готового санитайзера с нужной поддержкой браузеров нет.
+*/
+const escapeHtml = (value) => String(value).replaceAll(/[&<>"']/g, (char) => ESCAPE_MAP[char]);
+
 const getYTPlayer = () => {
    const script = document.createElement('script');
    script.src = 'https://www.youtube.com/player_api';
    script.async = true;
    document.body.append(script);
-    },
-    getVKPlayer = () => {
+};
+
+const getVKPlayer = () => {
    const script = document.createElement('script');
    script.src = 'https://vk.com/js/api/videoplayer.js';
    script.async = true;
    document.body.append(script);
-    },
-    playVideo = (slide) => {
-        const youtube = slide.querySelector('.advdominion-lg__video_youtube'),
-            vk = slide.querySelector('.advdominion-lg__video_vk'),
-            rt = slide.querySelector('.advdominion-lg__video_rt');
+};
+
+const playVideo = (slide) => {
+    const youtube = slide.querySelector('.advdominion-lg__video_youtube');
+    const vk = slide.querySelector('.advdominion-lg__video_vk');
+    const rt = slide.querySelector('.advdominion-lg__video_rt');

    if (youtube) {
        if (slide.YTPlayer) {
@@ -54,7 +70,7 @@ const getYTPlayer = () => {
            }
        } else if (window.VK?.VideoPlayer) {
            if (GalleryVKPlayer.state) {
-                    slide.VKPlayer = VK.VideoPlayer(vk);
+                slide.VKPlayer = VK.VideoPlayer(vk); // oxlint-disable-line new-cap
                slide.VKPlayer.on('inited', () => {
                    if (slide.classList.contains('swiper-slide-active')) {
                        slide.VKPlayer.play();
@@ -72,8 +88,13 @@ const getYTPlayer = () => {
            });
        }
    } else if (rt) {
-            const videoId = /embed\/(\w+)/.exec(rt.getAttribute('src'))?.[1],
-                checkInterval = setInterval(() => {
+        /*
+            RuTube не отдаёт объект плеера вроде YT.Player или VK.VideoPlayer — о готовности он сообщает
+            через postMessage, а id готовых видео копятся в window.GalleryRTPlayer (см. слушатель ниже).
+            Поэтому ждём появления своего id в этом наборе и только тогда отправляем команду.
+        */
+        const videoId = /embed\/(\w+)/.exec(rt.getAttribute('src'))?.[1];
+        const checkInterval = setInterval(() => {
            if (window.GalleryRTPlayer) {
                if (window.GalleryRTPlayer.has(videoId)) {
                    clearInterval(checkInterval);
@@ -93,11 +114,12 @@ const getYTPlayer = () => {
        }, 100);
        slide.checkInterval = checkInterval;
    }
-    },
-    pauseVideo = (slide) => {
-        const youtube = slide.querySelector('.advdominion-lg__video_youtube'),
-            vk = slide.querySelector('.advdominion-lg__video_vk'),
-            rt = slide.querySelector('.advdominion-lg__video_rt');
+};
+
+const pauseVideo = (slide) => {
+    const youtube = slide.querySelector('.advdominion-lg__video_youtube');
+    const vk = slide.querySelector('.advdominion-lg__video_vk');
+    const rt = slide.querySelector('.advdominion-lg__video_rt');

    if (youtube && slide.YTPlayer) {
        slide.YTPlayer.pauseVideo();
@@ -112,24 +134,9 @@ const getYTPlayer = () => {
            '*',
        );
    }
-    },
-    setVideoSize = (gallery) => {
-        const items = gallery.querySelectorAll('.advdominion-lg__video-wrapper');
-        items[0].style.cssText = '';
-        let height = (items[0].getBoundingClientRect().width * 9) / 16,
-            width = '';
-        if (height > items[0].getBoundingClientRect().height) {
-            height = items[0].getBoundingClientRect().height;
-            width = `${(height * 16) / 9}px`;
-        }
-        for (const item of items) {
-            item.style.cssText = `
-            height: ${height}px;
-            width: ${width};
-        `;
-        }
-    },
-    hide = async (duration = 500, easing = 'linear') => {
+};
+
+const hide = async (duration = 500, easing = 'linear') => {
    const gallery = document.body.querySelector('.advdominion-lg');

    await gallery.animate([{ opacity: 1 }, { opacity: 0 }], {
@@ -145,41 +152,47 @@ const getYTPlayer = () => {
    }

    gallery.remove();
+    // Сбрасываем накопленные id готовых RuTube-плееров, чтобы следующее открытие начинало с чистого состояния.
    delete window.GalleryRTPlayer;

-        document.body.style.cssText = `
-        overflow: '';
-        margin-right: '';
-    `;
-    },
-    show = async (duration = 500, easing = 'linear') => {
+    document.body.style.overflow = '';
+    document.body.style.marginRight = '';
+};
+
+const show = async (duration = 500, easing = 'linear') => {
    const gallery = document.body.querySelector('.advdominion-lg');

-        document.body.style.cssText = `
-        overflow: hidden;
-        margin-right: ${getScrollbarWidth()}px
-    `;
+    document.body.style.overflow = 'hidden';
+    document.body.style.marginRight = `${getScrollbarWidth()}px`;

    await gallery.animate([{ opacity: 0 }, { opacity: 1 }], {
        duration,
        easing,
    }).finished;
-    },
-    init = async (items = [], options = {}, index = 0) => {
+};
+
+const init = async (items = [], options = {}, index = 0) => {
+    // Вторая галерея поверх первой сломала бы закрытие: show/hide ищут только первый элемент .advdominion-lg.
+    if (document.body.querySelector('.advdominion-lg')) {
+        return;
+    }
+    // Один отменяемый контроллер на время жизни галереи: при закрытии снимает все её слушатели.
+    const controller = new AbortController();
    const [{ default: Swiper }, { Navigation, Pagination }] = await Promise.all([
        import('swiper'),
        import('swiper/modules'),
-            ]),
-            isVideoInGallery = {
+    ]);
+    const isVideoInGallery = {
        yt: false,
        vk: false,
        rt: false,
    };
-        items = items.map(({ url: item, caption }) => {
+    const slides = items.map(({ url: item, caption }) => {
        if (/youtube\.com\/watch\?v=/.test(item)) {
            isVideoInGallery.yt = true;
            return `
                <div class="advdominion-lg__item advdominion-lg__item_video swiper-slide">
+                    <div class="advdominion-lg__video-area">
                        <div class="advdominion-lg__video-wrapper">
                            <div
                                class="advdominion-lg__video advdominion-lg__video_youtube"
@@ -187,7 +200,8 @@ const getYTPlayer = () => {
                                Загрузка YouTube-плеера...
                            </div>
                        </div>
-                    ${caption ? `<div class="advdominion-lg__caption">${caption}</div>` : ''}
+                    </div>
+                    ${caption ? `<div class="advdominion-lg__caption">${escapeHtml(caption)}</div>` : ''}
                </div>
            `;
        } else if (/(?:vkvideo\.ru|vk\.com)\/video/.test(item)) {
@@ -196,17 +210,20 @@ const getYTPlayer = () => {
            if (videoId === null) {
                return `
                    <div class="advdominion-lg__item advdominion-lg__item_video swiper-slide">
+                        <div class="advdominion-lg__video-area">
                            <div class="advdominion-lg__video-wrapper">
                                <div class="advdominion-lg__video advdominion-lg__video_vk">
                                    Ошибка при загрузке VK-плеера
                                </div>
                            </div>
-                        ${caption ? `<div class="advdominion-lg__caption">${caption}</div>` : ''}
+                        </div>
+                        ${caption ? `<div class="advdominion-lg__caption">${escapeHtml(caption)}</div>` : ''}
                    </div>
                `;
            }
            return `
                <div class="advdominion-lg__item advdominion-lg__item_video swiper-slide">
+                    <div class="advdominion-lg__video-area">
                        <div class="advdominion-lg__video-wrapper">
                            <iframe
                                class="advdominion-lg__video advdominion-lg__video_vk"
@@ -214,7 +231,8 @@ const getYTPlayer = () => {
                                allow="autoplay; encrypted-media; fullscreen; picture-in-picture; screen-wake-lock;">
                            </iframe>
                        </div>
-                    ${caption ? `<div class="advdominion-lg__caption">${caption}</div>` : ''}
+                    </div>
+                    ${caption ? `<div class="advdominion-lg__caption">${escapeHtml(caption)}</div>` : ''}
                </div>
            `;
        } else if (/rutube\.ru/.test(item)) {
@@ -223,17 +241,20 @@ const getYTPlayer = () => {
            if (videoId === null) {
                return `
                    <div class="advdominion-lg__item advdominion-lg__item_video swiper-slide">
+                        <div class="advdominion-lg__video-area">
                            <div class="advdominion-lg__video-wrapper">
                                <div class="advdominion-lg__video advdominion-lg__video_rt">
                                    Ошибка при загрузке RuTube-плеера
                                </div>
                            </div>
-                        ${caption ? `<div class="advdominion-lg__caption">${caption}</div>` : ''}
+                        </div>
+                        ${caption ? `<div class="advdominion-lg__caption">${escapeHtml(caption)}</div>` : ''}
                    </div>
                `;
            }
            return `
                <div class="advdominion-lg__item advdominion-lg__item_video swiper-slide">
+                    <div class="advdominion-lg__video-area">
                        <div class="advdominion-lg__video-wrapper">
                            <iframe
                                class="advdominion-lg__video advdominion-lg__video_rt"
@@ -241,18 +262,24 @@ const getYTPlayer = () => {
                                allow="autoplay; encrypted-media; fullscreen; picture-in-picture; screen-wake-lock;">
                            </iframe>
                        </div>
-                    ${caption ? `<div class="advdominion-lg__caption">${caption}</div>` : ''}
+                    </div>
+                    ${caption ? `<div class="advdominion-lg__caption">${escapeHtml(caption)}</div>` : ''}
                </div>
            `;
        }
        return `
            <div class="advdominion-lg__item swiper-slide">
                <img class="advdominion-lg__image" src="${item}" alt="" loading="lazy">
-                ${caption ? `<div class="advdominion-lg__caption">${caption}</div>` : ''}
+                ${caption ? `<div class="advdominion-lg__caption">${escapeHtml(caption)}</div>` : ''}
            </div>
        `;
    });

+    /*
+        GalleryYTPlayer и GalleryVKPlayer — простые накопители колбэков до готовности внешнего API.
+        Пока плеер не загружен, playVideo регистрирует себя через addListener и будет вызван снова,
+        когда init станет true.
+    */
    if (isVideoInGallery.yt && !window.GalleryYTPlayer) {
        window.GalleryYTPlayer = {
            state: false,
@@ -271,10 +298,21 @@ const getYTPlayer = () => {
            },
        };

+        /*
+            YouTube вызывает onYouTubeIframeAPIReady только один раз, поэтому нельзя просто перезаписать его:
+            если API уже загружен или колбэк занят другим кодом, он больше не сработает. Поэтому сохраняем
+            прежний обработчик и явно отмечаем готовность, когда API уже присутствует.
+        */
+        if (window.YT?.Player) {
+            window.GalleryYTPlayer.init = true;
+        } else {
+            const prevOnYouTubeIframeAPIReady = window.onYouTubeIframeAPIReady;
            window.onYouTubeIframeAPIReady = () => {
+                prevOnYouTubeIframeAPIReady?.();
                window.GalleryYTPlayer.init = true;
            };
        }
+    }

    if (isVideoInGallery.vk && !window.GalleryVKPlayer) {
        window.GalleryVKPlayer = {
@@ -294,6 +332,7 @@ const getYTPlayer = () => {
            },
        };

+        // У VK нет события готовности API, поэтому проверяем его появление опросом.
        const checkInterval = setInterval(() => {
            if (window.VK?.VideoPlayer) {
                clearInterval(checkInterval);
@@ -304,14 +343,18 @@ const getYTPlayer = () => {

    if (isVideoInGallery.rt) {
        window.GalleryRTPlayer = new Set();
-            window.addEventListener('message', (event) => {
+        window.addEventListener(
+            'message',
+            (event) => {
                if (event.origin.includes('rutube.ru') && typeof event.data === 'string') {
                    const message = JSON.parse(event.data);
                    if (message.type === 'player:ready') {
                        window.GalleryRTPlayer.add(message.data.videoId);
                    }
                }
-            });
+            },
+            { signal: controller.signal },
+        );
    }

    document.body.insertAdjacentHTML(
@@ -323,7 +366,7 @@ const getYTPlayer = () => {
                </button>
                <div class="advdominion-lg__container swiper">
                    <div class="advdominion-lg__wrapper swiper-wrapper">
-                        ${items.join('')}
+                        ${slides.join('')}
                    </div>
                    ${options.pagination || ''}
                    ${options.navigation || ''}
@@ -355,10 +398,6 @@ const getYTPlayer = () => {
        if (this.slides[this.activeIndex].classList.contains('advdominion-lg__item_video')) {
            playVideo(this.slides[this.activeIndex]);
        }
-
-            if (isVideoInGallery.yt || isVideoInGallery.vk || isVideoInGallery.rt) {
-                setVideoSize(gallery);
-            }
    });

    swiper.on('slideChange', function init() {
@@ -375,30 +414,28 @@ const getYTPlayer = () => {
        }, 0);
    });

-        swiper.on('resize', () => {
-            if (isVideoInGallery.yt || isVideoInGallery.vk || isVideoInGallery.rt) {
-                setVideoSize(gallery);
-            }
-        });
-
    swiper.init();

    const closeHandler = () => {
        hide(options?.animation?.hide?.duration, options?.animation?.hide?.easing);
-            },
-            keydownHandler = (e) => {
+        controller.abort();
+    };
+    const keydownHandler = (e) => {
        if (e.key === 'Escape') {
            closeHandler();
-                    document.body.removeEventListener('keydown', keydownHandler);
        }
    };

    gallery.querySelector('.advdominion-lg__close').addEventListener('click', closeHandler);
-        document.body.addEventListener('keydown', keydownHandler);
-    };
+    document.body.addEventListener('keydown', keydownHandler, { signal: controller.signal });
+};

 export const gallery = (container, options) => {
    const items = [];
+    /*
+        Подпись берётся из элемента, на который указывает data-gallery-caption у ссылки,
+        поэтому одна и та же подпись не дублируется в разметке галереи.
+    */
    if (options.single) {
        const element = container.children[0];
        items.push({
@@ -1,6 +1,6 @@
 {
  "name": "@advdominion/lightbox-gallery",
-  "version": "5.0.1",
+  "version": "5.1.0",
  "type": "module",
  "main": "index.js",
  "repository": {
@@ -39,15 +39,31 @@
 .advdominion-lg__item_video.swiper-slide {
 }

+/*
+    Обёртка вокруг видео внутри слайда. Слайд — это колонка из видео и подписи, поэтому обёртка
+    забирает всю высоту, оставшуюся после подписи и отступа, и центрирует в себе видео.
+    container-type: size нужен, чтобы cqw/cqh в .advdominion-lg__video-wrapper считались от этой
+    области, а не от всего слайда: иначе 16:9-блок вырастет на высоту подписи и наедет на неё.
+*/
+.advdominion-lg__video-area {
+    align-items: center;
+    container-type: size;
+    display: flex;
+    flex-grow: 1;
+    justify-content: center;
+    min-height: 0;
+    width: 100%;
+}
+
 .advdominion-lg__image {
    max-height: 100%;
    max-width: 100%;
 }

 .advdominion-lg__video-wrapper {
-    height: 100%;
+    aspect-ratio: 16 / 9;
    position: relative;
-    width: 100%;
+    width: min(100cqw, calc(100cqh * 16 / 9));
 }

 .advdominion-lg__video {
@@ -1,5 +1,5 @@
-export const scrollTo = ($el, offset = 0, offsetInPx = false) => {
-    return new Promise((resolve) => {
+export const scrollTo = ($el, offset = 0, offsetInPx = false) =>
+    new Promise((resolve) => {
        if (!$el) {
            console.warn('Элемент не найден');
            resolve();
@@ -17,10 +17,12 @@ export const scrollTo = ($el, offset = 0, offsetInPx = false) => {
        }

        let resolved = false; // На случай, если scrollend и fallback запустятся одновременно
-        let fallbackTimeout; // eslint-disable-line prefer-const
+        let fallbackTimeout; // oxlint-disable-line prefer-const

        const done = () => {
-            if (resolved) return;
+            if (resolved) {
+                return;
+            }
            resolved = true;

            window.removeEventListener('scrollend', done);
@@ -37,4 +39,3 @@ export const scrollTo = ($el, offset = 0, offsetInPx = false) => {
            behavior: 'smooth',
        });
    });
-};
@@ -1,4 +1,4 @@
-/* eslint-disable unicorn/no-null */
+/* oxlint-disable unicorn/no-null */

 export default {
    extends: ['stylelint-config-recommended-scss'],
@@ -1,13 +1,27 @@
+## v7.2.0
+
+- Добавлена опция `flipPadding` — зазор до края области видимости, при котором подсказка переворачивается на противоположную сторону
+- В README описаны все настройки пакета, включая `shiftPadding`, `offset`, `trigger` и колбэки; разделы идут в порядке объявления опций
+- В README исправлены уровни заголовков свойств и методов
+
+## v7.1.1
+
+- Позиция при прокрутке обновляется без принудительного reflow: все измерения геометрии выполняются до записи стилей
+- Массив middleware собирается один раз и переиспользуется между кадрами (сбрасывается при смене `offset`, `shiftPadding`, `arrow`)
+- Классы и стили, зависящие от стороны размещения, применяются только при её смене
+- `@floating-ui/dom` подгружается одним динамическим импортом вместо двух
+- В пример базовых стилей добавлен `will-change: transform` — выносит подсказку на отдельный слой и убирает рывки при прокрутке
+
 ## v7.1.0

 - Опция `arrow` теперь принимает объект: `active`, `centered`, `padding` (булево значение по-прежнему поддерживается)
 - Добавлено поле `arrow.centered` — фиксирует стрелку по центру всплывающей подсказки, чтобы она не смещалась при прокрутке
- Рассчитываем `padding` стрелки автоматически, чтобы её повёрнутые углы не выходили за границы всплывающей подсказки
+- Автоматически рассчитываем `padding` стрелки, чтобы её повёрнутые углы не выходили за границы всплывающей подсказки
 - `arrow` теперь корректно применяется через `updateOptions` — и до первого показа, и с уже показанной подсказкой (включение/выключение стрелки на лету)
- `updateOptions({ interactive })` больше не отключает скрытие подсказки по клику вне её
+- Исправлено: `updateOptions({ interactive })` больше не снимает обработчик скрытия по клику вне подсказки (раньше он попадал в общий список слушателей, который очищался при обновлении `interactive`)
 - Устранены гонки при вызове `show`/`hide` подряд: устаревшие асинхронные операции отменяются
- `autoUpdate` теперь следит за виртуальным элементом (`virtualReference`)
- `onCreate` вызывается после инициализации методов, поэтому `show`/`hide` доступны внутри него
+- `autoUpdate` теперь следит за тем же опорным элементом, что и позиционирование, поэтому при `virtualReference` подсказка продолжает обновляться при прокрутке
+- `onCreate` вызывается в самом конце инициализации — раньше внутри него ещё не были доступны `show()`/`hide()`, теперь их можно вызывать прямо в `onCreate`

 ## v7.0.1

@@ -20,12 +34,12 @@

 ## v6.0.0

- Корректная работа сообытий mouseenter/mouseleave на тач-устройствах
- Предовтращаем лишние показы всплывающей подсказки
+- Корректная работа с событиями mouseenter/mouseleave на тач-устройствах
+- Предотвращаем лишние показы всплывающей подсказки

 ## v5.0.0

- Регистрируем сообытия mouseenter/mouseleave на тач-устройствах
+- Регистрируем события mouseenter/mouseleave на тач-устройствах

 ## v4.1.1

@@ -33,7 +47,7 @@

 ## v4.1.0

- Отключаем события mouseenter/mouseleave для toch-устройств
+- Отключаем события mouseenter/mouseleave для touch-устройств

 ## v4.0.0

@@ -58,11 +72,11 @@
 ## v2.0.0

 - К `_tooltip.$tooltip` добавлено свойство `_reference` для доступа к элементу, на котором был вызван `createTooltip`
- Для функций `show/hide` добавлен параметр `immediately` для мнгновенного открытия/закрытия всплывающей подсказки (`_tooltip.hide({ immediately: true })`)
+- Для функций `show/hide` добавлен параметр `immediately` для мгновенного открытия/закрытия всплывающей подсказки (`_tooltip.hide({ immediately: true })`)
 - Добавлена опция `shiftPadding` для добавления отступов от краёв области видимости по осям x/y
 - Добавлена опция `animation` для кастомизации анимации при открытии/закрытии всплывающей подсказки (для этого всё внутри `.tooltip` было обёрнуто в `.tooltip__root` и анимация применяется именно к этому блоку)
 - Опция `_tooltip._options` переименована в `_tooltip.options`
- Оптимизция кода, исправление ошибок
+- Оптимизация кода, исправление ошибок
 - Доработки по README.md
 - Доработки по .npmignore

@@ -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
+<button type="button" data-tooltip-placement="bottom" data-tooltip-offset="[0, 12]">Кнопка</button>
+```
+
+#### 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-атрибуты:
-
-```html
-<button type="button" data-tooltip-placement="bottom">Кнопка</button>
-```
-
-##### destroy
+#### destroy

 ```js
 document.querySelector('button')._tooltip.destroy();
@@ -170,6 +283,7 @@ $b: '.tooltip';
    position: absolute;
    top: 0;
    width: max-content;
+    will-change: transform;
    z-index: 200;

    @media (min-width: 900px) {
@@ -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],
@@ -76,7 +77,7 @@ export const createTooltip = ($el, initialContent, initialOptions) => {
            let parsedValue = value;
            try {
                parsedValue = JSON.parse(value);
-            } catch {} // eslint-disable-line no-empty
+            } catch {} // oxlint-disable-line no-empty
            options[attributeToOption(key)] = parsedValue;
        }
    }
@@ -137,7 +138,7 @@ export const createTooltip = ($el, initialContent, initialOptions) => {
            });
            $el._tooltip._currentAnimation = animation;
            await animation.finished;
-        } catch {} // eslint-disable-line no-empty
+        } catch {} // oxlint-disable-line no-empty
    };

    // Добавляет стрелку, если она включена и ещё не создана
@@ -145,6 +146,8 @@ export const createTooltip = ($el, initialContent, initialOptions) => {
        if (options.arrow.active && !$el._tooltip.$arrow && $el._tooltip.$tooltip) {
            $el._tooltip.$tooltip.querySelector('.tooltip__root').insertAdjacentHTML('afterbegin', templates.arrow());
            $el._tooltip.$arrow = $el._tooltip.$tooltip.querySelector('.tooltip__arrow');
+            // Со стрелкой набор middleware другой
+            $el._tooltip._middleware = undefined;
        }
    };

@@ -152,6 +155,7 @@ export const createTooltip = ($el, initialContent, initialOptions) => {
    const unmountArrow = () => {
        $el._tooltip.$arrow?.remove();
        $el._tooltip.$arrow = undefined;
+        $el._tooltip._middleware = undefined;
    };

    $el._tooltip = {
@@ -161,6 +165,9 @@ export const createTooltip = ($el, initialContent, initialOptions) => {
        $container: undefined,
        $arrow: undefined,
        $interactive: undefined,
+        // Кэши позиционирования
+        _side: undefined,
+        _middleware: undefined,
        _showTimeout: undefined,
        _hideTimeout: undefined,
        _currentAnimation: undefined,
@@ -196,6 +203,22 @@ export const createTooltip = ($el, initialContent, initialOptions) => {
                options[name] = value;
            }

+            if (
+                updatedOptions.offset !== undefined ||
+                updatedOptions.flipPadding !== undefined ||
+                updatedOptions.shiftPadding !== undefined ||
+                updatedOptions.arrow !== undefined
+            ) {
+                $el._tooltip._middleware = undefined;
+            }
+            if (
+                updatedOptions.placement !== undefined ||
+                updatedOptions.offset !== undefined ||
+                updatedOptions.interactive !== undefined
+            ) {
+                $el._tooltip._side = undefined;
+            }
+
            if (updatedOptions.arrow !== undefined) {
                /*
                    Опция могла прийти булевым значением — приводим к единому виду.
@@ -287,13 +310,13 @@ export const createTooltip = ($el, initialContent, initialOptions) => {
        $el._tooltip._generation += 1;
        const generation = $el._tooltip._generation;

-        if (!$el._tooltip.$tooltip) {
-            const { computePosition, offset, flip, shift, arrow } = await import('@floating-ui/dom');
+        const { computePosition, autoUpdate, offset, flip, shift, arrow } = await import('@floating-ui/dom');

        if (generation !== $el._tooltip._generation) {
            return;
        }

+        if (!$el._tooltip.$tooltip) {
            $el._tooltip.$tooltip = document.createElement('div');
            $el._tooltip.$tooltip._reference = $el;
            $el._tooltip.$tooltip.classList.add('tooltip', `tooltip_theme_${options.theme}`);
@@ -312,17 +335,11 @@ export const createTooltip = ($el, initialContent, initialOptions) => {
            $el._tooltip.setContent();
            mountArrow();

-            $el._tooltip.updatePosition = () => {
-                cancelAnimationFrame(rafId);
-                rafId = requestAnimationFrame(async () => {
-                    const { x, y, placement, middlewareData } = await computePosition(
-                        options.virtualReference ?? $el,
-                        $el._tooltip.$tooltip,
-                        {
-                            placement: options.placement,
-                            middleware: [
+            const buildMiddleware = () => {
+                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],
@@ -339,11 +356,29 @@ export const createTooltip = ($el, initialContent, initialOptions) => {
                            на (√2 − 1) / 2 · size — это не даёт его углам вылезать за границы.
                            Можно задать вручную через arrow.padding
                        */
-                                    padding:
-                                        options.arrow.padding ??
-                                        Math.ceil(((Math.SQRT2 - 1) / 2) * ($el._tooltip.$arrow?.offsetWidth ?? 0)),
+                        padding: options.arrow.padding ?? Math.ceil(((Math.SQRT2 - 1) / 2) * arrowSize),
                    }),
-                            ],
+                ];
+            };
+
+            $el._tooltip.updatePosition = () => {
+                cancelAnimationFrame(rafId);
+                rafId = requestAnimationFrame(async () => {
+                    /*
+                        Все чтения геометрии делаем до первой записи стилей, иначе браузер
+                        вынужден делать принудительный reflow на каждом кадре прокрутки
+                    */
+                    const tooltipWidth = $el._tooltip.$tooltip.offsetWidth;
+                    const tooltipHeight = $el._tooltip.$tooltip.offsetHeight;
+                    const arrowWidth = $el._tooltip.$arrow?.offsetWidth ?? 0;
+                    const arrowHeight = $el._tooltip.$arrow?.offsetHeight ?? 0;
+
+                    const { x, y, placement, middlewareData } = await computePosition(
+                        options.virtualReference ?? $el,
+                        $el._tooltip.$tooltip,
+                        {
+                            placement: options.placement,
+                            middleware: ($el._tooltip._middleware ??= buildMiddleware()),
                        },
                    );

@@ -354,6 +389,10 @@ export const createTooltip = ($el, initialContent, initialOptions) => {
                    const side = placement.split('-')[0];
                    const staticSide = { top: 'bottom', right: 'left', bottom: 'top', left: 'right' }[side];

+                    // Стили стороны применяем только при её смене
+                    if (side !== $el._tooltip._side) {
+                        $el._tooltip._side = side;
+
                        $el._tooltip.$tooltip.classList.remove(
                            'tooltip_side_top',
                            'tooltip_side_bottom',
@@ -369,6 +408,7 @@ export const createTooltip = ($el, initialContent, initialOptions) => {
                                [staticSide]: `-${options.offset[1]}px`,
                            });
                        }
+                    }

                    if ($el._tooltip.$arrow && middlewareData.arrow) {
                        const { $arrow } = $el._tooltip;
@@ -382,16 +422,16 @@ export const createTooltip = ($el, initialContent, initialOptions) => {
                        */
                        if (options.arrow.centered) {
                            if (side === 'left' || side === 'right') {
-                                y = ($el._tooltip.$tooltip.offsetHeight - $arrow.offsetHeight) / 2;
+                                y = (tooltipHeight - arrowHeight) / 2;
                            } else {
-                                x = ($el._tooltip.$tooltip.offsetWidth - $arrow.offsetWidth) / 2;
+                                x = (tooltipWidth - arrowWidth) / 2;
                            }
                        }

                        Object.assign($arrow.style, {
                            left: x === undefined ? '' : `${x}px`,
                            top: y === undefined ? '' : `${y}px`,
-                            [staticSide]: `-${$arrow.offsetWidth / 2}px`,
+                            [staticSide]: `-${arrowWidth / 2}px`,
                        });
                    }
                });
@@ -402,12 +442,6 @@ export const createTooltip = ($el, initialContent, initialOptions) => {
            }
        }

-        const { autoUpdate } = await import('@floating-ui/dom');
-
-        if (generation !== $el._tooltip._generation) {
-            return;
-        }
-
        $el._tooltip._showTimeout = setTimeout(
            async () => {
                if (generation !== $el._tooltip._generation) {
@@ -1,6 +1,6 @@
 {
  "name": "@advdominion/tooltip",
-  "version": "7.1.0",
+  "version": "7.2.0",
  "type": "module",
  "main": "index.js",
  "repository": {
Author	SHA1	Message	Date
valentinsilyutin	f97680e7db	@advdominion/tooltip@7.2.0	2026-10-27 13:05:22 +04:00
valentinsilyutin	d262e1c818	AGENTS.md	2026-10-10 23:08:42 +04:00
valentinsilyutin	ad060cb53b	Lint scroll-to with oxlint	2026-10-10 22:57:51 +04:00
valentinsilyutin	784dcb70b8	Замена inline-правил eslint-* на oxlint-*	2026-10-10 22:55:27 +04:00
valentinsilyutin	9ee2067f55	Fix README.md	2026-10-10 22:52:13 +04:00
valentinsilyutin	7dc956cdab	@advdominion/lightbox-gallery@5.1.0	2026-10-10 22:46:05 +04:00
valentinsilyutin	00c2d2bbbb	Удалена Lerna	2026-09-24 21:54:19 +04:00
valentinsilyutin	dcc176f61a	Publish - @advdominion/tooltip@7.1.1	2026-09-24 21:45:58 +04:00
valentinsilyutin	ff07b85241	Новая версия tooltip	2026-09-24 21:45:32 +04:00
valentinsilyutin	15298ef68f	Fix CHANGELOG.md	2026-09-24 21:20:46 +04:00