@voila.dev/motion 0.0.0-stage → 5.0.113

package/src/view/scroll-measure.ts

@@ -0,0 +1,83 @@
+import type { ScrollGeometry } from "#/view/scroll-offset.ts";
+
+export type ScrollAxis = "x" | "y";
+
+interface AxisKeys {
+	readonly scroll: "scrollTop" | "scrollLeft";
+	readonly scrollLength: "scrollHeight" | "scrollWidth";
+	readonly client: "clientHeight" | "clientWidth";
+	readonly clientStart: "clientTop" | "clientLeft";
+	readonly rectStart: "top" | "left";
+	readonly rectLength: "height" | "width";
+}
+
+const AXES: Readonly<Record<ScrollAxis, AxisKeys>> = {
+	y: {
+		scroll: "scrollTop",
+		scrollLength: "scrollHeight",
+		client: "clientHeight",
+		clientStart: "clientTop",
+		rectStart: "top",
+		rectLength: "height",
+	},
+	x: {
+		scroll: "scrollLeft",
+		scrollLength: "scrollWidth",
+		client: "clientWidth",
+		clientStart: "clientLeft",
+		rectStart: "left",
+		rectLength: "width",
+	},
+};
+
+/** The page's own scroller, which reports its scroll events on `window`. */
+export function documentScroller(): Element {
+	return document.scrollingElement ?? document.documentElement;
+}
+
+export interface ScrollMeasurement {
+	readonly scroll: number;
+	/** The furthest the container can scroll along the axis. */
+	readonly scrollLength: number;
+	readonly geometry: ScrollGeometry;
+}
+
+/**
+ * Reads layout, so it belongs in the frame's read phase only. Without a
+ * target, the target is the scrolled content itself.
+ */
+export function measureScroll(
+	container: Element,
+	axis: ScrollAxis,
+	target: Element | undefined,
+): ScrollMeasurement {
+	const keys = AXES[axis];
+	const scroll = container[keys.scroll];
+	const viewportLength = container[keys.client];
+	const contentLength = container[keys.scrollLength];
+	const scrollLength = Math.max(0, contentLength - viewportLength);
+	if (target === undefined) {
+		return {
+			scroll,
+			scrollLength,
+			geometry: { targetStart: 0, targetLength: contentLength, viewportLength },
+		};
+	}
+	// The page scroller's own rect moves with its scroll; its scrollport is
+	// the viewport, which starts at 0.
+	const scrollportStart =
+		container === documentScroller()
+			? 0
+			: container.getBoundingClientRect()[keys.rectStart] +
+				container[keys.clientStart];
+	const targetRect = target.getBoundingClientRect();
+	return {
+		scroll,
+		scrollLength,
+		geometry: {
+			targetStart: targetRect[keys.rectStart] - scrollportStart + scroll,
+			targetLength: targetRect[keys.rectLength],
+			viewportLength,
+		},
+	};
+}

package/src/view/scroll-offset.ts

@@ -0,0 +1,100 @@
+/**
+ * Where a scroll animation starts and ends, as Motion writes it: each offset
+ * is "<target edge> <container edge>", the scroll position at which that
+ * point of the target meets that point of the scrollport. "start end" is the
+ * target's top touching the viewport's bottom.
+ */
+export type ScrollEdge =
+	| "start"
+	| "center"
+	| "end"
+	| number
+	| `${number}px`
+	| `${number}%`;
+
+export type ScrollOffsetPoint =
+	| `${string} ${string}`
+	| readonly [ScrollEdge, ScrollEdge];
+
+export type ScrollOffset = readonly [ScrollOffsetPoint, ScrollOffsetPoint];
+
+/** The target crossing the scrollport, from first pixel in to last pixel out. */
+export const ENTER_TO_EXIT: ScrollOffset = ["start end", "end start"];
+/** The whole scroll range, when there is no target. */
+export const FULL_RANGE: ScrollOffset = ["start start", "end end"];
+
+const NAMED_EDGES: Readonly<Record<string, number>> = {
+	start: 0,
+	center: 0.5,
+	end: 1,
+};
+
+/** An edge as pixels along a length: named and bare numbers are fractions. */
+export function resolveEdge(edge: ScrollEdge, length: number): number {
+	if (typeof edge === "number") {
+		return edge * length;
+	}
+	const named = NAMED_EDGES[edge];
+	if (named !== undefined) {
+		return named * length;
+	}
+	const value = Number.parseFloat(edge);
+	if (Number.isNaN(value)) {
+		throw new Error(`Unknown scroll edge: ${edge}`);
+	}
+	if (edge.endsWith("%")) {
+		return (value / 100) * length;
+	}
+	return edge.endsWith("px") ? value : value * length;
+}
+
+export function parseOffsetPoint(
+	point: ScrollOffsetPoint,
+): readonly [ScrollEdge, ScrollEdge] {
+	if (typeof point !== "string") {
+		return point;
+	}
+	const [target, container = target] = point.trim().split(/\s+/);
+	return [parseEdge(target), parseEdge(container)];
+}
+
+function parseEdge(text: string): ScrollEdge {
+	return text in NAMED_EDGES || /[a-z%]$/.test(text)
+		? (text as ScrollEdge)
+		: Number(text);
+}
+
+export interface ScrollGeometry {
+	/** The target's start along the axis, in the container's content coordinates. */
+	readonly targetStart: number;
+	readonly targetLength: number;
+	/** The scrollport's visible length. */
+	readonly viewportLength: number;
+}
+
+/** The scroll position at which one offset point is reached. */
+export function offsetPosition(
+	point: ScrollOffsetPoint,
+	geometry: ScrollGeometry,
+): number {
+	const [target, container] = parseOffsetPoint(point);
+	return (
+		geometry.targetStart +
+		resolveEdge(target, geometry.targetLength) -
+		resolveEdge(container, geometry.viewportLength)
+	);
+}
+
+/** Progress 0..1 of `scroll` between the two offsets, clamped. */
+export function scrollProgress(
+	scroll: number,
+	offset: ScrollOffset,
+	geometry: ScrollGeometry,
+): number {
+	const from = offsetPosition(offset[0], geometry);
+	const to = offsetPosition(offset[1], geometry);
+	if (to === from) {
+		return scroll >= to ? 1 : 0;
+	}
+	return Math.min(1, Math.max(0, (scroll - from) / (to - from)));
+}

package/src/view/scroll.ts

@@ -0,0 +1,143 @@
+import { cancelFrame, frame } from "#/frame/frame.ts";
+import { resize } from "#/view/resize.ts";
+import {
+	documentScroller,
+	measureScroll,
+	type ScrollAxis,
+} from "#/view/scroll-measure.ts";
+import {
+	ENTER_TO_EXIT,
+	FULL_RANGE,
+	type ScrollOffset,
+	scrollProgress,
+} from "#/view/scroll-offset.ts";
+
+/** What `animate()` returns, seen from the scroll side. */
+export interface ScrollDrivable {
+	time: number;
+	readonly duration: number;
+	/** Hands the native timeline to WAAPI animations; false when it can't (JS-driven). */
+	attachTimeline?(timeline: AnimationTimeline): boolean;
+	/** Scroll alone moves it once driven: its own clock must stop. */
+	pause?(): void;
+}
+
+export interface ScrollInfo {
+	readonly progress: number;
+	/** Pixels scrolled along the axis. */
+	readonly scroll: number;
+	/** The furthest the container can scroll along the axis. */
+	readonly scrollLength: number;
+	readonly axis: ScrollAxis;
+}
+
+export interface ScrollOptions {
+	/** The scrolling element; the page by default. */
+	readonly container?: Element;
+	/** Track this element crossing the container instead of the whole scroll range. */
+	readonly target?: Element;
+	readonly axis?: ScrollAxis;
+	readonly offset?: ScrollOffset;
+}
+
+export type OnScroll = (progress: number, info: ScrollInfo) => void;
+
+type TimelineConstructor = new (options: object) => AnimationTimeline;
+
+function sameOffset(a: ScrollOffset, b: ScrollOffset): boolean {
+	return String(a[0]) === String(b[0]) && String(a[1]) === String(b[1]);
+}
+
+/**
+ * The browser's own timeline, which runs the animation off the main thread.
+ * Only for the offsets a bare timeline means by itself: the full range for
+ * a ScrollTimeline, enter-to-exit ("cover") for a ViewTimeline.
+ */
+function nativeTimeline(
+	container: Element,
+	axis: ScrollAxis,
+	target: Element | undefined,
+	offset: ScrollOffset,
+): AnimationTimeline | undefined {
+	const scope = globalThis as unknown as Record<string, TimelineConstructor>;
+	const Timeline = target ? scope.ViewTimeline : scope.ScrollTimeline;
+	const expected = target ? ENTER_TO_EXIT : FULL_RANGE;
+	if (Timeline === undefined || !sameOffset(offset, expected)) {
+		return undefined;
+	}
+	return target
+		? new Timeline({ subject: target, axis })
+		: new Timeline({ source: container, axis });
+}
+
+/**
+ * Drives a callback, or an animation's time, from scroll progress. Returns a
+ * function that stops listening.
+ */
+export function scroll(
+	onScroll: OnScroll | ScrollDrivable,
+	options: ScrollOptions = {},
+): () => void {
+	const container = options.container ?? documentScroller();
+	const axis = options.axis ?? "y";
+	const target = options.target;
+	const offset = options.offset ?? (target ? ENTER_TO_EXIT : FULL_RANGE);
+
+	if (typeof onScroll !== "function" && onScroll.attachTimeline) {
+		const timeline = nativeTimeline(container, axis, target, offset);
+		if (timeline && onScroll.attachTimeline(timeline)) {
+			return () => {};
+		}
+	}
+
+	if (typeof onScroll !== "function") onScroll.pause?.();
+	const apply: OnScroll =
+		typeof onScroll === "function"
+			? onScroll
+			: (progress) => {
+					onScroll.time = progress * onScroll.duration;
+				};
+	let info: ScrollInfo | undefined;
+	let scheduled = false;
+
+	function update() {
+		if (info) {
+			apply(info.progress, info);
+		}
+	}
+	function measure() {
+		scheduled = false;
+		const measured = measureScroll(container, axis, target);
+		info = {
+			progress: scrollProgress(measured.scroll, offset, measured.geometry),
+			scroll: measured.scroll,
+			scrollLength: measured.scrollLength,
+			axis,
+		};
+		frame.update(update);
+	}
+	function schedule() {
+		if (!scheduled) {
+			scheduled = true;
+			frame.read(measure);
+		}
+	}
+
+	// The page scroller fires its scroll events on window, not on itself.
+	const eventSource: EventTarget =
+		container === documentScroller() ? window : container;
+	eventSource.addEventListener("scroll", schedule, { passive: true });
+	const stopResize = [
+		resize(schedule),
+		resize(target ? [container, target] : [container], schedule),
+	];
+	schedule();
+	return () => {
+		eventSource.removeEventListener("scroll", schedule);
+		for (const stop of stopResize) {
+			stop();
+		}
+		cancelFrame(measure);
+		cancelFrame(update);
+	};
+}