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

package/src/touch.ts

@@ -0,0 +1,169 @@
+// Touch and pen drags (and mouse drags with `grab`). One gesture at a time across every scroller: the innermost one
+// under the finger starts it, and once the direction is clear it goes to the innermost scroller that can move that
+// way, or to the page when none can.
+import { Velocity } from './physics'
+import { registry, type Engine } from './engine'
+import type { Axis } from './types'
+
+const SLOP = 8
+
+interface Gesture {
+  id: number
+  chain: Engine[]
+  owner: Engine | null
+  page: Element | null
+  axes: Axis[]
+  x0: number
+  y0: number
+  lastX: number
+  lastY: number
+  raw: { x: number; y: number }
+  vel: Velocity
+  moved: boolean
+}
+
+let g: Gesture | null = null
+
+/** The scrollers from `e` outwards. */
+function chainFrom(e: Engine) {
+  const out: Engine[] = []
+  for (let at: Engine | null = e; at; at = at.parent()) out.push(at)
+  return out
+}
+
+/** Listen for drags starting in the viewport. Returns the cleanup. */
+export function touchInput(e: Engine) {
+  const onDown = (ev: PointerEvent) => {
+    if (g?.id === ev.pointerId || !ev.isPrimary) return
+    const mouse = ev.pointerType === 'mouse'
+    const js = e.o.touch === 'js' && e.o.mode === 'engine'
+    if (mouse ? !e.o.grab || ev.button !== 0 : !js) return
+    const chain = chainFrom(e)
+    let caught = false
+    for (const s of chain)
+      for (const a of s.axes) {
+        if (a.anim?.kind === 'coast' && Math.abs(a.v) > 0.1) caught = true
+        if (a.anim?.kind !== 'spring') s.stop(a.axis)
+      }
+    if (mouse) ev.preventDefault()
+    g = {
+      id: ev.pointerId,
+      chain,
+      owner: null,
+      page: null,
+      axes: [],
+      x0: ev.clientX,
+      y0: ev.clientY,
+      lastX: ev.clientX,
+      lastY: ev.clientY,
+      raw: { x: 0, y: 0 },
+      vel: new Velocity(),
+      moved: caught,
+    }
+    g.vel.add(ev.timeStamp, -ev.clientX, -ev.clientY)
+    addEventListener('pointermove', onMove)
+    addEventListener('pointerup', onUp)
+    addEventListener('pointercancel', onUp)
+  }
+  e.vp.addEventListener('pointerdown', onDown)
+  return () => {
+    e.vp.removeEventListener('pointerdown', onDown)
+    if (g?.chain[0] === e) end()
+  }
+}
+
+function onMove(ev: PointerEvent) {
+  if (!g || ev.pointerId !== g.id) return
+  const dx = ev.clientX - g.x0
+  const dy = ev.clientY - g.y0
+  if (!g.axes.length) {
+    if (Math.hypot(dx, dy) < SLOP) return
+    pick(g, dx, dy)
+    g.moved = true
+  }
+  g.vel.add(ev.timeStamp, -ev.clientX, -ev.clientY)
+  if (g.owner) {
+    for (const axis of g.axes) g.owner.drag(axis, g.raw[axis] - (axis === 'x' ? dx : dy))
+  } else if (g.page) {
+    g.page.scrollBy({
+      left: g.axes.includes('x') ? g.lastX - ev.clientX : 0,
+      top: g.axes.includes('y') ? g.lastY - ev.clientY : 0,
+      behavior: 'instant',
+    })
+  }
+  g.lastX = ev.clientX
+  g.lastY = ev.clientY
+}
+
+/** Lock the direction and choose who moves: the innermost scroller that can, as browsers chain overscroll. */
+function pick(gest: Gesture, dx: number, dy: number) {
+  const ax = Math.abs(dx)
+  const ay = Math.abs(dy)
+  const both = gest.chain[0]!.ax
+  if (ax > ay * 1.5 || !both.y.on) gest.axes = ['x']
+  else if (ay > ax * 1.5 || !both.x.on) gest.axes = ['y']
+  else gest.axes = ['x', 'y']
+  const can = (s: Engine) => gest.axes.some((a) => s.canMove(a, -Math.sign(a === 'x' ? dx : dy)))
+  let owner: Engine | null = null
+  for (const s of gest.chain) {
+    if (can(s) || s.o.chain === 'contain') {
+      owner = s
+      break
+    }
+  }
+  const outer = gest.chain.at(-1)!
+  if (!owner && outer.o.chain === 'auto') {
+    const page = scrollParent(outer.root)
+    if (page && gest.axes.some((a) => nativeRoom(page, a, -Math.sign(a === 'x' ? dx : dy))))
+      gest.page = page
+  }
+  // Nothing anywhere can move this way: the innermost area takes it, to rubber-band.
+  if (!owner && !gest.page) owner = gest.chain[0]!
+  gest.owner = owner
+  // Measured from where the slop ended, so the content doesn't jump by the slop when the drag starts.
+  if (owner) for (const a of gest.axes) gest.raw[a] = owner.rawPos(a) + (a === 'x' ? dx : dy)
+}
+
+function onUp(ev: PointerEvent) {
+  if (!g || ev.pointerId !== g.id) return
+  const v = ev.type === 'pointercancel' ? { x: 0, y: 0 } : g.vel.get(ev.timeStamp)
+  if (g.owner) for (const axis of g.axes) g.owner.release(axis, v[axis])
+  if (g.moved) swallowClick()
+  end()
+}
+
+function end() {
+  g = null
+  removeEventListener('pointermove', onMove)
+  removeEventListener('pointerup', onUp)
+  removeEventListener('pointercancel', onUp)
+}
+
+/** A drag that moved, or a tap that caught a coast, isn't a click on what's under it. */
+function swallowClick() {
+  const stop = (ev: Event) => {
+    ev.stopPropagation()
+    ev.preventDefault()
+  }
+  addEventListener('click', stop, { capture: true, once: true })
+  setTimeout(() => removeEventListener('click', stop, { capture: true }), 350)
+}
+
+/** The nearest natively scrolling ancestor, or the page. */
+function scrollParent(from: Element): Element | null {
+  for (let el = from.parentElement; el; el = el.parentElement) {
+    if (registry.has(el)) return null
+    const s = getComputedStyle(el)
+    if (/(auto|scroll)/.test(s.overflowY + s.overflowX) && el.scrollHeight > el.clientHeight)
+      return el
+  }
+  return document.scrollingElement
+}
+
+/** Whether a native scroller has room to move `dir` along `axis`. */
+function nativeRoom(el: Element, axis: Axis, dir: number) {
+  const max = axis === 'y' ? el.scrollHeight - el.clientHeight : el.scrollWidth - el.clientWidth
+  const at = axis === 'y' ? el.scrollTop : Math.abs(el.scrollLeft)
+  const forward = axis === 'x' && getComputedStyle(el).direction === 'rtl' ? -dir : dir
+  return forward > 0 ? at < max - 0.5 : at > 0.5
+}

package/src/types.ts

@@ -0,0 +1,178 @@
+// The public shapes: options in, state out, and what a renderer is handed each frame.
+
+/** A scroll axis. */
+export type Axis = 'x' | 'y'
+/** Where the movement came from. `native` is the browser moving it: focus, find-in-page, an anchor. */
+export type ScrollSource = 'wheel' | 'touch' | 'key' | 'bar' | 'api' | 'snap' | 'select' | 'native'
+/** Maps 0..1 time to 0..1 progress. */
+export type Easing = (t: number) => number
+
+/** The thumb's size. Leave `size` out for a thumb that grows and shrinks with the content, as a native one does. */
+export interface ThumbOptions {
+  /** A fixed length in px: the thumb never grows or shrinks. */
+  size?: number
+  /** The shortest a proportional thumb gets. Default 24. */
+  min?: number
+  /** The longest a proportional thumb gets. */
+  max?: number
+}
+
+/** How the bars look and where they sit. Colours are any CSS colour. */
+export interface BarOptions {
+  /** Thumb thickness at rest, px. Default 6. */
+  width?: number
+  /** Thumb thickness while hovered or dragged, px. Default 10. */
+  hoverWidth?: number
+  /** Gap between the thumb and the edge of the area, px. Default 2. */
+  inset?: number
+  /** Corner radius, px. Default: half the thickness. */
+  radius?: number
+  color?: string
+  hoverColor?: string
+  activeColor?: string
+  /** The track behind the thumb. Default transparent. */
+  track?: string
+  hoverTrack?: string
+  /** `overlay` floats over the content; `gutter` reserves room beside it. Default `overlay`. */
+  layout?: 'overlay' | 'gutter'
+  /** When the bar shows. `scroll` (default): while scrolling or hovered. `hover`: while the pointer is over the area. */
+  show?: 'always' | 'scroll' | 'hover' | 'never'
+  /** How long the bar stays after scrolling stops, ms. Default 900. */
+  hideDelay?: number
+  /** Fade length, ms. Default 200. */
+  fade?: number
+  /** A press on the track: `page` steps a page (repeating while held), `jump` moves there. Alt flips it. */
+  trackClick?: 'page' | 'jump'
+}
+
+/** Snapping, as CSS scroll-snap does it. */
+export interface SnapOptions {
+  /** Snap positions in px, or a function returning them (read again on every resize). */
+  points?: readonly number[] | (() => readonly number[])
+  /** Elements in the content to snap to, aligned by `align`. */
+  selector?: string
+  align?: 'start' | 'center' | 'end'
+  /** `mandatory` always rests on a point; `proximity` only when within `proximity` px. Default `proximity`. */
+  type?: 'mandatory' | 'proximity'
+  proximity?: number
+  axis?: Axis
+}
+
+/** What a scroller does and how it looks. Every field is optional. */
+export interface ScrollOptions {
+  /**
+   * Who moves the content. `native` (default): the browser scrolls it, on the compositor, so it keeps moving while
+   * the main thread is busy; this draws the bars and runs the API, and the wheel, touch and key options are the
+   * browser's own. `engine`: every input runs here, with this package's easing, momentum, rubber band and keys.
+   */
+  mode?: 'native' | 'engine'
+  /** Which axes scroll. Default `both`: an axis whose content fits shows no bar. */
+  axes?: Axis | 'both'
+  thumb?: ThumbOptions
+  bar?: BarOptions
+  /** Draws the bars. Default: DOM elements styled by CSS. `canvas()` from `@weft-js/scroll/canvas` paints them. */
+  renderer?: Renderer
+  /** Animation length for wheel notches, keys and smooth `scrollTo`, ms. Default 220. */
+  duration?: number
+  easing?: Easing
+  /** Touch inertia: the share of velocity kept per ms. Default 0.998 (iOS's normal rate). */
+  friction?: number
+  /** Coast after a touch fling. Default true. */
+  momentum?: boolean
+  /** Wheel distance multiplier. Default 1. */
+  wheelSpeed?: number
+  /** px for a wheel "line" and an arrow key. Default 40. */
+  lineHeight?: number
+  /** Rubber-band past the edges on touch. Default `bounce`. */
+  overscroll?: 'bounce' | 'none'
+  /** At an edge, hand the gesture to the scroller outside (`auto`), or keep it (`contain`). Default `auto`. */
+  chain?: 'auto' | 'contain'
+  snap?: SnapOptions
+  /** Arrows, Page keys, Home, End and Space scroll the area. Default true. */
+  keyboard?: boolean
+  /** Scroll while a text selection or a drag is held past the edge. Default true. */
+  autoscroll?: boolean
+  /** Touch input: `js` (default) runs it here; `native` leaves touch to the browser. */
+  touch?: 'js' | 'native'
+  /** Drag the content with a mouse, as a hand tool. Default false. */
+  grab?: boolean
+  /** `reduce` makes every animated scroll instant. Default `auto`: follows prefers-reduced-motion. */
+  motion?: 'auto' | 'reduce' | 'full'
+  /** The viewport's accessible name. With it, the viewport is a `region` landmark. */
+  label?: string
+  /** Also fire a `scroll` event in the frame a position is written, so listeners draw with that frame. Default true. */
+  syncEvents?: boolean
+  /** Called once per frame in which the position or overscroll changed. */
+  onScroll?: (state: ScrollState) => void
+}
+
+/** Where the scroller is. `x` is the DOM's `scrollLeft`, so it runs negative in right-to-left content. */
+export interface ScrollState {
+  x: number
+  y: number
+  /** The furthest `y` and furthest-from-zero `x` can go. */
+  maxX: number
+  maxY: number
+  /** 0 at the start, 1 at the end, for each axis. In right-to-left content `progressX` 0 is the right edge. */
+  progressX: number
+  progressY: number
+  /** Rubber-band offset past an edge, px. */
+  overscrollX: number
+  overscrollY: number
+  /** px per ms. */
+  velocityX: number
+  velocityY: number
+  source: ScrollSource
+}
+
+/** One bar as a renderer draws it: boxes are px within the bar's own track. */
+export interface BarFrame {
+  axis: Axis
+  track: { width: number; height: number }
+  thumb: { x: number; y: number; width: number; height: number }
+  /** 0 at rest, 1 fully hovered: a renderer can ease the thickness with it. */
+  grow: number
+  hover: boolean
+  active: boolean
+  progress: number
+  /** The thumb's offset along the track at the scroll start and at the end, px: what a scroll timeline animates. */
+  span: { start: number; end: number }
+  rtl: boolean
+  bar: Required<Omit<BarOptions, 'radius'>> & { radius: number }
+}
+
+/** Draws the bars. The scroller owns the track elements and their pointer handling; a renderer only paints. */
+export interface Renderer {
+  /** Build what it needs inside a bar's track element. */
+  mount(track: HTMLElement, axis: Axis): void
+  /** Paint a frame. Called only when something about it changed. */
+  draw(track: HTMLElement, frame: BarFrame): void
+  /** Called while `grow` eases: true asks for another frame. */
+  animates?: boolean
+  unmount(track: HTMLElement): void
+}
+
+/** What `scroller` returns. */
+export interface Scroller {
+  /** The current position and limits. */
+  state(): ScrollState
+  scrollTo(to: { top?: number; left?: number; behavior?: ScrollBehavior }): void
+  scrollBy(by: { top?: number; left?: number; behavior?: ScrollBehavior }): void
+  /** Bring `el` into view, as `Element.scrollIntoView` does, within this scroller only. */
+  scrollIntoView(
+    el: Element,
+    o?: {
+      block?: ScrollLogicalPosition
+      inline?: ScrollLogicalPosition
+      behavior?: ScrollBehavior
+      margin?: number
+    },
+  ): void
+  /** Stop any animation or coast where it is. */
+  stop(): void
+  /** Measure again: call after a change no ResizeObserver can see. */
+  refresh(): void
+  update(options: ScrollOptions): void
+  destroy(): void
+  readonly viewport: HTMLElement
+}

package/src/wheel-input.ts

@@ -0,0 +1,112 @@
+// Wheel and trackpad input. A gesture latches to the scroller it started on, as browsers do: one that starts at an
+// edge goes to the scroller outside (or to the page), one that reaches an edge midway stays put.
+import { registry, type Engine } from './engine'
+import { normalizeWheel, pageStep } from './wheel'
+import type { Axis } from './types'
+
+const LATCH_MS = 300
+const SETTLE_MS = 140
+let latch: { owner: Engine | Element; t: number } | null = null
+
+/** Listen for wheel events on the viewport. Returns the cleanup. */
+export function wheelInput(e: Engine) {
+  let settle: ReturnType<typeof setTimeout> | undefined
+  const onWheel = (ev: WheelEvent) => {
+    if (ev.defaultPrevented || ev.ctrlKey) return
+    const o = e.o
+    const step = normalizeWheel(ev, o.lineHeight, {
+      x: pageStep(e.ax.x.view),
+      y: pageStep(e.ax.y.view),
+    })
+    const dx = step.x * o.wheelSpeed
+    const dy = step.y * o.wheelSpeed
+    if (!dx && !dy) return
+    if (!claims(e, ev, dx, dy)) return
+    ev.preventDefault()
+    latch = { owner: e, t: performance.now() }
+    for (const [axis, d] of [
+      ['x', dx],
+      ['y', dy],
+    ] as [Axis, number][]) {
+      if (!d || !e.ax[axis].on) continue
+      if (step.notched) e.tweenBy(axis, d, 'wheel')
+      else {
+        const a = e.ax[axis]
+        const from = a.anim?.kind === 'tween' ? a.anim.to : a.pos
+        e.moveTo(axis, from + d, 'wheel')
+      }
+    }
+    clearTimeout(settle)
+    settle = setTimeout(() => {
+      e.settle('x')
+      e.settle('y')
+    }, SETTLE_MS)
+  }
+  e.vp.addEventListener('wheel', onWheel, { passive: false })
+  if (!watching) {
+    watching = true
+    addEventListener('wheel', pageTook, { passive: true })
+  }
+  return () => {
+    clearTimeout(settle)
+    e.vp.removeEventListener('wheel', onWheel)
+    if (latch?.owner === e) latch = null
+  }
+}
+
+/** Whether this scroller takes the event: it is latched here, or a new gesture it can move with. */
+function claims(e: Engine, ev: WheelEvent, dx: number, dy: number) {
+  const live = latch && performance.now() - latch.t < LATCH_MS && performance.now() >= latch.t
+  if (live && latch) {
+    if (latch.owner === e) {
+      latch.t = performance.now()
+      return true
+    }
+    // Latched outside this scroller (a parent, or the page), or on a native scroller inside it: not ours.
+    const el = latch.owner instanceof Element ? latch.owner : latch.owner.vp
+    if (el.contains(e.vp) || (e.vp.contains(el) && el.contains(ev.target as Node))) {
+      latch.t = performance.now()
+      return false
+    }
+  }
+  const native = nativeTaker(ev.target as Element, e.vp, dx, dy)
+  if (native) {
+    latch = { owner: native, t: performance.now() }
+    return false
+  }
+  if (e.canMove('x', Math.sign(dx)) || e.canMove('y', Math.sign(dy))) return true
+  if (e.o.chain === 'contain') return true
+  // Handed on: a scroller outside may claim it; if none does, the page has it (see `pageTook`).
+  handed = ev
+  return false
+}
+
+let handed: WheelEvent | null = null
+let watching = false
+/** Passive, so it costs the page's own scrolling nothing: notes that a handed-on gesture went to the page. */
+const pageTook = (ev: WheelEvent) => {
+  if (ev === handed && !ev.defaultPrevented)
+    latch = { owner: document.documentElement, t: performance.now() }
+  handed = null
+}
+
+/** A natively scrolling element between the target and the viewport that can take this delta itself. */
+function nativeTaker(target: Element | null, stop: Element, dx: number, dy: number) {
+  for (let el = target; el && el !== stop; el = el.parentElement) {
+    if (registry.has(el)) return null
+    if (el.scrollHeight <= el.clientHeight && el.scrollWidth <= el.clientWidth) continue
+    const s = getComputedStyle(el)
+    const scrolls = (v: string) => v === 'auto' || v === 'scroll'
+    if (dy && scrolls(s.overflowY) && room(el.scrollTop, el.scrollHeight - el.clientHeight, dy))
+      return el
+    if (dx && scrolls(s.overflowX)) {
+      const wide = el.scrollWidth - el.clientWidth
+      const rtl = s.direction === 'rtl'
+      const at = rtl ? el.scrollLeft + wide : el.scrollLeft
+      if (room(at, wide, dx)) return el
+    }
+  }
+  return null
+}
+
+const room = (at: number, max: number, d: number) => (d > 0 ? at < max - 0.5 : at > 0.5)

package/src/wheel.ts

@@ -0,0 +1,32 @@
+// Wheel events into pixels, and which kind of device sent them: a notched wheel animates each step, a trackpad's
+// pixel deltas (already carrying the OS's own momentum) apply as they come.
+
+/** One wheel event, normalised. */
+export interface WheelStep {
+  x: number
+  y: number
+  /** A mouse wheel's notch, not a trackpad: animate it. */
+  notched: boolean
+}
+
+/** Pixels for a wheel event. `line` px per line; a page is `page` px (the viewport less a little overlap). */
+export function normalizeWheel(
+  e: Pick<WheelEvent, 'deltaX' | 'deltaY' | 'deltaMode' | 'shiftKey'> & { wheelDeltaY?: number },
+  line: number,
+  page: { x: number; y: number },
+): WheelStep {
+  const scale = e.deltaMode === 1 ? line : 1
+  let x = e.deltaMode === 2 ? e.deltaX * page.x : e.deltaX * scale
+  let y = e.deltaMode === 2 ? e.deltaY * page.y : e.deltaY * scale
+  const raw = e.wheelDeltaY ?? 0
+  const notched = e.deltaMode !== 0 || (raw !== 0 && Math.abs(raw) % 120 === 0 && Math.abs(y) >= 50)
+  // Windows and Linux send Shift+wheel as vertical; macOS has already swapped it, so deltaX is set there.
+  if (e.shiftKey && !x && y) {
+    x = y
+    y = 0
+  }
+  return { x, y, notched }
+}
+
+/** The page step for a viewport of `size` px, as browsers size Page Down: most of a screen, keeping some context. */
+export const pageStep = (size: number) => Math.max(size * 0.875, size - 40)

package/src/wrap.ts

@@ -0,0 +1,27 @@
+// For pages without a framework: turn an element into a scroll area in place.
+import { scroller } from './scroller'
+import type { ScrollOptions, Scroller } from './types'
+
+/**
+ * Make `el` a scroll area without writing the markup: its children move into a viewport and content wrapper, `el`
+ * becomes the root. `destroy` puts them back.
+ */
+export function wrap(el: HTMLElement, options: ScrollOptions = {}): Scroller {
+  const viewport = document.createElement('div')
+  viewport.dataset.part = 'viewport'
+  const content = document.createElement('div')
+  content.dataset.part = 'content'
+  content.append(...el.childNodes)
+  viewport.append(content)
+  el.append(viewport)
+  const s = scroller(el, options)
+  return {
+    ...s,
+    destroy() {
+      s.destroy()
+      el.append(...content.childNodes)
+      viewport.remove()
+      delete el.dataset.scroll
+    },
+  }
+}