AdapterHandle (core)

Defined in: adapter.ts:24

The framework-agnostic glue behind every Riffle adapter (React’s useRiffle, Vue’s useRiffle and its directives): builds and tears down the engine as rootRef/registerCard attach and detach elements, and diffs option objects into update() calls so a framework never has to.

Example

import { createAdapterHandle } from '@rpxl/riffle'

const handle = createAdapterHandle({ count: 5, cardWidth: 300, cardHeight: 400 })
const stack = document.querySelector<HTMLElement>('#stack')
handle.rootRef(stack)
const el = document.querySelector<HTMLElement>('#card-0')
if (el) handle.registerCard(0, el)
handle.next()

Properties

instance

readonly instance: Riffle | null

Defined in: adapter.ts:26

The live engine, or null before the container mounts and after it unmounts.

---

rootRef

readonly rootRef: (el) => void

Defined in: adapter.ts:46

Attach to the container, or pass null to detach. Stable identity; safe to call repeatedly. A null call does not tear the engine down immediately: it defers teardown by one microtask, and if rootRef is called again with the same element before that microtask runs, the pending teardown is cancelled and the live engine is kept. This makes a null-then-same-element round trip within one tick, such as React’s StrictMode double-invoking ref callbacks at mount, or an inline ref callback that recreates on every render, a no-op rather than a destroy-and-rebuild.

Call it with null before moving to a different element, as React and Vue both do. A different element tears the old engine down synchronously (including one whose teardown is pending) and attaches a fresh one.

While a teardown is pending, setOptions only stores the options. If the same element returns, they are applied then (rebuilding if they need it); if the teardown runs, the next attach builds with them.

Parameters

el

HTMLElement | null

Returns

void

Methods

cardRef()

cardRef(index): (el) => void

Defined in: adapter.ts:53

A stable ref callback for the card at index. Relies on the framework detaching every changed ref before attaching any, which React guarantees. Frameworks that process refs one node at a time should use registerCard and unregisterCard instead.

Parameters

index

number

Returns

(el) => void

---

getSnapshot()

getSnapshot(): RiffleSnapshot

Defined in: adapter.ts:68

Referentially stable while nothing has changed, including across mount.

Returns

RiffleSnapshot

---

goTo()

goTo(index, opts?): void

Defined in: adapter.ts:76

Moves to index, animated unless opts.animate is false. A no-op while unmounted.

Parameters

index

number

opts?

animate?

boolean

Returns

void

---

next()

next(): void

Defined in: adapter.ts:72

Advances to the next card, animated. A no-op while unmounted.

Returns

void

---

on()

on<K>(event, fn): () => void

Defined in: adapter.ts:70

Subscribes to one engine event. Returns an unsubscribe function; a no-op while unmounted.

Type Parameters

K

K extends keyof RiffleEventMap

Parameters

event

K

fn

(payload) => void

Returns

() => void

---

prev()

prev(): void

Defined in: adapter.ts:74

Moves to the previous card, animated. A no-op while unmounted.

Returns

void

---

registerCard()

registerCard(index, el): void

Defined in: adapter.ts:55

Registers the element for the card at index, same as calling cardRef(index) with it.

Parameters

index

number

el

HTMLElement

Returns

void

---

setOptions()

setOptions(next): void

Defined in: adapter.ts:64

Apply changed options. Diffs against the previous set and calls the engine’s update() with only what changed. An axis change, or a card dimension crossing between a number and ‘auto’, rebuilds the engine and keeps position. startIndex is read only when an engine is first built.

Parameters

next

RiffleOptions

Returns

void

---

subscribe()

subscribe(listener): () => void

Defined in: adapter.ts:66

Notified whenever getSnapshot() would return a new value. Returns an unsubscribe function.

Parameters

listener

() => void

Returns

() => void

---

unregisterCard()

unregisterCard(index, el): void

Defined in: adapter.ts:57

Only unregisters if el is still the element registered at index.

Parameters

index

number

el

HTMLElement

Returns

void