Довідник API ядра

Повний довідник @reelkit/core : конфігурація, колбеки, методи та стан.

API SliderController

Ядро без прив’язки до фреймворку. Одна фабрика будує контролер із конфігурації та необов’язкових подій: Опції конфігурації — це конфігурація, Колбеки — події, а Методи — те, що надає повернений контролер.

Фабрична функція

Експорт	Тип	Опис
createSliderController	(config: SliderConfig, events?: SliderEvents) => SliderController	Створює контролер слайдера. `config` обов’язковий (опції нижче); `events` необов’язковий (колбеки нижче). Повертає контролер, методи якого ним керують.

Опції конфігурації

Властивість	Тип	Типове значення	Опис
count	number	required	Загальна кількість елементів
initialIndex	number	0	Початковий індекс
direction	'vertical' \| 'horizontal'	'vertical'	Напрямок прокручування
enableGestures	boolean	true	Вмикає навігацію перетягуванням дотиком або мишею. Якщо false, контролер жестів не підключається.
enableNavKeys	boolean	true	Вмикає навігацію стрілками клавіатури
enableWheel	boolean	false	Вмикає колесо миші
wheelDebounceMs	number	200	Час дебаунсу колеса
loop	boolean	false	Циклічна навігація
transitionDuration	number	300	Тривалість анімації в мілісекундах
swipeDistanceFactor	number	0.12	Поріг свайпу (0–1)
rangeExtractor	(index: number, count: number, loop: boolean) => number[]	defaultRangeExtractor	Власна функція, що визначає, які індекси рендеряться

Колбеки

Колбек	Тип	Опис
onBeforeChange	(index, nextIndex, rangeIndex) => void	Перед зміною слайда
onAfterChange	(index, rangeIndex) => void	Після зміни слайда
onDragStart	(index) => void	Перетягування почалося
onDragEnd	(index) => void	Перетягування завершилося
onDragCanceled	(index) => void	Перетягування скасовано
onTap	(event: GestureCommonEvent) => void	Одиночний дотик (із затримкою на вікно подвійного дотику)
onDoubleTap	(event: GestureCommonEvent) => void	Виявлено подвійний дотик
onLongPress	(event: GestureCommonEvent) => void	Виявлено довге натискання
onLongPressEnd	(event: GestureEvent) => void	Вказівник відпущено після довгого натискання
onNavKeyPress	(increment: -1 \| 1) => void	Власний обробник навігації стрілками. Замінює стандартну поведінку prev/next.

Методи

Метод	Тип	Опис
attach(element)	(HTMLElement) => void	Підключає контролер до елемента DOM для розпізнавання жестів
detach()	() => void	Знімає обробники DOM (жести, клавіатура, колесо). Безпечно для повторного підключення через observe(). Використовуйте для очищення ефекту в React.
dispose()	() => void	Остаточне згортання: від’єднує всі контролери й прибирає спостерігачів сигналів. Використовуйте в Angular onDestroy.
observe()	() => void	Починає стежити за жестами, клавіатурою та колесом миші. Враховує прапорці конфігурації enableGestures, enableNavKeys та enableWheel.
unobserve()	() => void	Припиняє стежити за жестами, клавіатурою та колесом миші
next()	() => Promise<void>	Перейти до наступного слайда
prev()	() => Promise<void>	Перейти до попереднього слайда
goTo(index, animate?)	(number, boolean?) => Promise<void>	Перейти до конкретного слайда
adjust(duration?)	(number?) => void	Перерахувати позиції слайдів
setPrimarySize(size)	(number) => void	Оновити розмір контейнера
updateConfig(config)	(Partial<SliderConfig>) => void	Оновити опції конфігурації
updateEvents(events)	(Partial<SliderEvents>) => void	Замінити обробники подій (наявні обробники, яких немає в переданих, зберігаються)
getRangeIndex()	() => number	Повертає позицію активного індексу в масиві видимого діапазону

Властивості стану

Властивість	Тип	Опис
index	Signal<number>	Поточний індекс слайда
axisValue	Signal<AnimatedValue>	Поточне значення позиції по осі (анімоване)
indexes	ComputedSignal<number[]>	Видимі індекси для віртуалізації

Екстрактор діапазону

Експорт	Тип	Опис
defaultRangeExtractor	(index: number, count: number, loop: boolean) => number[]	Стандартний екстрактор, який рендерить 3 елементи навколо поточного індексу

Signal API

Легкі реактивні примітиви, які використовуються по всьому ядру.

Інтерфейс Signal

Член	Тип	Опис
value	T	Читає або задає поточне значення. Запис сповіщає спостерігачів, якщо значення змінилося.
observe(callback)	(callback: () => void) => () => void	Реєструє слухача, що викликається на кожну зміну значення. Повертає функцію звільнення, яка його знімає.

Фабричні функції

Експорт	Тип	Опис
createSignal	<T>(initial: T) => Signal<T>	Створює змінюваний реактивний сигнал
createComputed	<T>(fn: () => T, deps: () => Subscribable[]) => ComputedSignal<T>	Створює похідний обчислюваний сигнал. Другий аргумент — фабрика залежностей, що повертає сигнали для стеження.
reaction	(deps: () => Subscribable[], effect: () => void) => () => void	Виконує побічний ефект, коли змінюється будь-який залежний сигнал; повертає функцію звільнення. Значення сигналів читайте всередині колбека ефекту.
batch	(fn: () => void) => void	Групує кілька оновлень сигналів в одне сповіщення; підтримує вкладеність

Переходи

Вбудовані функції переходів, які обчислюють CSS-перетворення для кожного слайда під час анімованої навігації. Передайте одну з них у пропс transitionTransformFn компонента фреймворку.

Експорт	Тип	Опис
TransitionTransformFn	type	Сигнатура для власних функцій переходу
getSlideProgress	(axisValue: number, slideIndex: number, primarySize: number) => number	Повертає нормалізоване зміщення (від -1 до 1) слайда відносно області перегляду. Використовуйте у власних функціях переходу.
slideTransition	TransitionTransformFn	Стандартний перехід зсувом (translateX/Y)
fadeTransition	TransitionTransformFn	Перехід плавним затуханням
flipTransition	TransitionTransformFn	3D-перехід перевертанням картки
cubeTransition	TransitionTransformFn	3D-перехід обертанням куба
zoomTransition	TransitionTransformFn	Перехід масштабуванням

Завантаження вмісту

Утиліти для відстеження стану завантаження й помилок кожного слайда та попереднього завантаження медіа. Контролер завантаження звіряє індекс і відкидає застарілі колбеки від раніше активних слайдів. Попереднє завантаження використовує LRU-кеш (типово 200 завантажених, 100 з помилкою), тож повторний перехід до зіпсованого URL одразу показує помилку без нової спроби.

Експорт	Тип	Опис
createContentLoadingController	() => ContentLoadingController	Відстеження стану завантаження й помилок для кожного слайда
createContentPreloader	(config: ContentPreloaderConfig) => ContentPreloader	Попереднє завантаження медіа з LRU-кешем і кешуванням помилок
observeMediaLoading	(video: HTMLVideoElement, callbacks: MediaLoadingCallbacks) => () => void	Стежить за станом завантаження відео (playing, canplaythrough, waiting). Повертає функцію звільнення.

ContentLoadingController

Експорт	Тип	Опис
isLoading	Signal<boolean>	Чи завантажується активний слайд
isError	Signal<boolean>	Чи сталася помилка на активному слайді
setActiveIndex	(index: number) => void	Оновлює активний індекс і скидає стан завантаження та помилки
onReady	(index: number) => void	Позначає слайд готовим (ігнорується, якщо індекс не збігається з активним)
onWaiting	(index: number) => void	Позначає слайд таким, що завантажується (ігнорується, якщо індекс не збігається з активним)
onError	(index: number) => void	Позначає слайд помилковим (ігнорується, якщо індекс не збігається з активним)

ContentPreloader

Експорт	Тип	Опис
preload	(src: string, type?: "image" \| "video") => void	Починає попереднє завантаження URL медіа
isLoaded	(src: string) => boolean	Перевіряє, чи URL є в LRU-кеші завантажених (максимум 200)
isErrored	(src: string) => boolean	Перевіряє, чи URL є в LRU-кеші помилок (максимум 100)
markLoaded	(src: string) => void	Вручну позначає URL завантаженим
markErrored	(src: string) => void	Вручну позначає URL помилковим
onLoaded	(src: string, cb: () => void) => () => void	Підписка на завершення завантаження; повертає функцію звільнення

Звук

Спільний стан звуку для відтворення медіа. Контролер звуку дає реактивний сигнал muted, який можна синхронізувати з відеоелементами й перемикати з власних елементів керування.

Експорт	Тип	Опис
createSoundController	() => SoundController	Контролер спільного стану звуку
syncMutedToVideo	(video: HTMLVideoElement, sound: SoundController) => () => void	Синхронізує сигнал muted із відеоелементом. Повертає функцію звільнення.

Таймлайн

Контролер таймлайну відтворення для перемотування відео. Відстежує тривалість, поточний час, буферизовані діапазони та стан перемотування як реактивні сигнали. Один виклик навішує обробку вказівника й клавіатури на будь-який елемент DOM, і той поводиться як рідна смуга перемотування: із захопленням вказівника, живою перемоткою та повною підтримкою клавіатури (стрілки, Home/End, PageUp/PageDown).

Експорт	Тип	Опис
createTimelineController	(config?: TimelineControllerConfig) => TimelineController	Фабрика, що повертає контролер із сигналами duration, currentTime, progress, bufferedRanges, та isScrubbing та методами attach, detach, bindInteractions, та seek methods.
TimelineControllerConfig	інтерфейс	keyboardStepSeconds (default 5), keyboardPageFraction (типово 0.1) і onSeek, onScrubStart, onScrubEnd callbacks.
BufferedRange	{ start: number; end: number }	Одна суцільна буферизована ділянка у частках від 0 до 1 загальної тривалості. Видається відсортованою й без перекриттів.

Повний екран

Кросбраузерні утиліти повного екрана із запобіжниками для вендорних префіксів Safari. Сигнал повного екрана — лінивий синглтон, що реактивно відстежує стан.

Експорт	Тип	Опис
fullscreenSignal	Signal<boolean>	Реактивний сигнал, що показує, чи документ у повноекранному режимі
requestFullscreen	(element: HTMLElement) => Promise<void>	Переводить заданий елемент у повний екран
exitFullscreen	() => Promise<void>	Виходить із повноекранного режиму

Утиліти DOM та очищення

Низькорівневі помічники для роботи з подіями DOM і передбачуваного очищення. Використовуються всередині всіх контролерів і доступні для власних інтеграцій.

Експорт	Тип	Опис
observeDomEvent	(target, event, handler, options?) => () => void	Додає обробник події DOM і повертає функцію звільнення, яка його знімає
createDisposableList	() => DisposableList	Список для збирання функцій звільнення. Викличте dispose(), щоб виконати їх усі одразу.
createBodyLock	() => BodyLock	Блокування прокручування body з підрахунком посилань. Кілька споживачів можуть блокувати одночасно; прокручування повертається, коли всі розблокують.
sharedBodyLock	BodyLock	Синглтон на рівні модуля. Беріть його, коли кілька компонентів застосунку мають ділити один лічильник посилань, щоб вкладені модальні вікна й оверлеї коректно чергувалися. Прив’язки до фреймворків (`@reelkit/react`, `@reelkit/vue`, `@reelkit/angular`) використовують саме його під капотом.

Керування фокусом

Примітиви доступності діалогів без прив’язки до фреймворку. Пакети оверлеїв використовують їх, щоб повернути фокус на елемент-тригер після закриття й утримати Tab / Shift+Tab усередині відкритого оверлея. Безпечні для SSR: поза браузером кожен помічник повертає порожню функцію звільнення.

Експорт	Тип	Опис
captureFocusForReturn	() => Disposer	Запам’ятовує елемент, який зараз у фокусі, і повертає функцію звільнення, що знову його фокусує. За можливості: якщо елемент уже видалено з DOM, функція нічого не робить.
createFocusTrap	(container: HTMLElement) => Disposer	Утримує Tab / Shift+Tab усередині `container`. Tab на останньому фокусованому елементі переходить на перший; Shift+Tab на першому — на останній; фокус, що вислизнув із контейнера (клік поза ним, програмна установка), повертається назад. Під час активації фокус у контейнер не переводиться — це вирішує викликач.
getFocusableElements	(container: HTMLElement) => HTMLElement[]	Повертає всіх нащадків, доступних із клавіатури, у порядку DOM, пропускаючи вимкнені, приховані та `tabindex="-1"` елементи.

Використання

typescript

Відеоутиліти

Утиліти спільного відтворення відео між слайдами без прив’язки до фреймворку. Використовуються всередині @reelkit/react-reel-player та @reelkit/react-lightbox, доступні для власних прив’язок до фреймворків.

Експорт	Тип	Опис
captureFrame	(video: HTMLVideoElement) => string \| null	Знімає поточний кадр відео як data URL у форматі JPEG. Повертає null у разі помилок міждоменного доступу.
createSharedVideo	(config: SharedVideoConfig) => SharedVideoInstance	Створює обмежений областю синглтон спільного відео з мапами позицій відтворення та знятих кадрів. Кожен споживач отримує ізольований екземпляр — заради безперервності звуку на iOS.
syncVideoObjectFit	(video: HTMLVideoElement, fallbackIsVertical: boolean) => Disposer	Тримає video.style.objectFit синхронно з реальною орієнтацією відео. Одразу застосовує запасне значення (із заявленого співвідношення сторін), а потім на loadedmetadata читає справжні videoWidth / videoHeight і перемикається на 'cover' для портретного, 'contain' для альбомного. Стійке до неправильно заявлених метаданих.

Стан в URL

Віддзеркалює один параметр запиту в сигнал і назад. Дві осі, кожна зі своєю задачею: codec — формат передавання (текст параметра ↔ стабільна ідентичність), а locator — пошук (де ця ідентичність лежить у колекції).

Експорт	Тип	Опис
createUrlStateController	({ param, adapter?, codec?, locator? }) => UrlStateController	Віддзеркалює один параметр запиту в сигнал і записує зміни назад в URL. Перший запис відсутнього параметра додає один запис в історію; кожен наступний його замінює. Якщо передано `codec` or `locator` він також виводить `position: Signal<Pos \| null>`, застосовуючи засувку відкриття й закриття та самовідновлення параметра, який не називає жодного слайда — тож кожна прив’язка підписується, а не виводить це заново.
createHistoryAdapter	() => UrlAdapter	Типовий адаптер над History API. Застосунок із роутером має передати власний, інакше місцеположення роутера застаріє і наступна навігація втратить параметр.
indexCodec	UrlCodec<number>	Читає `?photo=3` як слайд 3. Передайте його, щоб отримати виведення індексу без власного кодека. Для нескінченного або посторінкового списку передайте `locator` — параметр переживає очікування проміса, тож пряме посилання на незавантажену сторінку не зникає посеред запиту.
createIndexLocator	(countGetter: () => number) => UrlLocator<number>	Типовий локатор за індексом: позиція слайда відповідає сама собі, обмежена живою кількістю, яку повертає геттер. Індекс поза межами дає `null`, тож застарілий `?photo=99` сам зникає з URL — він відхиляється, а не підганяється до найближчого слайда, бо той відкрив би не те, що називав URL. Геттер, а не число, тож межа читає поточний розмір під час пошуку, поки посторінкова галерея росте.
urlIndexKey	(countGetter, locateAsync?) => UrlKey<number>	Узгоджена пара для галереї з адресацією за індексом: `indexCodec` плюс `createIndexLocator` , прив’язаний до розміру галереї. Розгортайте його (`{ param, ...urlIndexKey(() => count) }`), щоб кодек не розійшовся з локатором. Передайте другий аргумент `locateAsync` , щоб гортати посторінкову стрічку вікнами — якщо не знайшлося, дотягнути сторінки до потрібного індексу й повернути його.
urlIndexTwoAxisKey	(opts) => UrlKey<TwoAxisIdentity, TwoAxisPosition>	Як `urlIndexKey` але для двовісного плеєра: один суворо крапковий параметр `?p=<outer>.<inner>` , який дає `TwoAxisPosition` `{ outer, inner }`. Опції (`UrlIndexTwoAxisKeyOptions`): `outerCount`, `innerCounts`, необов’язковий `outerCodec`/`outerLocator` для зовнішньої осі, а `innerCodec`/`innerLocate`/`innerIdentify` — щоб адресувати внутрішню вісь теж за id. Кожна вісь типово обмежена простим індексом. На цьому працює плеєр історій, керований URL.
createStableIdCodec	(hashCodec?: UrlCodec<string>) => UrlCodec<string>	Кодек зі стабільним формат передавання, експортований для складання — текстом параметра є `id`елемента, записаний як є або перетворений через `hashCodec` (передайте `base64UrlCodec` для оборотного base64url). Аналог `indexCodec`зі стабільним id: поєднайте його з власним локатором замість того, щоб брати цілий `urlStableIdKey`.
base64UrlCodec	UrlCodec<string>	Готовий механізм хешування для ключа зі стабільним id: оборотний base64url (безпечний для URL алфавіт, без доповнення, UTF-8) — не криптографічний хеш. Передайте його як `hashCodec` , щоб замаскувати id в URL, або реалізуйте власний `UrlCodec<string>` , щоб підключити іншу схему.
createStableIdLocator	(items, locateAsync?) => UrlLocator<string, number>	Кодек зі стабільним пошук, експортований для складання — сканує `items()` у пошуках відповідного `id`; зниклий id дає `null` і самовідновлюється. Необов’язковий `locateAsync` гортає посторінкову стрічку вікнами. Аналог зі стабільним id для `createIndexLocator`.
urlStableIdKey	(opts) => UrlKey<string, number>	Адресує галерею за стабільним `id` — `?photo=<id>` кожного елемента — замість позиції, тож закладка переживає зміну порядку списку. Опції (`UrlStableIdKeyOptions`): `items` (живий геттер), необов’язковий `hashCodec` (передайте `base64UrlCodec`, щоб перетворити id у параметрі, необов’язковий `locateAsync` , щоб гортати посторінкову стрічку вікнами (якщо не знайшлося — вантажити, доки id не з’явиться, і повернути його індекс). Обирайте замість `urlIndexKey` , коли список може змінитися під надісланим посиланням.
urlStableIdTwoAxisKey	(opts) => UrlKey<TwoAxisIdentity<string>, TwoAxisPosition>	Двовісний аналог: зовнішня вісь за стабільним id, внутрішня — за локальним індексом: `?story=user_42.3`. Передайте `innerItems` замість `innerCounts` щоб адресувати внутрішню теж за id (`?story=user_42.photo_7`); `hashCodec` (e.g. `base64UrlCodec`) перетворює обидва id. Опції `UrlStableIdTwoAxisKeyOptions` (внутрішня за індексом) або `UrlStableIdTwoAxisIdInnerOptions` (внутрішня за id); типи елементів задовольняють `Identified` (`{ id: string }`).
UrlCodec<Id>	{ decode(raw) => Id \| null; encode(id) => string }	Формат передавання: текст параметра ↔ стабільна ідентичність, незалежно від колекції. `decode` що повертає `null` означає зіпсований текст.
UrlLocator<Id>	{ locate(id) => number \| null; locateAsync?(id) => Promise<number \| null>; identify(index) => id }	Пошук: де ідентичність лежить у колекції. `locate` синхронний, `locateAsync` — запасний варіант для посторінкового списку, а `identify` перетворює індекс назад в ідентичність для запису.
UrlKey<Id>	{ codec: UrlCodec<Id>; locator: UrlLocator<Id> }	Узгоджена пара кодек + локатор для одного параметра. Вони мають однаковий `Id` і завжди йдуть разом — кодек записує ідентичність в URL, локатор знаходить, де вона лежить, — тож саме побудова парою не дає їм розійтися.
UrlAdapter	{ read, subscribe, push, replace, getState, goBack }	Точка підключення роутера. Застосунок із роутером має надати свій, інакше власне місцеположення роутера застаріє.
UrlStateOptions<Id>	{ param: string; adapter?: UrlAdapter; codec?: UrlCodec<Id>; locator?: UrlLocator<Id> }	Опції, які приймає `createUrlStateController` , — експортовані, щоб споживач міг типізувати конфігурацію, зібрану окремо, перед передаванням.