@xingwangzhe/stalux 1.2.0

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

@@ -0,0 +1,134 @@
+---
+import style from "@styles/components/posts/randomPost.module.css";
+import { getCollection } from "astro:content";
+import { createTranslator } from "@utils/i18n";
+
+interface Props {
+    count?: number;
+    title?: string;
+}
+
+const configEntries = await getCollection("config");
+const siteConfig = (configEntries.find(e => e.id === "site")?.data ?? {}) as Record<string, unknown>;
+const { t } = createTranslator((siteConfig.lang as string) || "zh-CN");
+const { count = 5, title = t("randomPost.title") } = Astro.props;
+---
+
+<aside class={style.container} transition:persist-props aria-label={t("randomPost.title")}>
+    <div class={style.header}>
+        <h3 class={style.title}>{title}</h3>
+        <button
+            id="refresh-random-posts"
+            class={style.refreshButton}
+            title={t("randomPost.refresh")}
+            aria-label={t("randomPost.refresh")}
+        >
+            <svg
+                xmlns="http://www.w3.org/2000/svg"
+                width="16"
+                height="16"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                stroke-width="2"
+                stroke-linecap="round"
+                stroke-linejoin="round"
+            >
+                <path
+                    d="M21.5 2v6h-6M2.5 22v-6h6M2 11.5a10 10 0 0 1 18.8-4.3M22 12.5a10 10 0 0 1-18.8 4.2"
+                ></path>
+            </svg>
+        </button>
+    </div>
+    <ul class={style.list} id="random-posts-list">
+        <li class={style.loading}>{t("randomPost.loading")}</li>
+	    </ul>
+	</aside>
+
+<script define:vars={{ count, labels: { noPosts: t("randomPost.noPosts"), loadFailed: t("randomPost.loadFailed"), loadError: t("randomPost.loadError") } }}>
+    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+    // 费雪-耶茨洗牌（crypto 优先，回退 Math.random）
+    const shuffleArray = (array) => {
+        const shuffled = [...array];
+        const randomIndex = (max) => {
+            if (globalThis.crypto?.getRandomValues) {
+                const buf = new Uint32Array(1);
+                crypto.getRandomValues(buf);
+                return buf[0] % max;
+            }
+            return Math.floor(Math.random() * max);
+        };
+        for (let i = shuffled.length - 1; i > 0; i--) {
+            const j = randomIndex(i + 1);
+            [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+        }
+        return shuffled;
+    };
+
+    const fetchRandomPosts = async () => {
+        try {
+            const response = await fetch("/api/post.abbrlink.json");
+            if (!response.ok) throw new Error(`HTTP error! status: ${response.status}`);
+            return (await response.json()) ?? [];
+        } catch (error) {
+            console.error("Failed to fetch posts:", error);
+            return [];
+        }
+    };
+
+    const generatePostsHTML = (posts) => {
+        if (posts.length === 0) {
+            return `<li class="no-posts">${labels.noPosts}</li>`;
+        }
+        return posts
+            .map(
+                (post) => `
+            <li class="random-post-item">
+                <a href="/posts/${post.abbrlink}/" class="random-post-link a-none">
+                    ${post.title}
+                </a>
+            </li>
+        `,
+            )
+            .join("");
+    };
+
+    const renderRandomPosts = async (listEl, emptyMsg, errorMsg) => {
+        try {
+            const allPosts = await fetchRandomPosts();
+            if (allPosts.length === 0) {
+                listEl.innerHTML = `<li class="no-posts">${emptyMsg}</li>`;
+                return;
+            }
+            listEl.innerHTML = generatePostsHTML(shuffleArray(allPosts).slice(0, count));
+        } catch (error) {
+            console.error("Error rendering random posts:", error);
+            listEl.innerHTML = `<li class="error">${errorMsg}</li>`;
+        }
+    };
+
+    const refreshRandomPosts = async () => {
+        const randomPostsList = document.getElementById("random-posts-list");
+        if (!randomPostsList) return;
+
+        randomPostsList.style.opacity = "0.5";
+        await sleep(300);
+        await renderRandomPosts(randomPostsList, labels.noPosts, labels.loadFailed);
+        randomPostsList.style.opacity = "1";
+    };
+
+    document.addEventListener("astro:page-load", () => {
+        const refreshButton = document.getElementById("refresh-random-posts");
+        refreshButton?.addEventListener("click", async (e) => {
+            e.preventDefault();
+            refreshButton.classList.add("rotating");
+            await refreshRandomPosts();
+            await sleep(600);
+            refreshButton.classList.remove("rotating");
+        });
+
+        const list = document.getElementById("random-posts-list");
+        if (list) void renderRandomPosts(list, labels.noPosts, labels.loadError);
+    });
+</script>

package/src/components/stalux/tags/tagHeader.astro

@@ -0,0 +1,50 @@
+---
+interface Props {
+    type: string;
+    typeKey?: string;
+    name: string;
+    count: number;
+}
+const props = Astro.props as Props;
+import { getCollection } from "astro:content";
+import { getSiteData } from "@utils/config-utils";
+import { createTranslator } from "@utils/i18n";
+import styles from "@styles/components/tags/tagHeader.module.css";
+
+const configEntries = await getCollection("config");
+const siteConfig = getSiteData(configEntries);
+const { t } = createTranslator(siteConfig.lang || "zh-CN");
+
+const typeKey = props.typeKey || props.type;
+let typeUrl = "";
+if (typeKey === "category" || typeKey === "categories" || typeKey === "分类") {
+    typeUrl = "/categories/";
+} else if (typeKey === "tag" || typeKey === "tags" || typeKey === "标签") {
+    typeUrl = "/tags/";
+}
+---
+
+<header class={styles.pageHeader}>
+    <h1 class={styles.pageTitle}>
+        <span class={styles.categoryIcon}>
+            <svg
+                xmlns="http://www.w3.org/2000/svg"
+                viewBox="0 0 24 24"
+                width="28"
+                height="28"
+                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>
+        </span>
+        {props.type}: {props.name}
+    </h1>
+    <p class={styles.pageDescription}>{t("taxonomy.foundPosts", { count: props.count })}</p>
+    <a href={typeUrl} class={styles.backLink} data-astro-prefetch>{t("taxonomy.backToList", { type: props.type })}</a>
+</header>

package/src/components/stalux/tags/tagsCloud.astro

@@ -0,0 +1,100 @@
+---
+import { getTagCountList } from "@utils/collections-stats";
+import { getCollection } from "astro:content";
+import { getSiteData } from "@utils/config-utils";
+import { createTranslator } from "@utils/i18n";
+import styles from "@styles/components/tags/tagsCloud.module.css";
+
+const configEntries = await getCollection("config");
+const siteConfig = getSiteData(configEntries);
+const { t } = createTranslator(siteConfig.lang || "zh-CN");
+const tagList = await getTagCountList();
+const tagLinks = tagList.map((t) => ({ type: "link" as const, text: t.name, url: `/tags/${t.name}/` }));
+---
+
+<!-- 移动端：SSR 卡片 -->
+<div class={styles.cards} id="tags-cards">
+    {
+        tagList.length > 0 ? (
+            tagList.map(({ name, count }) => (
+                <a
+                    href={`/tags/${name}/`}
+                    class={styles.tagCard}
+                    data-count={count}
+                    data-astro-prefetch
+                >
+                    <span class={styles.tagName}>{name}</span>
+                    <span class={styles.tagCount}>{count}</span>
+                </a>
+            ))
+        ) : (
+            <div class={styles.noTags}>{t("tags.noTags")}</div>
+        )
+    }
+</div>
+
+<!-- 桌面端：Canvas 标签云 -->
+<div
+    class={styles.canvas}
+    id="tags-canvas"
+    data-tags={JSON.stringify(tagLinks)}
+></div>
+
+<script>
+    import { TagCloud } from "@xingwangzhe/tags-cloud";
+    import { stagger, createTimeline } from "animejs";
+
+    document.addEventListener("astro:page-load", () => {
+        // ── 移动端卡片入场动画 ──
+        const cardsContainer = document.getElementById("tags-cards");
+        if (cardsContainer && window.matchMedia("(max-width: 768px)").matches) {
+            if (!cardsContainer.dataset.animated) {
+                cardsContainer.dataset.animated = "1";
+                const cards = cardsContainer.querySelectorAll<HTMLElement>(".tagCard");
+                if (cards.length > 0) {
+                    cards.forEach((c) => (c.style.opacity = "0"));
+                    createTimeline().add(
+                        cards,
+                        { opacity: [0, 1], duration: 400, ease: "outExpo", delay: stagger(30, { start: 0 }) },
+                        0,
+                    );
+                }
+            }
+        }
+
+        // ── 桌面端：3D 标签云 ──
+        const canvasContainer = document.getElementById("tags-canvas");
+        if (!canvasContainer) return;
+        if (canvasContainer.dataset.inited === "1") return;
+        if (window.matchMedia("(max-width: 768px)").matches) return;
+
+        canvasContainer.dataset.inited = "1";
+
+        type LinkTag = { type: "link"; text: string; url: string };
+        const rawTags: LinkTag[] = JSON.parse(canvasContainer.dataset.tags || "[]");
+        if (rawTags.length === 0) return;
+        // 内部链接不应打开新标签页 — TagCloud 默认 link 类型会 window.open(_, _blank)
+        const tags = rawTags.map((t) => ({ ...t, onClick: () => { window.location.href = t.url; } }));
+
+        const N = tags.length;
+        const vw = window.innerWidth;
+        const baseRadius = vw < 1024 ? 330 : vw < 1440 ? 420 : 480;
+        const baseN = 100;
+        const densityScale = Math.sqrt(Math.max(N, baseN) / baseN);
+        const containerWidth = canvasContainer.getBoundingClientRect().width;
+        const maxRadius = Math.round(containerWidth * 0.6);
+        const radius = Math.min(Math.round(baseRadius * densityScale), maxRadius);
+
+        // 扩展容器高度以容纳球体垂直投影（宽度保持 100% 自然居中）
+        canvasContainer.style.height = `${Math.round(radius * 2)}px`;
+
+        new TagCloud(canvasContainer, {
+            tags,
+            radius,
+            spinY: 0.15,
+            fontSize: 16,
+            color: "#ffffff",
+            fontFamily: "system-ui, -apple-system, sans-serif",
+        });
+    });
+</script>

package/src/components/stalux/words/wordCard.astro

@@ -0,0 +1,62 @@
+---
+import type { CollectionEntry } from "astro:content";
+import { render } from "astro:content";
+import styles from "@styles/components/words/wordCard.module.css";
+import "@styles/components/markdown.css";
+import { toMachineDateTime } from "@utils/semantic-time";
+
+interface Props {
+    entry: CollectionEntry<"words">;
+    timezone?: string;
+}
+
+const { entry, timezone } = Astro.props;
+const { Content } = await render(entry);
+const { source, link, sourceDate, date, abbrlink } = entry.data;
+
+const machineDate = date && timezone
+    ? toMachineDateTime(date, timezone)
+    : date;
+---
+
+<article class={styles.card} id={abbrlink ? `word-${abbrlink}` : undefined}>
+    <div class={styles.body} data-pagefind-body>
+        <Content />
+    </div>
+    {
+        (date || source || sourceDate) && (
+            <footer class={styles.footer}>
+                {date ? (
+                    <time class={styles.date} datetime={machineDate}>
+                        {date}
+                    </time>
+                ) : (
+                    <span />
+                )}
+                {
+                    (source || sourceDate) && (
+                        <div class={styles.sourceMeta}>
+                            {sourceDate && (
+                                <span class={styles.sourceDate}>{sourceDate}</span>
+                            )}
+                            {source && (
+                                link ? (
+                                    <a
+                                        href={link}
+                                        target="_blank"
+                                        rel="noopener noreferrer"
+                                        class={styles.sourceLink}
+                                    >
+                                        — {source}
+                                    </a>
+                                ) : (
+                                    <span class={styles.sourceText}>— {source}</span>
+                                )
+                            )}
+                        </div>
+                    )
+                }
+            </footer>
+        )
+    }
+</article>

package/src/components/stalux/words/wordList.astro

@@ -0,0 +1,70 @@
+---
+import WordCard from "@components/stalux/words/wordCard.astro";
+import styles from "@styles/components/words/wordList.module.css";
+import type { CollectionEntry } from "astro:content";
+import { toTimestamp } from "@utils/dayjs";
+
+interface Props {
+    entries: CollectionEntry<"words">[];
+    timezone?: string;
+}
+
+const { entries, timezone } = Astro.props;
+
+const sorted = [...entries].sort((a, b) => {
+    const ta = toTimestamp(a.data.date || a.id);
+    const tb = toTimestamp(b.data.date || b.id);
+    return tb - ta;
+});
+---
+
+<ul class={`${styles.list} stagger-children`}>
+    {
+        sorted.map((entry) => {
+            const hash = entry.data.abbrlink ? `#word-${entry.data.abbrlink}` : undefined;
+            return (
+                <li class={styles.item}>
+                    {hash ? (
+                        <a href="javascript:void(0)" class="a-none" data-word-hash={hash}>
+                            <WordCard entry={entry} timezone={timezone} />
+                        </a>
+                    ) : (
+                        <WordCard entry={entry} timezone={timezone} />
+                    )}
+                </li>
+            );
+        })
+    }
+</ul>
+
+<script>
+    const scrollToWord = (hash) => {
+        const el = document.getElementById(hash.slice(1));
+        if (!el) return;
+
+        // 清除之前的高亮
+        for (const c of document.querySelectorAll("[data-glow]")) {
+            c.removeAttribute("data-glow");
+        }
+        // 高亮当前卡片
+        el.dataset.glow = "";
+
+        el.scrollIntoView({ behavior: "smooth", block: "center" });
+        history.replaceState(null, "", hash);
+    };
+
+    // 页面加载时：覆盖浏览器默认的瞬间跳转（双 rAF 等到布局稳定）
+    if (location.hash.startsWith("#word-")) {
+        requestAnimationFrame(() => {
+            requestAnimationFrame(() => scrollToWord(location.hash));
+        });
+    }
+
+    // 点击卡片时：阻止默认跳转，改为居中平滑滚动
+    document.addEventListener("click", (e) => {
+        const link = e.target.closest("a[data-word-hash]");
+        if (!link) return;
+        e.preventDefault();
+        scrollToWord(link.getAttribute("data-word-hash"));
+    });
+</script>

package/src/config.ts

@@ -0,0 +1,58 @@
+/**
+ * Stalux 集成配置选项
+ *
+ * 用户在 astro.config.mjs 中传入这些选项来自定义主题行为。
+ */
+
+import type { StaluxComponentKey } from "./internal/override";
+
+/** 用户可覆盖的组件映射 */
+export type ComponentOverrideMap = Partial<Record<StaluxComponentKey, string>>;
+
+/** 内容集合路径配置 */
+export interface ContentPaths {
+  /** 内容根目录，默认为 "stalux" */
+  root?: string;
+  /** 文章目录，相对于 root */
+  posts?: string;
+  /** 配置目录，相对于 root */
+  config?: string;
+  /** 关于页面目录，相对于 root */
+  about?: string;
+  /** 随想目录，相对于 root */
+  words?: string;
+}
+
+/** Analytics 配置 */
+export interface AnalyticsConfig {
+  googleAnalyticsId?: string;
+  bingClarityId?: string;
+  umami?: {
+    id: string;
+    url: string;
+  };
+}
+
+/** Stalux 集成选项 */
+export interface StaluxOptions {
+  /** 内容目录路径（默认 "stalux"） */
+  contentDir?: string;
+
+  /** 内容子目录路径覆盖 */
+  contentPaths?: ContentPaths;
+
+  /** 组件覆盖映射 */
+  components?: ComponentOverrideMap;
+
+  /** Analytics 配置 */
+  analytics?: AnalyticsConfig;
+
+  /** 构建后是否自动运行 Pagefind 索引（默认 true） */
+  pagefind?: boolean;
+
+  /** 开发工具栏应用（默认 true） */
+  devToolbar?: boolean;
+
+  /** 站点 URL（默认从 astro.config 读取） */
+  site?: string;
+}

package/src/i18n/en.json

@@ -0,0 +1,193 @@
+{
+    "nav": {
+        "menu": "Open navigation menu",
+        "scrollLeft": "Scroll navigation left",
+        "scrollRight": "Scroll navigation right",
+        "search": "Search"
+    },
+    "search": {
+        "title": "Search",
+        "close": "Close search",
+        "placeholder": "Type keywords to search...",
+        "inputLabel": "Search input",
+        "noResults": "No results found",
+        "typePost": "Post",
+        "typeAbout": "About",
+        "typeWord": "Word"
+    },
+    "page404": {
+        "title": "404 - Page Not Found",
+        "description": "Sorry, the page you are looking for does not exist.",
+        "pageNotFound": "Page Not Found",
+        "countdown": "Redirecting to home in {n} seconds...",
+        "backHome": "Back to Home"
+    },
+    "post": {
+        "publishTime": "Published: ",
+        "updateTime": "Updated: ",
+        "readingTime": "🕒 Reading time: ",
+        "wordCount": "📝 Words: ",
+        "viewCount": "👀 Views: ",
+        "prevPost": "Previous",
+        "nextPost": "Next",
+        "noPrev": "No older posts",
+        "noNext": "No newer posts",
+        "author": "Author: ",
+        "articleLink": "Article link: ",
+        "licensedUnder": "This article is licensed under ",
+        "licenseSuffix": ".",
+        "viewSource": "View Markdown source"
+    },
+    "taxonomy": {
+        "tag": "Tag",
+        "category": "Category",
+        "toc": "Table of Contents",
+        "noTags": "No tags",
+        "noCategories": "No categories",
+        "noToc": "No table of contents",
+        "backToList": "Back to {type} list",
+        "foundPosts": "Found {count} related posts",
+        "browseTag": "Browse {count} articles tagged with “{tag}” on {title}. Explore tutorials, programming notes, and practical content related to this topic of interest.",
+        "browseCategory": "Browse {count} articles under category “{category}” on {title}. Find tutorials, development notes, and practical guides related to this topic area."
+    },
+    "archives": {
+        "title": "Archives",
+        "description": "Browse the complete timeline of all articles on {title}, organized by publication date. Access programming tutorials, dev notes, open source projects, and tech insights in chronological order.",
+        "heading": "Archives",
+        "desc": "All posts on the timeline ({n} total)",
+        "postCount": "{n} posts",
+        "month": "{n}",
+        "noPosts": "No posts",
+        "loadMore": "Load more",
+        "allLoaded": "All content loaded",
+        "viewAll": "View all posts"
+    },
+    "footer": {
+        "visitors": "Visitors: ",
+        "visits": "visitors",
+        "totalVisits": "Total visits: ",
+        "times": "times",
+        "totalWords": "Total words: ",
+        "chars": "chars",
+        "runningTime": "Site running for",
+        "runtimeFormat": "{days}d {hours}h {minutes}m {seconds}s",
+        "rightsReserved": "All rights reserved.",
+        "securityIcon": "Public security filing icon"
+    },
+    "comment": {
+        "title": "Comments",
+        "disclaimer": "Comments are user-generated and do not reflect the views of this site."
+    },
+    "randomPost": {
+        "title": "Random Post",
+        "refresh": "Refresh random post",
+        "loading": "Loading random post...",
+        "noPosts": "No posts available",
+        "loadFailed": "Failed to load, please try again",
+        "loadError": "Load failed"
+    },
+    "categories": {
+        "title": "Categories",
+        "description": "Browse all article categories on {title}, covering web development, Linux operations, open source projects, algorithms, AI, and programming tutorials. Find topics of interest organized by category.",
+        "heading": "Categories",
+        "browseByTopic": "Browse by topic",
+        "postCount": "{n} posts"
+    },
+    "tags": {
+        "title": "Tags",
+        "description": "Explore all tags on {title} — a keyword index covering web development, Linux, open source, AI, algorithms, and programming content. Discover articles by topic tags.",
+        "heading": "Tag Cloud",
+        "explore": "Explore article tags across different topics",
+        "noTags": "No tags"
+    },
+    "words": {
+        "title": "Words",
+        "description": "Collected quotes and snippets",
+        "heading": "Words",
+        "desc": "Fragments of words, voices of the heart ({n} entries)"
+    },
+    "links": {
+        "defaultTitle": "Links",
+        "iconAlt": "{name} icon"
+    },
+    "rss": {
+        "copyright": "Unless otherwise noted, each article is licensed under its own Creative Commons license."
+    },
+    "common": {
+        "uncategorized": "Uncategorized",
+        "minute": "{n} min",
+        "lessThanOneMinute": "Less than 1 min",
+        "tenThousand": "{n}0k",
+        "k": "{n}k",
+        "dateFormat": "MMM dd, yyyy"
+    },
+    "cc": {
+        "format": "Creative Commons {elements} {version} International License",
+        "zero": "CC0 1.0 Universal",
+        "BY": "Attribution",
+        "NC": "NonCommercial",
+        "SA": "ShareAlike",
+        "ND": "NoDerivatives"
+    },
+    "console": {
+        "name": "Stalux - Modern Astro Blog Theme",
+        "author": "xingwangzhe",
+        "copyright": "© xingwangzhe. All rights reserved.",
+        "certNumber": "Software Copyright No. 16914672",
+        "certUrl": "https://stalux.needhelp.icu/软著证明.pdf",
+        "regDate": "2025-11-24",
+        "labelVersion": "📦 Version: ",
+        "labelAuthor": "👤 Author: ",
+        "labelRepo": "🔗 Repository: ",
+        "labelWebsite": "🌐 Website: ",
+        "labelCert": "📜 Certificate: ",
+        "labelCertNumber": "🎫 Registration No.: ",
+        "labelRegDate": "📅 Registration Date: ",
+        "labelLicense": "⚖️  License: ",
+        "labelAuthNote": "✅ Authorization: ",
+        "labelTip": "💡 Tip: ",
+        "labelFeedback": "🐛 Feedback: ",
+        "authNote": "This software is licensed under the MIT open source license. You are free to use, modify, and distribute this software, but please retain the original copyright notice.",
+        "tip": "If you like this theme, please give us a ⭐️ on GitHub!",
+        "feedback": "https://github.com/xingwangzhe/stalux/issues"
+    },
+    "ai": {
+        "contact": "Contact",
+        "author": "Author",
+        "email": "Email",
+        "socialMedia": "Social media",
+        "noContact": "No public contact information available",
+        "posts": "Posts",
+        "noPosts": "No posts available",
+        "untitled": "Untitled",
+        "pages": "Pages",
+        "about": "About",
+        "aboutDesc": "About the author",
+        "archives": "Archives",
+        "archivesDesc": "All posts archive",
+        "tags": "Tags",
+        "tagsDesc": "Tags index",
+        "categories": "Categories",
+        "categoriesDesc": "Categories index",
+        "words": "Words",
+        "wordsDesc": "Quotes and snippets",
+        "links": "Links",
+        "aiDiscoveryFiles": "AI Discovery Files",
+        "llmsTxtDesc": "Site summary and post index",
+        "llmsFullTxtDesc": "Full-text Markdown dataset of all posts",
+        "optional": "Optional",
+        "morePosts": "More posts",
+        "rss": "RSS Feed",
+        "atom": "Atom Feed",
+        "mdAvailable": "Markdown source available for each post; links point to .md versions",
+        "siteLicense": "Unless otherwise noted, content on this site is licensed under CC-BY-NC-SA-4.0.",
+        "fullDataset": "LLM Full-Text Dataset",
+        "fullDatasetDesc": "The complete Markdown source of all public posts, for LLM training and citation.",
+        "license": "Content license",
+        "postCount": "Post count",
+        "markdownSources": "Markdown Sources",
+        "latestPosts": "Latest Posts",
+        "allCategories": "All Categories",
+        "allTags": "All Tags"
+    }
+}