@xingwangzhe/stalux 1.44.0 → 1.45.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@xingwangzhe/stalux",
-    "version": "1.44.0",
+    "version": "1.45.0",
     "description": "A powerful, modern Astro blog theme — use as template or install as plugin",
     "keywords": [
         "astro",

package/src/components/stalux/archives/archivesList.astro

@@ -77,9 +77,12 @@ const archiveYears = [...archivesByYearMonth.entries()]
                                     { length: Math.ceil(monthPosts.length / 12) },
                                     (_, index) => monthPosts.slice(index * 12, (index + 1) * 12),
                                 ).map((group) => (
-                                    <ul class="stalux-archive-post-list">
+                                    <ul class="stalux-archive-post-list" data-stalux-reveal>
                                         {group.map((post) => (
-                                            <li class="stalux-archive-post-item">
+                                            <li
+                                                class="stalux-archive-post-item"
+                                                data-stalux-reveal-item
+                                            >
                                                 <time
                                                     class="stalux-archive-post-date"
                                                     datetime={toMachineDateTime(
@@ -127,7 +130,10 @@ const archiveYears = [...archivesByYearMonth.entries()]
 
 <script>
 import { mountArchiveDescriptions } from "../../../scripts/archive-descriptions";
+import { mountListReveal } from "../../../scripts/list-reveal";
 import { registerPageLifecycle } from "../../../scripts/page-runtime";
 
 registerPageLifecycle("archive-descriptions", mountArchiveDescriptions);
+// The archive cascade ships only with the archive markup it animates.
+registerPageLifecycle("list-reveal", mountListReveal);
 </script>

package/src/components/stalux/posts/PostTaxonomy.astro

@@ -46,12 +46,13 @@ const cfg = {
 <nav class="stalux-post-taxonomy-container" aria-label={title ?? cfg.heading}>
     <h3 class="stalux-post-taxonomy-title">{title ?? cfg.heading}</h3>
     {items.length > 0 ? (
-        <div class={cfg.listClass}>
+        <div class={cfg.listClass} data-stalux-reveal>
             {items.map((item) => (
                 <a
                     href={`${cfg.prefix}${item}/`}
                     class={`${cfg.itemClass} a-none`}
                     data-astro-prefetch
+                    data-stalux-reveal-item
                 >
                     {item}
                 </a>

package/src/components/stalux/posts/postLeft.astro

@@ -5,7 +5,7 @@ import PostAuthor from "@components/stalux/posts/postAuthor.astro";
 import RandomPost from "@components/stalux/posts/randomPost.astro";
 ---
 
-<aside class="stalux-sidebar">
+<aside class="stalux-sidebar" data-swup-persist="post-sidebar-left">
     <div class="stalux-sidebar-container" data-stalux-module="sidebar">
         <PostAuthor />
     </div>

package/src/components/stalux/posts/postRight.astro

@@ -15,7 +15,11 @@ const { headings = [], tags = [], categories = [] } = Astro.props;
 ---
 
 <aside class="stalux-sidebar-right" data-stalux-scroll-pane>
-    <div class="stalux-sidebar-container" data-stalux-module="sidebar">
+    <div
+        class="stalux-sidebar-container"
+        data-stalux-module="sidebar"
+        data-swup-persist="post-sidebar-clock"
+    >
         <PostDate />
         <Weather />
     </div>

package/src/components/stalux/posts/postToc.astro

@@ -32,9 +32,9 @@ const tocItems = headings
 <nav data-toc-active-class="stalux-toc-active" aria-label={t("taxonomy.toc")}>
     <h3 class="stalux-toc-title">{title}</h3>
     {tocItems.length > 0 ? (
-        <ul class="stalux-toc-list">
+        <ul class="stalux-toc-list" data-stalux-reveal>
             {tocItems.map((heading) => (
-                <li>
+                <li data-stalux-reveal-item>
                     <a
                         class={`stalux-toc-item ${({ 1: "stalux-toc-depth-1", 2: "stalux-toc-depth-2", 3: "stalux-toc-depth-3", 4: "stalux-toc-depth-4", 5: "stalux-toc-depth-5", 6: "stalux-toc-depth-6" } as Record<number, string>)[heading.depth] || ""} a-none`}
                         href={`#${heading.slug}`}

package/src/layouts/PostLayout.astro

@@ -92,3 +92,11 @@ const walineConfig = walineSection?.serverURL
         <PostRight headings={headings} tags={tags} categories={categories} />
     </div>
 </div>
+
+<script>
+import { mountListReveal } from "../scripts/list-reveal";
+import { registerPageLifecycle } from "../scripts/page-runtime";
+
+// Article sidebars cascade their lists; the script ships with article pages only.
+registerPageLifecycle("list-reveal", mountListReveal);
+</script>

package/src/scripts/list-reveal.ts

@@ -0,0 +1,81 @@
+const CONTAINER = "[data-stalux-reveal]";
+const ITEM = ":scope > [data-stalux-reveal-item]";
+// A cascade is only ever a bounded group cue: never one observer per row, and
+// never a queue long enough to keep the reader waiting for the last item.
+const MAX_CONTAINERS = 48;
+const MAX_ITEMS = 16;
+const STAGGER_MS = 22;
+const MAX_DELAY_MS = 176;
+const DURATION_MS = 240;
+
+/**
+ * Lists cascade in once, when their group becomes visible.
+ *
+ * Text is authored fully visible; the effect only dims a group that is about to
+ * be read. Rows outside the group cap, restored history entries, reduced
+ * motion, persisted shells and hidden documents are left untouched.
+ */
+export function mountListReveal(): (() => void) | undefined {
+    if (typeof IntersectionObserver !== "function") return;
+    const preference = window.matchMedia("(prefers-reduced-motion: reduce)");
+    if (preference.matches || document.hidden) return;
+    // Returning to a history entry restores what the reader already saw.
+    if (document.documentElement.dataset.staluxVtPreset === "restore") return;
+    const containers = [...document.querySelectorAll<HTMLElement>(CONTAINER)]
+        .filter((element) => !element.closest("[data-swup-persist]"))
+        .slice(0, MAX_CONTAINERS);
+    if (!containers.length) return;
+
+    const active = new Set<Animation>();
+    const cancel = () => {
+        for (const animation of active) animation.cancel();
+        active.clear();
+    };
+    const reveal = (container: HTMLElement) => {
+        if (document.hidden || preference.matches) return;
+        const items = [...container.querySelectorAll<HTMLElement>(ITEM)].slice(0, MAX_ITEMS);
+        for (const [index, item] of items.entries()) {
+            if (typeof item.animate !== "function") continue;
+            try {
+                const animation = item.animate(
+                    {
+                        opacity: [0.6, 1],
+                        transform: ["translateY(8px)", "translateY(0)"],
+                    },
+                    {
+                        duration: DURATION_MS,
+                        delay: Math.min(index * STAGGER_MS, MAX_DELAY_MS),
+                        easing: "cubic-bezier(0.2, 0.7, 0.2, 1)",
+                        // Dimmed during the stagger delay instead of popping in.
+                        fill: "backwards",
+                    },
+                );
+                active.add(animation);
+                const release = () => {
+                    active.delete(animation);
+                    animation.cancel();
+                };
+                void animation.finished.then(release, release);
+            } catch {
+                /* An unsupported effect leaves the authored visible list. */
+            }
+        }
+    };
+    const observer = new IntersectionObserver(
+        (entries) => {
+            for (const entry of entries) {
+                if (!entry.isIntersecting) continue;
+                observer.unobserve(entry.target);
+                reveal(entry.target as HTMLElement);
+            }
+        },
+        { threshold: 0.05 },
+    );
+    for (const container of containers) observer.observe(container);
+    preference.addEventListener("change", cancel);
+    return () => {
+        observer.disconnect();
+        preference.removeEventListener("change", cancel);
+        cancel();
+    };
+}

package/src/scripts/module-motion.ts

@@ -32,6 +32,9 @@ export function mountModuleMotion(): (() => void) | undefined {
                     motionPreference.matches ||
                     document.documentElement.classList.contains("is-changing") ||
                     document.documentElement.dataset.staluxVtPreset ||
+                    // A persisted node kept its identity across the visit; it was
+                    // never rebuilt, so re-entering it would be a second cue.
+                    element.closest("[data-swup-persist]") ||
                     element.closest("[data-stalux-motion-region]") ||
                     entry.boundingClientRect.height > Math.min(420, window.innerHeight * 0.6) ||
                     typeof element.animate !== "function"

package/src/scripts/random-posts.ts

@@ -50,6 +50,9 @@ export function mountRandomPosts(): (() => void) | undefined {
     };
     const reveal = () => {
         if (reducedMotion.matches || document.hidden || typeof list.animate !== "function") return;
+        // A persisted sidebar keeps its node across visits; fading it again would
+        // read as the fixed shell blinking, which is exactly what it must not do.
+        if (container.closest("[data-swup-persist]")) return;
         try {
             // Real titles can wrap the sidebar beyond the same bounded-region
             // budget used for route effects. Keep that result immediately readable.

package/src/scripts/smooth-scroll.ts

@@ -4,6 +4,93 @@ 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 = 160;
+const GLIDE_MAX_MS = 360;
+const GLIDE_SAFETY_MS = 760;
+
+/**
+ * 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 / 10);
+    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,

package/src/scripts/swup-router.ts

@@ -12,7 +12,7 @@ import "./navigation-client";
 import { prepareNavigationScripts } from "./navigation-scripts";
 import { prepareRouteMotion, type RouteMotion } from "./route-motion";
 import { animateRouteOut } from "./route-out";
-import { cancelPageScroll, scrollPage } from "./smooth-scroll";
+import { cancelPageScroll, glideToTop, type PageGlide, scrollPage } from "./smooth-scroll";
 
 interface NavigationContext {
     controller: AbortController;
@@ -27,6 +27,7 @@ interface NavigationContext {
     executeScripts?: (signal?: AbortSignal) => Promise<void>;
     scriptsReady?: Promise<void>;
     obsoleteStyles: Element[];
+    glide?: PageGlide;
     releaseOutgoing?: () => void;
 }
 
@@ -251,12 +252,17 @@ export function installSwupRouter(): Swup {
         const next = visit.to.document;
         if (!context || !next || !replace) throw new Error("Missing Swup document");
         if (context.controller.signal.aborted) return;
-        // Keep the old page readable until HTML, styles and fonts are ready.
+        // Two cues overlap on the outgoing document: a bounded fade on the
+        // changing content region, and the whole page walking back to the top.
+        // The frame, sidebars and header are never part of either one.
         if (context.navigationType !== "traverse" && context.preset !== "none") {
-            context.releaseOutgoing = await animateRouteOut(
+            const outgoing = animateRouteOut(
                 document.querySelector<HTMLElement>("[data-stalux-motion-focus]"),
                 context.controller.signal,
             );
+            if (!context.to.hash) context.glide = glideToTop();
+            await context.glide?.promise;
+            context.releaseOutgoing = await outgoing;
             if (context.controller.signal.aborted || visit !== swup.visit) {
                 context.releaseOutgoing();
                 return;
@@ -270,6 +276,7 @@ export function installSwupRouter(): Swup {
         context.motion = prepareRouteMotion(dispatchNavigation("astro:before-swap", context, next));
         if (context.controller.signal.aborted) return;
         await replace(visit, args);
+        // The old region is detached; drop any fill effect left on it.
         context.releaseOutgoing?.();
         if (context.controller.signal.aborted) return;
         for (const element of context.obsoleteStyles) element.remove();
@@ -349,7 +356,7 @@ export function installSwupRouter(): Swup {
     const cancel = (visit: Visit) => {
         const context = contexts.get(visit);
         context?.controller.abort();
-        context?.releaseOutgoing?.();
+        context?.glide?.cancel();
         context?.motion?.cancel();
         if (context === activeContext) {
             clearMotionState();
@@ -361,7 +368,7 @@ export function installSwupRouter(): Swup {
     swup.hooks.on("visit:fail", cancel);
     swup.hooks.on("visit:end", (visit) => {
         const context = contexts.get(visit);
-        context?.releaseOutgoing?.();
+        context?.glide?.cancel();
         context?.motion?.start(null, { skip: true });
         if (activeContext === context) {
             clearMotionState();