@xingwangzhe/stalux 1.30.3 → 1.31.0

package/README.md

@@ -10,6 +10,8 @@
 
 A dark-themed, high-performance Astro blog theme with elegant glassmorphism design, native per-page CJK font subsets, and a focus on content-first reading experience.
 
+All HTML routes include a circular back-to-top button at the bottom right. It appears after scrolling 240px and scrolls smoothly to the top, respecting reduced motion preferences. A 64px right gutter keeps it clear of content; it is hidden when printing. No configuration is required.
+
 ---
 
 ## 🚀 Quick Start

package/package.json

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

package/src/components/stalux/categories/categoriesCard.astro

@@ -20,35 +20,37 @@ const siteConfig = (configEntries.find((e) => e.id === "site")?.data ?? {}) as R
 const { t } = createTranslator((siteConfig.lang as string) || "zh-CN");
 ---
 
-<article class="stalux-category-card">
-    <a
-        href={`/categories/${props.category.name}/`}
-        class="stalux-categoryheader a-none"
-        data-astro-prefetch
-    >
-        <div class="stalux-category-icon">
-            <svg
-                aria-hidden="true"
-                xmlns="http://www.w3.org/2000/svg"
-                viewBox="0 0 24 24"
-                width="24"
-                height="24"
-                fill="none"
-                stroke="currentColor"
-                stroke-width="2"
-                stroke-linecap="round"
-                stroke-linejoin="round"
-            >
-                <path
-                    d="M22 19a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h5l2 3h9a2 2 0 0 1 2 2z"
-                ></path>
-            </svg>
-        </div>
-        <div class="stalux-category-content">
-            <h2 class="categoryName">{props.category.name}</h2>
-            <div class="categoryCount">
-                {t("categories.postCount", { n: props.category.count })}
+<div class="stalux-category-shell">
+    <article class="stalux-category-card">
+        <a
+            href={`/categories/${props.category.name}/`}
+            class="stalux-categoryheader a-none"
+            data-astro-prefetch
+        >
+            <div class="stalux-category-icon">
+                <svg
+                    aria-hidden="true"
+                    xmlns="http://www.w3.org/2000/svg"
+                    viewBox="0 0 24 24"
+                    width="24"
+                    height="24"
+                    fill="none"
+                    stroke="currentColor"
+                    stroke-width="2"
+                    stroke-linecap="round"
+                    stroke-linejoin="round"
+                >
+                    <path
+                        d="M22 19a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h5l2 3h9a2 2 0 0 1 2 2z"
+                    ></path>
+                </svg>
             </div>
-        </div>
-    </a>
-</article>
+            <div class="stalux-category-content">
+                <h2 class="categoryName">{props.category.name}</h2>
+                <div class="categoryCount">
+                    {t("categories.postCount", { n: props.category.count })}
+                </div>
+            </div>
+        </a>
+    </article>
+</div>

package/src/components/stalux/layout/BackToTop.astro

@@ -0,0 +1,69 @@
+---
+import { ArrowUp } from "@lucide/astro";
+
+const { lang = "zh-CN" } = Astro.props;
+const label = lang.startsWith("zh") ? "回到顶部" : "Back to top";
+---
+
+<button
+    type="button"
+    class="stalux-back-to-top"
+    data-stalux-back-to-top
+    aria-label={label}
+    title={label}
+    hidden
+>
+    <ArrowUp size={20} aria-hidden="true" />
+</button>
+
+<script>
+import { mountBackToTop } from "../../../scripts/back-to-top";
+import { registerPageLifecycle } from "../../../scripts/page-runtime";
+
+registerPageLifecycle("back-to-top", mountBackToTop);
+</script>
+
+<style is:global>
+/* Reserve a rail outside content, including on narrow screens. */
+.stalux-root {
+    box-sizing: border-box;
+    padding-right: calc(64px + env(safe-area-inset-right, 0px));
+}
+.stalux-back-to-top {
+    position: fixed;
+    right: calc(10px + env(safe-area-inset-right, 0px));
+    bottom: calc(20px + env(safe-area-inset-bottom, 0px));
+    width: 44px;
+    height: 44px;
+    display: grid;
+    place-items: center;
+    padding: 0;
+    border: 1px solid var(--stalux-accent-color);
+    border-radius: 50%;
+    color: var(--stalux-accent-color);
+    background: #202020;
+    box-shadow: 0 2px 12px #0006;
+    cursor: pointer;
+    z-index: 20;
+}
+.stalux-back-to-top[hidden] {
+    display: none;
+}
+.stalux-back-to-top:focus-visible {
+    outline: 2px solid white;
+    outline-offset: 3px;
+}
+@media (hover: hover) {
+    .stalux-back-to-top:hover {
+        background: #353535;
+    }
+}
+@media print {
+    .stalux-root {
+        padding-right: 0;
+    }
+    .stalux-back-to-top {
+        display: none;
+    }
+}
+</style>

package/src/components/stalux/links/linkCard.astro

@@ -29,18 +29,20 @@ const desc = link.description ?? "";
 const icon = link.icon ?? link.avatar ?? "/favicon.ico";
 ---
 
-<a class="stalux-link-card" href={href} target="_blank" rel="noopener">
-    <div class="stalux-link-card-avatar">
-        <img
-            src={icon}
-            alt={t("links.iconAlt", { name: title })}
-            loading="lazy"
-            width="80"
-            height="80"
-        >
-    </div>
-    <div class="stalux-link-card-content">
-        <h2 class="stalux-link-card-title">{title}</h2>
-        {desc && <p class="stalux-link-card-description">{desc}</p>}
+<a class="stalux-link-shell a-none" href={href} target="_blank" rel="noopener">
+    <div class="stalux-link-card">
+        <div class="stalux-link-card-avatar">
+            <img
+                src={icon}
+                alt={t("links.iconAlt", { name: title })}
+                loading="lazy"
+                width="80"
+                height="80"
+            >
+        </div>
+        <div class="stalux-link-card-content">
+            <h2 class="stalux-link-card-title">{title}</h2>
+            {desc && <p class="stalux-link-card-description">{desc}</p>}
+        </div>
     </div>
 </a>

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

@@ -20,7 +20,7 @@ const timezone = siteConfig.timezone;
 const description = post.data.desc || "";
 ---
 
-<article class="block h-full text-inherit no-underline">
+<article class="stalux-post-card-shell block h-full text-inherit no-underline">
     <div class="stalux-post-card stalux-u-flex stalux-u-flex-col stalux-u-w-full stalux-u-min-w-0">
         {post.data.cover && (
     <a

package/src/internal/html-images.ts

@@ -0,0 +1,65 @@
+import { type DefaultTreeAdapterMap, parse } from "parse5";
+
+export interface HtmlImage {
+    start: number;
+    end: number;
+    tag: string;
+    attributes: Map<string, string>;
+    locations: Map<string, { startOffset: number; endOffset: number }>;
+    body?: number;
+}
+
+/** Source ranges preserve scripts and code-copy attributes byte-for-byte. */
+export function findHtmlImages(html: string): HtmlImage[] {
+    const images: HtmlImage[] = [];
+    function visit(node: DefaultTreeAdapterMap["node"], body?: number) {
+        if ("tagName" in node) {
+            if (node.tagName === "template") return;
+            const location = node.sourceCodeLocation;
+            if (
+                node.tagName === "section" &&
+                node.attrs.some((attr) => attr.name === "data-pagefind-body")
+            )
+                body = location?.startOffset;
+            if (node.tagName === "img" && location?.startTag) {
+                const { startOffset: start, endOffset: end } = location.startTag;
+                images.push({
+                    start,
+                    end,
+                    tag: html.slice(start, end),
+                    attributes: new Map(node.attrs.map((attr) => [attr.name, attr.value])),
+                    locations: new Map(Object.entries(location.attrs ?? {})),
+                    body,
+                });
+            }
+        }
+        if ("childNodes" in node) for (const child of node.childNodes) visit(child, body);
+    }
+    visit(parse(html, { sourceCodeLocationInfo: true }));
+    return images.sort((left, right) => left.start - right.start);
+}
+
+export function updateImageTag(image: HtmlImage, updates: Record<string, string>): string {
+    let tag = image.tag;
+    const edits: Array<{ start: number; end: number; value: string }> = [];
+    const additions: string[] = [];
+    for (const [name, value] of Object.entries(updates)) {
+        const attribute = `${name}="${value.replaceAll("&", "&amp;").replaceAll('"', "&quot;")}"`;
+        const location = image.locations.get(name);
+        if (location)
+            edits.push({
+                start: location.startOffset - image.start,
+                end: location.endOffset - image.start,
+                value: attribute,
+            });
+        else additions.push(attribute);
+    }
+    for (const edit of edits.sort((left, right) => right.start - left.start))
+        tag = tag.slice(0, edit.start) + edit.value + tag.slice(edit.end);
+    if (additions.length)
+        tag = tag.replace(
+            /\s*\/?\s*>$/,
+            (ending) => ` ${additions.join(" ")}${ending.trimStart()}`,
+        );
+    return tag;
+}

package/src/internal/image-dimensions.ts

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
+import { findHtmlImages, updateImageTag } from "./html-images";
 
 export type ImageDimensions = { width: number; height: number };
 
@@ -74,12 +75,11 @@ export function readImageDimensions(data: Buffer): ImageDimensions | undefined {
 export async function addLocalImageDimensions(html: string, outputDir: string): Promise<string> {
     const dimensionsCache = new Map<string, Promise<ImageDimensions | undefined>>();
     const root = path.resolve(outputDir);
-    const tags = [...html.matchAll(/<img\b[^>]*>/gi)];
+    const tags = findHtmlImages(html);
 
-    for (const match of tags) {
-        const tag = match[0];
-        if (!tag || (/\swidth=/i.test(tag) && /\sheight=/i.test(tag))) continue;
-        const src = tag.match(/\ssrc="([^"]+)"/i)?.[1];
+    for (const image of tags.reverse()) {
+        if (image.attributes.has("width") && image.attributes.has("height")) continue;
+        const src = image.attributes.get("src");
         if (!src) continue;
 
         let filePath: string;
@@ -102,21 +102,11 @@ export async function addLocalImageDimensions(html: string, outputDir: string):
         const size = await dimensions;
         if (!size || size.width <= 0 || size.height <= 0) continue;
 
-        const hasWidth = /\swidth=/i.test(tag);
-        const hasHeight = /\sheight=/i.test(tag);
-        const updated =
-            hasWidth && !hasHeight
-                ? tag.replace(/\s*\/?\s*>$/, (ending) => ` height="${size.height}"${ending}`)
-                : hasHeight && !hasWidth
-                  ? tag.replace(
-                        /\sheight="[^"]*"/i,
-                        ` width="${size.width}" height="${size.height}"`,
-                    )
-                  : tag.replace(
-                        /\s*\/?\s*>$/,
-                        (ending) => ` width="${size.width}" height="${size.height}"${ending}`,
-                    );
-        html = html.replace(tag, updated);
+        const updates: Record<string, string> = {};
+        if (!image.attributes.has("width")) updates.width = String(size.width);
+        if (!image.attributes.has("height")) updates.height = String(size.height);
+        const updated = updateImageTag(image, updates);
+        html = html.slice(0, image.start) + updated + html.slice(image.end);
     }
     return html;
 }

package/src/layouts/Stalux.astro

@@ -1,5 +1,6 @@
 ---
 import { getCollection } from "astro:content";
+import BackToTop from "@components/stalux/layout/BackToTop.astro";
 import Footer from "@components/stalux/layout/footer.astro";
 import Head from "@components/stalux/layout/head.astro";
 import { getAccentColorStyle } from "@utils/accent-color";
@@ -103,5 +104,6 @@ const routeAnimation = getRouteAnimation(routeKind);
             <slot />
         </main>
         <Footer />
+        <BackToTop lang={htmlLang} />
     </body>
 </html>

package/src/plugins/feature-flags.ts

@@ -16,6 +16,7 @@ import type { HastVisitorContext, MdastNode, MdastVisitorContext } from "satteri
  * - 数学公式由 satteri-temml 插件直接输出 MathML，无需额外标记
  */
 import { defineHastPlugin, defineMdastPlugin } from "satteri";
+import { findHtmlImages, updateImageTag } from "../internal/html-images";
 import { logDetail } from "../utils/diagnostics";
 
 declare module "satteri" {
@@ -246,44 +247,25 @@ export function applyImageLoadingPolicy(
 }
 
 export function applyHtmlImageLoadingPolicy(html: string): string {
-    return html.replace(
-        /<section\b(?=[^>]*\bdata-pagefind-body\b)[^>]*>[\s\S]*?<\/section>/gi,
-        (body) => {
-            let imageIndex = 0;
-            return body.replace(/<img\b[^>]*>/gi, (tag) => {
-                const isFirstBodyImage = imageIndex++ === 0;
-                const attributes = new Map<string, string>();
-                for (const match of tag.matchAll(/\s([\w:-]+)(?:="([^"]*)")?/g)) {
-                    const name = match[1];
-                    if (name) attributes.set(name.toLowerCase(), match[2] ?? "");
-                }
-
-                const updates: Record<string, string> = {
-                    decoding: attributes.get("decoding") || "async",
-                    loading: isFirstBodyImage ? "eager" : "lazy",
-                };
-                if (isFirstBodyImage) {
-                    updates.fetchpriority = "high";
-                } else if (attributes.get("fetchpriority") === "high") {
-                    updates.fetchpriority = "auto";
-                }
-
-                let result = tag;
-                for (const [name, value] of Object.entries(updates)) {
-                    const pattern = new RegExp(`\\s${name}(?:="[^"]*")?`, "i");
-                    if (pattern.test(result)) {
-                        result = result.replace(pattern, ` ${name}="${value}"`);
-                    } else {
-                        result = result.replace(
-                            /\s*\/?>$/,
-                            (ending) => ` ${name}="${value}"${ending.trimStart()}`,
-                        );
-                    }
-                }
-                return result;
-            });
-        },
-    );
+    const firstSeen = new Set<number>();
+    const changes = findHtmlImages(html)
+        .filter((image) => image.body !== undefined)
+        .map((image) => {
+            const body = image.body as number;
+            const first = !firstSeen.has(body);
+            firstSeen.add(body);
+            const updates: Record<string, string> = {
+                decoding: image.attributes.get("decoding") || "async",
+                loading: first ? "eager" : "lazy",
+            };
+            if (first) updates.fetchpriority = "high";
+            else if (image.attributes.get("fetchpriority") === "high")
+                updates.fetchpriority = "auto";
+            return { image, tag: updateImageTag(image, updates) };
+        });
+    for (const { image, tag } of changes.reverse())
+        html = html.slice(0, image.start) + tag + html.slice(image.end);
+    return html;
 }
 
 type FeatureFlagsResult = {

package/src/scripts/back-to-top.ts

@@ -0,0 +1,23 @@
+/** Bind to the current page DOM; the shared lifecycle disposes before a body swap. */
+export function mountBackToTop() {
+    const button = document.querySelector<HTMLButtonElement>("[data-stalux-back-to-top]");
+    if (!button) return;
+    const update = () => {
+        button.hidden = window.scrollY < 240;
+    };
+    const scrollToTop = () => {
+        window.scrollTo({
+            top: 0,
+            behavior: window.matchMedia("(prefers-reduced-motion: reduce)").matches
+                ? "instant"
+                : "smooth",
+        });
+    };
+    update();
+    window.addEventListener("scroll", update, { passive: true });
+    button.addEventListener("click", scrollToTop);
+    return () => {
+        window.removeEventListener("scroll", update);
+        button.removeEventListener("click", scrollToTop);
+    };
+}

package/src/styles/base.css

@@ -48,7 +48,7 @@
     }
 
     /* 下划线动画 */
-    a::after {
+    a:not(.a-none):not([class*="card"]):not(.stalux-nav-link)::after {
         content: "";
         position: absolute;
         left: 0;
@@ -61,19 +61,27 @@
         transition: transform 0.25s cubic-bezier(0.25, 0.9, 0.2, 1);
         pointer-events: none;
     }
-
-    a:hover::after,
-    a:focus-visible::after,
-    a:active::after {
+    a:not(.a-none):not([class*="card"]):not(.stalux-nav-link):focus-visible::after,
+    a:not(.a-none):not([class*="card"]):not(.stalux-nav-link):active::after {
         transform: scaleX(1);
     }
+    @media (hover: hover) and (pointer: fine) {
+        a:not(.a-none):not([class*="card"]):not(.stalux-nav-link):hover::after {
+            transform: scaleX(1);
+        }
+    }
 
-    a:hover,
     a:active,
     a:focus-visible {
         text-decoration: none;
         /* 保持颜色不变，避免 hover 时颜色跳变 */
     }
+    @media (hover: hover) and (pointer: fine) {
+        a:hover {
+            text-decoration: none;
+            /* 保持颜色不变，避免 hover 时颜色跳变 */
+        }
+    }
 
     a:focus {
         outline: none;
@@ -240,9 +248,10 @@
         border-radius: 4px;
         transition: background 0.3s ease-out;
     }
-
-    ::-webkit-scrollbar-thumb:hover {
-        background: #5a5a5a;
+    @media (hover: hover) and (pointer: fine) {
+        ::-webkit-scrollbar-thumb:hover {
+            background: #5a5a5a;
+        }
     }
 
     ::-webkit-scrollbar-corner {
@@ -285,3 +294,81 @@
         -webkit-backdrop-filter: blur(16px);
     }
 }
+
+@layer components {
+    .stalux-main,
+    .stalux-post-page,
+    .stalux-post-layout > *,
+    .stalux-link-card-content,
+    .stalux-word-list-item,
+    .stalux-word-card {
+        min-width: 0;
+        max-width: 100%;
+        box-sizing: border-box;
+    }
+    .stalux-main {
+        overflow-wrap: anywhere;
+    }
+    .stalux-link-shell {
+        display: block;
+        min-width: 0;
+        max-width: 100%;
+    }
+    .stalux-link-card {
+        box-sizing: border-box;
+        max-width: 100%;
+        width: 100%;
+    }
+    .stalux-category-shell {
+        min-width: 0;
+        width: 100%;
+    }
+    .stalux-author-figure > a {
+        display: inline-block;
+        flex-shrink: 0;
+    }
+    .stalux-author-figure img {
+        display: block;
+    }
+    .stalux-post-card-shell,
+    .stalux-category-shell,
+    .stalux-link-shell {
+        position: relative;
+    }
+    .stalux-post-card,
+    .stalux-category-card,
+    .stalux-link-card,
+    .stalux-word-card {
+        transition:
+            transform 200ms ease,
+            background-color 200ms ease,
+            border-color 200ms ease,
+            box-shadow 200ms ease;
+    }
+    :is(.stalux-post-card-shell, .stalux-category-shell):focus-within > *,
+    .stalux-link-shell:focus-visible > * {
+        box-shadow: var(--card-box-shadow-hover);
+    }
+    :is(button, summary, [role="button"]):focus-visible {
+        outline: 2px solid var(--stalux-accent-color);
+        outline-offset: 3px;
+    }
+    @media (prefers-reduced-motion: reduce) {
+        .stalux-main *,
+        .stalux-main *::before,
+        .stalux-main *::after {
+            animation: none !important;
+            transition-duration: 0ms !important;
+        }
+        .stalux-post-card,
+        .stalux-category-card,
+        .stalux-link-card,
+        .stalux-link-card-content,
+        .stalux-card-post-cover img,
+        .stalux-category-icon,
+        .stalux-author-figure img,
+        .stalux-link-card-avatar img {
+            transform: none !important;
+        }
+    }
+}