@weft-js/scroll 0.0.0-stage → 0.1.5-nightly.20261111.3

package/src/engine.ts

@@ -0,0 +1,374 @@
+// The scroller's state and its one frame loop. The viewport stays a real scroll container with `overflow: hidden`:
+// the engine writes scrollTop and scrollLeft, so focus, find-in-page, anchors, sticky positioning, screen readers and
+// any library listening for `scroll` (a virtualizer) keep working. Input modules only move numbers here.
+import { coast, rubber, spring, unrubber } from './physics'
+import { snapStep, snapTo } from './snap'
+import { axisState, type AxisState } from './axis'
+import type { Resolved } from './options'
+import type { Axis, ScrollSource, ScrollState } from './types'
+
+export type { AxisState } from './axis'
+
+let query: MediaQueryList | null | undefined
+/** One shared query for every scroller: making a MediaQueryList costs more than the rest of a scroller's setup. */
+export const reduceQuery = () =>
+  (query ??=
+    typeof matchMedia === 'function' ? matchMedia('(prefers-reduced-motion: reduce)') : null)
+
+/** Every live scroller by its viewport, so nested ones can find the one outside them. */
+export const registry = new WeakMap<Element, Engine>()
+
+export class Engine {
+  readonly ax = { x: axisState('x'), y: axisState('y') }
+  rtl = false
+  source: ScrollSource = 'api'
+  frame = 0
+  last = 0
+  dispatching = false
+  measured = false
+  /** DOM thumbs follow a CSS scroll timeline, on the compositor: frames leave their position alone. */
+  timeline = false
+  private dirty = false
+  private seen = 0
+  /** Runs after each frame's writes: the bars draw here. */
+  onFrame: (now: number) => boolean = () => false
+  /** Runs after an autoscroll step, so a held selection can follow the content. */
+  afterAuto: (() => void) | null = null
+  /** Runs when the position moves for any reason: the bars show. */
+  onActivity: () => void = () => {}
+  /** What `destroy` runs. */
+  destroyHooks: (() => void)[] = []
+
+  constructor(
+    readonly root: HTMLElement,
+    readonly vp: HTMLElement,
+    public content: HTMLElement | null,
+    public o: Resolved,
+  ) {}
+
+  get axes(): AxisState[] {
+    return [this.ax.x, this.ax.y]
+  }
+
+  reduced() {
+    return this.o.motion === 'reduce' || (this.o.motion === 'auto' && !!reduceQuery()?.matches)
+  }
+
+  parent(): Engine | null {
+    const up = this.root.parentElement?.closest('[data-scroll-viewport]')
+    return (up && registry.get(up)) || null
+  }
+
+  /** Read sizes and the position from the DOM. Only call where layout is already clean or a read is wanted. */
+  measure() {
+    this.measured = true
+    const { vp } = this
+    this.rtl = getComputedStyle(vp).direction === 'rtl'
+    const { x, y } = this.ax
+    y.view = vp.clientHeight
+    y.total = vp.scrollHeight
+    y.max = Math.max(0, y.total - y.view)
+    x.view = vp.clientWidth
+    x.total = vp.scrollWidth
+    const wide = Math.max(0, x.total - x.view)
+    x.min = this.rtl ? -wide : 0
+    x.max = this.rtl ? 0 : wide
+    for (const a of this.axes) {
+      if (!a.anim && a.pos === a.written)
+        a.pos = a.written = a.axis === 'y' ? vp.scrollTop : vp.scrollLeft
+      a.pos = clamp(a.pos, a.min, a.max)
+      if (a.track) {
+        const inset = this.o.bar.inset
+        const long = a.axis === 'y' ? a.track.clientHeight : a.track.clientWidth
+        a.trackLen = Math.max(0, long - 2 * inset)
+        a.trackCross = a.axis === 'y' ? a.track.clientWidth : a.track.clientHeight
+      }
+    }
+    this.measureSnap()
+    this.dirty = true
+  }
+
+  private measureSnap() {
+    const s = this.o.snap
+    for (const a of this.axes) a.points = []
+    if (!s) return
+    const a = this.ax[s.axis ?? 'y']
+    const given = typeof s.points === 'function' ? s.points() : (s.points ?? [])
+    a.points = [...given]
+    if (!s.selector) return
+    const box = this.vp.getBoundingClientRect()
+    const y = a.axis === 'y'
+    for (const el of this.vp.querySelectorAll(s.selector)) {
+      const r = el.getBoundingClientRect()
+      const at = (y ? r.top - box.top : r.left - box.left) + a.pos
+      const size = y ? r.height : r.width
+      const align = s.align ?? 'start'
+      a.points.push(
+        align === 'start' ? at : align === 'end' ? at + size - a.view : at + size / 2 - a.view / 2,
+      )
+    }
+  }
+
+  /** Measure now if no ResizeObserver has yet: input or an API call before the first layout batch. */
+  ready() {
+    if (!this.measured) this.measure()
+  }
+
+  canMove(axis: Axis, dir: number) {
+    this.ready()
+    const a = this.ax[axis]
+    if (!a.on || a.max - a.min < 1) return false
+    return dir > 0 ? a.pos < a.max - 0.5 : dir < 0 ? a.pos > a.min + 0.5 : false
+  }
+
+  wake() {
+    if (!this.frame && typeof requestAnimationFrame === 'function') {
+      this.frame = requestAnimationFrame(this.tick)
+      this.last = 0
+    }
+  }
+
+  stop(axis?: Axis) {
+    for (const a of this.axes) {
+      if (axis && a.axis !== axis) continue
+      if (a.anim?.kind === 'spring') continue
+      a.anim = null
+      a.v = 0
+    }
+  }
+
+  /** Move straight there: a trackpad delta, a finger, a thumb drag. */
+  moveTo(axis: Axis, to: number, source: ScrollSource) {
+    this.ready()
+    const a = this.ax[axis]
+    if (a.anim?.kind !== 'spring') a.anim = null
+    a.pos = clamp(to, a.min, a.max)
+    this.source = source
+    this.wake()
+  }
+
+  /** Animate there over `duration`, or jump when motion is reduced. */
+  tweenTo(
+    axis: Axis,
+    to: number,
+    source: ScrollSource,
+    dur = this.o.duration,
+    ease = this.o.easing,
+  ) {
+    this.ready()
+    const a = this.ax[axis]
+    const end = clamp(to, a.min, a.max)
+    this.source = source
+    if (dur <= 0 || this.reduced()) return this.moveTo(axis, end, source)
+    a.anim = { kind: 'tween', from: a.pos, to: end, start: -1, dur, ease }
+    this.wake()
+  }
+
+  /** Add to where any running animation is heading, as successive wheel notches and key repeats do. */
+  tweenBy(axis: Axis, d: number, source: ScrollSource) {
+    const a = this.ax[axis]
+    const from = a.anim?.kind === 'tween' ? a.anim.to : a.pos
+    const snapped = this.o.snap?.type === 'mandatory' && a.points.length
+    this.tweenTo(axis, snapped ? snapStep(a.points, from, Math.sign(d), a.max) : from + d, source)
+  }
+
+  /** A finger or grab drag: `raw` is where the finger puts the content, maybe past an edge. */
+  drag(axis: Axis, raw: number) {
+    const a = this.ax[axis]
+    a.anim = null
+    const pos = clamp(raw, a.min, a.max)
+    a.pos = pos
+    a.over = this.o.overscroll === 'bounce' && !this.reduced() ? rubber(raw - pos, a.view) : 0
+    this.source = 'touch'
+    this.wake()
+  }
+
+  /** Where a drag would start from now, overscroll included, so catching a bounce doesn't jump. */
+  rawPos(axis: Axis) {
+    this.ready()
+    const a = this.ax[axis]
+    return a.pos + unrubber(a.over, a.view)
+  }
+
+  /** A finger lifted with velocity `v` (px/ms, content direction): bounce back, coast, or glide to a snap point. */
+  release(axis: Axis, v: number) {
+    const a = this.ax[axis]
+    if (a.over) {
+      a.anim = { kind: 'spring', x0: a.over, v0: 0, start: -1 }
+      return this.wake()
+    }
+    const glide = this.o.momentum ? v : 0
+    if (a.points.length) {
+      const end = a.pos + (Math.abs(glide) > 0.05 ? glide / -Math.log(this.o.friction) : 0)
+      const to = snapTo(a.points, end, { ...this.o.snap, dir: Math.sign(glide), max: a.max })
+      if (to !== end || this.o.snap?.type === 'mandatory') {
+        const dur =
+          Math.abs(glide) > 0.05
+            ? clamp((3 * Math.abs(to - a.pos)) / Math.abs(glide), 180, 900)
+            : 260
+        return this.tweenTo(axis, to, 'snap', dur)
+      }
+    }
+    if (Math.abs(glide) > 0.05) {
+      a.anim = { kind: 'coast', v: glide }
+      this.wake()
+    }
+  }
+
+  /** Scrolling stopped: rest on a snap point if one applies. */
+  settle(axis: Axis) {
+    const a = this.ax[axis]
+    if (!a.points.length || a.anim) return
+    const to = snapTo(a.points, a.pos, { ...this.o.snap, max: a.max })
+    if (Math.abs(to - a.pos) > 0.5) this.tweenTo(axis, to, 'snap')
+  }
+
+  /** Keep scrolling at `v` px/ms until called with 0: selection and drag autoscroll. */
+  auto(axis: Axis, v: number) {
+    const a = this.ax[axis]
+    if (!v) {
+      if (a.anim?.kind === 'auto') a.anim = null
+      return
+    }
+    a.anim = { kind: 'auto', v }
+    this.source = 'select'
+    this.wake()
+  }
+
+  /** The browser moved the viewport (focus, find, an anchor, someone else's scrollTop): adopt it. */
+  adopt() {
+    const t = performance.now()
+    const dt = t - this.seen
+    this.seen = t
+    for (const a of this.axes) {
+      const now = a.axis === 'y' ? this.vp.scrollTop : this.vp.scrollLeft
+      if (Math.abs(now - a.written) <= 1) continue
+      a.v = dt > 0 && dt < 100 ? (now - a.pos) / dt : 0
+      a.anim = null
+      a.pos = a.written = now
+      this.source = 'native'
+      this.dirty = true
+    }
+    if (!this.dirty) return
+    this.onActivity()
+    this.wake()
+  }
+
+  private step(a: AxisState, now: number, dt: number) {
+    const m = a.anim
+    if (!m) return false
+    if (m.kind === 'tween') {
+      if (m.start < 0) m.start = now - 16
+      const t = Math.min(1, (now - m.start) / m.dur)
+      const before = a.pos
+      a.pos = clamp(m.from + (m.to - m.from) * m.ease(t), a.min, a.max)
+      a.v = dt ? (a.pos - before) / dt : 0
+      if (t < 1) return true
+      a.anim = null
+      a.v = 0
+      return false
+    }
+    if (m.kind === 'coast') return this.coastStep(a, m, dt)
+    if (m.kind === 'spring') {
+      if (m.start < 0) m.start = now - 16
+      const t = now - m.start
+      a.over = spring(m.x0, m.v0, t)
+      if (t > 60 && Math.abs(a.over) < 0.4) {
+        a.over = 0
+        a.anim = null
+        return false
+      }
+      return true
+    }
+    a.pos = clamp(a.pos + m.v * dt, a.min, a.max)
+    this.afterAuto?.()
+    return true
+  }
+
+  private coastStep(a: AxisState, m: { v: number }, dt: number) {
+    const { moved, v } = coast(m.v, this.o.friction, dt)
+    const next = a.pos + moved
+    m.v = a.v = v
+    if (next < a.min || next > a.max) {
+      a.pos = clamp(next, a.min, a.max)
+      const bounce = this.o.overscroll === 'bounce' && !this.reduced() && Math.abs(v) > 0.2
+      a.anim = bounce ? { kind: 'spring', x0: 0, v0: v, start: -1 } : null
+      return bounce
+    }
+    a.pos = next
+    if (Math.abs(v) >= 0.01) return true
+    a.anim = null
+    a.v = 0
+    this.settle(a.axis)
+    return !!a.anim
+  }
+
+  tick = (now: number) => {
+    this.frame = 0
+    const dt = this.last ? Math.min(64, now - this.last) : 16
+    this.last = now
+    let busy = false
+    for (const a of this.axes) if (this.step(a, now, dt)) busy = true
+    const moved = this.write()
+    if (moved) this.onActivity()
+    if (this.onFrame(now)) busy = true
+    if (moved || this.dirty) this.emit()
+    this.dirty = false
+    if (busy) {
+      this.frame = requestAnimationFrame(this.tick)
+    } else this.last = 0
+  }
+
+  /** Write positions and overscroll to the DOM. Returns whether anything moved. */
+  write() {
+    const { x, y } = this.ax
+    let moved = false
+    if (y.pos !== y.written) {
+      this.vp.scrollTop = y.written = y.pos
+      moved = true
+    }
+    if (x.pos !== x.written) {
+      this.vp.scrollLeft = x.written = x.pos
+      moved = true
+    }
+    const over = `${x.over}|${y.over}`
+    if (this.content && this.content.dataset.over !== over) {
+      this.content.dataset.over = over
+      this.content.style.transform =
+        x.over || y.over ? `translate3d(${-x.over}px, ${-y.over}px, 0)` : ''
+      moved = true
+    }
+    // The browser fires its own in native mode, in the frame it draws.
+    if (moved && this.o.syncEvents && this.o.mode === 'engine') {
+      this.dispatching = true
+      this.vp.dispatchEvent(new Event('scroll'))
+      this.dispatching = false
+    }
+    return moved
+  }
+
+  state(): ScrollState {
+    this.ready()
+    const { x, y } = this.ax
+    const px = x.max - x.min > 0 ? (x.pos - x.min) / (x.max - x.min) : 0
+    return {
+      x: x.pos,
+      y: y.pos,
+      maxX: this.rtl ? x.min : x.max,
+      maxY: y.max,
+      progressX: this.rtl ? 1 - px : px,
+      progressY: y.max > 0 ? y.pos / y.max : 0,
+      overscrollX: x.over,
+      overscrollY: y.over,
+      velocityX: x.v,
+      velocityY: y.v,
+      source: this.source,
+    }
+  }
+
+  emit() {
+    this.o.onScroll?.(this.state())
+  }
+}
+
+export const clamp = (v: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, v))

package/src/index.ts

@@ -0,0 +1,21 @@
+// @weft-js/scroll: scrolling run in JavaScript, with bars drawn in the DOM or (from `./canvas`) on a canvas.
+export { scroller } from './scroller'
+export { wrap } from './wrap'
+export { domRenderer } from './render'
+export { easings, easeOut, coastDistance, rubber } from './physics'
+export { thumbLength, thumbOffset, dragRatio, progressAt } from './bar'
+export { snapTo, snapStep } from './snap'
+export { normalizeWheel, pageStep } from './wheel'
+export type {
+  Axis,
+  BarFrame,
+  BarOptions,
+  Easing,
+  Renderer,
+  ScrollOptions,
+  ScrollSource,
+  ScrollState,
+  Scroller,
+  SnapOptions,
+  ThumbOptions,
+} from './types'

package/src/keys.ts

@@ -0,0 +1,87 @@
+// Keyboard scrolling, with the keys and step sizes browsers use. A key the area can't act on (already at that edge)
+// is left alone, so it reaches the scroller outside or the page.
+import type { Engine } from './engine'
+import { pageStep } from './wheel'
+import type { Axis } from './types'
+
+/** Roles whose widgets use the arrow keys themselves. */
+const WIDGETS =
+  /^(?:slider|listbox|menu|menubar|grid|treegrid|tree|tablist|radiogroup|spinbutton|combobox|textbox|toolbar|option|menuitem|tab|radio)$/
+
+/** Whether keys typed at `el` belong to it rather than to scrolling. `space` asks about the space bar. */
+export function ownsKeys(el: Element | null, space: boolean) {
+  if (!el || !(el instanceof HTMLElement)) return false
+  if (el.isContentEditable) return true
+  const tag = el.tagName
+  if (tag === 'TEXTAREA' || tag === 'SELECT') return true
+  if (tag === 'INPUT') {
+    const t = (el as HTMLInputElement).type
+    return space || !/^(?:checkbox|radio|button|submit|reset|image|file|color)$/.test(t)
+  }
+  const role = el.getAttribute('role') ?? ''
+  if (WIDGETS.test(role)) return true
+  if (space)
+    return (
+      tag === 'BUTTON' ||
+      tag === 'SUMMARY' ||
+      tag === 'A' ||
+      role === 'button' ||
+      role === 'checkbox' ||
+      role === 'switch'
+    )
+  return false
+}
+
+/** The move a key asks for, or null. */
+export function keyMove(
+  e: Engine,
+  ev: KeyboardEvent,
+): { axis: Axis; by?: number; to?: number } | null {
+  const line = e.o.lineHeight
+  const { x, y } = e.ax
+  switch (ev.key) {
+    case 'ArrowDown':
+      return { axis: 'y', by: line }
+    case 'ArrowUp':
+      return { axis: 'y', by: -line }
+    case 'ArrowRight':
+      return { axis: 'x', by: line }
+    case 'ArrowLeft':
+      return { axis: 'x', by: -line }
+    case 'PageDown':
+      return { axis: 'y', by: pageStep(y.view) }
+    case 'PageUp':
+      return { axis: 'y', by: -pageStep(y.view) }
+    case ' ':
+      return { axis: 'y', by: (ev.shiftKey ? -1 : 1) * pageStep(y.view) }
+    case 'Home':
+      return y.max > 0 || !x.on
+        ? { axis: 'y', to: y.min }
+        : { axis: 'x', to: e.rtl ? x.max : x.min }
+    case 'End':
+      return y.max > 0 || !x.on
+        ? { axis: 'y', to: y.max }
+        : { axis: 'x', to: e.rtl ? x.min : x.max }
+    default:
+      return null
+  }
+}
+
+/** Listen for keys on the viewport and anything focused inside it. Returns the cleanup. */
+export function keyInput(e: Engine) {
+  const onKey = (ev: KeyboardEvent) => {
+    if (!e.o.keyboard || ev.defaultPrevented || ev.altKey || ev.metaKey) return
+    if (ev.ctrlKey && ev.key !== 'Home' && ev.key !== 'End') return
+    const move = keyMove(e, ev)
+    if (!move || ownsKeys(ev.target as Element, ev.key === ' ')) return
+    const a = e.ax[move.axis]
+    const heading = a.anim?.kind === 'tween' ? a.anim.to : a.pos
+    const dir = move.to !== undefined ? Math.sign(move.to - heading) : Math.sign(move.by ?? 0)
+    if (!a.on || !e.canMove(move.axis, dir)) return
+    ev.preventDefault()
+    if (move.to !== undefined) e.tweenTo(move.axis, move.to, 'key')
+    else e.tweenBy(move.axis, move.by ?? 0, 'key')
+  }
+  e.vp.addEventListener('keydown', onKey)
+  return () => e.vp.removeEventListener('keydown', onKey)
+}

package/src/options.ts

@@ -0,0 +1,88 @@
+// Defaults, and options resolved into the numbers the engine reads every frame.
+import { easeOut } from './physics'
+import type { BarFrame, BarOptions, ScrollOptions } from './types'
+
+export type Resolved = Required<
+  Omit<ScrollOptions, 'renderer' | 'snap' | 'label' | 'onScroll' | 'thumb' | 'bar'>
+> & { [K in 'renderer' | 'snap' | 'label' | 'onScroll']: ScrollOptions[K] | undefined } & {
+  thumb: NonNullable<ScrollOptions['thumb']>
+  bar: BarFrame['bar']
+}
+
+/** The look a bar has when no option or CSS says otherwise. Colours follow the text colour, so themes come free. */
+export const BAR_DEFAULTS: BarFrame['bar'] = {
+  width: 6,
+  hoverWidth: 10,
+  inset: 2,
+  radius: 3,
+  color: 'color-mix(in srgb, currentColor 32%, transparent)',
+  hoverColor: 'color-mix(in srgb, currentColor 48%, transparent)',
+  activeColor: 'color-mix(in srgb, currentColor 60%, transparent)',
+  track: 'transparent',
+  hoverTrack: 'color-mix(in srgb, currentColor 8%, transparent)',
+  layout: 'overlay',
+  show: 'scroll',
+  hideDelay: 900,
+  fade: 200,
+  trackClick: 'page',
+}
+
+export function resolve(o: ScrollOptions): Resolved {
+  const bar = { ...BAR_DEFAULTS, ...defined(o.bar ?? {}) }
+  if (o.bar?.radius === undefined) bar.radius = bar.width / 2
+  return {
+    mode: o.mode ?? 'native',
+    axes: o.axes ?? 'both',
+    thumb: o.thumb ?? {},
+    bar,
+    renderer: o.renderer,
+    duration: o.duration ?? 220,
+    easing: o.easing ?? easeOut,
+    friction: o.friction ?? 0.998,
+    momentum: o.momentum ?? true,
+    wheelSpeed: o.wheelSpeed ?? 1,
+    lineHeight: o.lineHeight ?? 40,
+    overscroll: o.overscroll ?? 'bounce',
+    chain: o.chain ?? 'auto',
+    snap: o.snap,
+    keyboard: o.keyboard ?? true,
+    autoscroll: o.autoscroll ?? true,
+    touch: o.touch ?? 'js',
+    grab: o.grab ?? false,
+    motion: o.motion ?? 'auto',
+    label: o.label,
+    syncEvents: o.syncEvents ?? true,
+    onScroll: o.onScroll,
+  }
+}
+
+const defined = (o: BarOptions) =>
+  Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined)) as BarOptions
+
+/** The CSS custom properties a bar option sets, so DOM bars and stylesheets read the same values. */
+export const BAR_VARS: Partial<Record<keyof BarOptions, string>> = {
+  width: '--scroll-width',
+  hoverWidth: '--scroll-hover-width',
+  inset: '--scroll-inset',
+  radius: '--scroll-radius',
+  color: '--scroll-color',
+  hoverColor: '--scroll-hover-color',
+  activeColor: '--scroll-active-color',
+  track: '--scroll-track',
+  hoverTrack: '--scroll-hover-track',
+  fade: '--scroll-fade',
+}
+
+/** Write the options the caller gave as custom properties on the root; the rest come from the stylesheet. */
+export function writeVars(root: HTMLElement, bar: BarOptions | undefined, reduced: boolean) {
+  for (const [key, name] of Object.entries(BAR_VARS)) {
+    const v = bar?.[key as keyof BarOptions]
+    if (v === undefined) root.style.removeProperty(name)
+    else
+      root.style.setProperty(
+        name,
+        typeof v === 'number' ? `${v}${key === 'fade' ? 'ms' : 'px'}` : v,
+      )
+  }
+  if (reduced) root.style.setProperty('--scroll-fade', '0ms')
+}

package/src/physics.ts

@@ -0,0 +1,65 @@
+// The numbers behind the feel: easing curves, inertia, the rubber band and the spring back. Pure, so tests pin them.
+import type { Easing } from './types'
+
+/** Ease-out with a soft landing; the curve browsers use for smooth scrolling is close to this. */
+export const easeOut: Easing = (t) => 1 - (1 - t) ** 3
+/** Named curves to pass as `easing`. */
+export const easings = {
+  linear: (t: number) => t,
+  easeOut,
+  easeOutQuint: (t: number) => 1 - (1 - t) ** 5,
+  easeInOut: (t: number) => (t < 0.5 ? 4 * t * t * t : 1 - (-2 * t + 2) ** 3 / 2),
+  /** Exponential ease-out: quick start, long tail, like a coasting fling. */
+  expo: (t: number) => (t >= 1 ? 1 : 1 - 2 ** (-10 * t)),
+} satisfies Record<string, Easing>
+
+/** Where a coast from velocity `v` (px/ms) ends, with `friction` kept per ms. */
+export function coastDistance(v: number, friction: number) {
+  return friction >= 1 || friction <= 0 ? 0 : v / -Math.log(friction)
+}
+
+/** Advance a coast by `dt` ms: the distance moved and the velocity left. */
+export function coast(v: number, friction: number, dt: number) {
+  const k = friction ** dt
+  return { moved: coastDistance(v, friction) * (1 - k), v: v * k }
+}
+
+/** How far content follows a finger dragged `excess` px past an edge of a `size` px viewport. */
+export function rubber(excess: number, size: number) {
+  if (!excess || size <= 0) return 0
+  const s = Math.sign(excess)
+  return s * (1 - 1 / ((Math.abs(excess) * 0.55) / size + 1)) * size
+}
+
+/** The finger distance that gives `offset` of rubber band: `rubber`'s inverse. */
+export function unrubber(offset: number, size: number) {
+  if (!offset || size <= 0) return 0
+  const a = Math.min(Math.abs(offset), size * 0.999)
+  return (Math.sign(offset) * (size / (1 - a / size) - size)) / 0.55
+}
+
+/** A critically damped spring toward 0, from `x0` with velocity `v0`: where it is after `t` ms. */
+export function spring(x0: number, v0: number, t: number, omega = 0.014) {
+  return (x0 + (v0 + omega * x0) * t) * Math.exp(-omega * t)
+}
+
+/** Tracks pointer velocity over the last ~100 ms, as touch scrollers do, so a pause before lifting stops a fling. */
+export class Velocity {
+  private samples: { t: number; x: number; y: number }[] = []
+  reset() {
+    this.samples.length = 0
+  }
+  add(t: number, x: number, y: number) {
+    this.samples.push({ t, x, y })
+    while (this.samples.length > 2 && t - this.samples[0]!.t > 100) this.samples.shift()
+  }
+  /** px per ms, pointing the way the content should move. Zero when the last move is stale. */
+  get(now: number) {
+    const s = this.samples
+    const last = s.at(-1)
+    const first = s[0]
+    if (!last || !first || last === first || now - last.t > 50) return { x: 0, y: 0 }
+    const dt = Math.max(1, last.t - first.t)
+    return { x: (last.x - first.x) / dt, y: (last.y - first.y) / dt }
+  }
+}