@coffic/cosy-ui 0.4.5 → 0.4.9

package/dist/components/base/Module.astro

@@ -0,0 +1,18 @@
+---
+import { Image } from 'astro:assets';
+import type { ImageMetadata } from 'astro';
+
+interface Props {
+  title: string;
+  description: string;
+  image: ImageMetadata;
+}
+
+const { title, description, image } = Astro.props;
+---
+
+<div class="flex flex-col items-center gap-4">
+  <Image src={image} alt={title} class="w-48 h-48 object-contain" />
+  <h3 class="text-xl font-semibold">{title}</h3>
+  <p class="text-gray-600">{description}</p>
+</div>

package/dist/components/base/Speak.astro

@@ -0,0 +1,22 @@
+---
+import { Image } from 'astro:assets';
+import type { ImageMetadata } from 'astro';
+
+interface Props {
+  speakerName: string;
+  speakerTitle: string;
+  image: ImageMetadata;
+  words: string;
+}
+
+const { speakerName, speakerTitle, image, words } = Astro.props;
+---
+
+<div class="flex flex-col items-center gap-4 p-6 bg-white rounded-lg shadow-lg">
+  <Image src={image} alt={speakerName} class="w-32 h-32 object-contain" width={128} height={128} />
+  <div class="text-center">
+    <h3 class="text-xl font-semibold">{speakerName}</h3>
+    <p class="text-gray-600">{speakerTitle}</p>
+  </div>
+  <p class="text-gray-700 italic">{words}</p>
+</div>

package/dist/components/layouts/AppLayout.astro

@@ -184,7 +184,7 @@ const {
 	showSidebar = true,
 	class: className,
 	'class:list': classList,
-	debug = true,
+	debug = false,
 	mainContentConfig,
 	footerConfig,
 	headerConfig,

package/dist/components/layouts/Header.astro

@@ -58,7 +58,7 @@ import '../../app.css';
 import Link from '../base/Link.astro';
 import Image from '../base/Image.astro';
 import type { HeaderProps } from '../../index';
-import Logo from '../../assets/logo.png';
+import Logo from '../../assets/logo-rounded.png';
 
 interface Props extends HeaderProps {}
 

package/dist/components/layouts/Sidebar.astro

@@ -26,9 +26,9 @@ import { isPathMatch } from '../../utils/path';
 import Modal from '../display/Modal.astro';
 import SidebarNav from './SidebarNav.astro';
 import MenuIcon from '../icons/MenuIcon.astro';
-import type { SidebarProps } from '../../types/sidebar';
+import type { SidebarProps } from '../../index';
 
-export interface Props extends SidebarProps{}
+export interface Props extends SidebarProps {}
 
 const {
 	sidebarItems,

package/dist/components/typography/Article.astro

@@ -127,6 +127,7 @@ const baseClasses = [
 	'cosy:mx-auto',
 	'cosy:dark:prose-invert', // 暗黑模式支持,
 	'cosy:m-0',
+	'cosy:min-h-screen',
 	'cosy:pb-96',
 	widthClasses,
 	className,

package/dist/database/BaseDB.ts

@@ -0,0 +1,164 @@
+import { getCollection, getEntry, type CollectionEntry, type DataEntryMap } from "astro:content";
+import { logger } from "../utils/logger";
+
+/**
+ * BaseDB 是所有数据库类的基类，提供了通用的文档操作功能。
+ * 
+ * 使用方法：
+ * ```typescript
+ * class MyDB extends BaseDB<'collection', MyEntry, MyDoc> {
+ *     protected collectionName = 'collection' as const;
+ *     protected createDoc(entry: MyEntry): MyDoc {
+ *         return new MyDoc(entry);
+ *     }
+ * }
+ * 
+ * // 使用单例模式获取实例
+ * const db = MyDB.getInstance();
+ * const docs = await db.allTopLevelDocs();
+ * ```
+ * 
+ * 类型参数说明：
+ * @template Collection - Astro content collection 的名称，必须是 DataEntryMap 的键
+ * @template Entry - Collection 对应的条目类型
+ * @template Doc - 文档类型，通常是自定义的文档类
+ */
+export abstract class BaseDB<
+    Collection extends keyof DataEntryMap,
+    Entry extends CollectionEntry<Collection>,
+    Doc
+> {
+    /** 集合名称，必须在子类中指定 */
+    protected abstract collectionName: Collection;
+
+    /** 
+     * 创建文档实例的方法，必须在子类中实现
+     * @param entry - 集合条目
+     * @returns 文档实例
+     */
+    protected abstract createDoc(entry: Entry): Doc;
+
+    /**
+     * 获取集合中的所有条目
+     * @returns 返回所有条目的数组
+     */
+    async getEntries(): Promise<Entry[]> {
+        const entries = await getCollection(this.collectionName);
+        return entries.map(entry => entry as Entry);
+    }
+
+    /**
+     * 获取指定深度的文档
+     * 深度是指文档 ID 中斜杠的数量加1
+     * 例如：
+     * - "blog.md" 深度为1
+     * - "zh-cn/blog.md" 深度为2
+     * - "zh-cn/tech/blog.md" 深度为3
+     * 
+     * @param depth - 文档深度
+     * @returns 返回指定深度的文档数组
+     */
+    async getDocsByDepth(depth: number): Promise<Doc[]> {
+        const entries = await getCollection(this.collectionName, ({ id }) => id.split('/').length === depth);
+        return entries.map(entry => this.createDoc(entry as Entry));
+    }
+
+    /**
+     * 根据ID查找单个文档
+     * @param id - 文档ID
+     * @returns 返回找到的文档，如果不存在则返回null
+     */
+    async find(id: string): Promise<Doc | null> {
+        const entry = await getEntry(this.collectionName, id);
+        return entry ? this.createDoc(entry as Entry) : null;
+    }
+
+    /**
+     * 获取指定文档的直接子文档（不包括更深层级的文档）
+     * 例如对于文档 "zh-cn/blog"：
+     * - "zh-cn/blog/post1.md" 会被包含
+     * - "zh-cn/blog/2024/post2.md" 不会被包含
+     * 
+     * @param parentId - 父文档ID
+     * @returns 返回子文档数组
+     */
+    async getChildren(parentId: string): Promise<Doc[]> {
+        const parentLevel = parentId.split('/').length;
+        const childrenLevel = parentLevel + 1;
+
+        const entries = await getCollection(this.collectionName,
+            ({ id }) => id.startsWith(parentId) && id.split('/').length === childrenLevel);
+        return entries.map(entry => this.createDoc(entry as Entry));
+    }
+
+    /**
+     * 获取指定文档的所有后代文档（包括所有层级）
+     * 例如对于文档 "zh-cn/blog"，以下都会被包含：
+     * - "zh-cn/blog/post1.md"
+     * - "zh-cn/blog/2024/post2.md"
+     * - "zh-cn/blog/2024/tech/post3.md"
+     * 
+     * @param parentId - 父文档ID
+     * @returns 返回所有后代文档数组
+     */
+    async getDescendantDocs(parentId: string): Promise<Doc[]> {
+        const entries = await getCollection(this.collectionName, ({ id }) => id.startsWith(parentId));
+        return entries.map(entry => this.createDoc(entry as Entry));
+    }
+
+    /**
+     * 获取指定语言的顶级文档
+     * 通过检查文档ID是否以指定语言代码开头来筛选
+     * 
+     * @param lang - 语言代码（如 'zh-cn', 'en'）
+     * @returns 返回指定语言的顶级文档数组
+     */
+    async allDocsByLang(lang: string): Promise<Doc[]> {
+        const debug = false;
+        const docs = await this.getDocsByDepth(2);
+
+        if (debug) {
+            logger.array('所有顶级文档', docs);
+        }
+
+        return docs.filter(doc => {
+            const id = (doc as any).getId();
+            return id && typeof id === 'string' && id.startsWith(lang);
+        });
+    }
+
+    /**
+     * 获取用于 Astro 静态路由生成的路径参数
+     * 为每个文档生成包含语言和slug的路径参数
+     * 
+     * @returns 返回路径参数数组，每个元素包含 lang 和 slug
+     * @example
+     * ```typescript
+     * const paths = await db.getStaticPaths();
+     * // 返回格式：
+     * // [
+     * //   { params: { lang: 'zh-cn', slug: 'post1' } },
+     * //   { params: { lang: 'en', slug: 'post1' } }
+     * // ]
+     * ```
+     */
+    async getStaticPaths() {
+        const debug = false;
+        const docs = await this.getDescendantDocs('');
+        const paths = docs.map((doc) => {
+            const docWithMethods = doc as any;
+            return {
+                params: {
+                    lang: docWithMethods.getLang?.() || '',
+                    slug: docWithMethods.getSlug?.() || '',
+                },
+            };
+        });
+
+        if (debug) {
+            logger.array('所有文档的路径', paths);
+        }
+
+        return paths;
+    }
+} 

package/dist/entities/SidebarItem.ts

@@ -0,0 +1,96 @@
+/**
+ * 侧边栏项目接口
+ */
+export interface SidebarItemProps {
+    label: string;
+    link?: string;
+    items?: SidebarItem[];
+}
+
+/**
+ * 侧边栏项目类
+ * 用于构建网站的侧边栏导航
+ */
+export class SidebarItem {
+    label: string;
+    link: string;
+    items: SidebarItem[];
+
+    constructor(props: SidebarItemProps) {
+        this.label = props.label;
+        this.link = props.link || '';
+        this.items = props.items || [];
+    }
+
+    /**
+     * 添加子项目
+     * @param item 要添加的子项目
+     */
+    addItem(item: SidebarItem): void {
+        this.items.push(item);
+    }
+
+    /**
+     * 获取所有子项目
+     * @returns 子项目数组
+     */
+    getItems(): SidebarItem[] {
+        return this.items;
+    }
+
+    /**
+     * 获取项目标签
+     * @returns 项目标签
+     */
+    getLabel(): string {
+        return this.label;
+    }
+
+    /**
+     * 获取项目链接
+     * @returns 项目链接
+     */
+    getLink(): string {
+        return this.link;
+    }
+
+    /**
+     * 获取包括自身在内的所有项目
+     * @returns 包括自身在内的所有项目
+     */
+    getItemsIncludingSelf(): SidebarItem[] {
+        return [this, ...this.getItems()];
+    }
+
+    /**
+     * 判断是否是分组（有子项目）
+     * @returns 是否是分组
+     */
+    isGroup(): boolean {
+        return this.items.length > 0;
+    }
+
+    /**
+     * 判断是否不是分组
+     * @returns 是否不是分组
+     */
+    isNotGroup(): boolean {
+        return !this.isGroup();
+    }
+}
+
+/**
+ * 侧边栏提供者接口
+ * 实现此接口的类可以提供侧边栏项目
+ */
+export interface SidebarProvider {
+    /**
+     * 转换为侧边栏项目
+     */
+    toSidebarItem(): Promise<SidebarItem>;
+
+    /**
+     * 获取顶级侧边栏项目
+     */
+    getTopSidebarItem?(): Promise<SidebarItem>;
+} 

package/dist/i18n/Language.ts

@@ -0,0 +1,25 @@
+export type LangCode = 'zh-cn' | 'en';
+
+export default class Language {
+    code: LangCode;
+
+    constructor(code: LangCode) {
+        this.code = code;
+    }
+
+    static fromString(lang: string): Language {
+        return new Language(lang as LangCode);
+    }
+
+    isChinese(): boolean {
+        return this.code === 'zh-cn';
+    }
+
+    isEnglish(): boolean {
+        return this.code === 'en';
+    }
+
+    static isCodeValid(code: string): boolean {
+        return code === 'zh-cn' || code === 'en';
+    }
+}

package/dist/i18n/ui.ts

@@ -0,0 +1,18 @@
+export const languages = {
+    en: 'English',
+    'zh-cn': '简体中文',
+};
+
+export const defaultLang = 'zh-cn';
+
+export const ui = {
+    en: {
+        'nav.home': 'Home',
+        'nav.about': 'About',
+        'nav.twitter': 'Twitter',
+    },
+    'zh-cn': {
+        'nav.home': '首页',
+        'nav.about': '关于',
+    },
+} as const;

package/dist/i18n/utils.ts

@@ -0,0 +1,54 @@
+import { ui, defaultLang } from './ui';
+
+export function getLangFromUrl(url: URL) {
+    const [, lang] = url.pathname.split('/');
+    if (lang in ui) return lang as keyof typeof ui;
+    return defaultLang;
+}
+
+export function t(lang: string, key: keyof typeof ui[typeof defaultLang]) {
+    return ui[lang in ui ? lang as keyof typeof ui : defaultLang][key];
+}
+
+export const normalizeLang = (lang: string) => {
+    if (lang === 'zh-CN') {
+        return 'zh-cn';
+    }
+    return lang;
+}
+
+export const getLangFromSlug = (slug: string) => {
+    let lang = slug.split('/')[0];
+
+    return normalizeLang(lang);
+}
+
+export const getLangFromPathname = (pathname: string) => {
+    // 去除开头的 /
+    pathname = pathname.slice(1);
+
+    let lang = pathname.split('/')[0];
+
+    return normalizeLang(lang);
+}
+
+export const isValidLang = (lang: string) => {
+    return ['zh-cn', 'en'].includes(lang);
+}
+
+export const getLang = (...args: string[]) => {
+    const debug = false
+
+    if (debug) {
+        // eslint-disable-next-line no-console
+        console.log('getLang', args);
+    }
+
+    for (const arg of args) {
+        let normalizedLang = normalizeLang(arg);
+        if (isValidLang(normalizedLang)) {
+            return normalizedLang;
+        }
+    }
+    return 'zh-cn';
+}

package/dist/index.ts

@@ -4,6 +4,8 @@ export { default as Link } from './components/base/Link.astro';
 export { default as Image } from './components/base/Image.astro';
 export { default as ThemeItem } from './components/base/ThemeItem.astro';
 export { default as Alert } from './components/base/Alert.astro';
+export { default as Speak } from './components/base/Speak.astro';
+export { default as Module } from './components/base/Module.astro';
 
 // Navigation
 export { default as ThemeSwitcher } from './components/navigation/ThemeSwitcher.astro';
@@ -74,6 +76,8 @@ export * from './utils/i18n';
 export * from './utils/path';
 export * from './utils/url';
 export * from './utils/language';
+export * from './utils/logger';
+export * from './utils/link';
 
 // Types
 export * from './types/sidebar';
@@ -81,5 +85,12 @@ export * from './types/main';
 export * from './types/article';
 export * from './types/layout';
 export * from './types/header';
+export * from './types/heading';
 export * from './types/meta';
 export type { ImageProvider, ImageOptions } from './utils/image';
+
+// Models
+export * from './models/BaseDoc';
+
+// Database
+export * from './database/BaseDB';

package/dist/models/BaseDoc.ts

@@ -0,0 +1,164 @@
+import { render, type RenderResult, type CollectionEntry, type DataEntryMap } from "astro:content";
+import { SidebarItem, type SidebarProvider } from "../entities/SidebarItem";
+import { logger } from "../utils/logger";
+
+/**
+ * 文档基类，提供所有文档类型共享的基本功能
+ */
+export abstract class BaseDoc<Collection extends keyof DataEntryMap, T extends CollectionEntry<Collection>> implements SidebarProvider {
+    protected entry: T;
+
+    constructor(entry: T) {
+        this.entry = entry;
+    }
+
+    /**
+     * 获取文档ID
+     */
+    getId(): string {
+        return this.entry.id;
+    }
+
+    /**
+     * 获取文档标题
+     */
+    getTitle(): string {
+        return this.entry.data.title as string;
+    }
+
+    /**
+     * 获取文档语言
+     */
+    getLang(): string {
+        return this.entry.id.split('/')[0];
+    }
+
+    /**
+     * 获取文档slug
+     */
+    getSlug(): string {
+        return this.getId().split('/').slice(1).join('/');
+    }
+
+    /**
+     * 获取文档描述
+     */
+    getDescription(): string {
+        return this.entry.data.description as string;
+    }
+
+    /**
+     * 获取文档链接
+     * 每个子类必须实现此方法以提供正确的链接
+     */
+    abstract getLink(): string;
+
+    /**
+     * 渲染文档内容
+     */
+    async render(): Promise<RenderResult> {
+        return await render(this.entry);
+    }
+
+    /**
+     * 获取文档的层级深度
+     * 例如：对于 ID 为 "zh-cn/blog/typescript" 的文档，深度为3
+     */
+    getLevel(): number {
+        return this.entry.id.split('/').length;
+    }
+
+    /**
+     * 转换为侧边栏项目
+     * 基本实现，只包含当前文档
+     */
+    async toSidebarItem(): Promise<SidebarItem> {
+        return new SidebarItem({
+            label: this.getTitle(),
+            link: this.getLink(),
+        });
+    }
+}
+
+/**
+ * 层级文档基类，为有层级结构的文档类型提供额外功能
+ * 例如课程等有父子关系的文档
+ */
+export abstract class HierarchicalDoc<Collection extends keyof DataEntryMap, T extends CollectionEntry<Collection>> extends BaseDoc<Collection, T> {
+    /**
+     * 获取父文档ID
+     * 例如：对于 ID 为 "zh-cn/blog/typescript" 的文档，父ID为 "zh-cn/blog"
+     * 
+     * @returns 父文档ID，如果没有父文档则返回null
+     */
+    getParentId(): string | null {
+        const parts = this.entry.id.split('/');
+        return parts.length > 1 ? parts.slice(0, -1).join('/') : null;
+    }
+
+    /**
+     * 获取顶级文档的ID
+     * 例如：对于 ID 为 "zh-cn/blog/typescript" 的文档，顶级ID为 "zh-cn/blog"
+     * 
+     * 默认实现假设顶级ID是前两部分
+     * 子类可以根据需要覆盖此方法
+     */
+    async getTopDocId(): Promise<string> {
+        const id = this.entry.id;
+        const parts = id.split('/');
+        return parts[0] + '/' + parts[1];
+    }
+
+    /**
+     * 获取顶级文档
+     * 子类应该实现此方法以提供正确的顶级文档
+     */
+    abstract getTopDoc(): Promise<HierarchicalDoc<Collection, T> | null>;
+
+    /**
+     * 获取子文档
+     * 子类应该实现此方法以提供正确的子文档列表
+     */
+    abstract getChildren(): Promise<HierarchicalDoc<Collection, T>[]>;
+
+    /**
+     * 转换为侧边栏项目
+     * 如果文档有子文档，会包含子文档的侧边栏项目
+     */
+    override async toSidebarItem(): Promise<SidebarItem> {
+        const debug = false;
+
+        const children = await this.getChildren();
+        const childItems = await Promise.all(children.map(child => child.toSidebarItem()));
+
+        if (debug) {
+            logger.info(`${this.entry.id} 的侧边栏项目`);
+            // eslint-disable-next-line no-console
+            console.log(childItems);
+        }
+
+        return new SidebarItem({
+            label: this.getTitle(),
+            items: childItems,
+            link: this.getLink(),
+        });
+    }
+
+    /**
+     * 获取顶级侧边栏项目
+     * 如果有顶级文档，返回顶级文档的侧边栏项目
+     * 否则返回当前文档的侧边栏项目
+     */
+    async getTopSidebarItem(): Promise<SidebarItem> {
+        const topDoc = await this.getTopDoc();
+        if (topDoc) {
+            return await topDoc.toSidebarItem();
+        }
+
+        return new SidebarItem({
+            label: this.getTitle(),
+            items: [],
+            link: this.getLink(),
+        });
+    }
+} 

package/dist/types/heading.ts

@@ -0,0 +1,13 @@
+/**
+ * 表示文档中的标题结构
+ */
+export interface Heading {
+    /** 标题深度，如 h1=1, h2=2, h3=3 等 */
+    depth: number;
+
+    /** 标题的唯一标识符，用于锚点链接 */
+    slug: string;
+
+    /** 标题文本内容 */
+    text: string;
+} 

package/dist/utils/link.ts

@@ -0,0 +1,216 @@
+import { logger } from "./logger";
+
+export class LinkUtil {
+    /**
+     * 规范化语言代码
+     * @param lang - 语言代码
+     * @returns 规范化后的语言代码
+     */
+    static normalizeLanguage(lang: string): string {
+        const normalizedLang = lang.toLowerCase().replace('zh-CN', 'zh-cn');
+        if (normalizedLang.length == 0) {
+            console.error('lang is empty');
+            return 'en';
+        }
+        return normalizedLang;
+    }
+
+    static getHomeLink(lang: string): string {
+        return `/${lang}`;
+    }
+
+    static getLessonsLink(lang: string): string {
+        return `/${lang}/lessons`;
+    }
+
+    static getExperimentsLink(lang: string): string {
+        return `/${lang}/experiments`;
+    }
+
+    static getExperimentLink(lang: string, experimentId: string): string {
+        if (experimentId.endsWith(lang)) {
+            return `/${lang}/experiments/${experimentId.replace(`${lang}`, '')}`;
+        } else {
+            const idWithoutLang = experimentId.replace(`${lang}/`, '');
+            return `/${lang}/experiments/${idWithoutLang}`;
+        }
+    }
+
+    static getCoursesLink(lang: string): string {
+        return `/${lang}/courses`;
+    }
+
+    static getBlogsLink(lang: string): string {
+        return `/${lang}/blogs`;
+    }
+
+    static getLessonLink(lang: string, lessonId: string): string {
+        if (lessonId.endsWith(lang)) {
+            return `/${lang}/lessons/${lessonId.replace(`${lang}`, '')}`;
+        } else {
+            const idWithoutLang = lessonId.replace(`${lang}/`, '');
+            return `/${lang}/lessons/${idWithoutLang}`;
+        }
+    }
+
+    static getTagLink(lang: string, tagName: string): string {
+        return `/${lang}/blogs/tag/${tagName}`;
+    }
+
+    static getBlogLink(blogId: string, lang: string): string {
+        const debug = false
+        const blogIdWithoutLang = blogId.replace(`${lang}/`, '')
+
+        if (debug) {
+            logger.info(`获取博客文档链接，博客文档ID: ${blogId}`);
+        }
+
+        return `/${lang}/blogs/${blogIdWithoutLang}`;
+    }
+
+    static getCourseLink(courseId: string): string {
+        const debug = false
+        const lang = courseId.split('/')[0]
+        const courseIdWithoutLang = courseId.replace(`${lang}/`, '')
+
+        if (debug) {
+            logger.info(`获取课程文档链接，课程文档ID: ${courseId}`);
+        }
+
+        return `/${lang}/courses/${courseIdWithoutLang}`;
+    }
+
+    static getMetaLink(lang: string, slug: string): string {
+        return `/${this.normalizeLanguage(lang)}/meta/${slug}`;
+    }
+
+    static getSigninLink(lang: string): string {
+        return `/${this.normalizeLanguage(lang)}/signin`;
+    }
+
+    static getAuthCallbackCookieLink(lang: string): string {
+        return `/${this.normalizeLanguage(lang)}/auth/callback_cookie`;
+    }
+
+    static getAuthCallbackTokenLink(lang: string): string {
+        return `/${this.normalizeLanguage(lang)}/auth/callback_token`;
+    }
+
+    static getAuthAccountLink(lang: string): string {
+        return `/${this.normalizeLanguage(lang)}/auth/account`;
+    }
+
+    static getDashboardUrl(lang: string): string {
+        return `/${this.normalizeLanguage(lang)}/auth/dashboard`;
+    }
+
+    static getAuthErrorLink(lang: string): string {
+        return `/${this.normalizeLanguage(lang)}/auth/error`;
+    }
+
+    static getPrivacyLink(lang: string): string {
+        return this.getMetaLink(lang, 'privacy');
+    }
+
+    static getTermsLink(lang: string): string {
+        return this.getMetaLink(lang, 'terms');
+    }
+
+    static getAboutLink(lang: string): string {
+        return this.getMetaLink(lang, 'about');
+    }
+
+    /**
+     * 根据ID生成链接
+     * 
+     * 该函数根据文档ID生成对应的链接路径。
+     * 
+     * @param {string} id - 文档ID, 例如 'courses/zh-cn/supervisor/index.md'
+     * @returns {string} 返回生成的链接路径
+     * @example
+     * // 例如：
+     * // id=courses/zh-cn/supervisor/index.md，则返回/zh-cn/courses/supervisor
+     * // id=courses/en/supervisor/index.md，则返回/en/courses/supervisor
+     */
+    static getLink(id: string): string {
+        let category = id.split('/')[0];
+        let lang = id.split('/')[1];
+        let path = id.split('/').slice(2).join('/');
+
+        let link = `/${lang}/${category}/${path}`;
+        return link.replace(/\/+/g, '/');
+    }
+
+    /**
+     * 根据分类生成顶级链接
+     * 
+     * @param {string} category - 分类名称
+     * @param {string} lang - 语言代码，例如 'zh-cn', 'en'
+     * @returns {string} 返回生成的顶级链接路径
+     * @example
+     * // 例如：
+     * // category=courses, lang=zh-cn，则返回/zh-cn/courses
+     * // category=courses, lang=en，则返回/en/courses
+     */
+    static getTopLevelLink(category: string, lang: string): string {
+        return `/${lang}/${category}`;
+    }
+
+    /**
+     * 处理首页重定向
+     * @param locale - 语言代码
+     * @returns 规范化的语言代码
+     */
+    static homeRedirect(locale: string): string {
+        return locale || "en";
+    }
+
+    /**
+     * 检查是否为首页路径
+     * @param pathname - 路径
+     * @returns 是否为首页
+     */
+    static isHomePath(pathname: string): boolean {
+        return pathname === "/" || pathname === "";
+    }
+
+    static isHomeLink(path: string, lang: string): boolean {
+        return path === `/${lang}` || path === `/${lang}/`;
+    }
+
+    static isLessonsLink(path: string, lang: string): boolean {
+        return path === `/${lang}/lessons` ||
+            path === `/${lang}/lessons/` ||
+            path.startsWith(`/${lang}/lessons/`);
+    }
+
+    static isExperimentsLink(path: string, lang: string): boolean {
+        return path === `/${lang}/experiments` ||
+            path === `/${lang}/experiments/` ||
+            path.startsWith(`/${lang}/experiments/`);
+    }
+
+    static isCoursesLink(path: string, lang: string): boolean {
+        return path === `/${lang}/courses`
+            || path === `/${lang}/courses/`
+            || path.startsWith(`/${lang}/courses/`);
+    }
+
+    static isBlogsLink(path: string, lang: string): boolean {
+        return path === `/${lang}/blogs`
+            || path === `/${lang}/blogs/`
+            || path.startsWith(`/${lang}/blogs/`);
+    }
+
+    static getOAuthSuccessLink(currentOrigin: string): string {
+        return `${currentOrigin}/api/callback_success`;
+    }
+
+    static getOAuthErrorLink(currentOrigin: string): string {
+        return `${currentOrigin}/api/callback_error`;
+    }
+
+    static getLoginLink(currentOrigin: string): string {
+        return `${currentOrigin}/api/login`;
+    }
+}

package/dist/utils/logger.ts

@@ -0,0 +1,139 @@
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+// 控制是否显示时间戳
+const SHOW_TIMESTAMP = false;
+
+// ANSI 颜色代码
+const colors = {
+    reset: '\x1b[0m',
+    debug: '\x1b[36m', // 青色
+    info: '\x1b[32m',  // 绿色
+    warn: '\x1b[33m',  // 黄色
+    error: '\x1b[31m', // 红色
+    gray: '\x1b[90m',  // 灰色用于时间戳
+};
+
+class Logger {
+    private getCallerInfo(): string {
+        const error = new Error();
+        const stackLines = error.stack?.split('\n') || [];
+
+        // 从第3行开始查找，跳过不是来自logger.ts的第一个调用
+        let targetLine = '';
+        for (let i = 3; i < stackLines.length; i++) {
+            const line = stackLines[i];
+            if (!line.includes('logger.ts')) {
+                targetLine = line;
+                break;
+            }
+        }
+
+        if (!targetLine) return '';
+
+        // 匹配文件路径和行号
+        const match = targetLine.match(/\((.+):(\d+):\d+\)/) || targetLine.match(/at (.+):(\d+):\d+/);
+        if (!match) return '';
+
+        const [_, filePath, line] = match;
+        return `${filePath}:${line}`;
+    }
+
+    private formatArray(arr: any[]): string {
+        const MAX_LINES = 30;
+        const MAX_LENGTH = 100;
+
+        const truncateString = (str: string): string => {
+            return str.length > MAX_LENGTH ? str.slice(0, MAX_LENGTH) + '...' : str;
+        };
+
+        const truncateObject = (obj: any): any => {
+            if (typeof obj !== 'object' || obj === null) {
+                return typeof obj === 'string' ? truncateString(obj) : obj;
+            }
+
+            const result: any = Array.isArray(obj) ? [] : {};
+            for (const [key, value] of Object.entries(obj)) {
+                result[key] = typeof value === 'string' ? truncateString(value)
+                    : typeof value === 'object' ? truncateObject(value)
+                        : value;
+            }
+            return result;
+        };
+
+        const items = arr.slice(0, MAX_LINES).map(item => {
+            const truncatedItem = truncateObject(item);
+            // 使用2个空格缩进，并在每行前添加 "  • "
+            const jsonString = JSON.stringify(truncatedItem, null, 2)
+                .split('\n')
+                .map((line, index) => index === 0 ? `  • ${line}` : `    ${line}`)
+                .join('\n');
+            return jsonString;
+        });
+
+        let output = items.join('\n');
+        if (arr.length > MAX_LINES) {
+            const remainingCount = arr.length - MAX_LINES;
+            output += `\n  ⋮ ... and ${remainingCount} more items`;
+        }
+
+        return output;
+    }
+
+    private log(level: LogLevel, message: string | object | any[]) {
+        const caller = this.getCallerInfo();
+        // 使用本地时间，并格式化为 HH:mm:ss 格式
+        const timestamp = new Date().toLocaleTimeString('zh-CN', {
+            hour12: false,
+            hour: '2-digit',
+            minute: '2-digit',
+            second: '2-digit'
+        });
+
+        const formattedMessage = Array.isArray(message)
+            ? this.formatArray(message)
+            : typeof message === 'object'
+                ? JSON.stringify(message, null, 2)
+                : message;
+
+        const timestampPart = SHOW_TIMESTAMP
+            ? `${colors.gray}${timestamp}${colors.reset} `
+            : '';
+
+        const emoji = {
+            debug: '🔍',
+            info: '🐳',
+            warn: '🚨',
+            error: '❌'
+        }[level];
+
+        // eslint-disable-next-line no-console
+        console.log(
+            timestampPart +
+            `${colors[level]}${emoji} ${level.toUpperCase()}${colors.reset} ` +
+            `${colors.gray}:${colors.reset} ` +
+            `${colors[level]}${formattedMessage}${colors.reset}`
+        );
+    }
+
+    debug(message: string | object) {
+        this.log('debug', message);
+    }
+
+    info(message: string | object) {
+        this.log('info', message);
+    }
+
+    warn(message: string | object) {
+        this.log('warn', message);
+    }
+
+    error(message: string | object) {
+        this.log('error', message);
+    }
+
+    array(title: string, arr: any[]) {
+        this.log('info', title + '\n' + this.formatArray(arr));
+    }
+}
+
+export const logger = new Logger();

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@coffic/cosy-ui",
-    "version": "0.4.5",
+    "version": "0.4.9",
     "description": "An astro component library",
     "author": {
         "name": "nookery",