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

package/src/autoscroll.ts

@@ -0,0 +1,91 @@
+// Autoscroll: holding a text selection past the edge, or dragging something over the edge, scrolls toward it, faster
+// the further out the pointer is. The selection follows the content as it moves, as it does natively.
+import type { Engine } from './engine'
+import type { Axis } from './types'
+
+/** px per ms for a pointer `out` px past an edge. */
+export const autoSpeed = (out: number) =>
+  out ? Math.sign(out) * Math.min(4, Math.max(0.15, Math.abs(out) / 25)) : 0
+
+/** How far `p` is outside `[lo, hi]`, signed. */
+const outside = (p: number, lo: number, hi: number) => (p < lo ? p - lo : p > hi ? p - hi : 0)
+
+type CaretDoc = Document & {
+  caretPositionFromPoint?: (x: number, y: number) => { offsetNode: Node; offset: number } | null
+  caretRangeFromPoint?: (x: number, y: number) => Range | null
+}
+
+/** The caret under a point: Chrome and Firefox have the standard call, Safari the older one. */
+function caretAt(x: number, y: number) {
+  const doc = document as CaretDoc
+  const pos = doc.caretPositionFromPoint?.(x, y)
+  if (pos) return pos
+  const r = doc.caretRangeFromPoint?.(x, y)
+  return r ? { offsetNode: r.startContainer, offset: r.startOffset } : null
+}
+
+/** Listen for held selections and drags over the viewport. Returns the cleanup. */
+export function autoscroll(e: Engine) {
+  let point: { x: number; y: number } | null = null
+  const set = (axis: Axis, v: number) => e.auto(axis, e.o.autoscroll ? v : 0)
+  const halt = () => {
+    point = null
+    set('x', 0)
+    set('y', 0)
+  }
+  e.afterAuto = () => {
+    if (!point) return
+    const r = e.vp.getBoundingClientRect()
+    const x = Math.min(r.right - 2, Math.max(r.left + 2, point.x))
+    const y = Math.min(r.bottom - 2, Math.max(r.top + 2, point.y))
+    const sel = getSelection()
+    const at = caretAt(x, y)
+    if (sel && at && sel.rangeCount && e.vp.contains(at.offsetNode))
+      sel.extend(at.offsetNode, at.offset)
+  }
+
+  const move = (ev: PointerEvent) => {
+    if (!(ev.buttons & 1)) return up()
+    const sel = getSelection()
+    if (!sel || sel.isCollapsed) return (set('x', 0), set('y', 0))
+    const r = e.vp.getBoundingClientRect()
+    point = { x: ev.clientX, y: ev.clientY }
+    set('x', autoSpeed(outside(ev.clientX, r.left, r.right)))
+    set('y', autoSpeed(outside(ev.clientY, r.top, r.bottom)))
+  }
+  const up = () => {
+    halt()
+    removeEventListener('pointermove', move)
+    removeEventListener('pointerup', up)
+  }
+  const down = (ev: PointerEvent) => {
+    if (ev.pointerType !== 'mouse' || ev.button !== 0 || e.o.grab) return
+    addEventListener('pointermove', move)
+    addEventListener('pointerup', up)
+  }
+
+  let dragTimer: ReturnType<typeof setTimeout> | undefined
+  const over = (ev: DragEvent) => {
+    const r = e.vp.getBoundingClientRect()
+    const band = Math.min(40, r.height / 4, r.width / 4)
+    const edge = (p: number, lo: number, hi: number) =>
+      p < lo + band ? p - lo - band : p > hi - band ? p - hi + band : 0
+    point = null
+    set('x', autoSpeed(edge(ev.clientX, r.left, r.right)))
+    set('y', autoSpeed(edge(ev.clientY, r.top, r.bottom)))
+    clearTimeout(dragTimer)
+    dragTimer = setTimeout(halt, 150)
+  }
+
+  e.vp.addEventListener('pointerdown', down)
+  e.vp.addEventListener('dragover', over)
+  e.vp.addEventListener('drop', halt)
+  return () => {
+    clearTimeout(dragTimer)
+    up()
+    e.afterAuto = null
+    e.vp.removeEventListener('pointerdown', down)
+    e.vp.removeEventListener('dragover', over)
+    e.vp.removeEventListener('drop', halt)
+  }
+}

package/src/axis.ts

@@ -0,0 +1,59 @@
+// One axis of a scroller: where it is, how far it can go, what is animating it, and its bar's geometry.
+import type { Axis, Easing } from './types'
+
+export type Anim =
+  | { kind: 'tween'; from: number; to: number; start: number; dur: number; ease: Easing }
+  | { kind: 'coast'; v: number }
+  | { kind: 'spring'; x0: number; v0: number; start: number }
+  | { kind: 'auto'; v: number }
+
+/** One axis: positions are physical (`scrollLeft` runs negative in right-to-left content). */
+export interface AxisState {
+  axis: Axis
+  on: boolean
+  pos: number
+  written: number
+  min: number
+  max: number
+  view: number
+  total: number
+  over: number
+  v: number
+  anim: Anim | null
+  track: HTMLElement | null
+  trackLen: number
+  trackCross: number
+  thumbOff: number
+  thumbLen: number
+  grow: number
+  hover: boolean
+  active: boolean
+  drawn: string
+  aria: number
+  points: number[]
+}
+
+export const axisState = (axis: Axis): AxisState => ({
+  axis,
+  on: true,
+  pos: 0,
+  written: 0,
+  min: 0,
+  max: 0,
+  view: 0,
+  total: 0,
+  over: 0,
+  v: 0,
+  anim: null,
+  track: null,
+  trackLen: 0,
+  trackCross: 0,
+  thumbOff: 0,
+  thumbLen: 0,
+  grow: 0,
+  hover: false,
+  active: false,
+  drawn: '',
+  aria: -1,
+  points: [],
+})

package/src/bar-input.ts

@@ -0,0 +1,104 @@
+// Pointer input on the bars: drag the thumb, press the track to page (held, it repeats until the thumb reaches the
+// pointer) or to jump, and hover. Hit-testing uses the engine's geometry, so a canvas bar works the same as a DOM one.
+import { dragRatio, progressAt } from './bar'
+import type { AxisState, Engine } from './engine'
+import type { Visibility } from './render'
+import { pageStep } from './wheel'
+
+/** Listen on each bar's track. Returns the cleanup. */
+export function barInput(e: Engine, vis: Visibility) {
+  const offs: (() => void)[] = []
+  for (const a of e.axes) {
+    const track = a.track
+    if (!track) continue
+    const along = (ev: PointerEvent) => {
+      const r = track.getBoundingClientRect()
+      return a.axis === 'y' ? ev.clientY - r.top : ev.clientX - r.left
+    }
+    const hover = (on: boolean) => () => {
+      a.hover = on
+      vis.apply()
+      e.wake()
+    }
+    const enter = hover(true)
+    const leave = hover(false)
+    const down = (ev: PointerEvent) => {
+      if (ev.button !== 0) return
+      ev.preventDefault()
+      const at = along(ev)
+      const c = { e, vis, a, track, along }
+      if (at >= a.thumbOff && at <= a.thumbOff + a.thumbLen) drag(c, ev, at)
+      else press(c, ev, at)
+    }
+    track.addEventListener('pointerenter', enter)
+    track.addEventListener('pointerleave', leave)
+    track.addEventListener('pointerdown', down)
+    offs.push(() => {
+      track.removeEventListener('pointerenter', enter)
+      track.removeEventListener('pointerleave', leave)
+      track.removeEventListener('pointerdown', down)
+    })
+  }
+  return () => offs.forEach((f) => f())
+}
+
+/** One bar's pointer handling: the engine, its axis, the track and where a pointer is along it. */
+interface Bar {
+  e: Engine
+  vis: Visibility
+  a: AxisState
+  track: HTMLElement
+  along: (ev: PointerEvent) => number
+}
+
+function drag({ e, vis, a, track, along }: Bar, ev: PointerEvent, at: number) {
+  const start = a.pos
+  const ratio = dragRatio(a.trackLen, a.thumbLen, a.max - a.min)
+  track.setPointerCapture?.(ev.pointerId)
+  a.active = true
+  vis.apply()
+  const move = (m: PointerEvent) => e.moveTo(a.axis, start + (along(m) - at) * ratio, 'bar')
+  const up = () => {
+    a.active = false
+    vis.apply()
+    e.settle(a.axis)
+    e.wake()
+    track.removeEventListener('pointermove', move)
+    track.removeEventListener('pointerup', up)
+    track.removeEventListener('pointercancel', up)
+  }
+  track.addEventListener('pointermove', move)
+  track.addEventListener('pointerup', up)
+  track.addEventListener('pointercancel', up)
+}
+
+function press({ e, a, track, along }: Bar, ev: PointerEvent, at: number) {
+  const jump = (e.o.bar.trackClick === 'jump') !== ev.altKey
+  if (jump) {
+    const p = progressAt(a.trackLen, a.thumbLen, at - e.o.bar.inset)
+    return e.tweenTo(a.axis, a.min + p * (a.max - a.min), 'bar')
+  }
+  let pointer = at
+  const dir = at < a.thumbOff ? -1 : 1
+  const page = () => {
+    const before = pointer < a.thumbOff ? -1 : pointer > a.thumbOff + a.thumbLen ? 1 : 0
+    if (before === dir) e.tweenBy(a.axis, dir * pageStep(a.view), 'bar')
+    else stop()
+  }
+  let timer: ReturnType<typeof setTimeout> = setTimeout(function repeat() {
+    page()
+    timer = setTimeout(repeat, 60)
+  }, 350)
+  track.setPointerCapture?.(ev.pointerId)
+  const move = (m: PointerEvent) => (pointer = along(m))
+  const stop = () => {
+    clearTimeout(timer)
+    track.removeEventListener('pointermove', move)
+    track.removeEventListener('pointerup', stop)
+    track.removeEventListener('pointercancel', stop)
+  }
+  track.addEventListener('pointermove', move)
+  track.addEventListener('pointerup', stop)
+  track.addEventListener('pointercancel', stop)
+  e.tweenBy(a.axis, dir * pageStep(a.view), 'bar')
+}

package/src/bar.ts

@@ -0,0 +1,29 @@
+// Scrollbar geometry: how long the thumb is and where it sits, and the inverse for a drag. Pure.
+import type { ThumbOptions } from './types'
+
+/** The thumb's length for a `track` px track over a `view` px window into `total` px of content. */
+export function thumbLength(track: number, view: number, total: number, o: ThumbOptions = {}) {
+  if (track <= 0) return 0
+  if (o.size !== undefined) return Math.min(track, Math.max(0, o.size))
+  const min = Math.min(track, o.min ?? 24)
+  const max = Math.min(track, o.max ?? track)
+  const proportional = total > 0 ? (track * view) / total : track
+  return Math.max(min, Math.min(max, proportional))
+}
+
+/** The thumb's offset along the track for scroll `progress` 0..1. */
+export function thumbOffset(track: number, length: number, progress: number) {
+  return Math.max(0, track - length) * Math.min(1, Math.max(0, progress))
+}
+
+/** How many px of scroll one px of thumb drag moves. */
+export function dragRatio(track: number, length: number, max: number) {
+  const room = track - length
+  return room > 0 ? max / room : 0
+}
+
+/** The progress that centres the thumb on `at` px along the track: where a jump-click lands. */
+export function progressAt(track: number, length: number, at: number) {
+  const room = track - length
+  return room > 0 ? Math.min(1, Math.max(0, (at - length / 2) / room)) : 0
+}

package/src/canvas.ts

@@ -0,0 +1,111 @@
+// The canvas renderer: each bar paints into its own canvas, sized to the track at the device's pixel ratio. Colours
+// may be any CSS colour, `color-mix()` and `currentColor` included: they are resolved through the track's style.
+import { BAR_VARS } from './options'
+import type { BarFrame, Renderer } from './types'
+
+/** Paints one bar. `paint` is the default look, for a draw that adds to it rather than replacing it. */
+export type DrawBar = (
+  ctx: CanvasRenderingContext2D,
+  frame: BarFrame,
+  paint: (ctx: CanvasRenderingContext2D, frame: BarFrame) => void,
+) => void
+
+/** Options for the canvas renderer. */
+export interface CanvasOptions {
+  /** Your own painting. Default: rounded track and thumb in the bar's colours. */
+  draw?: DrawBar
+}
+
+interface Painted {
+  canvas: HTMLCanvasElement
+  ctx: CanvasRenderingContext2D
+  bar: BarFrame['bar'] | null
+  dark: boolean
+  colors: BarFrame['bar'] | null
+}
+const canvases = new WeakMap<HTMLElement, Painted>()
+const COLORS = ['color', 'hoverColor', 'activeColor', 'track', 'hoverTrack'] as const
+let scheme: MediaQueryList | null | undefined
+const dark = () =>
+  !!(scheme ??=
+    typeof matchMedia === 'function' ? matchMedia('(prefers-color-scheme: dark)') : null)?.matches
+
+/** A CSS colour as the canvas can take it: `color-mix()`, `currentColor` and `var()` resolve against `el`. */
+export function cssColor(el: HTMLElement, css: string) {
+  const probe = el.ownerDocument.createElement('i')
+  probe.style.cssText = `position:absolute;display:none`
+  probe.style.color = css
+  el.append(probe)
+  const out = getComputedStyle(probe).color || css
+  probe.remove()
+  return out
+}
+
+/** The bar's colours resolved once per options and colour scheme; the stylesheet's custom properties win. */
+function colors(track: HTMLElement, p: Painted, bar: BarFrame['bar']) {
+  if (p.colors && p.bar === bar && p.dark === dark()) return p.colors
+  const out = { ...bar }
+  for (const k of COLORS) out[k] = cssColor(track, `var(${BAR_VARS[k]}, ${bar[k]})`)
+  p.bar = bar
+  p.dark = dark()
+  p.colors = out
+  return out
+}
+
+/** The default look: the track (when it has a colour) and a rounded thumb that thickens on hover. */
+export function paintBar(ctx: CanvasRenderingContext2D, f: BarFrame) {
+  const { bar, thumb } = f
+  ctx.fillStyle = f.hover || f.active ? bar.hoverTrack : bar.track
+  ctx.fillRect(0, 0, f.track.width, f.track.height)
+  ctx.fillStyle = f.active ? bar.activeColor : f.hover ? bar.hoverColor : bar.color
+  const r = bar.radius * (Math.min(thumb.width, thumb.height) / bar.width)
+  ctx.beginPath()
+  ctx.roundRect(
+    thumb.x,
+    thumb.y,
+    thumb.width,
+    thumb.height,
+    Math.max(0, Math.min(r, thumb.width / 2, thumb.height / 2)),
+  )
+  ctx.fill()
+}
+
+/** A renderer that paints the bars on canvas. Pass it as `renderer`. */
+export function canvas(o: CanvasOptions = {}): Renderer {
+  return {
+    animates: true,
+    mount(track) {
+      const c = document.createElement('canvas')
+      c.dataset.part = 'canvas'
+      c.setAttribute('aria-hidden', 'true')
+      c.style.cssText =
+        'position:absolute;inset:0;inline-size:100%;block-size:100%;pointer-events:none'
+      track.querySelector('[data-part="thumb"]')?.setAttribute('hidden', '')
+      track.append(c)
+      const ctx = c.getContext('2d')
+      if (ctx) canvases.set(track, { canvas: c, ctx, bar: null, dark: false, colors: null })
+    },
+    draw(track, f) {
+      const got = canvases.get(track)
+      if (!got) return
+      const { canvas: c, ctx } = got
+      const frame = { ...f, bar: colors(track, got, f.bar) }
+      const dpr = globalThis.devicePixelRatio || 1
+      const w = Math.round(f.track.width * dpr)
+      const h = Math.round(f.track.height * dpr)
+      if (c.width !== w || c.height !== h) {
+        c.width = w
+        c.height = h
+      }
+      ctx.setTransform(dpr, 0, 0, dpr, 0, 0)
+      ctx.clearRect(0, 0, f.track.width, f.track.height)
+      if (o.draw) o.draw(ctx, frame, paintBar)
+      else paintBar(ctx, frame)
+    },
+    unmount(track) {
+      canvases.get(track)?.canvas.remove()
+      canvases.delete(track)
+      track.querySelector('[data-part="thumb"]')?.removeAttribute('hidden')
+    },
+  }
+}