Primitives / DOM
keepScroll: the window's scroll across navigations
An entry, lifted with Subscription.persistentEntry, that sends no Messages: it
keeps the window's scroll across same-document navigations, so a pushed entry
starts at the top and Back, Forward, or a reload return where that entry was.
Without a window the stream is empty. The CMS example lifts it beside its
other subscriptions.
ts
import { Schema } from 'effect'
import { defineMessageUnion } from 'foldkit/message'
import * as Subscription from 'foldkit/subscription'
import { keepScroll } from 'foldkit-primitives/dom'
const ShellModel = Schema.Struct({})
type ShellModel = typeof ShellModel.Type
const ShellMessage = defineMessageUnion({ Noted: {} })
type ShellMessage = typeof ShellMessage.Type
const subscriptions = Subscription.make<ShellModel, ShellMessage>()(() => ({
// The window, for a page that scrolls as a document.
scroll: Subscription.persistentEntry(keepScroll()),
// An element, for a shell whose centre column scrolls and the window does not.
column: Subscription.persistentEntry(
keepScroll({
scroller: () => document.getElementById('main'),
storageKey: 'foldkit:column-scroll',
}),
),
}))scroller names the element that scrolls in place of the window; it is looked up
each time, since the application draws it. Give each scroller its own storageKey.
What it does and when:
- The offset is taken when the reader acts (a click or key, in the capture phase) and as Back and Forward begin: the next screen is drawn before the address is pushed, so by then the scroller is already clamped to the shorter page.
- A restore holds its place while the screen settles: the offset is applied each frame once the
page is tall enough, and the hold ends when the page's height has stood still for two frames at
the offset, the reader scrolls, touches or types, or another navigation starts.
patience(default 10 s) is only the ceiling. - A reload restores from
sessionStorage, keyed by the Navigation API's entry key. The offsets are written atbeforeunload(the one that runs on a desktop reload before Foldkit disposes the runtime, which it does atpagehide), and again atvisibilitychangeto hidden and atpagehide, which cover a page put away withoutbeforeunload(a phone's tab switch) or kept for Back and Forward. There is nounloadhandler: it makes a page ineligible for the back/forward cache. - Without the Navigation API the stream attaches nothing and the browser's own behaviour stands.