@swiftbrowser/web 0.9.10 → 0.9.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swiftbrowser/web",
-  "version": "0.9.10",
+  "version": "0.9.11",
   "type": "module",
   "description": "SwiftBrowser web renderer and dev server: applies render ops from a Swift/Wasm app to the DOM inside an iPhone frame.",
   "repository": {

package/src/renderer.ts

@@ -151,7 +151,8 @@ import { VideoEvents, applyVideo, stopVideos } from './video';
 import { PinchController } from './pinch';
 import { applyCanvas, createCanvasElement } from './canvasDrawing';
 import { scrollToTarget } from './scrollTo';
-import { POSITION_SETTLE_MS, anchorPoint, positionTarget, type PositionCandidate } from './scrollPosition';
+import { POSITION_SETTLE_MS, POSITION_SNAP_WAITS, anchorPoint, positionTarget, restsOnSnapPoint, type PositionCandidate } from './scrollPosition';
+import { TouchPaging } from './touchPaging';
 import { applyDefaultScrollAnchor, keepScrollAnchors } from './scrollAnchor';
 import { EMPTY_CATALOG, assetColorVar, type AssetCatalog } from './assets';
 import { HIERARCHY_OPACITY, colorToCSS, effectsCSS, styleToCSS, type PaintCSS } from './styles';
@@ -396,6 +397,7 @@ export class Renderer {
   /** Text, links and files dragged in from outside the page (src/dragDrop.ts). */
   private readonly externalDrops: ExternalDrops;
   private readonly pinches: PinchController;
+  private readonly touchPaging: TouchPaging;
   /** `video` elements' media events, as `video` events (src/video.ts). */
   private readonly videoEvents: VideoEvents;
   private readonly measurer = new CanvasTextMeasurer();
@@ -884,6 +886,12 @@ export class Renderer {
     this.externalDrops = new ExternalDrops(host);
     // Two-finger gestures: MagnifyGesture and RotateGesture (src/pinch.ts).
     this.pinches = new PinchController(host);
+    // A finger on a paging scroll view pages it as iOS does (src/touchPaging.ts);
+    // the view it drives reports its position once the drive rests it on a page.
+    this.touchPaging = new TouchPaging(root, (el) => {
+      this.heldScrolls.delete(el);
+      this.armPositionReport(el);
+    });
     root.addEventListener('change', this.onChange);
     root.addEventListener('pointerdown', this.onSliderPointerDown);
     if (typeof ResizeObserver !== 'undefined') {
@@ -1588,6 +1596,7 @@ export class Renderer {
     this.pressEffects.dispose();
     this.externalDrops.dispose();
     this.pinches.dispose();
+    this.touchPaging.dispose();
     this.videoEvents.dispose();
     this.resizeObserver?.disconnect();
     this.hostObserver?.disconnect();
@@ -1711,11 +1720,14 @@ export class Renderer {
     }
   };
 
-  /** The last finger lifted: the held scroll views settle from here. */
+  /** The last finger lifted: the held scroll views settle from here (one the finger paged, once its run rests). */
   private readonly onPositionTouchEnd = (event: Event): void => {
     if ((event as TouchEvent).touches?.length > 0) return;
-    for (const el of this.heldScrolls) this.armPositionReport(el);
-    this.heldScrolls.clear();
+    for (const el of this.heldScrolls) {
+      if (this.touchPaging.drives(el)) continue;
+      this.heldScrolls.delete(el);
+      this.armPositionReport(el);
+    }
   };
 
   private armPositionReport(el: HTMLElement): void {
@@ -1731,9 +1743,13 @@ export class Renderer {
    * Which scroll target of a settled scroll view is at its anchor point: the
    * `scrollID` boxes inside it whose nearest scrolling ancestor it is, along
    * the axis it scrolls on (the vertical one when it scrolls both ways). Sent
-   * to that target when it is not the one reported last.
+   * to that target when it is not the one reported last. A snapping scroll
+   * view that settled off its snap points is still between a gesture and
+   * the browser's snap animation: it waits (a bounded number of settles)
+   * until the animation has carried it onto one, so the target reported is
+   * the page the browser chose, never one passing by mid-snap.
    */
-  private reportPosition(el: HTMLElement): void {
+  private reportPosition(el: HTMLElement, waited = 0): void {
     const pending = this.positionTimers.get(el);
     if (pending !== undefined) window.clearTimeout(pending);
     this.positionTimers.delete(el);
@@ -1743,7 +1759,8 @@ export class Renderer {
     const anchor = node.props['positionAnchor'] as { x?: unknown; y?: unknown } | undefined;
     const fraction = horizontal ? anchor?.x : anchor?.y;
     const box = el.getBoundingClientRect();
-    const point = anchorPoint(horizontal ? { start: box.left, length: box.width } : { start: box.top, length: box.height }, typeof fraction === 'number' ? fraction : 0);
+    const viewport = horizontal ? { start: box.left, length: box.width } : { start: box.top, length: box.height };
+    const point = anchorPoint(viewport, typeof fraction === 'number' ? fraction : 0);
     const candidates: PositionCandidate[] = [];
     for (const target of el.querySelectorAll<HTMLElement>('[data-sb-id]')) {
       const id = Number(target.dataset[ID_ATTR]);
@@ -1752,6 +1769,19 @@ export class Renderer {
       const rect = target.getBoundingClientRect();
       candidates.push(horizontal ? { id, start: rect.left, length: rect.width } : { id, start: rect.top, length: rect.height });
     }
+    if (el.dataset['sbSnap'] !== undefined && waited < POSITION_SNAP_WAITS) {
+      const computed = getComputedStyle(el);
+      const padding = parseFloat(horizontal ? computed.scrollPaddingLeft : computed.scrollPaddingTop) || 0;
+      const offset = horizontal ? el.scrollLeft : el.scrollTop;
+      const max = horizontal ? el.scrollWidth - el.clientWidth : el.scrollHeight - el.clientHeight;
+      if (!restsOnSnapPoint(candidates, viewport.start + padding, viewport.length, offset, max)) {
+        this.positionTimers.set(
+          el,
+          window.setTimeout(() => this.reportPosition(el, waited + 1), POSITION_SETTLE_MS),
+        );
+        return;
+      }
+    }
     const target = positionTarget(candidates, point);
     if (target === null || this.reportedPositions.get(el) === target) return;
     this.reportedPositions.set(el, target);

package/src/scrollPosition.ts

@@ -17,6 +17,37 @@ export interface PositionCandidate {
 /** A settled scroll is one with no `scroll` event for this long (`scrollend`, where the browser has it, ends the wait). */
 export const POSITION_SETTLE_MS = 120;
 
+/**
+ * A snapping scroll view that settles off its snap points is between a
+ * gesture and the browser's snap animation (a trackpad swipe ended, the
+ * snap not yet begun): it waits this many settles more for the animation
+ * to carry it onto one before reporting where it is.
+ */
+export const POSITION_SNAP_WAITS = 6;
+
+/** How far from a snap point still counts as on it (subpixel scroll offsets). */
+const SNAP_TOLERANCE = 1;
+
+/**
+ * Whether a snapping scroll view (`scrollTargetBehavior`) is at rest on a
+ * snap point, so that the target at its anchor is the one the browser
+ * chose rather than one passing by mid-snap: a target starts at the
+ * snapport's start (`start` is the viewport's start plus its scroll
+ * padding), or a target longer than the viewport covers the whole of it
+ * (the browser lets the view rest anywhere such a target fills), or the
+ * view is at either end of its range (the last snap point may be out of
+ * reach).
+ */
+export function restsOnSnapPoint(candidates: readonly PositionCandidate[], start: number, viewportLength: number, offset: number, maxOffset: number): boolean {
+  if (offset <= SNAP_TOLERANCE || offset >= maxOffset - SNAP_TOLERANCE) return true;
+  for (const c of candidates) {
+    if (c.length <= 0) continue;
+    if (Math.abs(c.start - start) <= SNAP_TOLERANCE) return true;
+    if (c.start <= start + SNAP_TOLERANCE && c.start + c.length >= start + viewportLength - SNAP_TOLERANCE && c.length > viewportLength + SNAP_TOLERANCE) return true;
+  }
+  return false;
+}
+
 /**
  * The target at `point` along the axis: the one whose extent holds the point
  * (the last of several, as a later sibling draws over an earlier one), else

package/src/styles.css

@@ -740,6 +740,17 @@ svg[data-sb-symbol="progress.indicator"] > line:nth-child(8) { animation-delay:
   scroll-snap-stop: always;
 }
 
+/* A finger pages a paging scroll view as iOS does (src/touchPaging.ts): the
+   browser keeps off its axis and the page drives the offset; a pan along
+   the other axis still scrolls what the view sits in. */
+.sb-scrollview[data-sb-snap="paging"][data-sb-axes="horizontal"] {
+  touch-action: pan-y pinch-zoom;
+}
+
+.sb-scrollview[data-sb-snap="paging"][data-sb-axes="vertical"] {
+  touch-action: pan-x pinch-zoom;
+}
+
 .sb-scroll-content,
 .sb-list-content {
   position: relative;

package/src/touchPaging.ts

@@ -0,0 +1,286 @@
+/**
+ * iOS paging under a finger for `.scrollTargetBehavior(.paging)`
+ * (docs/ops-protocol.md, "Scroll targets"). A `UIScrollView` with paging
+ * follows the finger and, when it lifts, goes one page in the direction of
+ * a flick however short the drag was, or to the nearest page from a slow
+ * release (half a page across is the next page), with its own deceleration.
+ * CSS scroll snapping chooses by the projected end of the fling instead, so
+ * a short flick in Safari and Chrome falls back to the page it left. On a
+ * touch device the browser is kept off the paging axis (`touch-action` in
+ * styles.css) and this controller drives the scroll offset: 1:1 with the
+ * finger, then an eased run to the page `pagingDestination` chooses. Wheel
+ * and trackpad scrolling stay native, snapped by CSS.
+ */
+
+/** A lift moving at least this fast (px per ms) is a flick: one page on in its direction. */
+export const FLICK_VELOCITY = 0.3;
+/** The finger's velocity is measured over its last moves within this window; a pause before the lift is no flick. */
+export const FLICK_WINDOW_MS = 100;
+/** How far a flick carries on inside a page longer than the viewport (its velocity times this). */
+export const FLICK_RUN_MS = 250;
+/** A touch is a drag once it moved this far; the larger axis then decides whose gesture it is. */
+export const DIRECTION_SLOP = 6;
+
+/** Where a scroll view may rest for one page: at its start, or anywhere a page longer than the viewport fills it (`start === end` for a page the viewport's size). */
+export interface RestInterval {
+  start: number;
+  end: number;
+}
+
+export interface TouchSample {
+  t: number;
+  pos: number;
+}
+
+/** The rest intervals of pages (offsets along the axis in scroll coordinates), in order; pages of no length are left out. */
+export function restIntervals(pages: readonly { start: number; length: number }[], viewportLength: number, maxOffset: number): RestInterval[] {
+  const clamp = (v: number) => Math.min(maxOffset, Math.max(0, v));
+  return pages
+    .filter((p) => p.length > 0)
+    .map((p) => ({ start: clamp(p.start), end: clamp(Math.max(p.start, p.start + p.length - viewportLength)) }))
+    .sort((a, b) => a.start - b.start);
+}
+
+/**
+ * The finger's velocity (px per ms) at the lift from its last moves: the
+ * change over the samples inside the window before `now`; zero after a
+ * pause longer than the window, or with fewer than two samples in it.
+ */
+export function flickVelocity(samples: readonly TouchSample[], now: number): number {
+  const recent = samples.filter((s) => now - s.t <= FLICK_WINDOW_MS);
+  if (recent.length < 2) return 0;
+  const first = recent[0]!;
+  const last = recent[recent.length - 1]!;
+  if (last.t <= first.t) return 0;
+  return (last.pos - first.pos) / (last.t - first.t);
+}
+
+/**
+ * The offset to run to when the finger lifts at `offset` with the scroll
+ * offset changing at `velocity` (px per ms, positive toward later pages).
+ * A flick goes one page on in its direction, from the page the offset is
+ * on; inside a page longer than the viewport it runs on as far as its
+ * momentum carries, to the page's edge at most. A slow release goes to
+ * the nearest rest: for pages the viewport's size, the page more than
+ * half across.
+ */
+export function pagingDestination(offset: number, velocity: number, intervals: readonly RestInterval[], maxOffset: number): number {
+  const clamp = (v: number) => Math.min(maxOffset, Math.max(0, v));
+  if (intervals.length === 0) return clamp(offset);
+  if (velocity >= FLICK_VELOCITY) {
+    // The page the offset is on: the last starting at or before it.
+    let at = 0;
+    for (let i = 0; i < intervals.length; i++) if (intervals[i]!.start <= offset + 1) at = i;
+    const page = intervals[at]!;
+    if (offset < page.end - 1) return clamp(Math.min(offset + velocity * FLICK_RUN_MS, page.end));
+    const next = intervals[at + 1];
+    return clamp(next ? next.start : page.end);
+  }
+  if (velocity <= -FLICK_VELOCITY) {
+    // The page the offset is on: the first ending at or after it.
+    let at = intervals.length - 1;
+    for (let i = intervals.length - 1; i >= 0; i--) if (intervals[i]!.end >= offset - 1) at = i;
+    const page = intervals[at]!;
+    if (offset > page.start + 1) return clamp(Math.max(offset + velocity * FLICK_RUN_MS, page.start));
+    const previous = intervals[at - 1];
+    return clamp(previous ? previous.end : page.start);
+  }
+  let best = offset;
+  let distance = Infinity;
+  for (const i of intervals) {
+    const rest = Math.min(i.end, Math.max(i.start, offset));
+    const d = Math.abs(offset - rest);
+    if (d < distance) {
+      distance = d;
+      best = rest;
+    }
+  }
+  return clamp(best);
+}
+
+/** The eased run to a page: ease-out, 200...450 ms by distance. */
+export function runDuration(distance: number): number {
+  return Math.min(450, 200 + Math.abs(distance) * 0.3);
+}
+
+export function easeOut(t: number): number {
+  const u = 1 - Math.min(1, Math.max(0, t));
+  return 1 - u * u * u;
+}
+
+interface Gesture {
+  el: HTMLElement;
+  horizontal: boolean;
+  startX: number;
+  startY: number;
+  /** Null until the drag passed the slop; then whether it is ours (along the paging axis) or the browser's. */
+  ours: boolean | null;
+  /** The scroll offset where our drag took over. */
+  from: number;
+  /** The finger position (along the axis) where our drag took over. */
+  fromPos: number;
+  samples: TouchSample[];
+}
+
+interface Run {
+  el: HTMLElement;
+  frame: number;
+  /** The offset the last frame wrote: another writer moving the view ends the run. */
+  written: number;
+}
+
+const PAGING_SELECTOR = '.sb-scrollview[data-sb-snap="paging"]';
+
+/** Pages of a paging scroll view in scroll coordinates along its axis: the children of its `scrollTargetLayout` stack, else of its content. */
+export function pagesOf(el: HTMLElement, horizontal: boolean): { start: number; length: number }[] {
+  const targets = [...el.querySelectorAll<HTMLElement>('[data-sb-scroll-target] > *')].filter((t) => t.parentElement?.closest('.sb-scrollview, .sb-list') === el);
+  const children = targets.length > 0 ? targets : [...((el.firstElementChild?.children ?? []) as Iterable<Element>)];
+  const box = el.getBoundingClientRect();
+  const computed = getComputedStyle(el);
+  const padding = parseFloat(horizontal ? computed.scrollPaddingLeft : computed.scrollPaddingTop) || 0;
+  const offset = horizontal ? el.scrollLeft : el.scrollTop;
+  return children.map((child) => {
+    const rect = child.getBoundingClientRect();
+    return horizontal ? { start: rect.left - box.left - padding + offset, length: rect.width } : { start: rect.top - box.top - padding + offset, length: rect.height };
+  });
+}
+
+export class TouchPaging {
+  private gesture: Gesture | null = null;
+  private run: Run | null = null;
+
+  /**
+   * `onRest(el)`: the view came to rest on a page after a gesture of ours
+   * (the renderer reports its position then; while a drive is on, a
+   * `scrollend` the browser fires for a frame's write is no settling).
+   */
+  constructor(
+    private readonly root: HTMLElement,
+    private readonly onRest: (el: HTMLElement) => void = () => {},
+  ) {
+    root.addEventListener('touchstart', this.onTouchStart, { passive: true });
+    root.addEventListener('touchmove', this.onTouchMove, { passive: true });
+    root.addEventListener('touchend', this.onTouchEnd, { passive: true });
+    root.addEventListener('touchcancel', this.onTouchEnd, { passive: true });
+  }
+
+  /** Whether a finger's drag along the paging axis, or the run after it, is moving `el`. */
+  drives(el: HTMLElement): boolean {
+    return (this.gesture?.el === el && this.gesture.ours === true) || this.run?.el === el;
+  }
+
+  dispose(): void {
+    this.root.removeEventListener('touchstart', this.onTouchStart);
+    this.root.removeEventListener('touchmove', this.onTouchMove);
+    this.root.removeEventListener('touchend', this.onTouchEnd);
+    this.root.removeEventListener('touchcancel', this.onTouchEnd);
+    this.stopRun();
+  }
+
+  private readonly onTouchStart = (event: TouchEvent): void => {
+    this.gesture = null;
+    const touch = event.touches[0];
+    if (!touch || event.touches.length !== 1 || !(event.target instanceof Element)) return;
+    const el = event.target.closest<HTMLElement>(PAGING_SELECTOR);
+    if (!el) return;
+    const axes = el.dataset['sbAxes'];
+    if (axes !== 'horizontal' && axes !== 'vertical') return;
+    const horizontal = axes === 'horizontal';
+    this.gesture = { el, horizontal, startX: touch.clientX, startY: touch.clientY, ours: null, from: 0, fromPos: 0, samples: [] };
+    // A finger on a page still running to its place catches it: the drag is
+    // ours from here, and the lift runs it on to a page.
+    if (this.run?.el === el) {
+      this.stopRun();
+      this.gesture.ours = true;
+      this.gesture.from = horizontal ? el.scrollLeft : el.scrollTop;
+      this.gesture.fromPos = horizontal ? touch.clientX : touch.clientY;
+      el.style.scrollSnapType = 'none';
+    }
+  };
+
+  private readonly onTouchMove = (event: TouchEvent): void => {
+    const g = this.gesture;
+    const touch = event.touches[0];
+    if (!g || !touch) return;
+    const pos = g.horizontal ? touch.clientX : touch.clientY;
+    if (g.ours === null) {
+      const dx = touch.clientX - g.startX;
+      const dy = touch.clientY - g.startY;
+      if (Math.abs(dx) < DIRECTION_SLOP && Math.abs(dy) < DIRECTION_SLOP) return;
+      g.ours = g.horizontal ? Math.abs(dx) >= Math.abs(dy) : Math.abs(dy) > Math.abs(dx);
+      if (!g.ours) {
+        this.gesture = null;
+        return;
+      }
+      // Ours: the snap is off while the offset follows the finger (a snapping
+      // container snaps every offset it is given), back on once it rests.
+      g.el.style.scrollSnapType = 'none';
+      g.from = g.horizontal ? g.el.scrollLeft : g.el.scrollTop;
+      g.fromPos = pos;
+    }
+    const max = g.horizontal ? g.el.scrollWidth - g.el.clientWidth : g.el.scrollHeight - g.el.clientHeight;
+    const offset = Math.min(max, Math.max(0, g.from - (pos - g.fromPos)));
+    if (g.horizontal) g.el.scrollLeft = offset;
+    else g.el.scrollTop = offset;
+    g.samples.push({ t: event.timeStamp, pos });
+    if (g.samples.length > 20) g.samples.shift();
+  };
+
+  private readonly onTouchEnd = (event: TouchEvent): void => {
+    const g = this.gesture;
+    if (!g) return;
+    if (event.touches.length > 0) return;
+    this.gesture = null;
+    if (!g.ours) return;
+    const el = g.el;
+    const max = g.horizontal ? el.scrollWidth - el.clientWidth : el.scrollHeight - el.clientHeight;
+    const offset = g.horizontal ? el.scrollLeft : el.scrollTop;
+    // The finger's velocity, as the offset's: a finger moving back moves the content on.
+    const velocity = event.type === 'touchcancel' ? 0 : -flickVelocity(g.samples, event.timeStamp);
+    const viewport = g.horizontal ? el.clientWidth : el.clientHeight;
+    const destination = pagingDestination(offset, velocity, restIntervals(pagesOf(el, g.horizontal), viewport, max), max);
+    this.runTo(el, g.horizontal, offset, destination);
+  };
+
+  /** Runs the offset to `to` with an ease-out, then lets the container snap again. */
+  private runTo(el: HTMLElement, horizontal: boolean, from: number, to: number): void {
+    this.stopRun();
+    const distance = to - from;
+    if (Math.abs(distance) < 0.5) {
+      el.style.scrollSnapType = '';
+      this.onRest(el);
+      return;
+    }
+    const duration = runDuration(distance);
+    const started = performance.now();
+    const step = (now: number): void => {
+      const run = this.run;
+      const current = horizontal ? el.scrollLeft : el.scrollTop;
+      // Another writer moved the view (an app re-centring on the page): the run is over.
+      if (run && Math.abs(current - run.written) > 1) {
+        this.stopRun();
+        this.onRest(el);
+        return;
+      }
+      const t = (now - started) / duration;
+      const offset = t >= 1 ? to : from + distance * easeOut(t);
+      if (horizontal) el.scrollLeft = offset;
+      else el.scrollTop = offset;
+      if (t >= 1) {
+        this.run = null;
+        el.style.scrollSnapType = '';
+        this.onRest(el);
+        return;
+      }
+      this.run = { el, frame: requestAnimationFrame(step), written: offset };
+    };
+    this.run = { el, frame: requestAnimationFrame(step), written: from };
+  }
+
+  private stopRun(): void {
+    if (!this.run) return;
+    cancelAnimationFrame(this.run.frame);
+    this.run.el.style.scrollSnapType = '';
+    this.run = null;
+  }
+}