Посібник з ядра

Огляд архітектури

Ядро побудоване на патерні контролерів із фабричними функціями. Жодних класів — лише звичайні об’єкти, повернуті із замикань. Нуль залежностей. Ядро узгоджує роботу:

• SliderController — центральний стан і навігація
• GestureController — обробка перетягування дотиком і вказівником
• KeyboardController — стрілки та Escape
• WheelController — колесо миші з тротлінгом

createSliderController

Створює новий екземпляр контролера слайдера, який керує всім станом і поведінкою.

Методи контролера

Навігація

Життєвий цикл

Оновлення стану

Віртуалізація

Ядро тримає в DOM лише 3 слайди у будь-який момент (поточний, попередній, наступний). Екстрактор діапазону вирішує, які індекси потрапляють у вікно рендерингу:

Сигнали

Для реактивності ядро використовує легку систему сигналів:

Стан контролера

Доступ до реактивного стану — через controller.state:

Контролер таймлайну

Зберіть власну смугу перемотування для будь-якого <video> елемента. Контролер дає реактивні сигнали тривалості, поточного часу, буферизованих діапазонів і стану перемотування, а також одним викликом навішує обробку вказівника й клавіатури на будь-який елемент DOM.

Стан в URL

Винесіть стан відкриття оверлея в адресний рядок: видимий слайд отримує посилання, яким можна поділитися, відкрити напряму й закрити кнопкою «назад». Модель живе в ядрі; прив’язки загортають її в хук (React / Vue useOverlayUrlState, Angular createOverlayUrlState) і компонент оверлея, керований URL.

Як це працює

createUrlStateController віддзеркалює один параметр запиту в сигнал і записує зміни назад. Відкриття додає один запис в історію; кожна навігація замінює його — сто свайпів не додають жодного, тож один крок назад завжди закриває. UrlAdapter — це змінний шов читання й запису: типовий керує history.pushState, а застосунок із роутером передає адаптер на базі роутера, щоб власне місцеположення роутера не застаріло.

Кодек і локатор — дві різні задачі

Ключ — це узгоджена пара { codec, locator } . Записати ідентичність в URL і знайти, де вона зараз, — різні задачі, тож і об’єкти різні:

• кодек — формат передавання. encode записує ідентичність у текст параметра; decode розбирає його назад і відхиляє зіпсоване значення, тож параметр сам зникає з URL.
• локатор — пошук. locate знаходить, де розкодована ідентичність лежить у живій колекції (або null якщо її вже немає); identify читає позицію назад в ідентичність для запису; необов’язковий locateAsync дотягує сторінку вікна чи нескінченної стрічки, якщо не знайшлося.

Роздільність дає змогу поєднати будь-який формат із будь-яким пошуком — наприклад, кодек зі стабільним id і локатор із підвантаженням.

Ключі за індексом і за стабільним id

Два вбудовані ключі будують цю пару за вас; різняться лише тим, що саме називає URL:

• urlIndexKey(() => count) адресує за позицією (?photo=3). Найпростіше, але після зміни порядку закладка відкриє інший елемент.
• urlStableIdKey({ items }) адресує за стабільним id (?photo=post_42), скануючи живий список — закладка називає той самий елемент і після зміни порядку, а якщо його немає, акуратно зникає. hashCodec: base64UrlCodec маскує id у base64url (оборотно, це не криптографічний хеш).

Гортаєте стрічку вікнами? Обидва вбудовані ключі приймають необов’язковий locateAsync — urlIndexKey(() => count, locateAsync) та urlStableIdKey({ items, locateAsync }). Синхронний пошук відповідає за вже завантажене; якщо не знайшлося, решта підвантажується, тож надіслане посилання за межі вікна все одно відкриється — без власноруч написаних кодека й локатора.

Дві осі? urlIndexTwoAxisKey несе ?p=<outer>.<inner> для допису разом із індексом внутрішнього медіа. Повний перелік опцій — у довіднику API ядра.

Переглянуте

Запам’ятовуйте, як далеко глядач дійшов у галереї, — між перезавантаженнями та вкладками: кільце, що показує переглянуте, галерея, що відкривається там, де її залишили. Це та сама модель, що й стан в URL, лише спрямована на сховище замість адресного рядка, тож обидві ділять один ключ.

Як це працює

createViewedStateController зберігає запис як точно той текст, який ніс би ?photo= посилання, і читає його назад через той самий цикл decode → locate. Збереженій позиції ніхто не довіряє. Розгорніть один ключ в обидві поверхні — і закладка та збережений запис будуть одним рядком.

Довговічність визначає ключ

Сховище не додає власного відновлення, тож який ключ ви розгорнете, те й переживе зміни: ключ за ідентифікатором зберігає місце попри перевпорядкування колекції, ключ за позицією — ні. Збережений запис називає найдальшу досягнуту точку, а не підрахунок переглядів, тож вилучення елемента із середини скорочує лічильник — те саме самовиправлення, яке отримує спільне посилання.

Читання лише синхронне. Запис, елементи якого ще не завантажено, читається як відсутній і лишається у сховищі недоторканим, тож віконна стрічка ніколи не з’їдає власну історію.

Сховище та термін дії

Типово сховище стоїть на localStorage; createSessionStorageAdapter() забуває при закритті вкладки, а власний StorageAdapter кладе його будь-куди синхронно. Нічого не читається до attach(), тож серверний рендер і перший клієнтський збігаються.

Записи зберігаються, доки їх явно не забути. Передайте ttlMs, щоб натомість вони закінчувалися — на трек, за ковзним годинником, тож те, що ще дивляться, не застаріває поруч із покинутим. Це змінює запис: кожен елемент стає парою [wire, timestamp], але читання приймає обидві форми незалежно від опції, тож запис, збережений до її ввімкнення, вважається свіжим, а не видаляється. maxTracks обмежує кількість, а не вік: понад ліміт найдавніше записаний трек вилучається під час наступного запису, а запис треку, навіть позиції позаду, переставляє його в кінець черги. Повний перелік опцій — у довіднику API ядра.