Referência da API do core

Referência completa da configuração, dos callbacks, dos métodos e do estado de @reelkit/core.

SliderController API

O core independente de framework. Uma fábrica monta o controlador a partir de uma configuração e de eventos opcionais: Opções de configuração são a configuração, Callbacks são os eventos e Métodos é o que o controlador devolvido expõe.

Função fábrica

Export	Tipo	Descrição
`createSliderController`	`(config: SliderConfig, events?: SliderEvents) => SliderController`	Monta um controlador de slider. `config` é obrigatório (opções abaixo); `events` é opcional (callbacks abaixo). Devolve o controlador cujos métodos o conduzem.

Opções de configuração

Propriedade	Tipo	Padrão	Descrição
`count`	`number`	obrigatório	Número total de itens
`initialIndex`	`number`	0	Índice inicial
`direction`	`SliderDirection`	'vertical'	Direção do deslocamento, `'vertical' \| 'horizontal'`
`enableGestures`	`boolean`	true	Liga a navegação por arrasto de toque ou mouse. Com false, o controlador de gestos nem é conectado.
`enableNavKeys`	`boolean`	true	Liga a navegação pelas setas do teclado
`enableWheel`	`boolean`	false	Liga a roda do mouse
`wheelDebounceMs`	`number`	200	Tempo de debounce da roda
`loop`	`boolean`	false	Navegação cíclica
`transitionDuration`	`number`	300	Duração da animação em ms
`swipeDistanceFactor`	`number`	0.12	Limiar do deslize (0-1)
`rangeExtractor`	`RangeExtractor`	defaultRangeExtractor	Função própria para decidir quais índices são renderizados

Callbacks

Callback	Tipo	Descrição
`onBeforeChange`	`(index, nextIndex, rangeIndex) => void`	Antes da troca de slide
`onAfterChange`	`(index, rangeIndex) => void`	Depois da troca de slide
`onDragStart`	`(index) => void`	Arrasto iniciado
`onDragEnd`	`(index) => void`	Arrasto encerrado
`onDragCanceled`	`(index) => void`	Arrasto cancelado
`onTap`	`(event: GestureCommonEvent) => void`	Toque único (adiado pela janela do toque duplo)
`onDoubleTap`	`(event: GestureCommonEvent) => void`	Toque duplo detectado
`onLongPress`	`(event: GestureCommonEvent) => void`	Toque longo detectado
`onLongPressEnd`	`(event: GestureEvent) => void`	Ponteiro solto depois do toque longo
`onNavKeyPress`	`(increment: -1 \| 1) => void`	Tratamento próprio das setas. Substitui o comportamento padrão de avançar e voltar.

Métodos

Método	Tipo	Descrição
`attach(element)`	`(HTMLElement) => void`	Liga o controlador ao elemento do DOM onde os gestos são detectados
`detach()`	`() => void`	Desliga as escutas do DOM (gestos, teclado, roda). Pode ser religado por observe(). Use na limpeza de efeitos do React.
`dispose()`	`() => void`	Desmontagem definitiva: desliga todos os controladores e limpa os observadores de sinais. Use no onDestroy do Angular.
`observe()`	`() => void`	Começa a observar gestos, teclado e roda. Respeita as flags enableGestures, enableNavKeys e enableWheel.
`unobserve()`	`() => void`	Para de observar gestos, teclado e roda
`next()`	`() => Promise<void>`	Vai para o próximo slide
`prev()`	`() => Promise<void>`	Vai para o slide anterior
`goTo(index, animate?)`	`(number, boolean?) => Promise<void>`	Vai para um slide específico
`adjust(duration?)`	`(number?) => void`	Recalcula as posições dos slides
`setPrimarySize(size)`	`(number) => void`	Atualiza o tamanho do contêiner
`updateConfig(config)`	`(Partial<SliderConfig>) => void`	Atualiza as opções de configuração
`updateEvents(events)`	`(Partial<SliderEvents>) => void`	Troca os tratadores de eventos (os que não vierem no objeto são preservados)
`getRangeIndex()`	`() => number`	Devolve a posição do índice ativo dentro do array do intervalo visível

Propriedades de estado

O campo state do controlador é um SliderState, com os três sinais abaixo. Tipe com SliderState um valor que o receba.

Propriedade	Tipo	Descrição
`index`	`Signal<number>`	Índice do slide atual
`axisValue`	`Signal<AnimatedValue>`	Valor da posição no eixo (animado)
`indexes`	`ComputedSignal<number[]>`	Índices visíveis para a virtualização

Extrator de intervalo

Export	Tipo	Descrição
`defaultRangeExtractor`	`RangeExtractor`	Extrator padrão, que renderiza 3 itens em torno do índice atual
`RangeExtractor`	`(current: number, count: number, loop: boolean) => number[]`	Assinatura de um extrator de intervalo. Tipe com ele o seu próprio `rangeExtractor`.

Signal API

Primitivas reativas enxutas, usadas em todo o core.

Interface Signal

Membro	Tipo	Descrição
`value`	`T`	Lê ou escreve o valor atual. A escrita avisa os observadores caso o valor mude.
`observe(callback)`	`(callback: () => void) => () => void`	Registra um ouvinte chamado a cada mudança de valor. Devolve a função que remove esse ouvinte.

Funções fábrica

Export	Tipo	Descrição
`createSignal`	`<T>(initial: T) => Signal<T>`	Cria um sinal reativo mutável
`createComputed`	`<T>(fn: () => T, deps: () => Subscribable[]) => ComputedSignal<T>`	Cria um sinal derivado. O segundo argumento é a fábrica de dependências, que devolve os sinais a acompanhar.
`reaction`	`(deps: () => Subscribable[], effect: () => void) => () => void`	Roda um efeito colateral quando qualquer sinal da dependência muda; devolve a função de descarte. Leia os valores dos sinais dentro do callback do efeito.
`batch`	`(fn: () => void) => void`	Agrupa várias escritas de sinal em um único aviso; aceita aninhamento
`Listener`	`() => void`	O callback que `observe` recebe. Tipe com ele um observador de sinal declarado à parte.
`Dispose`	`() => void`	O que `observe` e `reaction` devolvem: chame para parar de ouvir. Tipe com ele uma inscrição guardada.

Transições

Funções de transição prontas, que calculam as transformações CSS de cada slide durante a navegação animada. Passe uma delas na prop transitionTransformFn do componente do framework.

Export	Tipo	Descrição
`TransitionTransformFn`	`type`	Assinatura das funções de transição próprias
`getSlideProgress`	`(axisValue: number, slideIndex: number, primarySize: number) => number`	Devolve o deslocamento normalizado (de -1 a 1) de um slide em relação à área visível. Use dentro das suas funções de transição.
`slideTransition`	`TransitionTransformFn`	Transição padrão, deslizante (translateX/Y)
`fadeTransition`	`TransitionTransformFn`	Transição de opacidade cruzada
`flipTransition`	`TransitionTransformFn`	Transição de virada de carta em 3D
`cubeTransition`	`TransitionTransformFn`	Transição de rotação de cubo em 3D
`zoomTransition`	`TransitionTransformFn`	Transição de escala e aproximação
`SlideTransformStyle`	`{ transform?; transformOrigin?; opacity?; zIndex? }`	O que uma `TransitionTransformFn` devolve para um slide. Devolva-o de uma transição própria.

Controladores de entrada

O controlador do slider cria estes três sozinho, a partir das opções enableGestures, enableNavKeys e enableWheel. Crie um diretamente quando escrever a sua própria integração, ou quando precisar de gestos, setas ou roda em um elemento que não é um slider.

Controlador de gestos

Export	Tipo	Descrição
`createGestureController`	`(config?: GestureControllerConfig, events?: GestureControllerEvents) => GestureController`	Detecta toques, toques duplos, toques longos e arrastos em um elemento, e trava cada arrasto no seu eixo dominante.
`GestureController`	`{ attach; detach; observe; unobserve; updateEvents }`	Objeto que `createGestureController` devolve. `attach(element)` liga o elemento, `observe()` adiciona as escutas, `unobserve()` as remove e mantém o elemento, `detach()` remove tudo; `updateEvents(events)` mescla novos tratadores.
`GestureControllerConfig`	`{ useTouchEventsOnly?; longPressDurationMs?; doubleTapWindowMs? }`	Opções de `createGestureController`: ignorar o mouse (padrão `false`), tempo do toque longo (padrão `800` ms), janela do toque duplo (padrão `200` ms).
`GestureControllerEvents`	`{ onTap?; onDoubleTap?; onTapDown?; onTapUp?; onLongPress?; onLongPressEnd?; onHorizontalDragStart?; onHorizontalDragUpdate?; onHorizontalDragEnd?; onVerticalDragStart?; onVerticalDragUpdate?; onVerticalDragEnd?; onDragEnd? }`	Callbacks que `createGestureController` chama. Um arrasto vai para os tratadores horizontais ou verticais conforme o eixo dominante; `onDragEnd` dispara nos dois casos.
`GestureAxisDragUpdateEvent`	`GestureEvent & { delta; distance; primaryDelta; primaryDistance; cancel }`	Payload de `onHorizontalDragUpdate` e `onVerticalDragUpdate`: movimento desde a última atualização, distância total, os mesmos valores no eixo dominante, e `cancel()` para devolver o arrasto ao início.
`GestureAxisDragEndEvent`	`GestureAxisDragUpdateEvent` sem `cancel`, mais `{ velocity; primaryVelocity }`	Payload de `onHorizontalDragEnd` e `onVerticalDragEnd`, com a velocidade ao soltar em pixels por segundo.
`GestureDragEndEvent`	`GestureAxisDragEndEvent` sem os campos `primary`	Payload de `onDragEnd`, para um tratador que não se importa com o eixo do arrasto.
`Offset`	`[x: number, y: number]`	Um par de pixels, usado em toda posição, delta, distância e velocidade de um evento de gesto.
`EventKind`	`'touch' \| 'mouse'`	A entrada de onde o gesto veio, no campo `kind` de `GestureCommonEvent`.
`DragAxis`	`'horizontal' \| 'vertical' \| null`	O eixo dominante de um arrasto, `null` até o primeiro movimento decidir.

Controlador de teclado

Export	Tipo	Descrição
`createKeyboardController`	`(config: KeyboardControllerConfig, events: KeyboardControllerEvents) => KeyboardController`	Transforma o pressionar das setas em callbacks com `NavKey`.
`KeyboardController`	`{ attach; detach }`	Objeto que `createKeyboardController` devolve. `attach(target?)` escuta `keydown` no alvo (padrão `window`), `detach()` para.
`KeyboardControllerConfig`	`{ filter?; throttleMs? }`	Opções de `createKeyboardController`: as teclas a considerar (padrão: as quatro) e o tempo mínimo entre dois toques (padrão `0`, sem limitação).
`KeyboardControllerEvents`	`{ onKeyPress: (key: NavKey, event: KeyboardEvent) => void }`	Callback que `createKeyboardController` chama para cada tecla aceita.
`NavKey`	`'up' \| 'right' \| 'down' \| 'left'`	A seta pressionada, como o controlador de teclado a informa e filtra.

Controlador da roda

Export	Tipo	Descrição
`createWheelController`	`(config: WheelControllerConfig, events: WheelControllerEvents) => WheelController`	Transforma a rolagem da roda do mouse em um callback de direção por gesto, juntando a rajada de eventos que uma só rolagem produz.
`WheelController`	`{ attach; detach }`	Objeto que `createWheelController` devolve. `attach(target?)` escuta `wheel` no alvo (padrão `window`), `detach()` para e descarta um callback pendente.
`WheelControllerConfig`	`{ debounceMs?; deltaThreshold? }`	Opções de `createWheelController`: o tempo de silêncio que encerra um gesto (padrão `200` ms) e o menor delta considerado (padrão `10` px).
`WheelControllerEvents`	`{ onWheel: (direction: WheelDirection, event: WheelEvent) => void }`	Callback que `createWheelController` chama uma vez por gesto de rolagem.
`WheelDirection`	`'up' \| 'down' \| 'left' \| 'right'`	A direção de um gesto da roda.

Carregamento de conteúdo

Utilitários que acompanham o estado de carregamento e erro de cada slide e fazem o pré-carregamento das mídias. O controlador de carregamento usa uma guarda de índice para descartar callbacks atrasados de slides que já saíram de cena. O pré-carregador usa um cache LRU (por padrão 200 carregados e 100 com erro), então voltar a uma URL quebrada mostra o erro na hora, sem nova tentativa.

Export	Tipo	Descrição
`createContentLoadingController`	`() => ContentLoadingController`	Acompanha carregamento e erro por slide
`createContentPreloader`	`(config: ContentPreloaderConfig) => ContentPreloader`	Pré-carregador de mídia com cache LRU, inclusive para os erros
`observeMediaLoading`	`(video: HTMLVideoElement, callbacks: MediaLoadingCallbacks) => () => void`	Observa o estado de carregamento do vídeo (playing, canplaythrough, waiting). Devolve a função de descarte.

ContentLoadingController

Export	Tipo	Descrição
`isLoading`	`Signal<boolean>`	Se o slide ativo está carregando
`isError`	`Signal<boolean>`	Se o slide ativo deu erro
`setActiveIndex`	`(index: number) => void`	Troca o índice ativo e zera o estado de carregamento e erro
`onReady`	`(index: number) => void`	Marca o slide como pronto (ignorado se o índice não for o ativo)
`onWaiting`	`(index: number) => void`	Marca o slide como carregando (ignorado se o índice não for o ativo)
`onError`	`(index: number) => void`	Marca o slide como em erro (ignorado se o índice não for o ativo)

ContentPreloader

Export	Tipo	Descrição
`preload`	`(src: string, type?: "image" \| "video") => void`	Começa a pré-carregar a URL de uma mídia
`isLoaded`	`(src: string) => boolean`	Diz se a URL está no cache LRU de carregados (máximo 200)
`isErrored`	`(src: string) => boolean`	Diz se a URL está no cache LRU de erros (máximo 100)
`markLoaded`	`(src: string) => void`	Marca a URL como carregada manualmente
`markErrored`	`(src: string) => void`	Marca a URL como em erro manualmente
`onLoaded`	`(src: string, cb: () => void) => () => void`	Assina o fim do carregamento; devolve a função de descarte

Som

Estado de mudo compartilhado entre as mídias. O controlador de som oferece um sinal reativo de mudo, que dá para sincronizar com os elementos de vídeo e alternar a partir dos seus próprios controles.

Export	Tipo	Descrição
`createSoundController`	`() => SoundController`	Controlador do estado de mudo compartilhado
`syncMutedToVideo`	`(video: HTMLVideoElement, sound: SoundController) => () => void`	Sincroniza o sinal de mudo com um elemento de vídeo. Devolve a função de descarte.

Linha do tempo

Controlador da linha do tempo, para arrastar a reprodução do vídeo. Acompanha duração, tempo atual, trechos em buffer e o estado do arrasto como sinais reativos. Uma única chamada liga as interações de ponteiro e teclado a qualquer elemento do DOM, que passa a se comportar como uma barra de progresso nativa, com captura de ponteiro, busca ao vivo e suporte completo de teclado (setas, Home/End, PageUp/PageDown).

Export	Tipo	Descrição
`createTimelineController`	`(config?: TimelineControllerConfig) => TimelineController`	Fábrica que devolve um controlador com os sinais `duration`, `currentTime`, `progress`, `bufferedRanges` e `isScrubbing`, mais os métodos `attach`, `detach`, `bindInteractions` e `seek`.
`TimelineControllerConfig`	`interface`	`keyboardStepSeconds` (padrão 5), `keyboardPageFraction` (padrão 0.1) e os callbacks `onSeek`, `onScrubStart` e `onScrubEnd`.
`BufferedRange`	`{ start: number; end: number }`	Um trecho contínuo em buffer, expresso em frações de 0 a 1 da duração total. Emitido já ordenado e sem sobreposições.

Tela cheia

Utilitários de tela cheia entre navegadores, com as proteções para os prefixos do Safari. O sinal de tela cheia é um singleton preguiçoso que acompanha o estado de forma reativa.

Export	Tipo	Descrição
`fullscreenSignal`	`Signal<boolean>`	Sinal reativo que diz se o documento está em tela cheia
`requestFullscreen`	`(element: HTMLElement) => Promise<void>`	Entra em tela cheia no elemento informado
`exitFullscreen`	`() => Promise<void>`	Sai da tela cheia

Utilitários de DOM e limpeza

Auxiliares de baixo nível para gerenciar eventos do DOM e garantir uma limpeza previsível. Usados internamente por todos os controladores e disponíveis para integrações próprias.

Export	Tipo	Descrição
`observeDomEvent`	`(target, event, handler, options?) => () => void`	Registra uma escuta de evento no DOM e devolve a função que a remove
`createDisposableList`	`() => DisposableList`	Lista componível de funções de descarte. Chame dispose() para rodar todas de uma vez.
`createBodyLock`	`() => BodyLock`	Trava de rolagem do corpo com contagem de referências. Vários consumidores podem travar ao mesmo tempo; a rolagem volta quando todos destravam.
`sharedBodyLock`	`BodyLock`	Instância única em nível de módulo. Use quando vários componentes do seu app precisam compartilhar um único contador, para que modais e overlays aninhados se intercalem direito. Os bindings de framework (`@reelkit/react`, `@reelkit/vue`, `@reelkit/angular`) usam esta instância por baixo dos panos.

Utilitários

Pequenos auxiliares a partir dos quais os controladores são construídos. Os bindings de framework os reexportam, então um slide, uma transição ou uma integração própria pode usar os mesmos.

Export	Tipo	Descrição
`first`	`<T>(arr: readonly T[]) => T`	Primeiro elemento de um array, como o x de um `Offset` ou a largura de um tamanho.
`last`	`<T>(arr: readonly T[]) => T`	Último elemento de um array, como o y de um `Offset` ou a altura de um tamanho.
`generate`	`<G>(count: number, generator: (i: number) => G) => G[]`	Monta um array de `count` itens a partir do índice, por exemplo `generate(10, (i) => i)` para dados de demonstração.
`abs`	`(value: number) => number`	Valor absoluto.
`isNegative`	`(value: number) => boolean`	Se um número é menor que zero, por exemplo para distinguir um arrasto para trás de um para frente.
`clamp`	`(value: number, min: number, max: number) => number`	Mantém um número entre `min` e `max`, inclusive.
`lerp`	`(t: number, a: number, b: number) => number`	Interpolação linear: `a` em `t = 0`, `b` em `t = 1`. Use numa transição própria para converter o progresso do slide em um valor.
`extractRange`	`(count, start, end?, overscan?, loop?) => number[]`	Índices de `start` a `end` (padrão `start`) mais `overscan` de cada lado (padrão `1`), dando a volta nas pontas quando `loop` é true. Monte com ele um `RangeExtractor` próprio.
`noop`	`() => void`	Uma função que não faz nada, para um callback padrão.
`createDeferred`	`<T = void>() => Deferred<T>`	Uma promise junto com o `resolve` que a cumpre, para ligar uma API de callback a um `await`.
`Deferred`	`{ promise: Promise<T>; resolve: (value?: T) => void }`	Objeto que `createDeferred` devolve.
`createLruCache`	`<V>(maxSize: number, onEvict?: (value: V, key: string) => void) => LruCache<V>`	Um `Map` que guarda as `maxSize` entradas gravadas mais recentemente e descarta a mais antiga além disso. `onEvict` roda para cada entrada descartada, para limpezas como `URL.revokeObjectURL`.
`LruCache`	`Map<string, V>`	Objeto que `createLruCache` devolve. É um `Map` de verdade; só o `set` muda.
`animate`	`(options: AnimationOptions) => () => void`	Anima um número de `from` até `to` com uma curva ease-in-out, chamando `onUpdate` a cada quadro. Devolve uma função que cancela a animação.
`AnimationOptions`	`{ from; to; duration; onUpdate; onComplete? }`	Opções de `animate`: valor inicial e final, duração em milissegundos, o callback de cada quadro e um callback opcional ao terminar.

Detecção de tamanho

Como cada binding e cada overlay medem o contêiner e a janela. O Reel usa observeElementSize quando nenhum size é passado; o reel player, o lightbox e o stories player se dimensionam pela janela. Seguras no SSR: sem window ou sem ResizeObserver, as funções de leitura devolvem [0, 0] ou false e as de observação devolvem uma função de descarte que não faz nada.

Export	Tipo	Descrição
`observeElementSize`	`(element: Element, callback: (size: [number, number]) => void) => Disposer`	Informa a caixa de padding do elemento (`clientWidth` × `clientHeight`) sempre que ela muda. Ignora um tamanho com um lado zero (elemento escondido ou ainda sem layout) e um tamanho igual ao último informado.
`getViewportSize`	`() => [number, number]`	O tamanho da janela como `[innerWidth, innerHeight]`.
`observeViewportSize`	`(callback: (size: [number, number]) => void) => Disposer`	Chama o callback com o tamanho da janela a cada evento `resize`, inclusive quando o tamanho não muda (a emulação de dispositivo pode trocar para um aparelho de toque com as mesmas dimensões). Compare os tamanhos você mesmo se só a mudança importar.
`isMobileWidth`	`(viewportWidth: number) => boolean`	Se uma janela dessa largura recebe o layout de celular: 768px ou menos. Todos os overlays e as suas folhas de estilos trocam de layout nessa largura.
`fitAspectRatio`	`(viewport: [number, number], aspectRatio?: number) => [number, number]`	Tamanho do overlay para uma janela. Em largura de celular é a janela inteira; fora disso, a altura inteira da janela na proporção `aspectRatio`, estreitada até a largura da janela quando não couber. Uma proporção ausente, zero, negativa ou não finita volta para 9/16.
`isTouchDevice`	`() => boolean`	Se o dispositivo aceita entrada por toque (`ontouchstart` ou `maxTouchPoints`). É uma checagem de capacidade, não de tamanho de tela: um notebook com tela de toque conta, uma janela estreita no desktop não.

Reprodução automática

Timers para tudo o que avança sozinho. Como eles se comportam e como ligá-los está no guia de reprodução automática.

Export	Tipo	Descrição
`createTimerController`	`(config: TimerControllerConfig) => TimerController`	Conta uma duração de 0 a 1 e chama de volta quando termina. Conduz cada story nos players de stories.
`createSlideshowController`	`(config: SlideshowControllerConfig) => SlideshowController`	A máquina de estados por trás de uma galeria que avança sozinha. Conduz o `autoAdvance` do lightbox.

createTimerController

`TimerControllerConfig`	Tipo	Descrição
`duration`	`number`	Duração padrão em milissegundos, usada quando `start()` não recebe nenhuma
`onComplete`	`() => void`	Chamado quando o progresso chega a 1

`TimerController`	Tipo	Descrição
`progress`	`Signal<number>`	Progresso de 0 a 1; conduz uma barra de progresso
`isRunning`	`Signal<boolean>`	Se o timer está contando
`start(duration?)`	`(number?) => void`	Recomeça do 0, opcionalmente com outra duração para esta execução
`pause()`	`() => void`	Congela no progresso atual
`resume()`	`() => void`	Continua a partir do progresso congelado
`reset()`	`() => void`	Volta ao 0, parado
`dispose()`	`() => void`	Cancela o frame pendente

createSlideshowController

`SlideshowControllerConfig`	Tipo	Descrição
`interval`	`number`	Quanto tempo uma imagem fica, em milissegundos, contado a partir do momento em que ela carregou
`onAdvance`	`() => void`	O slide ativo terminou. Avance para o próximo slide ou chame `pause()` no último

`SlideshowController`	Tipo	Descrição
`isPlaying`	`Signal<boolean>`	Se a apresentação está ligada. As retenções não o alteram
`progress`	`Signal<number>`	Quanto do intervalo da imagem ativa já passou, de 0 a 1
`play()` / `pause()` / `toggle()`	`() => void`	Liga ou desliga; o slide ativo mantém seu progresso
`setInterval(ms)`	`(number) => void`	Muda o intervalo a partir da próxima imagem
`setSlide(kind)`	`(SlideshowSlideKind) => void`	Um novo slide ficou ativo: o progresso recomeça e espera por `ready()` ou `ended()`. `SlideshowSlideKind` é `'image' \| 'video'`
`ready()`	`() => void`	A imagem ativa carregou ou falhou ao carregar; seu intervalo começa
`ended()`	`() => void`	O vídeo ativo terminou; avança agora ou assim que nada mais o retiver
`hold(reason)` / `release(reason)`	`(string) => void`	Para o relógio por um motivo como `'hover'` ou `'drag'`. As retenções se acumulam
`dispose()`	`() => void`	Para o relógio e o listener de visibilidade

Download

Salvar um arquivo a partir de uma URL, inclusive de outra origem. O fallback que ele usa está no guia de download.

Export	Tipo	Descrição
`downloadFile`	`(url: string, filename?: string) => Promise<void>`	Salva um arquivo com o nome `filename`, por padrão o último segmento do caminho da URL. Ele busca o arquivo e salva o blob, porque o atributo `download` é ignorado num link de outra origem. Quando a busca falha ou o servidor responde com erro (um servidor de outra origem sem cabeçalhos CORS é o caso mais comum), a URL abre numa nova aba. Nunca rejeita; não faz nada sem uma janela.

Gerenciamento de foco

Primitivas de acessibilidade de diálogo, independentes de framework. Os pacotes de overlay as usam para devolver o foco ao gatilho ao fechar e para prender Tab / Shift+Tab dentro do overlay enquanto ele está aberto. Seguras no SSR: fora do navegador, cada auxiliar devolve uma função de descarte que não faz nada.

Export	Tipo	Descrição
`captureFocusForReturn`	`() => Disposer`	Guarda o elemento em foco e devolve uma função que o foca de novo. É o melhor esforço possível: se o elemento guardado já saiu do DOM, essa função não faz nada.
`createFocusTrap`	`(container: HTMLElement) => Disposer`	Prende Tab/Shift+Tab dentro de `container`. Tab no último elemento focável volta ao primeiro; Shift+Tab no primeiro salta para o último; um foco que escapa do contêiner (clique fora, foco por código) é trazido de volta. Não move o foco para dentro do contêiner ao ativar — quem decide isso é quem chamou.
`getFocusableElements`	`(container: HTMLElement) => HTMLElement[]`	Devolve todos os descendentes focáveis por teclado, na ordem do DOM, pulando os desabilitados, os ocultos e os com `tabindex="-1"`.

Uso

typescript

import { captureFocusForReturn, createFocusTrap } from '@reelkit/core';

// When your modal opens:
const restoreFocus = captureFocusForReturn();
container.focus({ preventScroll: true });
const releaseTrap = createFocusTrap(container);

// When the modal closes:
releaseTrap();
restoreFocus();

Utilitários de vídeo

Utilitários independentes de framework para compartilhar a reprodução de vídeo entre os slides. Usados internamente por @reelkit/react-reel-player e @reelkit/react-lightbox, e disponíveis para bindings próprios.

Export	Tipo	Descrição
`captureFrame`	`(video: HTMLVideoElement) => string \| null`	Captura o quadro atual do vídeo como uma data URL em JPEG. Devolve null em erros de origem cruzada.
`createSharedVideo`	`(config: SharedVideoConfig) => SharedVideoInstance`	Cria um vídeo compartilhado com escopo próprio, com mapas de posição de reprodução e de quadros capturados. Cada consumidor recebe uma instância isolada, o que mantém o som contínuo no iOS.
`syncVideoObjectFit`	`(video: HTMLVideoElement, fallbackIsVertical: boolean) => Disposer`	Mantém `video.style.objectFit` de acordo com a orientação real do vídeo. Aplica o padrão declarado na proporção de imediato e, em `loadedmetadata`, lê os valores reais de `videoWidth` / `videoHeight` e troca para `'cover'` no retrato e `'contain'` na paisagem. Aguenta metadados declarados errados.

Estado na URL

Espelha um parâmetro de consulta em um sinal e de volta. Dois eixos, cada um com um papel: o codec é o fio (texto do parâmetro ↔ identidade estável), o locator é a busca (onde essa identidade está na coleção).

Export	Tipo	Descrição
`createUrlStateController`	`({ param, adapter?, codec?, locator? }) => UrlStateController`	Espelha um parâmetro de consulta em um sinal e escreve as mudanças de volta na URL. A primeira escrita de um parâmetro ausente empilha uma entrada no histórico; toda escrita seguinte a substitui. Com um `codec` ou um `locator`, também deriva `position: Signal<Pos \| null>`, aplicando o trinco de abrir e fechar e curando sozinho um parâmetro que não nomeia slide nenhum — assim cada binding apenas assina, em vez de derivar tudo de novo. Escrever uma posição com o overlay fechado abre na hora, sem esperar o adaptador confirmar a escrita; `UrlChange` diz quando o fechamento volta uma entrada e quando limpa no lugar.
`createHistoryAdapter`	`() => UrlAdapter`	Adaptador padrão sobre a History API. Uma aplicação com rotas deve injetar o seu próprio; do contrário a localização do roteador fica desatualizada e a navegação seguinte derruba o parâmetro.
`indexCodec`	`UrlCodec<number>`	Lê `?photo=3` como o slide 3. Passe este codec para aderir à derivação por índice sem escrever um codec seu. Em uma lista infinita ou paginada, passe `locator` no lugar — o parâmetro sobrevive enquanto a promessa está pendente, então um link profundo para uma página ainda não carregada não é apagado no meio da busca.
`createIndexLocator`	`(countGetter: () => number) => UrlLocator<number>`	O locator de índice padrão: a posição de um slide aponta para si mesma, limitada pela contagem atual que o getter devolve. Um índice fora do intervalo resolve para `null`, então um `?photo=99` velho se cura sozinho saindo da URL — ele rejeita em vez de arredondar para o slide mais próximo, o que abriria um item que a URL nunca nomeou. É um getter, e não um número, para que o limite leia o tamanho atual no momento da busca, conforme a galeria paginada cresce.
`urlIndexKey`	`(countGetter, locateAsync?) => UrlKey<number>`	O par combinado para uma galeria endereçada por índice — `indexCodec` mais um `createIndexLocator` ligado ao tamanho da galeria. Espalhe o par (`{ param, ...urlIndexKey(() => count) }`) para que o codec não se afaste do locator. Passe um segundo argumento `locateAsync` para acompanhar um feed paginado: na falha da busca, ele pagina até o índice desejado e o devolve.
`urlIndexTwoAxisKey`	`(opts) => UrlKey<TwoAxisIdentity, TwoAxisPosition>`	Como `urlIndexKey`, mas para um player de dois eixos: um parâmetro `?p=<externo>.<interno>`, estritamente pontuado, que resolve para um `TwoAxisPosition` `{ outer, inner }`. Opções (`UrlIndexTwoAxisKeyOptions`): `outerCount`, `innerCounts`, os opcionais `outerCodec`/`outerLocator` para o eixo externo, e `innerCodec`/`innerLocate`/`innerIdentify` para endereçar o eixo interno por id também. Cada eixo assume, por padrão, um limite simples de índice. É o que move o stories player guiado pela URL.
`createStableIdCodec`	`(hashCodec?: UrlCodec<string>) => UrlCodec<string>`	O fio do id estável, exportado para você compor — o texto do parâmetro é o `id` do item, escrito cru ou transformado por `hashCodec` (passe `base64UrlCodec` para base64url reversível). É o análogo de `indexCodec` para id estável: combine-o com um locator seu em vez de levar o `urlStableIdKey` inteiro.
`base64UrlCodec`	`UrlCodec<string>`	O mecanismo de disfarce pronto para uma chave de id estável: base64url reversível (alfabeto seguro para URL, sem preenchimento, UTF-8) — não é um hash criptográfico. Passe como `hashCodec` para esconder o id na URL, ou implemente seu próprio `UrlCodec<string>` para usar outro esquema.
`createStableIdLocator`	`(items, locateAsync?) => UrlLocator<string, number>`	A busca do id estável, exportada para você compor — varre `items()` atrás do `id` correspondente; um id que sumiu resolve para `null` e se cura sozinho. O `locateAsync` opcional acompanha um feed paginado. É o análogo de `createIndexLocator` para id estável.
`urlStableIdKey`	`(opts) => UrlKey<string, number>`	Endereça a galeria pelo `id` estável de cada item — `?photo=<id>` — em vez da posição, então o favorito sobrevive à lista mudar de ordem. Opções (`UrlStableIdKeyOptions`): `items` (um getter atual), o opcional `hashCodec` (passe `base64UrlCodec`) para transformar o id no fio, e o opcional `locateAsync` para acompanhar um feed paginado (buscar até o id aparecer e então devolver seu índice). Prefira esta chave sempre que a lista puder mudar sob um link compartilhado.
`urlStableIdTwoAxisKey`	`(opts) => UrlKey<TwoAxisIdentity<string>, TwoAxisPosition>`	O análogo de dois eixos: o eixo externo por id estável, o interno por índice local — `?story=user_42.3`. Informe `innerItems` em vez de `innerCounts` para endereçar o interno por id também (`?story=user_42.photo_7`); `hashCodec` (por exemplo `base64UrlCodec`) transforma os dois ids. Opções `UrlStableIdTwoAxisKeyOptions` (interno por índice) ou `UrlStableIdTwoAxisIdInnerOptions` (interno por id); os tipos dos itens satisfazem `Identified` (`{ id: string }`).
`UrlCodec<Id>`	`{ decode(raw) => Id \| null; encode(id) => string }`	O formato do fio: texto do parâmetro ↔ identidade estável, sem enxergar a coleção. Um `decode` que devolve `null` significa texto malformado.
`UrlLocator<Id>`	`{ locate(id) => number \| null; locateAsync?(id) => Promise<number \| null>; identify(index) => id }`	A busca: onde a identidade está na coleção. `locate` é síncrono, `locateAsync` é seu plano B para uma lista paginada, e `identify` converte um índice de volta em identidade na hora de escrever.
`UrlKey<Id>`	`{ codec: UrlCodec<Id>; locator: UrlLocator<Id> }`	O par combinado de codec e locator de um parâmetro. Eles dividem o mesmo `Id` e andam sempre juntos — o codec escreve a identidade na URL, o locator descobre onde ela está — e construí-los como par é justamente o que impede que discordem.
`UrlAdapter`	`{ read, subscribe, push, replace, getState, goBack }`	O ponto de injeção de um roteador. Uma aplicação com rotas precisa fornecer o seu, senão a localização do próprio roteador fica desatualizada. O ouvinte de `subscribe` aceita um `UrlChange` opcional; chamá-lo sem nada é sempre válido e significa que o adaptador não sabe dizer como aquela entrada virou a atual.
`UrlChange`	`{ kind?: 'push' \| 'replace' \| 'pop' }`	O que o adaptador sabe sobre a navegação que acabou de acontecer. Informe `push` apenas para uma navegação que o próprio roteador fez na mesma página; é o único caso em que fechar pode desempilhar a entrada. Sem essa evidência a entrada nunca é reivindicada, e fechar limpa o parâmetro no lugar, deixando uma cópia da página no histórico em vez de arriscar um passo para fora do site.
`UrlStateOptions<Id>`	`{ param: string; adapter?: UrlAdapter; codec?: UrlCodec<Id>; locator?: UrlLocator<Id> }`	As opções que `createUrlStateController` recebe — exportadas para que se possa tipar uma configuração montada à parte antes de entregá-la.

Itens já vistos

Guarda até onde o leitor chegou, com a mesma chave que endereça a barra de endereços: a entrada é o próprio texto do parâmetro, relido pelo mesmo codec e pelo mesmo locator.

Export	Tipo	Descrição
`createViewedStateController`	`(options) => ViewedStateController<Pos>`	Lembra até onde o leitor chegou, guardando exatamente o texto que um parâmetro de URL carregaria. Recebe o mesmo par `codec`/`locator` da barra de endereços, mais `storageKey`, os opcionais `storage` e `trackOf` (uma entrada por grupo), e `progressOf`. Não lê nada antes de `attach()`, então é seguro em pré-renderização.
`twoAxisViewedTracking`	`{ trackOf, progressOf }`	O par de acompanhamento de um player de dois eixos: uma entrada por posição externa, com o índice interno medindo o avanço dentro dela. Espalhe ao lado de uma chave de dois eixos.
`createLocalStorageAdapter`	`() => StorageAdapter`	O armazenamento padrão. Há também `createSessionStorageAdapter`, para estado que não deve sobreviver à aba, e `createMemoryStorageAdapter`, para testes e renderização no servidor. Cada um absorve as próprias falhas — uma cota esgotada perde aquela escrita e nada além dela.
`ViewedStateController<Pos>`	`{ entries; resolve(track); record(position); forget(track?); attach() }`	`entries` é um sinal de trilha → texto guardado, então um anel se redesenha quando uma posição é registrada aqui ou em outra aba. `resolve` percorre o ciclo completo da chave a cada chamada.
`ViewedStateOptions<Id, Pos>`	`{ storageKey; codec; locator; storage?; trackOf?; progressOf; ttlMs?; maxTracks? }`	As opções que `createViewedStateController` recebe — exportadas para que se possa tipar uma configuração montada à parte antes de entregá-la. `progressOf` só é opcional para uma posição de índice simples, que já é sua própria medida de avanço; qualquer outra posição precisa dizer qual número comparar, e o tipo exige isso. `ttlMs` liga a expiração: a trilha é esquecida esse tanto de tempo depois do último registro, e registrá-la de novo reinicia o relógio. `maxTracks` mantém no máximo essa quantidade de trilhas, descartando na próxima escrita a registrada há mais tempo.
`StorageAdapter`	`{ read(key); write(key, value); subscribe?(key, listener) }`	O ponto de injeção da camada de armazenamento. Sem `subscribe`, o armazenamento simplesmente roda sem sincronização entre abas.