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

package/src/render.ts

@@ -0,0 +1,205 @@
+// The bars: their elements and ARIA, when they show, and the frame each renderer is asked to paint.
+import { thumbLength, thumbOffset } from './bar'
+import type { AxisState, Engine } from './engine'
+import type { BarFrame, Renderer } from './types'
+
+/** The default renderer: a `data-part="thumb"` element per bar, sized and moved here, styled by CSS. */
+export const domRenderer: Renderer = {
+  mount(track) {
+    if (track.querySelector('[data-part="thumb"]')) return
+    const thumb = document.createElement('div')
+    thumb.dataset.part = 'thumb'
+    thumb.dataset.made = ''
+    track.append(thumb)
+  },
+  draw(track, f) {
+    const thumb = track.querySelector<HTMLElement>('[data-part="thumb"]')
+    if (!thumb) return
+    const y = f.axis === 'y'
+    thumb.style.transform = y
+      ? `translate3d(0,${f.thumb.y}px,0)`
+      : `translate3d(${f.thumb.x}px,0,0)`
+    thumb.style[y ? 'height' : 'width'] = `${y ? f.thumb.height : f.thumb.width}px`
+    // What the stylesheet's scroll-timeline animation runs between, where the browser supports one.
+    thumb.style.setProperty('--scroll-thumb-start', `${f.span.start}px`)
+    thumb.style.setProperty('--scroll-thumb-end', `${f.span.end}px`)
+  },
+  unmount(track) {
+    const thumb = track.querySelector<HTMLElement>('[data-part="thumb"]')
+    if (thumb && thumb.dataset.made !== undefined) thumb.remove()
+    else thumb?.style.removeProperty('transform')
+  },
+}
+
+let ids = 0
+const ARIA = [
+  'role',
+  'aria-controls',
+  'aria-orientation',
+  'aria-valuemin',
+  'aria-valuemax',
+  'aria-valuenow',
+]
+
+/** Find or make each bar's track, give it scrollbar semantics, and hand it to the renderer. */
+export function mountBars(e: Engine, current: () => Renderer) {
+  const renderer = current()
+  const made: HTMLElement[] = []
+  if (!e.vp.id) e.vp.id = `scroll-${(ids++).toString(36)}-${Math.random().toString(36).slice(2, 6)}`
+  for (const a of e.axes) {
+    if (!a.on) continue
+    const orientation = a.axis === 'y' ? 'vertical' : 'horizontal'
+    let track = e.root.querySelector<HTMLElement>(
+      `:scope > [data-part="scrollbar"][data-orientation="${orientation}"]`,
+    )
+    if (!track) {
+      track = document.createElement('div')
+      track.dataset.part = 'scrollbar'
+      track.dataset.orientation = orientation
+      e.root.append(track)
+      made.push(track)
+    }
+    track.setAttribute('role', 'scrollbar')
+    track.setAttribute('aria-controls', e.vp.id)
+    track.setAttribute('aria-orientation', orientation)
+    track.setAttribute('aria-valuemin', '0')
+    track.setAttribute('aria-valuemax', '100')
+    track.setAttribute('aria-valuenow', '0')
+    a.track = track
+    renderer.mount(track, a.axis)
+  }
+  return () => {
+    for (const a of e.axes) {
+      if (!a.track) continue
+      current().unmount(a.track)
+      for (const name of ARIA) a.track.removeAttribute(name)
+      a.track = null
+      a.drawn = ''
+      a.aria = -1
+    }
+    for (const t of made) t.remove()
+  }
+}
+
+/** Paint whatever changed. Returns true while a hover grow is still easing (a renderer that animates it). */
+export function drawBars(e: Engine, renderer: Renderer, dt: number) {
+  let busy = false
+  for (const a of e.axes) {
+    if (!a.track) continue
+    const target = a.hover || a.active ? 1 : 0
+    if (a.grow !== target) {
+      a.grow = renderer.animates && !e.reduced() ? ease(a.grow, target, dt) : target
+      busy ||= a.grow !== target
+    }
+    const f = frame(e, a)
+    // On a timeline the compositor moves the thumb, so only its span and size are worth a draw.
+    const at = e.timeline ? `${f.span.start}|${f.span.end}` : `${f.thumb.x}|${f.thumb.y}`
+    const key = `${at}|${f.thumb.width}|${f.thumb.height}|${a.grow}|${a.hover}|${a.active}|${f.track.width}|${f.track.height}`
+    if (key !== a.drawn) {
+      a.drawn = key
+      renderer.draw(a.track, f)
+    }
+    const now100 = Math.round(f.progress * 100)
+    if (now100 !== a.aria) {
+      a.aria = now100
+      a.track.setAttribute('aria-valuenow', String(now100))
+    }
+  }
+  return busy
+}
+
+const ease = (from: number, to: number, dt: number) => {
+  const next = from + (to - from) * Math.min(1, dt / 70)
+  return Math.abs(to - next) < 0.02 ? to : next
+}
+
+function frame(e: Engine, a: AxisState): BarFrame {
+  const { bar } = e.o
+  const range = a.max - a.min
+  const progress = range > 0 ? (a.pos - a.min) / range : 0
+  // A native thumb shrinks against the edge while the content is pulled past it.
+  const len = Math.max(
+    Math.min(8, a.trackLen),
+    thumbLength(a.trackLen, a.view, a.total, e.o.thumb) - Math.abs(a.over) * 0.6,
+  )
+  const along = (p: number) => bar.inset + thumbOffset(a.trackLen, len, p)
+  const off = a.over > 0 ? bar.inset + a.trackLen - len : a.over < 0 ? bar.inset : along(progress)
+  // Right to left, a horizontal scroll starts at the right end.
+  const flip = a.axis === 'x' && e.rtl
+  a.thumbOff = off
+  a.thumbLen = len
+  const thick = bar.width + (bar.hoverWidth - bar.width) * a.grow
+  const y = a.axis === 'y'
+  const crossAt = y && e.rtl ? bar.inset : a.trackCross - bar.inset - thick
+  return {
+    axis: a.axis,
+    track: y
+      ? { width: a.trackCross, height: a.trackLen + 2 * bar.inset }
+      : { width: a.trackLen + 2 * bar.inset, height: a.trackCross },
+    thumb: y
+      ? { x: crossAt, y: off, width: thick, height: len }
+      : { x: off, y: crossAt, width: len, height: thick },
+    grow: a.grow,
+    hover: a.hover,
+    active: a.active,
+    progress: flip ? 1 - progress : progress,
+    span: { start: along(flip ? 1 : 0), end: along(flip ? 0 : 1) },
+    rtl: e.rtl,
+    bar,
+  }
+}
+
+/** Which bars show, as data attributes the stylesheet fades on. */
+export class Visibility {
+  private timer: ReturnType<typeof setTimeout> | undefined
+  private lastMove = 0
+  scrolling = false
+  inside = false
+
+  constructor(private e: Engine) {}
+
+  /** The position moved: show bars that show on scroll, and hide them again after the delay. */
+  moved() {
+    this.lastMove = performance.now()
+    if (!this.scrolling) {
+      this.scrolling = true
+      this.e.root.toggleAttribute('data-scrolling', true)
+      this.apply()
+    }
+    this.timer ??= setTimeout(this.idle, this.e.o.bar.hideDelay)
+  }
+
+  private idle = () => {
+    this.timer = undefined
+    const left = this.e.o.bar.hideDelay - (performance.now() - this.lastMove)
+    if (left > 4) {
+      this.timer = setTimeout(this.idle, left)
+      return
+    }
+    this.scrolling = false
+    this.e.root.toggleAttribute('data-scrolling', false)
+    this.apply()
+  }
+
+  apply() {
+    const { show } = this.e.o.bar
+    for (const a of this.e.axes) {
+      if (!a.track) continue
+      const none = !a.on || a.max - a.min < 1
+      a.track.toggleAttribute('data-none', none)
+      this.e.root.toggleAttribute(`data-overflow-${a.axis}`, !none)
+      const visible =
+        !none &&
+        (show === 'always' ||
+          (show !== 'never' &&
+            (this.scrolling || a.hover || a.active || (show === 'hover' && this.inside))))
+      a.track.toggleAttribute('data-visible', visible)
+      a.track.toggleAttribute('data-hover', a.hover)
+      a.track.toggleAttribute('data-active', a.active)
+    }
+  }
+
+  destroy() {
+    clearTimeout(this.timer)
+  }
+}

package/src/scroller-api.ts

@@ -0,0 +1,75 @@
+// The `Scroller` a caller holds: programmatic scrolling, scrollIntoView, and live option changes.
+import { clamp } from './engine'
+import { resolve } from './options'
+import type { Setup } from './scroller'
+import type { Axis, Scroller } from './types'
+
+type Move = { top?: number; left?: number; behavior?: ScrollBehavior }
+
+export function api(s: Setup, configure: () => void): Scroller {
+  const { e } = s
+  const move = (to: Move, by: boolean) => {
+    for (const [axis, v] of [
+      ['y', to.top],
+      ['x', to.left],
+    ] as [Axis, number | undefined][]) {
+      if (v === undefined || !Number.isFinite(v)) continue
+      const a = e.ax[axis]
+      const target = by ? (a.anim?.kind === 'tween' ? a.anim.to : a.pos) + v : v
+      if (to.behavior === 'smooth') e.tweenTo(axis, target, 'api')
+      else {
+        e.moveTo(axis, target, 'api')
+        e.write()
+      }
+    }
+  }
+  return {
+    viewport: e.vp,
+    state: () => e.state(),
+    scrollTo: (to) => move(to, false),
+    scrollBy: (by) => move(by, true),
+    scrollIntoView(el, o = {}) {
+      const box = e.vp.getBoundingClientRect()
+      const r = el.getBoundingClientRect()
+      const m = o.margin ?? 0
+      const plan = (axis: Axis, pos: ScrollLogicalPosition) => {
+        const a = e.ax[axis]
+        const y = axis === 'y'
+        const start = (y ? r.top - box.top : r.left - box.left) + a.pos
+        const size = y ? r.height : r.width
+        let to = a.pos
+        if (pos === 'start') to = start - m
+        else if (pos === 'end') to = start + size - a.view + m
+        else if (pos === 'center') to = start + size / 2 - a.view / 2
+        else if (start - m < a.pos || size + 2 * m > a.view) to = start - m
+        else if (start + size + m > a.pos + a.view) to = start + size - a.view + m
+        return clamp(to, a.min, a.max)
+      }
+      const top = plan('y', o.block ?? 'start')
+      const left = plan('x', o.inline ?? 'nearest')
+      move({ top, left, behavior: o.behavior ?? 'auto' }, false)
+    },
+    stop: () => e.stop(),
+    refresh: s.remeasure,
+    update(next) {
+      s.options = { ...s.options, ...next }
+      const axes = e.o.axes
+      e.o = resolve(s.options)
+      const wanted = next.renderer
+      if (wanted && wanted !== s.renderer) {
+        for (const a of e.axes) {
+          if (!a.track) continue
+          s.renderer.unmount(a.track)
+          wanted.mount(a.track, a.axis)
+          a.drawn = ''
+        }
+        s.renderer = wanted
+      }
+      configure()
+      s.reinput()
+      if (e.o.axes !== axes) s.rebar()
+      else s.remeasure()
+    },
+    destroy: () => e.destroyHooks.splice(0).forEach((f) => f()),
+  }
+}

package/src/scroller.ts

@@ -0,0 +1,240 @@
+// `scroller`: puts the engine, its inputs and its bars on a root element. `scroller-api.ts` is what it returns.
+import { autoscroll } from './autoscroll'
+import { barInput } from './bar-input'
+import { Engine, reduceQuery, registry } from './engine'
+import { keyInput } from './keys'
+import { resolve, writeVars } from './options'
+import { domRenderer, drawBars, mountBars, Visibility } from './render'
+import { api } from './scroller-api'
+import { touchInput } from './touch'
+import { wheelInput } from './wheel-input'
+import type { Renderer, ScrollOptions, Scroller } from './types'
+
+const FOCUSABLE =
+  'a[href],button:not([disabled]),input:not([disabled]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex="-1"]),[contenteditable]:not([contenteditable="false"]),summary,iframe,audio[controls],video[controls]'
+
+/** What the setup steps share. */
+export interface Setup {
+  e: Engine
+  vis: Visibility
+  options: ScrollOptions
+  renderer: Renderer
+  remeasure: () => void
+  /** Rebuild the bars, for a change of axes. */
+  rebar: () => void
+  /** Attach the inputs again, for a change of mode. */
+  reinput: () => void
+}
+
+/**
+ * Custom scrolling on `root`, which holds a `[data-part="viewport"]` element (and, inside that, the content). In the
+ * default `native` mode the browser scrolls the viewport, with its own bars hidden, and this draws the bars; in
+ * `engine` mode the viewport is `overflow: hidden` and every input runs here. Either way it keeps real scroll offsets,
+ * so focus, find, anchors and `scroll` listeners still work. Bars are found as `[data-part="scrollbar"]
+ * [data-orientation]` children of `root`, or made. Load `@weft-js/scroll/styles.css`.
+ */
+export function scroller(root: HTMLElement, options: ScrollOptions = {}): Scroller {
+  const vp = root.querySelector<HTMLElement>(':scope > [data-part="viewport"]') ?? root
+  registry
+    .get(vp)
+    ?.destroyHooks.splice(0)
+    .forEach((f) => f())
+  const content = vp === root ? null : (vp.firstElementChild as HTMLElement | null)
+  const e = new Engine(root, vp, content, resolve(options))
+  const vis = new Visibility(e)
+  const hooks = e.destroyHooks
+  const tabStop = focusable(vp, hooks)
+  // Reads happen in one place (measure, from the ResizeObserver batch) and writes in the frame, so a page that mounts
+  // many scrollers lays out once, not once per scroller.
+  let stale = true
+  const s: Setup = {
+    e,
+    vis,
+    options,
+    renderer: e.o.renderer ?? domRenderer,
+    remeasure: () => {
+      e.measure()
+      stale = true
+      e.wake()
+    },
+    rebar: () => {},
+    reinput: () => {},
+  }
+  vp.setAttribute('data-scroll-viewport', '')
+  configure(s)
+  tabStop()
+  let unbar = mountBars(e, () => s.renderer)
+  hooks.push(() => unbar())
+  root.toggleAttribute('data-ready', true)
+  if (typeof ResizeObserver !== 'function') e.measure()
+  e.onActivity = () => vis.moved()
+  e.onFrame = (now) => {
+    if (stale && e.measured) {
+      stale = false
+      tabStop()
+      vis.apply()
+    }
+    return drawBars(e, s.renderer, e.last ? now - e.last : 16)
+  }
+  const watching = watch(s)
+  s.rebar = () => {
+    unbar()
+    unbar = mountBars(e, () => s.renderer)
+    barsOff()
+    barsOff = barInput(e, vis)
+    watching.observe()
+    s.remeasure()
+  }
+  hooks.push(watching.stop, listen(s))
+  let barsOff = barInput(e, vis)
+  let inputsOff = inputs(e)
+  s.reinput = () => {
+    inputsOff()
+    inputsOff = inputs(e)
+  }
+  hooks.push(
+    () => inputsOff(),
+    () => barsOff(),
+  )
+  hooks.push(() => {
+    vis.destroy()
+    if (e.frame) cancelAnimationFrame(e.frame)
+    if (e.content) e.content.style.transform = ''
+    for (const name of ['data-ready', 'data-timeline', 'data-mode', 'data-chain'])
+      root.removeAttribute(name)
+    vp.removeAttribute('data-scroll-viewport')
+    registry.delete(vp)
+  })
+  registry.set(vp, e)
+  e.wake()
+  return api(s, () => configure(s))
+}
+
+/**
+ * The engine's input. In native mode even a wheel or touch listener that does nothing would cost the compositor its
+ * scrolling, so only keys (which reach the page first in any case, and which some browsers don't scroll a focused
+ * area for) and a mouse `grab` are attached.
+ */
+function inputs(e: Engine) {
+  const native = e.o.mode === 'native'
+  const offs = native
+    ? [keyInput(e), e.o.grab ? touchInput(e) : () => {}]
+    : [wheelInput(e), keyInput(e), touchInput(e), autoscroll(e)]
+  return () => offs.forEach((f) => f())
+}
+
+let timelines: boolean | undefined
+/** Whether CSS can drive the thumbs from the viewport's scroll position, as a named, scoped scroll timeline. */
+const canTimeline = () =>
+  (timelines ??=
+    typeof CSS !== 'undefined' &&
+    CSS.supports('animation-timeline: --a') &&
+    CSS.supports('timeline-scope: --a'))
+
+/** Options into attributes and custom properties on the root and viewport. */
+function configure({ e, options, renderer }: Setup) {
+  const { root, vp } = e
+  root.dataset.mode = e.o.mode
+  root.dataset.chain = e.o.chain
+  const timeline = e.o.mode === 'native' && renderer === domRenderer && canTimeline()
+  if (timeline !== e.timeline) for (const a of e.axes) a.drawn = ''
+  e.timeline = timeline
+  root.toggleAttribute('data-timeline', timeline)
+  e.ax.y.on = e.o.axes !== 'x'
+  e.ax.x.on = e.o.axes !== 'y'
+  root.dataset.scroll ??= ''
+  root.dataset.layout = e.o.bar.layout
+  root.dataset.show = e.o.bar.show
+  root.dataset.axes = e.o.axes
+  vp.dataset.touch = e.o.touch
+  writeVars(root, options.bar, e.reduced())
+  if (e.o.label) {
+    vp.setAttribute('role', 'region')
+    vp.setAttribute('aria-label', e.o.label)
+  }
+}
+
+/**
+ * As browsers treat scrollers: a tab stop only when nothing inside can take focus, and always focusable by a click so
+ * the keys work after one. Returns the check, to run again when the content changes.
+ */
+function focusable(vp: HTMLElement, hooks: (() => void)[]) {
+  if (vp.hasAttribute('tabindex')) return () => {}
+  hooks.push(() => vp.removeAttribute('tabindex'))
+  return () => {
+    vp.tabIndex = vp.querySelector(FOCUSABLE) ? -1 : 0
+  }
+}
+
+/** Measure again when the viewport, the content or a bar changes size, or the content is swapped. */
+function watch(s: Setup) {
+  const { e } = s
+  const ro = typeof ResizeObserver === 'function' ? new ResizeObserver(() => s.remeasure()) : null
+  const observe = () => {
+    ro?.disconnect()
+    ro?.observe(e.vp)
+    if (e.content) ro?.observe(e.content)
+    for (const a of e.axes) if (a.track) ro?.observe(a.track)
+  }
+  observe()
+  const mo =
+    typeof MutationObserver === 'function' && e.vp !== e.root
+      ? new MutationObserver(() => {
+          const next = e.vp.firstElementChild as HTMLElement | null
+          if (next === e.content) return
+          e.content = next
+          observe()
+          s.remeasure()
+        })
+      : null
+  mo?.observe(e.vp, { childList: true })
+  return {
+    observe,
+    stop: () => {
+      ro?.disconnect()
+      mo?.disconnect()
+    },
+  }
+}
+
+/** The browser's own scrolling, the pointer over the area, and the reduced-motion setting. */
+function listen({ e, vis, options }: Setup) {
+  let idle: ReturnType<typeof setTimeout> | undefined
+  // In native mode the browser's scroll has ended: rest on a snap point, as the engine does after its own input.
+  const settle = () => {
+    if (e.o.mode !== 'native') return
+    for (const a of e.axes) {
+      a.v = 0
+      e.settle(a.axis)
+    }
+  }
+  const ends = typeof window !== 'undefined' && 'onscrollend' in window
+  const onNative = () => {
+    if (e.dispatching) return
+    e.adopt()
+    if (ends) return
+    clearTimeout(idle)
+    idle = setTimeout(settle, 150)
+  }
+  const inside = (on: boolean) => () => {
+    vis.inside = on
+    vis.apply()
+  }
+  const enter = inside(true)
+  const leave = inside(false)
+  const motion = reduceQuery()
+  const onMotion = () => writeVars(e.root, options.bar, e.reduced())
+  e.vp.addEventListener('scroll', onNative, { passive: true })
+  e.vp.addEventListener('scrollend', settle)
+  e.root.addEventListener('pointerenter', enter)
+  e.root.addEventListener('pointerleave', leave)
+  motion?.addEventListener?.('change', onMotion)
+  return () => {
+    clearTimeout(idle)
+    e.vp.removeEventListener('scroll', onNative)
+    e.vp.removeEventListener('scrollend', settle)
+    e.root.removeEventListener('pointerenter', enter)
+    e.root.removeEventListener('pointerleave', leave)
+    motion?.removeEventListener?.('change', onMotion)
+  }
+}

package/src/snap.ts

@@ -0,0 +1,35 @@
+// Choosing the snap point a scroll comes to rest on. Pure: the points come in already measured.
+
+/**
+ * The point to rest at for a scroll that would end at `end`. `dir` (-1, 0, 1) is the way it was moving: a mandatory
+ * snap never pulls back against it once the scroll has passed a point. Returns `end` when nothing applies.
+ */
+export function snapTo(
+  points: readonly number[],
+  end: number,
+  o: { type?: 'mandatory' | 'proximity'; proximity?: number; dir?: number; max?: number } = {},
+) {
+  if (!points.length) return end
+  const max = o.max ?? Infinity
+  let best = end
+  let gap = Infinity
+  for (const raw of points) {
+    const p = Math.min(max, Math.max(0, raw))
+    const d = Math.abs(p - end)
+    if (d < gap) {
+      gap = d
+      best = p
+    }
+  }
+  if (o.type !== 'mandatory' && gap > (o.proximity ?? 120)) return end
+  return best
+}
+
+/** The next point past `from` in direction `dir`, for a key press or a wheel notch under mandatory snapping. */
+export function snapStep(points: readonly number[], from: number, dir: number, max: number) {
+  const sorted = [...new Set(points.map((p) => Math.min(max, Math.max(0, p))))].sort(
+    (a, b) => a - b,
+  )
+  if (dir > 0) return sorted.find((p) => p > from + 1) ?? Math.min(max, sorted.at(-1) ?? max)
+  return sorted.findLast((p) => p < from - 1) ?? Math.max(0, sorted[0] ?? 0)
+}