@anyknown/axis 0.0.0-stage → 0.2.1

package/dist/axis/create-hold.js

@@ -0,0 +1,38 @@
+export function createHold(el) {
+    let held = null;
+    let yielded = false;
+    const holdCurrent = () => {
+        held = { x: el.scrollLeft, y: el.scrollTop };
+    };
+    return {
+        holdCurrent,
+        release() {
+            held = null;
+        },
+        reset() {
+            held = null;
+            yielded = false;
+        },
+        yieldDrag(glideHoldsAtItsEnd) {
+            yielded = true;
+            if (!glideHoldsAtItsEnd)
+                holdCurrent();
+        },
+        holdIfYielded() {
+            if (yielded)
+                holdCurrent();
+        },
+        follow(axis) {
+            if (held)
+                held[axis] = axis === "x" ? el.scrollLeft : el.scrollTop;
+        },
+        undoAutoscroll() {
+            if (!held)
+                return;
+            if (Math.abs(el.scrollLeft - held.x) >= 1)
+                el.scrollLeft = held.x;
+            if (Math.abs(el.scrollTop - held.y) >= 1)
+                el.scrollTop = held.y;
+        },
+    };
+}

package/dist/axis/create-scroll-driver.d.ts

@@ -0,0 +1,2 @@
+import type { AxisCore, Hold, ScrollDriver, SnapSuspension } from "./types.js";
+export declare function createScrollDriver(core: AxisCore, snap: SnapSuspension, hold: Hold): ScrollDriver;

package/dist/axis/create-scroll-driver.js

@@ -0,0 +1,139 @@
+import { clamp, easeOutCubic, glideDuration, MIN_VELOCITY, capVelocity, momentumDistance, momentumStep, nearestSnap, prefersReducedMotion, } from "../utils/index.js";
+import { AXES, MAX_FRAME_MS, WHEEL_SETTLE_MS } from "./constants.js";
+import { dragsAlong } from "./drags-along.js";
+export function createScrollDriver(core, snap, hold) {
+    const { win, rtl, scrollRange, position, writePosition, options, motion, setMotion, isDestroyed } = core;
+    const { suspend, resume, snapAxes } = snap;
+    let frame = 0;
+    let wheelTimer = 0;
+    let glideTarget = { x: 0, y: 0 };
+    const stop = () => {
+        hold.release();
+        if (frame)
+            win.cancelAnimationFrame(frame);
+        frame = 0;
+        win.clearTimeout(wheelTimer);
+        wheelTimer = 0;
+    };
+    const settle = () => {
+        stop();
+        hold.holdIfYielded();
+        resume();
+        setMotion("idle");
+    };
+    const jump = (target) => {
+        stop();
+        suspend();
+        writePosition(target);
+        settle();
+    };
+    const glideTo = (target, velocity, kind) => {
+        stop();
+        const isRtlNow = rtl();
+        const from = position(isRtlNow);
+        const moving = AXES.filter((axis) => target[axis] !== undefined && Math.abs(target[axis] - from[axis]) >= 0.5);
+        if (moving.length === 0 || prefersReducedMotion(win)) {
+            jump(target);
+            return;
+        }
+        suspend();
+        glideTarget = { x: target.x ?? from.x, y: target.y ?? from.y };
+        const distance = { x: glideTarget.x - from.x, y: glideTarget.y - from.y };
+        const duration = Math.max(...moving.map((axis) => glideDuration(distance[axis], velocity[axis])));
+        const start = win.performance.now();
+        setMotion(kind);
+        if (isDestroyed())
+            return;
+        const tick = (now) => {
+            if (isDestroyed())
+                return;
+            const eased = easeOutCubic(clamp((now - start) / duration, 0, 1));
+            const next = {};
+            for (const axis of moving)
+                next[axis] = from[axis] + distance[axis] * eased;
+            writePosition(next, isRtlNow);
+            if (eased < 1)
+                frame = win.requestAnimationFrame(tick);
+            else
+                settle();
+        };
+        frame = win.requestAnimationFrame(tick);
+    };
+    const runMomentum = (velocity) => {
+        stop();
+        suspend();
+        setMotion("momentum");
+        if (isDestroyed())
+            return;
+        const isRtlNow = rtl();
+        const max = scrollRange();
+        const current = position(isRtlNow, max);
+        const speed = { ...velocity };
+        let last = win.performance.now();
+        const tick = (now) => {
+            if (isDestroyed())
+                return;
+            const dt = clamp(now - last, 0, MAX_FRAME_MS);
+            last = now;
+            const next = {};
+            for (const axis of AXES) {
+                if (speed[axis] === 0)
+                    continue;
+                const advance = momentumStep(speed[axis], dt);
+                current[axis] = clamp(current[axis] + advance.distance, 0, max[axis]);
+                speed[axis] = current[axis] <= 0 || current[axis] >= max[axis] ? 0 : advance.velocity;
+                next[axis] = current[axis];
+            }
+            writePosition(next, isRtlNow);
+            if (Math.hypot(speed.x, speed.y) < MIN_VELOCITY)
+                settle();
+            else
+                frame = win.requestAnimationFrame(tick);
+        };
+        frame = win.requestAnimationFrame(tick);
+    };
+    const nearestSnapToLanding = (speed, snaps) => {
+        const max = scrollRange();
+        const from = position(rtl(), max);
+        const positions = core.snapPoints();
+        const target = {};
+        for (const axis of AXES) {
+            const landing = clamp(from[axis] + momentumDistance(speed[axis]), 0, max[axis]);
+            target[axis] = snaps[axis] ? nearestSnap(positions[axis], landing) : landing;
+        }
+        return target;
+    };
+    return {
+        stop,
+        settle,
+        jump,
+        glideTo,
+        interrupt() {
+            hold.reset();
+            if (motion() === "momentum" || motion() === "glide")
+                settle();
+        },
+        fling(scrollVelocity) {
+            const { momentum, axis, maxGlide } = options();
+            const allowed = momentum && !prefersReducedMotion(win);
+            const speed = {
+                x: allowed && dragsAlong(axis, "x") ? capVelocity(scrollVelocity.x, maxGlide) : 0,
+                y: allowed && dragsAlong(axis, "y") ? capVelocity(scrollVelocity.y, maxGlide) : 0,
+            };
+            const snaps = snapAxes();
+            if (snaps.x || snaps.y)
+                glideTo(nearestSnapToLanding(speed, snaps), speed, "momentum");
+            else if (Math.hypot(speed.x, speed.y) > MIN_VELOCITY)
+                runMomentum(speed);
+            else
+                settle();
+        },
+        afterWheelPause(settleWheel) {
+            wheelTimer = win.setTimeout(() => {
+                wheelTimer = 0;
+                settleWheel();
+            }, WHEEL_SETTLE_MS);
+        },
+        glideTarget: () => glideTarget,
+    };
+}

package/dist/axis/create-snap-suspension.d.ts

@@ -0,0 +1,2 @@
+import type { SnapSuspension, StyleOverrides } from "./types.js";
+export declare function createSnapSuspension(win: Window, el: HTMLElement, styles: StyleOverrides): SnapSuspension;

package/dist/axis/create-snap-suspension.js

@@ -0,0 +1,23 @@
+import { parseSnapType } from "../utils/index.js";
+export function createSnapSuspension(win, el, styles) {
+    const { override, restore } = styles;
+    let suspendedSnapType = null;
+    return {
+        suspend() {
+            if (suspendedSnapType !== null)
+                return;
+            suspendedSnapType = win.getComputedStyle(el).scrollSnapType;
+            override("scroll-snap-type", "none", true);
+            override("scroll-behavior", "auto", true);
+        },
+        resume() {
+            if (suspendedSnapType === null)
+                return;
+            suspendedSnapType = null;
+            restore("scroll-snap-type");
+            restore("scroll-behavior");
+        },
+        snapAxes: () => parseSnapType(suspendedSnapType ?? win.getComputedStyle(el).scrollSnapType),
+        isSuspended: () => suspendedSnapType !== null,
+    };
+}

package/dist/axis/create-style-overrides.d.ts

@@ -0,0 +1,2 @@
+import type { StyleOverrides } from "./types.js";
+export declare function createStyleOverrides(el: HTMLElement, observer: MutationObserver, onMutations: (records: MutationRecord[]) => void): StyleOverrides;

package/dist/axis/create-style-overrides.js

@@ -0,0 +1,35 @@
+export function createStyleOverrides(el, observer, onMutations) {
+    const saved = new Map();
+    const writeUnobserved = (write) => {
+        const pendingRecords = observer.takeRecords();
+        write();
+        observer.takeRecords();
+        if (pendingRecords.length > 0)
+            queueMicrotask(() => onMutations(pendingRecords));
+    };
+    const override = (prop, value, important = false) => {
+        if (!saved.has(prop)) {
+            saved.set(prop, [el.style.getPropertyValue(prop), el.style.getPropertyPriority(prop)]);
+        }
+        else if (el.style.getPropertyValue(prop) === value)
+            return;
+        writeUnobserved(() => el.style.setProperty(prop, value, important ? "important" : ""));
+    };
+    const restore = (prop) => {
+        const original = saved.get(prop);
+        if (!original)
+            return;
+        saved.delete(prop);
+        writeUnobserved(() => {
+            if (original[0])
+                el.style.setProperty(prop, original[0], original[1]);
+            else
+                el.style.removeProperty(prop);
+        });
+    };
+    const restoreAll = () => {
+        for (const prop of saved.keys())
+            restore(prop);
+    };
+    return { override, restore, restoreAll };
+}

package/dist/axis/create-wheel.d.ts

@@ -0,0 +1,5 @@
+import type { AxisCore, ScrollDriver, SnapSuspension } from "./types.js";
+export declare function createWheel(core: AxisCore, snap: SnapSuspension, driver: ScrollDriver): {
+    sync: () => void;
+    remove: () => void;
+};

package/dist/axis/create-wheel.js

@@ -0,0 +1,57 @@
+import { adjacentSnap, clamp, nearestSnap, wheelDeltaYPx } from "../utils/index.js";
+import { EDGE, ZERO } from "./constants.js";
+export function createWheel(core, snap, driver) {
+    const { el, rtl, scrollRange, position, writePosition, options, motion, setMotion, isDestroyed } = core;
+    let direction = 1;
+    let attached = false;
+    const settleOnNextSnapInWheelDirection = () => {
+        if (isDestroyed())
+            return;
+        if (!snap.snapAxes().x) {
+            driver.settle();
+            return;
+        }
+        const current = position().x;
+        const positions = core.snapPoints().x;
+        const target = adjacentSnap(positions, current - 2 * direction, direction) ?? nearestSnap(positions, current);
+        driver.glideTo({ x: target }, ZERO, "glide");
+    };
+    const onWheel = (event) => {
+        if (options().axis !== "x" || event.ctrlKey || event.shiftKey)
+            return;
+        if (Math.abs(event.deltaY) <= Math.abs(event.deltaX))
+            return;
+        if (motion() === "pressed" || motion() === "dragging")
+            return;
+        const delta = wheelDeltaYPx(event, el.clientWidth);
+        const isRtlNow = rtl();
+        const max = scrollRange();
+        const current = position(isRtlNow, max).x;
+        const leavesPageScrollingAtEdge = delta > 0 ? current >= max.x - EDGE : current <= EDGE;
+        if (leavesPageScrollingAtEdge)
+            return;
+        event.preventDefault();
+        driver.stop();
+        snap.suspend();
+        direction = delta > 0 ? 1 : -1;
+        writePosition({ x: clamp(current + delta, 0, max.x) }, isRtlNow);
+        if (motion() !== "wheel")
+            setMotion("wheel");
+        if (isDestroyed())
+            return;
+        driver.afterWheelPause(settleOnNextSnapInWheelDirection);
+    };
+    const sync = () => {
+        const { wheel, axis } = options();
+        const wanted = wheel && axis === "x";
+        if (wanted === attached)
+            return;
+        attached = wanted;
+        if (wanted)
+            el.addEventListener("wheel", onWheel, { passive: false });
+        else
+            el.removeEventListener("wheel", onWheel);
+    };
+    const remove = () => el.removeEventListener("wheel", onWheel);
+    return { sync, remove };
+}

package/dist/axis/drags-along.d.ts

@@ -0,0 +1,2 @@
+import type { AxisMode, AxisName } from "./types.js";
+export declare const dragsAlong: (mode: AxisMode, axis: AxisName) => boolean;

package/dist/axis/drags-along.js

@@ -0,0 +1 @@
+export const dragsAlong = (mode, axis) => mode === "both" || mode === axis;

package/dist/axis/index.d.ts

@@ -0,0 +1,2 @@
+export { createAxis } from "./create-axis.js";
+export type { AxisInstance, AxisMode, AxisName, AxisOptions, AxisPosition, AxisScrollState, AxisScrollToOptions, AxisState, } from "./types.js";

package/dist/axis/index.js

@@ -0,0 +1 @@
+export { createAxis } from "./create-axis.js";

package/dist/axis/merge-options.d.ts

@@ -0,0 +1,2 @@
+import type { AxisOptions } from "./types.js";
+export declare function mergeOptions(base: Required<AxisOptions>, patch: AxisOptions): Required<AxisOptions>;

package/dist/axis/merge-options.js

@@ -0,0 +1,9 @@
+import { DEFAULTS } from "./constants.js";
+export function mergeOptions(base, patch) {
+    const next = { ...base };
+    for (const key of Object.keys(DEFAULTS)) {
+        if (patch[key] !== undefined)
+            next[key] = patch[key];
+    }
+    return next;
+}

package/dist/axis/next-axis-state.d.ts

@@ -0,0 +1,2 @@
+import type { AxisState } from "./types.js";
+export declare function nextAxisState(scroll: number, max: number, previous: AxisState): AxisState;

package/dist/axis/next-axis-state.js

@@ -0,0 +1,14 @@
+import { EDGE } from "./constants.js";
+export function nextAxisState(scroll, max, previous) {
+    const next = {
+        scroll,
+        maxScroll: max,
+        progress: max > 0 ? scroll / max : 0,
+        canScrollPrev: scroll > EDGE,
+        canScrollNext: scroll < max - EDGE,
+    };
+    for (const key of Object.keys(next))
+        if (next[key] !== previous[key])
+            return next;
+    return previous;
+}

package/dist/axis/resolve-axis.d.ts

@@ -0,0 +1,2 @@
+import type { AxisMode, AxisName } from "./types.js";
+export declare function resolveAxis(method: string, axis: AxisName | undefined, mode: AxisMode): AxisName;

package/dist/axis/resolve-axis.js

@@ -0,0 +1,8 @@
+export function resolveAxis(method, axis, mode) {
+    if (axis)
+        return axis;
+    if (mode === "both") {
+        throw new Error(`axis: ${method}() needs an axis ("x" or "y") when the instance uses axis: "both"`);
+    }
+    return mode;
+}

package/dist/axis/types.d.ts

@@ -0,0 +1,146 @@
+import type { Vector } from "../utils/index.js";
+/** The direction(s) a mouse drag scrolls: horizontal, vertical, or free 2D panning. */
+export type AxisMode = "x" | "y" | "both";
+/** A single scroll axis. */
+export type AxisName = "x" | "y";
+/** Options for {@link createAxis}. Every option can be changed later with {@link AxisInstance.setOptions}. */
+export interface AxisOptions {
+    /**
+     * Which direction a mouse drag scrolls. `"x"` ignores vertical mouse movement, `"y"` ignores horizontal
+     * movement, and `"both"` pans freely in 2D.
+     * @default "x"
+     */
+    axis?: AxisMode;
+    /**
+     * Keep gliding after a fast mouse drag is released. Never applied under `prefers-reduced-motion: reduce`.
+     * @default true
+     */
+    momentum?: boolean;
+    /**
+     * The farthest a momentum glide may travel after one release, in px. A faster fling is slowed down to land
+     * within it, so one gesture never moves more than this.
+     * @default Infinity
+     */
+    maxGlide?: number;
+    /**
+     * Translate vertical mouse-wheel scrolling into horizontal scrolling. Only used with `axis: "x"`; at either
+     * end the wheel is left alone, so the page keeps scrolling.
+     * @default false
+     */
+    wheel?: boolean;
+    /**
+     * Set `cursor: grab` on the container while it can be dragged, and `grabbing` while dragging.
+     * @default true
+     */
+    cursor?: boolean;
+}
+/** Scroll state of one axis. Positions are logical: measured from the start edge, so positive in RTL too. */
+export interface AxisState {
+    /** Distance scrolled from the start edge, in px (0 to `maxScroll`). */
+    scroll: number;
+    /** Largest possible `scroll`, in px. 0 when the content fits. */
+    maxScroll: number;
+    /** `scroll / maxScroll`, from 0 to 1. 0 when the content fits. */
+    progress: number;
+    /** True when the container is more than 1px away from the start edge. */
+    canScrollPrev: boolean;
+    /** True when the container is more than 1px away from the end edge. */
+    canScrollNext: boolean;
+}
+/** Scroll state of both axes, whatever `axis` is set to. */
+export interface AxisScrollState {
+    x: AxisState;
+    y: AxisState;
+    /** True while a mouse drag is scrolling the container. */
+    isDragging: boolean;
+    /** True while the container glides after a drag is released (momentum or settling on a snap position). */
+    isMomentum: boolean;
+}
+/** A logical scroll position. Axes that are left out keep their current position. */
+export interface AxisPosition {
+    x?: number;
+    y?: number;
+}
+/** Options for {@link AxisInstance.scrollTo}. */
+export interface AxisScrollToOptions {
+    /** Animate the scroll. Ignored (jumps) under `prefers-reduced-motion: reduce`. @default true */
+    animate?: boolean;
+}
+/** An axis instance bound to one scroll container. */
+export interface AxisInstance {
+    /** The current state. The object is replaced, never mutated, when a value changes. */
+    getState(): AxisScrollState;
+    /** Calls `listener` whenever the state changes. Returns a function that removes the listener. */
+    subscribe(listener: (state: AxisScrollState) => void): () => void;
+    /**
+     * Scrolls `axis` to the previous snap position, or back by 90% of the visible size when it does not snap.
+     * `axis` defaults to the configured axis and is required with `axis: "both"`.
+     */
+    scrollPrev(axis?: AxisName): void;
+    /**
+     * Scrolls `axis` to the next snap position, or forward by 90% of the visible size when it does not snap.
+     * `axis` defaults to the configured axis and is required with `axis: "both"`.
+     */
+    scrollNext(axis?: AxisName): void;
+    /** Scrolls to a logical position (px from the start edge of each axis). */
+    scrollTo(position: AxisPosition, options?: AxisScrollToOptions): void;
+    /** Changes some options. Keys that are left out or `undefined` keep their current value. */
+    setOptions(options: AxisOptions): void;
+    /**
+     * Re-reads the layout: clears the cached snap positions and updates the state. Only needed after a change
+     * axis cannot observe, such as a stylesheet or media query changing snap properties without a resize.
+     */
+    refresh(): void;
+    /** Removes every listener and observer and restores every inline style that axis changed. */
+    destroy(): void;
+}
+export type Motion = "idle" | "pressed" | "dragging" | "momentum" | "glide" | "wheel";
+export type Glide = "momentum" | "glide";
+export interface Geometry {
+    rtl(): boolean;
+    scrollRange(): Vector;
+    position(rtl?: boolean, range?: Vector): Vector;
+    writePosition(position: AxisPosition, rtl?: boolean): void;
+}
+export interface AxisCore extends Geometry {
+    el: HTMLElement;
+    win: Window;
+    options(): Required<AxisOptions>;
+    motion(): Motion;
+    setMotion(next: Motion): void;
+    isDestroyed(): boolean;
+    snapPoints(): Record<AxisName, number[]>;
+}
+export interface StyleOverrides {
+    override(prop: string, value: string, important?: boolean): void;
+    restore(prop: string): void;
+    restoreAll(): void;
+}
+export interface SnapSuspension {
+    suspend(): void;
+    resume(): void;
+    snapAxes(): {
+        x: boolean;
+        y: boolean;
+    };
+    isSuspended(): boolean;
+}
+export interface Hold {
+    holdCurrent(): void;
+    release(): void;
+    reset(): void;
+    yieldDrag(glideHoldsAtItsEnd: boolean): void;
+    holdIfYielded(): void;
+    follow(axis: AxisName): void;
+    undoAutoscroll(): void;
+}
+export interface ScrollDriver {
+    stop(): void;
+    settle(): void;
+    interrupt(): void;
+    jump(target: AxisPosition): void;
+    glideTo(target: AxisPosition, velocity: Vector, kind: Glide): void;
+    fling(scrollVelocity: Vector): void;
+    afterWheelPause(settle: () => void): void;
+    glideTarget(): Vector;
+}

package/dist/axis/types.js

@@ -0,0 +1 @@
+export {};

package/dist/coordinator/constants.d.ts

@@ -0,0 +1,5 @@
+import type { Coordinator } from "./types.js";
+export declare const DRAG_THRESHOLD = 5;
+export declare const CLICK_SUPPRESS_MS = 100;
+export declare const NO_DRAG = "input, textarea, select, [contenteditable]:not([contenteditable='false']), [data-axis-no-drag]";
+export declare const coordinators: WeakMap<Window, Coordinator>;

package/dist/coordinator/constants.js

@@ -0,0 +1,5 @@
+import { EDITABLE } from "../utils/index.js";
+export const DRAG_THRESHOLD = 5;
+export const CLICK_SUPPRESS_MS = 100;
+export const NO_DRAG = `${EDITABLE}, [data-axis-no-drag]`;
+export const coordinators = new WeakMap();

package/dist/coordinator/create-coordinator.d.ts

@@ -0,0 +1,2 @@
+import type { Coordinator } from "./types.js";
+export declare function createCoordinator(win: Window): Coordinator;