itube-modern-player 0.8.4 → 0.8.5

package/README.md

@@ -30,6 +30,7 @@
   - [События](#события)
 - [События: `PlayerEventMap`](#события-playereventmap)
 - [Vue 3: `<ITubePlayer>`](#vue-3-itubeplayer)
+- [Меню в дровере приложения: `menus: 'external'`](#меню-в-дровере-приложения-menus-external)
 - [Экспортируемые типы](#экспортируемые-типы)
 - [Экспортируемые утилиты](#экспортируемые-утилиты)
 - [Темизация](#темизация)
@@ -377,6 +378,10 @@ new Player('#mount', {
   playbackRates: [0.5, 0.75, 1, 1.25, 1.5, 2],  // пункты меню скорости
   seekStep: 15,      // секунды для стрелок/кнопок перемотки (по умолчанию 15; показывается на кнопке)
   keyboard: true,    // горячие клавиши (на контейнере, не на document!)
+  // Кто рендерит меню контрол-бара: 'native' (дефолт) | 'external' | 'external-mobile'.
+  // 'external*' — вместо открытия меню плеер эмитит `menurequest`, рендерит приложение
+  // (см. раздел «Меню в дровере приложения»).
+  menus: 'native',
   className: 'my-player',       // свой класс на контейнер — хук для темизации
   crossOrigin: 'anonymous',     // если VTT/постеры на другом домене
   playsInline: true,
@@ -430,6 +435,8 @@ new Player('#mount', {
     play: true,
     progress: true,
     time: true,
+    // Громкость (mute + слайдер): true — только десктоп (на мобиле скрыта,
+    // там аппаратные кнопки); 'always' — показывать и на мобиле; false — нигде.
     volume: true,
     fullscreen: true,
     pip: true,
@@ -441,8 +448,14 @@ new Player('#mount', {
     subtitles: 'gear',   // субтитры; появляется только если у источника есть треки
     scenes: true,        // кнопка списка сцен (появляется при наличии chapters)
     sceneTypes: true,    // контрол выбора типа сцен (появляется при source.sceneGroups)
-    heatmap: true,       // диаграмма популярности (нужны данные source.heatmap)
+    // Хитмап популярности (нужны данные source.heatmap): true — только десктоп
+    // (на мобиле скрыт); 'always' — и на мобиле; false — нигде.
+    heatmap: true,
     seekButtons: true,   // или { back: 5, forward: 15, label: (sec, dir) => `${dir==='back'?'−':'+'}${sec}s` }
+    // Меню «⋯» (экшены + динамический overflow-коллапс узкого бара).
+    // false — «⋯» нет вовсе (как в макете): контролы никогда не сворачиваются,
+    // а actions без placement: 'bar' не отображаются.
+    more: true,
     // порядок правых контролов слева направо; пусто/нет — встроенный порядок.
     // перечисленные идут первыми, остальные сохраняют дефолтную позицию, ⋯ всегда последняя.
     order: ['gear', 'pip', 'fullscreen'],  // ControlBarItem[]: like|dislike|speed|quality|subtitles|gear|scenes|sceneTypes|playlist|pip|fullscreen|`custom:<id>`
@@ -698,6 +711,7 @@ player.off('timeupdate', fn)
 | `relatedclick` | `{ item }` | Клик по related-карточке |
 | `action` | `{ id }` | Кнопки: `like`, `dislike`, `addTo`, `share` (если нет нативного шеринга), `report` |
 | `customaction` | `{ id }` | Ваша кнопка из `actions.custom` |
+| `menurequest` | `MenuRequestPayload` | Нажата кнопка меню при `menus: 'external' \| 'external-mobile'` — приложение рендерит меню само ([раздел «Меню в дровере приложения»](#меню-в-дровере-приложения-menus-external)) |
 | `adstart` / `adend` / `adskip` / `adclick` | `{ ad: ResolvedAd }` | Жизненный цикл рекламы |
 | `adpause` / `adresume` | `{ ad: ResolvedAd }` | Креатив поставлен на паузу / возобновлён (+ VAST-пиксели pause/resume) |
 | `aderror` | `{ roll, error }` | Ролл не отыграл (контент продолжается автоматически) |
@@ -725,6 +739,149 @@ player.off('timeupdate', fn)
 
 CSS компонент подгружает сам (self-reference `itube-modern-player/style.css` через exports пакета); ручной импорт `style.css` в приложении продолжает работать и дедуплицируется бандлером — это фолбэк для экзотических сборок.
 
+## Меню в дровере приложения: `menus: 'external'`
+
+У контрол-бара три меню: **настройки** (шестерёнка: автоплей / скорость / качество / субтитры), **тайм-коды** (типы сцен с аккордеоном) и **⋯** (переполнившиеся контролы + ваши экшены). Кто их рисует — решает опция `menus`:
+
+| Значение | Поведение |
+| --- | --- |
+| `'native'` (по умолчанию) | Плеер рисует сам. Десктоп — попап у кнопки; мобила — дровер **снизу экрана**: открытое меню вместе с затемнением переезжает в фиксированный слой на `<body>` (порталится оно потому, что сам плеер обрезает fixed-потомков), страница под ним затемняется и не скроллится. Поверх шапки сайта дровер поднимает `z-index: var(--imp-sheet-z, 999)` — при конфликте задайте `--imp-sheet-z` на `:root` |
+| `'external'` | Плеер **никогда** не открывает меню — по нажатию любой меню-кнопки эмитит `menurequest`, рендер за вами |
+| `'external-mobile'` | Гибрид для приложений со своим дровером: десктоп — нативные попапы, мобильный вьюпорт (≤767px) — `menurequest` |
+
+### Контракт `menurequest`
+
+Один payload — всё, что нужно для рендера, плюс колбэки, которые **сами применяют выбор** (плеер перемотает/переключит и отправит свои обычные события — ничего дёргать вручную не надо):
+
+```ts
+type MenuRequestPayload =
+  // Шестерёнка. Строки трёх видов: тогл (toggle), дрилл в опции (options+select), просто значение.
+  | { kind: 'settings'; title: string; entries: ExternalSettingsEntry[] }
+  // Тайм-коды: группы сцен; active — текущий тип (в макете он раскрыт).
+  | { kind: 'sceneTypes'; title: string; groups: ExternalSceneGroup[];
+      activate(groupId: string): void            // раскрыли группу = сделали её активным типом
+      select(groupId: string, start: number): void } // тап по сцене: активирует группу, seek + play
+  // Всё остальное (⋯, отдельные кнопки скорости/качества/субтитров, если включены).
+  | { kind: 'menu'; title: string; sections: ExternalMenuSection[] }
+
+interface ExternalSettingsEntry {
+  key: string                 // 'autoplay' | 'speed' | 'quality' | 'subtitles'
+  label: string               // локализованная подпись
+  value?: string              // текущее значение для дрилл-строки («720p», «Обычная»)
+  toggle?: { value: boolean; set(on: boolean): void }
+  options?: { label: string; value: string; active: boolean }[]
+  select?(value: string): void
+}
+
+interface ExternalSceneGroup {
+  id: string; title: string; icon?: IconSource
+  active: boolean             // текущий тип сцен — подсветите/раскройте его
+  scenes: { label: string; time: string; start: number; current: boolean }[]
+}                             // current — сцена, играющая сейчас (подсветка в макете)
+
+interface ExternalMenuSection {
+  title: string
+  items: { label: string; value: string; active: boolean }[]
+  select(value: string): void
+}
+```
+
+Три правила, чтобы не отстрелить ногу:
+
+1. **Payload — снимок на момент нажатия.** Колбэки живые (замыкания на плеер), но `active`/`current`/`value` не обновляются сами. После `select`/`toggle` либо закрывайте дровер (обычный UX), либо обновите свою копию модели — по событиям плеера `ratechange`, `qualitychange`, `subtitlechange`, `scenetypechange`, `chapterchange`.
+2. **Не дублируйте работу колбэков.** `select` у `sceneTypes` уже делает `setSceneGroup + seek + play` — не вызывайте `player.seek()` сами.
+3. `menurequest` эмитится **на каждое нажатие** кнопки — если ваш дровер уже открыт, просто перерисуйте контент.
+
+### Интеграция в Nuxt 3 (со своим дровером)
+
+Пусть в приложении уже есть `<AppDrawer v-model="open" :title="...">` (любой ваш bottom-sheet). Вся интеграция — один обработчик и один рендер по `kind`:
+
+```vue
+<script setup lang="ts">
+import type { MenuRequestPayload } from 'itube-modern-player'
+
+const video = { src: '...', sceneGroups: [/* ... */] }
+
+const drawerOpen = ref(false)
+const menu = shallowRef<MenuRequestPayload | null>(null)
+// стек для дрилла «Настройки → Скорость» с кнопкой «назад»
+const drill = shallowRef<{ label: string; options: { label: string; value: string; active: boolean }[]; select(v: string): void } | null>(null)
+
+function onMenuRequest(req: MenuRequestPayload) {
+  menu.value = req
+  drill.value = null
+  drawerOpen.value = true
+}
+
+function pick(select: (v: string) => void, value: string) {
+  select(value)          // плеер применит сам и отправит свои события
+  drawerOpen.value = false
+}
+</script>
+
+<template>
+  <ITubePlayer
+    lazy
+    :source="video"
+    :options="{ menus: 'external-mobile' }"
+    @menurequest="onMenuRequest"
+  />
+
+  <AppDrawer v-model="drawerOpen" :title="drill?.label ?? menu?.title">
+    <!-- дрилл: список опций одной настройки -->
+    <template v-if="drill">
+      <button v-for="o in drill.options" :key="o.value"
+              :class="{ active: o.active }"
+              @click="pick(drill.select, o.value)">
+        {{ o.label }}
+      </button>
+    </template>
+
+    <!-- корень шестерёнки -->
+    <template v-else-if="menu?.kind === 'settings'">
+      <template v-for="e in menu.entries" :key="e.key">
+        <label v-if="e.toggle">
+          {{ e.label }}
+          <AppSwitch :model-value="e.toggle.value" @update:model-value="e.toggle.set($event)" />
+        </label>
+        <button v-else @click="drill = { label: e.label, options: e.options!, select: e.select! }">
+          {{ e.label }} <span class="value">{{ e.value }}</span>
+        </button>
+      </template>
+    </template>
+
+    <!-- тайм-коды: аккордеон типов сцен -->
+    <template v-else-if="menu?.kind === 'sceneTypes'">
+      <details v-for="g in menu.groups" :key="g.id" :open="g.active"
+               @toggle="(e: any) => e.target.open && !g.active && menu!.activate(g.id)">
+        <summary>{{ g.title }}</summary>
+        <button v-for="s in g.scenes" :key="s.start"
+                :class="{ current: s.current }"
+                @click="menu!.select(g.id, s.start); drawerOpen = false">
+          {{ s.label }} <span class="time">{{ s.time }}</span>
+        </button>
+      </details>
+    </template>
+
+    <!-- ⋯ и одиночные меню -->
+    <template v-else-if="menu?.kind === 'menu'">
+      <section v-for="(s, i) in menu.sections" :key="i">
+        <h3 v-if="s.title">{{ s.title }}</h3>
+        <button v-for="it in s.items" :key="it.value"
+                :class="{ active: it.active }"
+                @click="pick(s.select, it.value)">
+          {{ it.label }}
+        </button>
+      </section>
+    </template>
+  </AppDrawer>
+</template>
+```
+
+Дизайн строк под макет (те же значения, что в нативном дровере): строки настроек — 52px / 15px, разделители `rgba(39,39,42,.6)`; опции — 48px, активная `rgba(255,255,255,.10)` + белый бар 2px слева во всю высоту; шапка — 18px/700 uppercase на `#0d0d0d`.
+
+Ванилла-версия без Vue — то же самое через `player.on('menurequest', req => ...)`.
+
 ## Изоморфный шаблон заглушки: `itube-modern-player/placeholder`
 
 `renderPlaceholder(options, flags?) → string` — чистая строка без DOM-зависимостей, единый источник правды по разметке «постер + кнопка play». Используется внутри `createLazyPlayer` и Vue-`lazy`; экспортируется для SSR любого фреймворка:
@@ -890,6 +1047,46 @@ npm publish        # prepublishOnly прогонит typecheck + build
 
 Версионирование по [SemVer](https://semver.org/lang/ru/): `major.minor.patch`.
 
+### 0.8.5
+
+Дизайн-проход по макетам. Записи хронологические — макет уточнялся по ходу, поэтому при расхождении цифр (например, высота блока контролов 102 → 110px, зазоры 8 → 12px) верны **поздние** пункты; финальные значения также отражены в блоке опций выше.
+
+- **Центр-кластер по макету**: play — тёмный круг 80px (accent-заливка убрана из дефолта; `playButtonStyle: 'inverted'` работает как раньше), кнопки ±N — тёмные круги 52px, **число шага внутри кольца** (голое «15» вместо подписи «−15с» под иконкой; кастомный `seekButtons.label` уважается).
+- **Контрол-бар**: иконка play 24px, остальные кнопки 20px (макетное соотношение); добавлен зазор между прогресс-баром и рядом кнопок.
+- **Затенение под контролами**: градиент выше и плотнее (`transparent → rgba(0,0,0,.85)`, старт с 48px) — бар читается на светлых кадрах.
+- **Хитмап по макету**: кривая с явным отступом над полосой прогресса (bottom 18px, высота 22px), профиль с высокой базовой линией (`FLOOR` 0.08 → 0.35) — толстая мягкая лента с холмами вместо острых пиков.
+- **Превью момента**: кадр на 15% меньше (`scale 0.85` от нативного спрайт-региона), полоска с названием сцены и временем — **под** кадром, а не поверх него; карточка с тонкой рамкой-инсетом.
+- **Меню таймкодов — аккордеон**: типы сцен как раскрывающиеся заголовки (иконка + название + шеврон), раскрытый тип показывает список сцен со временем начала; текущая сцена подсвечена (белый + accent-время), раскрытие типа делает его активным. Клик по сцене — переход + воспроизведение.
+- **Ползунок → подсветка позиции**: белая точка на прогресс-баре следует за курсором/пальцем (позиция наведения), а не за воспроизведением; ловится и по полосе, и по зоне хитмапа (хитмап теперь часть hit-области перемотки).
+- **Пиксель-перфект контрол-бара (десктоп)**: ряд кнопок 36px, отступы блока 32/16/10 — общая высота с хитмапом ровно 102px; хитмап ниже (лента 16px, зазор 16px).
+- **Превью момента**: кадр без полей — на всю ширину карточки; карточка поднята над хитмапом (не перекрывает его).
+- **Иконки**: play/next/prev со скруглёнными углами, pause с более круглыми плашками; новая иконка громкости (скруглённый динамик + дуги с round-cap).
+- **Меню настроек (шестерёнка) по макету**: карточка 224px, радиус 12px, тонкая обводка + глубокая тень, без внутреннего паддинга; строки 14px c ховером во всю ширину; свитч 40×24. Подменю (скорость/качество): заголовок «‹ Название», опции по центру, блеклый ховер, активная — светлая полоса + белая палочка у правого края.
+- **Шестерёнка** слегка проворачивается по часовой (35°) пока меню открыто.
+- **Прогресс-бар**: высота всегда 4px — по ховеру не утолщается, а подсвечивается мягким белым свечением.
+- **Синхронизация с дизайн-референсом**: кнопки бара подсвечиваются цветом (серый → белый, play → accent) вместо фоновой плашки; зазоры в ряду 8px; время 12px/500; градиент подложки `transparent → rgba(0,0,0,.7)`; центр-кластер — кольца 48px с зазорами 24px и полупрозрачными чёрными фонами; превью следующего видео 320px с pop-анимацией (fade + scale).
+- **Мобильные меню — bottom-sheet по референсу**: шапка на тёмной подложке `#0d0d0d` с центрированным заголовком (18px, uppercase) и кнопкой ✕, в подменю — стрелка «назад» в шапке; карточка `#18181b` со скруглённым верхом 16px и линией-гранью; тап-строки 52px с разделителями, опции 48px (активная — светлая полоса + 2px бар слева во всю высоту), свитчи 44×24; затемнение подложки до 70%.
+- Исправлен `labels.settings` во всех локалях: легаси «Скорость воспроизведения» → «Настройки» (шестерёнка давно открывает общее меню настроек).
+- **Мобильный дровер на уровне экрана**: открытое меню (+ затемнение) порталится из плеера в фиксированный слой на `<body>` — дровер выезжает из низа экрана и затемняет всю страницу, как в макете; скролл страницы блокируется, тема (accent и пр.) переносится на портал автоматически; z-index настраивается через `--imp-sheet-z`; в фуллскрине хостом становится fullscreen-элемент.
+- **`menus: 'external' | 'external-mobile'` + событие `menurequest`**: режим, в котором меню рендерит приложение (свой дровер в Nuxt и т.п.) — плеер отдаёт типизированную модель (настройки/тайм-коды/⋯) с колбэками, применяющими выбор. Полный контракт и Nuxt-пример — в разделе README «Меню в дровере приложения».
+- **Текущая сцена подсвечивается во всех типах**: позиция воспроизведения попадает в сцену каждой группы — в меню тайм-кодов (и в `menurequest`-модели) подсветка теперь считается по позиции для каждой группы, а не только для активной.
+- **Шрифты по макету**: заголовки аккордеона и подпись кнопки типа сцен 14px/500 (были 13/600), активная сцена — 500, ширина аккордеона 256px, время в тултипе превью 12px.
+- **Превью сика поверх всего**: карточка превью получила `z-index: 9` — перекрывает центр-кластер и остальные оверлеи (раньше кнопки центра рисовались поверх неё).
+- **Полоса прогресса не утолщается и на мобиле**: убран остаток «трек 10px под пальцем» — состояние скраба показывает то же белое свечение; тач-зона и увеличение точки-ползунка сохранены.
+- **Хитмап и громкость на мобиле скрыты по умолчанию**: `controls.heatmap` / `controls.volume` теперь `boolean | 'always'` — `true` (дефолт) = только десктоп, `'always'` = принудительно и на мобильном вьюпорте, `false` = нигде.
+- **Ховер-свечение прогресс-бара приглушено** до макетного (blur 3px / 35% вместо 8px / 45%).
+- **Постер-стейт = рабочий плеер**: до первого запуска бар сидируется полностью — время «0:00 / длительность» (из `source.duration` или метаданных), лейбл стартовой главы, интерактивный прогресс с главами/хитмапом/превью; кнопка play на постере теперь идентична центральной кнопке рабочего плеера (тёмный круг 80px; `playButtonStyle: 'inverted'` работает как раньше).
+- **Мобильная версия заново сверена с макетом**: шестерёнка — плавающая круглая кнопка 36px в правом верхнем углу видео (из бара убрана, аватар канала сдвигается левее, в ⋯ не коллапсится); кнопки бара 36px и зазоры 8px как на десктопе (компакт-уменьшение убрано); центр-кластер держит десктопные размеры (play 80 / кольца 48 / зазор 24) и центрируется в зоне НАД контрол-баром (десктоп −64px, мобила −40px снизу); подпись у кнопки типа сцен снова видна (паддинги 8px, иконка 16px); время 12px; отступы низа 32/16/12.
+- **Иконка шестерёнки** заменена на макетную — контурная с округлыми лепестками и кружком в центре (lucide settings); поворот при открытии меню работает как прежде.
+- **`controls.more: false`** — полное отключение меню «⋯» (как в макете): кнопка не рендерится, overflow-коллапс выключен, контролы никогда не сворачиваются. Дефолт — `true` (прежнее поведение).
+- Фикс: на мобиле кнопка настроек «прыгала» вниз к бару при показе контролов до старта — режим peek делал низ оверлея positioned, и абсолютная шестерёнка начинала позиционироваться от бара. Подъём над постером теперь через z-index grid-элемента без `position` (containing block не меняется), а центр-кластер до старта остаётся скрыт за постером — без задвоения кнопки play.
+- **Синхронизация с обновлённым макетом (июльская ревизия)**: кнопки контрол-бара 44×44 (иконки прежние 24/20), зазоры ряда 12px, общая высота блока 110px; иконки центр-кластера укрупнены до 36px (play на мобиле 64px с 28px-иконкой, постер-кнопка зеркалит); мобильная шестерёнка 40×40; градиент подложки по новым стопам `0 → .35@35% → .7@70% → .92`; у времени лёгкая тень для светлых кадров.
+- **Мобильный бар справа как в макете**: тип сцен — квадратная 44px кнопка только с иконкой (20px, подпись скрыта на мобиле), рядом фуллскрин. Заодно это вернуло фуллскрин на узких экранах — широкая кнопка с текстом выталкивала его за край плеера.
+- **Постерная кнопка play центрируется как кластерная** — в зоне над контрол-баром (−64px десктоп / −40px мобила), а не по всему плееру: при раскрытии контролов кнопка больше не «переезжает».
+- **Мобила: контрол-бар виден в заглушке сразу** — при показе постера бар раскрывается автоматически (без тапа) и не автоскрывается до первого запуска; на десктопе прежнее поведение (появление по ховеру).
+- Фикс «клика насквозь» у дровера: тап по оверлею над кнопкой (например, шестерёнкой) закрывал дровер, но клик проваливался в кнопку под ним и срабатывал (меню тут же переоткрывалось). Бэкдроп теперь закрывается по `click`, а не `pointerdown`, и поглощает касание целиком.
+- Фикс collapse-логики ⋯: замер переполнения больше не учитывает сам ⋯, оставшийся с прошлого прохода — уходит цикл «спрятали кнопку ради ⋯, который жив только из-за спрятанной кнопки».
+
 ### 0.8.4
 
 - **Прогресс на тепловой карте.** Кривая хитмапа больше не одноцветная: проигранная часть (до плейхеда) подсвечивается ярче (`rgba(255,255,255,.75)` против базовых `.35`; кастомизируется по классу `imp-progress__heatmap-played`). Заполнение следует и за воспроизведением, и за скрабом.