reader.spine
The reader.spine reference: its element, the bounding box of its spine items, and which spine items the pages describe as the latest layout requested lays them out.
The reference for reader.spine, the spine items laid out one after the other.
.value
Section titled “.value”{ element: HTMLElement | undefined firstItemIndexAwaitingLayout: number | undefined}The spine's state, read synchronously.
| Field | Meaning |
|---|---|
element |
The element holding the spine items, created when the reader is mounted. undefined until then |
firstItemIndexAwaitingLayout |
The index of the first spine item the pages may no longer describe as the latest layout requested lays it out, see Layout. undefined while the pages describe every item |
.state$
Section titled “.state$”Observable<typeof reader.spine.value>The state as soon as you subscribe, then each time it changes. See Reactive state.
.watch()
Section titled “.watch()”type SpineState = typeof reader.spine.value
watch<K extends keyof SpineState>(key: K): Observable<SpineState[K]>watch<K extends keyof SpineState>(keys: K[]): Observable<Pick<SpineState, K>>See Reactive state.
Layout
Section titled “Layout”A spine item's place depends only on the items before it. A layout started by
an item's load lays that item out again. It lays out the ones after it again
only if that item's size changes and moves them, and it leaves the ones before
it as they are. A pre-paginated item keeps its size when it loads, so its load
lays out that item alone. The spine tracks the layout from the first item it
can change: its state's firstItemIndexAwaitingLayout. The items after that one
can change too, and the ones before it cannot.
It moves the moment a layout is requested, before anything is done for it:
- to
0forreader.layout(), and what calls it, such as a resize or a setting that moves the pages; - to a spine item's index when that item finishes loading, fails to load or finishes unloading.
A request never moves it past an earlier item still waiting. It turns
undefined once the pages of the latest request are published: the spine
updates its state before the pages reach anything else. A newer request
cancels everything still running for older ones, so the pages published then
are the ones it asked for. It is 0 until the first pages are published.
A layout that fails outside the layout of its items, through a bug of the
reader, publishes no pages, and the reader
reports its error:
firstItemIndexAwaitingLayout stays a number until a later request publishes
its pages. The reader requests none on its own: until a resize, a setting or
reader.layout() requests one, it loads no new item.
A layout runs only while the viewport has a size, see
reader.viewport.isSized$. A request made
while its container is hidden waits, and so does firstItemIndexAwaitingLayout,
until the container is shown again.
A layout that only the loads of spine items ask for also waits for a free
viewport, see reader.viewportState$:
it starts once the viewport has stayed free for 50 ms. It can move the spine
items after the ones that loaded, so it does not start while a page turns,
while the user scrolls or while a lock() is held.
Once it has started, it does not stop when the viewport becomes busy. Some spine items may already have moved, so the layout that completes it does not wait for a free viewport either: one that replaces it, one that follows its failure, or the same layout when it starts again.
A layout of the reader does not wait for a free viewport. reader.layout(), a
resize or a setting requests it, and it also lays out for the spine items that
loaded.
Read it before you use where a page is, with .isLayoutCurrent() or
.isLayoutCurrentFor(): while it is a number, the pages of that item and of the
ones after it describe the layout before the request. A spine item's place in
the spine does not wait for them: it is replaced once the items are laid out.
Neither does a spine item's isDirty: a layout clears it as soon as it lays
that item out, long before the pages are computed again. A request marks dirty
the spine items it changes: every one for reader.layout(), the one whose load
ended otherwise. A spine item that a layout moves is dirty only from the moment
the layout reaches it. For the latest
navigation with whether it holds on this layout, read
reader.navigation.navigationAgainstCurrentLayout$.
Three streams follow a layout after its request:
| Stream | Emits |
|---|---|
.itemsLayoutStart$ |
as the layout starts to lay the spine items out |
.itemsLayout$ |
once the spine items are laid out |
.layout$ |
once the pages are published |
.itemsLayoutStart$
Section titled “.itemsLayoutStart$”Observable<unknown>Emits as a layout starts to lay the spine items out, before it moves the first
one. A layout waits 50 ms after its request, unless it is asked for with
reader.layout({ immediate: true }), so this comes after the request, and
after any request that replaced it. A layout that only the loads of spine items
ask for also waits for a free viewport, see Layout.
From here until .itemsLayout$, the layout lays out again, one after the
other, the spine items it changes or moves, and the place the spine gives for
each one is still the place from before the layout. Read here what you need from before a layout, such as
what a book that scrolls shows.
It can emit twice with no .itemsLayout$ in between. A layout stops and starts
again when the reader's container is hidden and shown during it. A newer
request also replaces a layout that had started, and its own then starts. In
both cases, some spine items are already where the first start moved them.
.itemsLayout$
Section titled “.itemsLayout$”Observable<unknown>Emits once a layout has laid the spine items out. Their sizes and places in
the spine are the new ones, and so is .boundingBox. Their pages are not
published yet, so firstItemIndexAwaitingLayout is still a number.
.layout$
Section titled “.layout$”Observable<{ pages: PageEntry[] }>Emits the pages of a layout once they are published. The spine's state is
already up to date: firstItemIndexAwaitingLayout is undefined, unless a
newer layout is requested.
.isLayoutCurrent()
Section titled “.isLayoutCurrent()”() => booleanWhether the pages describe every spine item as the latest layout requested lays it out: no item awaits it. It reads the current state.
.isLayoutCurrentFor()
Section titled “.isLayoutCurrentFor()”(spineItem: SpineItem | number) => booleanWhether the pages describe a spine item, given as a SpineItem or by its
index, as the latest layout requested lays it out: whether it comes before the
state's firstItemIndexAwaitingLayout. Its place, its pages and what a position
shows of it are then the ones the reader shows, even while a layout of the
items after it is pending. It reads the current state.
Spine.isLayoutCurrent() and Spine.isLayoutCurrentFor()
Section titled “Spine.isLayoutCurrent() and Spine.isLayoutCurrentFor()”import { Spine } from "@prose-reader/core"
Spine.isLayoutCurrent(state: Pick<SpineState, "firstItemIndexAwaitingLayout">): booleanSpine.isLayoutCurrentFor( state: Pick<SpineState, "firstItemIndexAwaitingLayout">, spineItem: SpineItem | number,): booleanThe same answers, for a state you hold rather than the current one, such as the one a subscriber receives: its answer then matches that state, even if the state moves on while it is being reported.
reader.spine .pipe(map(Spine.isLayoutCurrent), distinctUntilChanged()) .subscribe((isLayoutCurrent) => { // true once the pages describe every item again }).boundingBox
Section titled “.boundingBox”SpineBoundingBox | undefined // { left, right, top, bottom, width, height, x, y }The smallest box that holds every spine item, in the coordinates the spine
places its items in, from the top-left corner of the first screen. When pages
turn horizontally, a book read right to left places the items after the first
screen on its left, at a negative left. A navigation stays within this box
wherever the box is larger than the viewport: one to a position past an edge
stops at that edge.
It holds the places of the last layout that laid the items out. A layout in
progress replaces it at .itemsLayout$. It is undefined until a layout has
laid out a spine item.