@xingwangzhe/stalux 1.57.0 → 1.58.0

package/src/scripts/route-motion.ts

@@ -1,340 +0,0 @@
-import type { RouteMotionPreset } from "../utils/route-motion-policy";
-
-export interface RouteMotionEvent {
-    // Retained for integrations using the shared gates with a native transition.
-    // Stalux's Swup router leaves this unset and owns the animation lifecycle.
-    viewTransition?: {
-        ready?: PromiseLike<unknown>;
-        finished?: PromiseLike<unknown>;
-    };
-    signal?: AbortSignal;
-}
-
-export interface RouteMotionOptions {
-    skip?: boolean;
-    /** Animate the route's own content stage instead of a bounded heading area. */
-    content?: boolean;
-    preset?: RouteMotionPreset;
-    browserMotion?: boolean;
-    /** Releases the outgoing fill effect inside the entry cue's sync block. */
-    releaseOutgoing?: () => void;
-}
-
-export interface RouteMotion {
-    ready: Promise<void>;
-    finished: Promise<void>;
-    start: (heading: HTMLElement | null, options?: RouteMotionOptions) => void;
-    cancel: () => void;
-}
-
-interface HeadingMotion {
-    opacity: number;
-    duration: number;
-    x?: number;
-    y?: number;
-}
-
-// Legacy heading cues remain available to integrations. The router requests
-// one content animation; it never stacks a second animation on the heading.
-const headingMotions: Record<Exclude<RouteMotionPreset, "none">, HeadingMotion> = {
-    glide: { opacity: 0.86, duration: 50 },
-    article: { opacity: 0.86, duration: 50 },
-    enter: { opacity: 0.86, duration: 70, y: 6 },
-    up: { opacity: 0.9, duration: 60, y: -4 },
-    taxonomy: { opacity: 0.85, duration: 60 },
-    previous: { opacity: 0.9, duration: 70, x: -8 },
-    next: { opacity: 0.9, duration: 70, x: 8 },
-    panel: { opacity: 0.9, duration: 60, y: 4 },
-    home: { opacity: 0.9, duration: 60, y: 4 },
-    restore: { opacity: 0.96, duration: 40 },
-    error: { opacity: 0.9, duration: 40 },
-};
-
-const MAIN = "main[data-stalux-route]";
-const ARTICLE = "article.stalux-article";
-// Authored per page type by the theme, not inferred from layout: the article
-// body, archive list, tag cloud, post list, word list, link list, home block.
-const CONTENT = "[data-stalux-motion-content]";
-// The one node a page nominates as its cue stage. Preferred over measuring,
-// because measuring an article column forces a full layout of a document that
-// is tens of thousands of pixels tall, before it has ever been painted.
-const STAGE = "[data-stalux-motion-stage]";
-// A persist node marks the three-column article shell. Those sidebars keep
-// their identity across visits and must never travel with a route cue.
-const PERSIST = "[data-swup-persist]";
-
-interface StageMotion {
-    opacity: number;
-    /**
-     * Enter offset in px. Positive y enters from below, positive x from the right.
-     * Zero means a pure cross-fade: the column is replaced in place.
-     */
-    distance: number;
-    axis: "x" | "y";
-    duration: number;
-}
-
-// One entry per route kind, because the components are not interchangeable: an
-// article opens from below and going back up to an index pulls away upward.
-//
-// Article-to-article is the exception: the reader keeps the same shell (sidebars,
-// header) and only the column changes, so the column fades in place instead of
-// travelling. Sliding a 28,000px column sideways made the whole page look like it
-// jerked, and the shell already tells the reader where they are.
-const stageMotions: Record<Exclude<RouteMotionPreset, "none">, StageMotion> = {
-    previous: { opacity: 0, distance: 0, axis: "x", duration: 150 },
-    next: { opacity: 0, distance: 0, axis: "x", duration: 150 },
-    // Entering a different article without a reading-direction trigger.
-    article: { opacity: 0, distance: 0, axis: "y", duration: 150 },
-    // Reaching an article from any list or the home block.
-    enter: { opacity: 0, distance: 56, axis: "y", duration: 170 },
-    home: { opacity: 0, distance: 48, axis: "y", duration: 160 },
-    // Leaving an article for the archive or a taxonomy index.
-    up: { opacity: 0, distance: -44, axis: "y", duration: 150 },
-    // Moving between two taxonomy detail pages.
-    taxonomy: { opacity: 0, distance: 36, axis: "y", duration: 140 },
-    // About / links / words: single-panel pages.
-    panel: { opacity: 0, distance: 44, axis: "y", duration: 150 },
-    glide: { opacity: 0, distance: 40, axis: "y", duration: 140 },
-    // History traversal restores what the reader already saw.
-    restore: { opacity: 0, distance: -36, axis: "y", duration: 140 },
-    error: { opacity: 0, distance: 28, axis: "y", duration: 130 },
-};
-
-const laidOut = (element: HTMLElement): boolean => {
-    const rect = element.getBoundingClientRect();
-    return rect.width > 0 && rect.height > 0;
-};
-
-/**
- * The single node a route cue may animate for the current document.
- *
- * A page can nominate its stage; only when it does not is the largest authored
- * content stage measured. Measuring is the fallback, not the rule: on an article
- * the column is tens of thousands of pixels tall and measuring it forces a full
- * layout of the incoming document at the exact moment the entry cue needs to
- * start. Sidebars (persisted shells), the header and the footer never qualify.
- */
-export function getRouteStage(): HTMLElement | null {
-    const main = document.querySelector<HTMLElement>(MAIN);
-    if (!main?.isConnected) return null;
-    const authored = main.querySelector<HTMLElement>(STAGE);
-    if (authored?.isConnected && !authored.closest(PERSIST)) return authored;
-    const candidates: HTMLElement[] = [];
-    const article = main.querySelector<HTMLElement>(ARTICLE);
-    if (article) candidates.push(article);
-    for (const element of main.querySelectorAll<HTMLElement>(CONTENT)) candidates.push(element);
-
-    let stage: HTMLElement | null = null;
-    let area = 0;
-    for (const element of candidates) {
-        // A stage inside a persisted subtree is the shell itself.
-        if (!element.isConnected || element.closest(PERSIST)) continue;
-        const rect = element.getBoundingClientRect();
-        if (rect.width <= 0 || rect.height <= 0) continue;
-        const current = rect.width * rect.height;
-        if (current > area) {
-            area = current;
-            stage = element;
-        }
-    }
-    if (stage) return stage;
-    if (main.querySelector(PERSIST)) return null;
-    return laidOut(main) ? main : null;
-}
-
-/** Offset applied to the outgoing document, continuing the entry direction. */
-export function getStageExit(preset: RouteMotionPreset): StageMotion | null {
-    if (preset === "none") return null;
-    const motion = stageMotions[preset];
-    // Entering from below means leaving upward, so both halves read as one
-    // continuous flow instead of an enter/leave bounce.
-    return { ...motion, distance: -Math.round(motion.distance * 0.72) };
-}
-
-const motions = new WeakMap<object, RouteMotion>();
-const settle = (promise?: PromiseLike<unknown>): Promise<void> =>
-    Promise.resolve(promise).then(
-        () => undefined,
-        () => undefined,
-    );
-function completion() {
-    let resolve = () => {};
-    const promise = new Promise<void>((done) => {
-        resolve = done;
-    });
-    return { promise, resolve };
-}
-
-/** A route transition never captures a long article, list, or off-screen heading. */
-export function getRouteMotionTarget(focus: HTMLElement | null): HTMLElement | null {
-    if (!(focus?.isConnected && focus.hasAttribute("data-stalux-motion-focus"))) return null;
-    const visible = (element: HTMLElement, maxHeight: number) => {
-        const rect = element.getBoundingClientRect();
-        return (
-            rect.width > 0 &&
-            rect.height > 0 &&
-            rect.height <= maxHeight &&
-            rect.top < window.innerHeight &&
-            rect.bottom > 0 &&
-            rect.left < window.innerWidth &&
-            rect.right > 0
-        );
-    };
-    if (!visible(focus, Math.min(320, window.innerHeight / 2))) return null;
-    const region = focus.closest?.<HTMLElement>("[data-stalux-motion-region]");
-    return region?.isConnected && visible(region, Math.min(420, window.innerHeight * 0.6))
-        ? region
-        : focus;
-}
-
-const regionMotions: Record<Exclude<RouteMotionPreset, "none">, HeadingMotion> = {
-    glide: { opacity: 0.72, duration: 80 },
-    article: { opacity: 0.72, duration: 90, y: 4 },
-    enter: { opacity: 0.72, duration: 90, y: 6 },
-    up: { opacity: 0.8, duration: 80, y: -4 },
-    taxonomy: { opacity: 0.72, duration: 80, x: 6 },
-    previous: { opacity: 0.76, duration: 90, x: -8 },
-    next: { opacity: 0.76, duration: 90, x: 8 },
-    panel: { opacity: 0.76, duration: 80, y: 4 },
-    home: { opacity: 0.76, duration: 90, y: 4 },
-    restore: { opacity: 1, duration: 0 },
-    error: { opacity: 0.85, duration: 50 },
-};
-
-/** Share Swup's actual content animation with background and analytics consumers. */
-export function prepareRouteMotion(event: RouteMotionEvent): RouteMotion {
-    const native = event.viewTransition;
-    const key = native ?? event;
-    const existing = motions.get(key);
-    if (existing) return existing;
-
-    // Installation is a separate gate: before-swap consumers must not mistake
-    // the gap before Swup's incoming animation hook for a completed transition.
-    const installed = completion();
-    const animationDone = completion();
-    const canceled = completion();
-    let animation: Animation | undefined;
-    let started = false;
-    let disposed = false;
-    const clearAnimation = () => {
-        const active = animation;
-        animation = undefined;
-        try {
-            // Remove fill effects and restore the authored final styles. No
-            // inline transform/opacity survives completion, failure or abort.
-            active?.cancel();
-        } catch {
-            // Releasing an already detached effect must not hold up navigation.
-        }
-        animationDone.resolve();
-    };
-    const cancel = () => {
-        if (disposed) return;
-        disposed = true;
-        started = true;
-        clearAnimation();
-        installed.resolve();
-        canceled.resolve();
-        event.signal?.removeEventListener("abort", cancel);
-    };
-    const ready = Promise.race([
-        canceled.promise,
-        Promise.all([settle(native?.ready), installed.promise]).then(() => undefined),
-    ]);
-    const finished = Promise.race([
-        canceled.promise,
-        Promise.all([settle(native?.finished), animationDone.promise]).then(() => undefined),
-    ]);
-    const motion: RouteMotion = {
-        ready,
-        finished,
-        start(heading, options) {
-            if (started) return;
-            started = true;
-            // Every exit path must release the outgoing fill, or the swapped
-            // document stays transparent behind a cancelled cue.
-            const release = options?.releaseOutgoing;
-            try {
-                const preset = options?.preset ?? "glide";
-                const mobile = window.matchMedia?.("(max-width: 768px)").matches;
-                if (
-                    options?.skip ||
-                    options?.browserMotion ||
-                    preset === "none" ||
-                    (options?.content && preset === "restore") ||
-                    // History never replays an entry on a phone: the reader is
-                    // returning to a position, not arriving somewhere new.
-                    (mobile && preset === "restore") ||
-                    document.hidden ||
-                    window.matchMedia?.("(prefers-reduced-motion: reduce)").matches
-                ) {
-                    release?.();
-                    animationDone.resolve();
-                    return;
-                }
-                const stage = options?.content ? getRouteStage() : null;
-                const target = stage ?? getRouteMotionTarget(heading);
-                if (!target || typeof target.animate !== "function") {
-                    release?.();
-                    animationDone.resolve();
-                    return;
-                }
-                // Cancelling the outgoing fill and starting the entry cue must
-                // share one synchronous block. Split across frames, the reader
-                // sees the new document at full opacity for a frame first.
-                release?.();
-                if (stage) {
-                    const spec = stageMotions[preset];
-                    // Phones get a shorter throw; the same offset reads as a much
-                    // larger move on a narrow viewport.
-                    const distance = mobile ? Math.round(spec.distance * 0.6) : spec.distance;
-                    const from =
-                        spec.axis === "x"
-                            ? `translate3d(${distance}px, 0, 0)`
-                            : `translate3d(0, ${distance}px, 0)`;
-                    // A zero distance is a cross-fade in place. Authoring a
-                    // translate3d(0,0,0) would put a 28,000px column on its own
-                    // compositor layer for nothing.
-                    const keyframes: PropertyIndexedKeyframes = { opacity: [spec.opacity, 1] };
-                    if (distance !== 0) keyframes.transform = [from, "translate3d(0, 0, 0)"];
-                    animation = stage.animate(keyframes, {
-                        duration: mobile ? Math.round(spec.duration * 0.9) : spec.duration,
-                        // Strong ease-out: quick arrival, soft settle. The
-                        // built-in ease-out is too weak to read at this size.
-                        easing: "cubic-bezier(0.23, 1, 0.32, 1)",
-                        fill: "both",
-                    });
-                } else {
-                    const spec = options?.content ? regionMotions[preset] : headingMotions[preset];
-                    const keyframes: PropertyIndexedKeyframes = { opacity: [spec.opacity, 1] };
-                    // Phones use a pure fade. Explicit previous/next alone imply a
-                    // lateral reading direction; history never replays the entry.
-                    if (!mobile && (spec.x || spec.y)) {
-                        keyframes.transform = [
-                            `translate3d(${spec.x ?? 0}px, ${spec.y ?? 0}px, 0)`,
-                            "translate3d(0px, 0px, 0)",
-                        ];
-                    }
-                    animation = target.animate(keyframes, {
-                        duration: mobile ? (options?.content ? 60 : 40) : spec.duration,
-                        easing: "cubic-bezier(0.2, 0.7, 0.2, 1)",
-                        fill: "both",
-                    });
-                }
-                void animation.finished.then(clearAnimation, clearAnimation);
-            } catch {
-                release?.();
-                clearAnimation();
-            } finally {
-                installed.resolve();
-            }
-        },
-        cancel,
-    };
-    motions.set(key, motion);
-    if (event.signal?.aborted) cancel();
-    else event.signal?.addEventListener("abort", cancel, { once: true });
-    void finished.then(() => event.signal?.removeEventListener("abort", cancel));
-    return motion;
-}

package/src/scripts/route-out.ts

@@ -1,63 +0,0 @@
-import type { RouteMotionPreset } from "../utils/route-motion-policy";
-import { getRouteStage, getStageExit } from "./route-motion";
-
-/**
- * Fade and shift the current content stage out, continuing the entry direction
- * so the two halves read as one movement instead of a flash.
- *
- * The returned release keeps the fill effect until the entry cue takes over.
- * Cancelling here would expose the freshly swapped document at full opacity for
- * a frame before it animates in — the exact flash this replaces.
- */
-export async function animateRouteOut(
-    preset: RouteMotionPreset,
-    signal: AbortSignal,
-): Promise<() => void> {
-    const spec = getStageExit(preset);
-    const stage = spec ? getRouteStage() : null;
-    if (
-        !(spec && stage) ||
-        signal.aborted ||
-        document.hidden ||
-        typeof stage.animate !== "function" ||
-        window.matchMedia("(prefers-reduced-motion: reduce)").matches
-    )
-        return () => {};
-    const mobile = window.matchMedia("(max-width: 768px)").matches;
-    const distance = mobile ? Math.round(spec.distance * 0.6) : spec.distance;
-    const to =
-        spec.axis === "x" ? `translate3d(${distance}px, 0, 0)` : `translate3d(0, ${distance}px, 0)`;
-    // Article-to-article has no distance: the column fades out in place, matching
-    // the entry fade, so the shell stays put and only the content disappears.
-    const keyframes: PropertyIndexedKeyframes = { opacity: [1, 0] };
-    if (distance !== 0) keyframes.transform = ["translate3d(0, 0, 0)", to];
-    let animation: Animation | undefined;
-    const cancel = () => {
-        const active = animation;
-        animation = undefined;
-        try {
-            active?.cancel();
-        } catch {
-            /* An already detached effect cannot be released further. */
-        }
-    };
-    try {
-        animation = stage.animate(keyframes, {
-            duration: mobile ? Math.round(spec.duration * 0.62) : Math.round(spec.duration * 0.58),
-            // Strong ease-in: the outgoing document accelerates away. An exit
-            // is the one place ease-in is correct; entrances use ease-out.
-            easing: "cubic-bezier(0.4, 0, 1, 1)",
-            fill: "forwards",
-        });
-        signal.addEventListener("abort", cancel, { once: true });
-        await animation.finished;
-        // The stage node survives the swap, so this filled effect is what holds
-        // the incoming document hidden until its own cue starts.
-    } catch {
-        /* Cancellation and unsupported animation must not block a visit. */
-    }
-    return () => {
-        signal.removeEventListener("abort", cancel);
-        cancel();
-    };
-}

package/src/scripts/smooth-scroll.ts

@@ -1,139 +0,0 @@
-let stopActive: (() => void) | undefined;
-
-export function cancelPageScroll(): void {
-    stopActive?.();
-}
-
-export interface PageGlide {
-    /** Settles when the page reaches the top, is interrupted, or is canceled. */
-    promise: Promise<void>;
-    /** Stop immediately at the current position without further frames. */
-    cancel: () => void;
-}
-
-/** Bound the pre-swap return-to-top so a 6000px article does not add a second. */
-const GLIDE_MIN_MS = 80;
-const GLIDE_MAX_MS = 180;
-const GLIDE_SAFETY_MS = 380;
-
-/**
- * Walk the current document back to the top before the container is replaced.
- * Swup's own between-page reset is instant; animating it after the swap would
- * make the new article start wherever the old page happened to be scrolled.
- * Doing it on the outgoing document keeps the incoming page at its real top.
- */
-export function glideToTop(): PageGlide {
-    const element = document.scrollingElement ?? document.documentElement;
-    const startTop = Math.max(0, element.scrollTop || window.scrollY || 0);
-    const startLeft = Math.max(0, element.scrollLeft || window.scrollX || 0);
-    let resolve = () => {};
-    const promise = new Promise<void>((done) => {
-        resolve = done;
-    });
-    if (
-        startTop < 1 ||
-        typeof requestAnimationFrame !== "function" ||
-        window.matchMedia?.("(prefers-reduced-motion: reduce)").matches ||
-        document.hidden
-    ) {
-        resolve();
-        return { promise, cancel: resolve };
-    }
-
-    // Longer documents take proportionally longer, but the ceiling keeps the
-    // whole cue inside the same budget as the content fade.
-    const duration = Math.min(GLIDE_MAX_MS, GLIDE_MIN_MS + startTop / 20);
-    let frame: number | undefined;
-    let settled = false;
-    const release = () => {
-        window.removeEventListener("wheel", finish);
-        window.removeEventListener("touchstart", finish);
-        window.removeEventListener("keydown", finish);
-        clearTimeout(safety);
-        if (stopActive === finish) stopActive = undefined;
-    };
-    const finish = () => {
-        if (settled) return;
-        settled = true;
-        if (frame !== undefined) cancelAnimationFrame(frame);
-        release();
-        resolve();
-    };
-    // A wheel/touch/key press means the reader reclaimed the scroll; stop at
-    // the frame already rendered instead of fighting the gesture.
-    const safety = setTimeout(finish, GLIDE_SAFETY_MS);
-    stopActive = finish;
-    window.addEventListener("wheel", finish, { passive: true, once: true });
-    window.addEventListener("touchstart", finish, { passive: true, once: true });
-    window.addEventListener("keydown", finish, { once: true });
-
-    const begin = performance.now();
-    let frames = 0;
-    const step = (now: number) => {
-        if (settled) return;
-        // Frame ceiling: a host that invokes rAF synchronously must not turn
-        // this loop into unbounded recursion. Real browsers reach the safety
-        // timeout first; twenty frames cover the 320ms budget at 60Hz.
-        if (++frames > 240) {
-            finish();
-            return;
-        }
-        const progress = Math.min(1, Math.max(0, (now - begin) / duration));
-        // Quadratic ease-out: reads as a scroll rather than a snap, and still
-        // spends most of its time near the top where the article begins.
-        const remaining = (1 - progress) ** 2;
-        element.scrollTop = Math.round(startTop * remaining);
-        element.scrollLeft = Math.round(startLeft * remaining);
-        if (progress < 1) frame = requestAnimationFrame(step);
-        else finish();
-    };
-    frame = requestAnimationFrame(step);
-    return { promise, cancel: finish };
-}
-
-/** Native scrolling with bounded completion and explicit listener cleanup. */
-export function scrollPage(
-    element: Element,
-    top: number,
-    left: number,
-    animate: boolean,
-    start: () => void,
-    end: () => void,
-): void {
-    stopActive?.();
-    start();
-    const smooth = animate && !window.matchMedia("(prefers-reduced-motion: reduce)").matches;
-    if (
-        !smooth ||
-        (Math.abs(element.scrollTop - top) < 1 && Math.abs(element.scrollLeft - left) < 1)
-    ) {
-        element.scrollTo({ top, left, behavior: "instant" });
-        end();
-        return;
-    }
-    const target =
-        element === document.documentElement || element === document.body ? window : element;
-    let finished = false;
-    const done = () => {
-        if (finished) return;
-        finished = true;
-        clearTimeout(timer);
-        target.removeEventListener("scrollend", done);
-        window.removeEventListener("wheel", interrupt);
-        window.removeEventListener("touchstart", interrupt);
-        window.removeEventListener("keydown", interrupt);
-        if (stopActive === interrupt) stopActive = undefined;
-        end();
-    };
-    const interrupt = () => {
-        element.scrollTo({ top: element.scrollTop, left: element.scrollLeft, behavior: "instant" });
-        done();
-    };
-    const timer = setTimeout(done, 1500);
-    stopActive = interrupt;
-    target.addEventListener("scrollend", done, { once: true });
-    window.addEventListener("wheel", interrupt, { passive: true, once: true });
-    window.addEventListener("touchstart", interrupt, { passive: true, once: true });
-    window.addEventListener("keydown", interrupt, { once: true });
-    element.scrollTo({ top, left, behavior: "smooth" });
-}