@coffic/cosy-ui 0.6.38 → 0.6.42

package/dist/entities/BaseDoc.ts

@@ -1,6 +1,6 @@
 import { render, type RenderResult, type CollectionEntry, type DataEntryMap } from 'astro:content';
 import { SidebarItemEntity, type SidebarProvider } from './SidebarItem';
-import { logger } from '../utils/logger';
+import { cosyLogger, ERROR_PREFIX } from '../cosy';
 
 /**
  * 文档基类，提供所有文档类型共享的基本功能
@@ -8,8 +8,7 @@ import { logger } from '../utils/logger';
 export abstract class BaseDoc<
 	Collection extends keyof DataEntryMap,
 	T extends CollectionEntry<Collection>,
-> implements SidebarProvider
-{
+> implements SidebarProvider {
 	protected entry: T;
 
 	constructor(entry: T) {
@@ -54,6 +53,28 @@ export abstract class BaseDoc<
 	 */
 	getAncestorId(level: number): string {
 		const ancestorIds = this.getAncestorIds();
+
+		if (level < 1) {
+			cosyLogger.error('Level must be greater than 0');
+			throw new Error(ERROR_PREFIX + 'Level must be greater than 0');
+		}
+
+		if (level >= this.getLevel()) {
+			cosyLogger.debug("当前文档的ID：" + this.entry.id);
+			cosyLogger.debug("当前文档的Level：" + this.getLevel());
+			cosyLogger.debug("正在获取祖先ID，level：" + level);
+
+			throw new Error(ERROR_PREFIX + 'Level must be less than the document level');
+		}
+
+		if (ancestorIds.length < level) {
+			cosyLogger.debug("当前文档的ID\n" + this.entry.id);
+			cosyLogger.array("当前文档的祖先IDs", ancestorIds);
+			cosyLogger.debug("正在获取祖先ID，level:\n" + level);
+
+			throw new Error(ERROR_PREFIX + 'Level must be greater than 0');
+		}
+
 		return ancestorIds[level - 1];
 	}
 
@@ -93,6 +114,12 @@ export abstract class BaseDoc<
 	 * 子类可以根据需要覆盖此方法
 	 */
 	getTopDocId(): string {
+		const level = this.getLevel();
+
+		if (level <= 2) {
+			return this.entry.id;
+		}
+
 		return this.getAncestorId(2);
 	}
 
@@ -155,7 +182,7 @@ export abstract class BaseDoc<
 		const childItems = await Promise.all(children.map((child) => child.toSidebarItem()));
 
 		if (debug) {
-			logger.info(`${this.entry.id} 的侧边栏项目`);
+			cosyLogger.info(`${this.entry.id} 的侧边栏项目`);
 			console.log(childItems);
 		}
 

package/dist/entities/BlogDoc.ts

@@ -5,6 +5,46 @@ import { BaseDoc } from './BaseDoc';
 import { COLLECTION_BLOG } from '../database/BlogDB';
 import { blogDB } from '../database/BlogDB';
 
+/**
+ * 博客文档类，配合 BlogDB 使用
+ * 
+ * 目录结构：
+ * ```
+ * blogs/
+ * ├── zh-cn/                        # 中文博客目录
+ * │   ├── typescript-intro.md      # 文章内容
+ * │   ├── images/                  # 文章相关图片
+ * │   └── web-performance.md
+ * └── en/                          # 英文博客目录
+ *     ├── typescript-intro.md
+ *     ├── images/
+ *     └── web-performance.md
+ * ```
+ *
+ * 说明：
+ * - 每个语言（如 zh-cn, en）是一个独立的目录，存放该语言下的所有博客文章
+ * - 每篇博客为一个 markdown 文件，文件名即为 slug
+ * - 每个语言目录下可包含 images 文件夹，存放该语言博客相关图片
+ * - 支持多语言博客内容，便于国际化
+ * - 博客目录可作为 git 子模块独立管理
+ *
+ * 相关：
+ * - BlogDB：博客数据库管理类，负责博客文档的增删查改
+ * - BlogDoc：博客文档实体类，封装单篇博客的相关操作
+ *
+ * 用法示例：
+ * ```typescript
+ * import BlogDoc from '../entities/BlogDoc';
+ * import { blogDB } from '../database/BlogDB';
+ *
+ * // 获取所有中文博客
+ * const blogs = await blogDB.allBlogsByLang('zh-cn');
+ *
+ * // 获取博客链接
+ * const link = blogs[0].getLink();
+ * ```
+ */
+
 export default class BlogDoc extends BaseDoc<typeof COLLECTION_BLOG, BlogEntry> {
 	private constructor(entry: BlogEntry) {
 		super(entry);

package/dist/entities/CourseDoc.ts

@@ -1,4 +1,4 @@
-import { logger } from '../utils/logger';
+import { cosyLogger } from '../cosy';
 import { SidebarItemEntity } from './SidebarItem';
 import type { CourseEntry } from '../database/CourseDB';
 import { courseDB } from '../database/CourseDB';
@@ -36,12 +36,12 @@ export default class CourseDoc extends BaseDoc<typeof COLLECTION_COURSE, CourseE
 	async getAncestor(level: number): Promise<CourseDoc | null> {
 		const debug = false;
 		if (debug) {
-			logger.info(`获取 ${this.entry.id} 的祖先文档，level: ${level}`);
+			cosyLogger.info(`获取 ${this.entry.id} 的祖先文档，level: ${level}`);
 		}
 
 		if (level >= this.getLevel()) {
 			if (debug) {
-				logger.info(`祖先文档为自身`);
+				cosyLogger.info(`祖先文档为自身`);
 			}
 			return this;
 		}
@@ -61,7 +61,7 @@ export default class CourseDoc extends BaseDoc<typeof COLLECTION_COURSE, CourseE
 			(a, b) => a.getOrder() - b.getOrder()
 		);
 		if (debug && children.length > 0) {
-			logger.array(
+			cosyLogger.array(
 				`${this.entry.id} 的子文档(${children.length})`,
 				children.map((child) => `#${child.getOrder()} ${child.entry.id}`)
 			);
@@ -79,7 +79,7 @@ export default class CourseDoc extends BaseDoc<typeof COLLECTION_COURSE, CourseE
 		}
 
 		if (debug) {
-			logger.info(`${this.entry.id} 的侧边栏项目`);
+			cosyLogger.info(`${this.entry.id} 的侧边栏项目`);
 			console.log(childItems);
 		}
 

package/dist/entities/ExperimentDoc.ts

@@ -1,6 +1,6 @@
 import type { ExperimentEntry } from '../database/ExperimentDB';
 import { experimentDB } from '../database/ExperimentDB';
-import { logger } from '../utils/logger';
+import { cosyLogger } from '../cosy';
 import { SidebarItemEntity } from './SidebarItem';
 import { LinkUtil } from '../utils/link';
 import { COLLECTION_EXPERIMENT } from '../database/ExperimentDB';
@@ -31,7 +31,7 @@ export default class ExperimentDoc extends BaseDoc<typeof COLLECTION_EXPERIMENT,
 		const link = LinkUtil.getExperimentLink(lang, this.getId());
 
 		if (debug) {
-			logger.info(`获取 ${this.entry.id} 的链接: ${link}`);
+			cosyLogger.info(`获取 ${this.entry.id} 的链接: ${link}`);
 		}
 
 		return link;
@@ -51,7 +51,7 @@ export default class ExperimentDoc extends BaseDoc<typeof COLLECTION_EXPERIMENT,
 		const lang = parts[1];
 
 		if (debug) {
-			logger.info(`获取 ${this.entry.id} 的语言: ${lang}`);
+			cosyLogger.info(`获取 ${this.entry.id} 的语言: ${lang}`);
 		}
 
 		return lang;
@@ -61,7 +61,7 @@ export default class ExperimentDoc extends BaseDoc<typeof COLLECTION_EXPERIMENT,
 		const debug = false;
 
 		if (debug) {
-			logger.info(`获取 ${this.entry.id} 的 HTML`);
+			cosyLogger.info(`获取 ${this.entry.id} 的 HTML`);
 		}
 
 		return this.entry.rendered?.html || '';
@@ -71,7 +71,7 @@ export default class ExperimentDoc extends BaseDoc<typeof COLLECTION_EXPERIMENT,
 		const debug = false;
 
 		if (debug) {
-			logger.info(`获取 ${this.entry.id} 的 headings`);
+			cosyLogger.info(`获取 ${this.entry.id} 的 headings`);
 		}
 
 		return (this.entry.rendered?.metadata?.headings as IHeadingType[]) || [];
@@ -101,7 +101,7 @@ export default class ExperimentDoc extends BaseDoc<typeof COLLECTION_EXPERIMENT,
 		}
 
 		if (debug) {
-			logger.info(`${this.entry.id} 的侧边栏项目`);
+			cosyLogger.info(`${this.entry.id} 的侧边栏项目`);
 			console.log(childItems);
 		}
 

package/dist/entities/LessonDoc.ts

@@ -1,12 +1,46 @@
 import type { LessonEntry } from '../database/LessonDB';
 import { lessonDB } from '../database/LessonDB';
-import { logger } from '../utils/logger';
+import { cosyLogger } from '../cosy';
 import { SidebarItemEntity } from './SidebarItem';
 import { LinkUtil } from '../utils/link';
 import { COLLECTION_LESSON } from '../database/LessonDB';
 import { BaseDoc } from './BaseDoc';
 import type { IHeadingType } from '../types/heading';
 
+/**
+ * 课程文档类，配合 LessonDB 使用
+ * 
+ * 目录结构：
+ * ```
+ * lessons/
+ * ├── build_your_own_web_toolbox/      # 课程目录
+ * │   ├── images/                      # 课程图片资源
+ * │   ├── components/                  # 课程组件
+ * │   ├── en/                          # 英文版本
+ * │   │   ├── index.mdx                # 课程首页
+ * │   │   ├── 1.mdx                    # 第一章
+ * │   │   └── 2.mdx                    # 第二章
+ * │   └── zh-cn/                       # 中文版本
+ * │       ├── index.mdx                # 课程首页
+ * │       ├── 1.mdx                    # 第一章
+ * │       └── 2.mdx                    # 第二章
+ * └── learn_astro/                     # 另一个课程
+ *     ├── en/
+ *     │   ├── index.mdx
+ *     │   ├── 1.mdx
+ *     │   └── 2.mdx
+ *     └── zh-cn/
+ *         ├── index.mdx
+ *         ├── 1.mdx
+ *         └── 2.mdx
+ * ```
+ *
+ * 说明：
+ * - 每个课程（如 build_your_own_web_toolbox）是一个独立的目录
+ * - 课程目录可以包含多语言版本（en, zh-cn 等）
+ * - 每个语言版本包含完整的课程内容
+ * - 课程目录可以作为 git 子模块独立管理
+ */
 export default class LessonDoc extends BaseDoc<typeof COLLECTION_LESSON, LessonEntry> {
 	constructor(entry: LessonEntry) {
 		super(entry);
@@ -31,7 +65,7 @@ export default class LessonDoc extends BaseDoc<typeof COLLECTION_LESSON, LessonE
 		const link = LinkUtil.getLessonLink(lang, this.getId());
 
 		if (debug) {
-			logger.info(`获取 ${this.entry.id} 的链接: ${link}`);
+			cosyLogger.info(`获取 ${this.entry.id} 的链接: ${link}`);
 		}
 
 		return link;
@@ -51,7 +85,7 @@ export default class LessonDoc extends BaseDoc<typeof COLLECTION_LESSON, LessonE
 		const lang = parts[1];
 
 		if (debug) {
-			logger.info(`获取 ${this.entry.id} 的语言: ${lang}`);
+			cosyLogger.info(`获取 ${this.entry.id} 的语言: ${lang}`);
 		}
 
 		return lang;
@@ -61,7 +95,7 @@ export default class LessonDoc extends BaseDoc<typeof COLLECTION_LESSON, LessonE
 		const debug = false;
 
 		if (debug) {
-			logger.info(`获取 ${this.entry.id} 的 HTML`);
+			cosyLogger.info(`获取 ${this.entry.id} 的 HTML`);
 		}
 
 		return this.entry.rendered?.html || '';
@@ -71,7 +105,7 @@ export default class LessonDoc extends BaseDoc<typeof COLLECTION_LESSON, LessonE
 		const debug = false;
 
 		if (debug) {
-			logger.info(`获取 ${this.entry.id} 的 headings`);
+			cosyLogger.info(`获取 ${this.entry.id} 的 headings`);
 		}
 
 		return (this.entry.rendered?.metadata?.headings as IHeadingType[]) || [];
@@ -101,7 +135,7 @@ export default class LessonDoc extends BaseDoc<typeof COLLECTION_LESSON, LessonE
 		}
 
 		if (debug) {
-			logger.info(`${this.entry.id} 的侧边栏项目`);
+			cosyLogger.info(`${this.entry.id} 的侧边栏项目`);
 			console.log(childItems);
 		}
 

package/dist/index.ts

@@ -1,3 +1,3 @@
 export * from './index_astro';
 export * from './index_utils';
-export * from './index_icons';
+export * from './index_icons';

package/dist/layout-app/AppLayout.astro

@@ -202,6 +202,7 @@ const {
 	author={metaConfig.author}
 	robots={metaConfig.robots}
 	head={metaConfig.head}
+	favicon={metaConfig.favicon}
 	debug={debug}
 	{...rest}>
 	<ClientRouter />

package/dist/layout-basic/BaseLayout.astro

@@ -50,7 +50,7 @@
  */
 
 import '../style.ts';
-import { LinkUtil, type IMetaProps } from '../index';
+import { type IMetaProps } from '../index';
 
 export interface Props extends IMetaProps {
 	debug?: boolean;
@@ -66,12 +66,12 @@ const {
 	head,
 	debug = true,
 	class: className,
+	favicon,
 	'class:list': classList,
 } = Astro.props;
 
 // 处理类名
 let bodyClasses = debug ? 'cosy:border cosy:border-red-500' : className || '';
-const faviconPath = LinkUtil.createUrl('/favicon.png');
 ---
 
 <!doctype html>
@@ -83,7 +83,7 @@ const faviconPath = LinkUtil.createUrl('/favicon.png');
 		{description && <meta name="description" content={description} />}
 		{keywords && <meta name="keywords" content={keywords} />}
 		<meta name="generator" content={Astro.generator} />
-		<link rel="icon" type="image/svg+xml" href={faviconPath} />
+		{favicon && <link rel="icon" type={favicon.format} href={favicon.src} />}
 
 		<!-- 自定义样式 -->
 		{customStyles && <style set:html={customStyles} />}

package/dist/types/meta.ts

@@ -5,6 +5,11 @@ export interface IMetaProps {
 	author: string;
 	robots: string;
 
+	/**
+	 * 图标
+	 */
+	favicon?: ImageMetadata;
+
 	/**
 	 * 基础路径，用于处理网站部署在二级目录的情况
 	 * @default ""

package/dist/utils/language.ts

@@ -1,16 +1,15 @@
-/**
- * 语言工具模块
- *
- * 提供语言相关的工具函数，用于多语言支持
- */
-
 import { getRelativeLocaleUrl } from 'astro:i18n';
-import { logger } from './logger';
 import type { AstroGlobal } from 'astro';
+import { cosyLogger } from '../cosy';
 
 // 默认语言
 export const DEFAULT_LANGUAGE = 'en';
 
+/**
+ * 语言工具模块
+ *
+ * 提供语言相关的工具函数，用于多语言支持
+ */
 export class LanguageUtil {
 	static getRelativeLink(locale: string, astro: AstroGlobal): string {
 		const debug = false;
@@ -19,7 +18,7 @@ export class LanguageUtil {
 		const result = getRelativeLocaleUrl(locale, originalPath.replaceAll('/' + currentLocale, ''));
 
 		if (debug) {
-			logger.debug(
+			cosyLogger.debug(
 				`getRelativeLink: locale=${locale}, currentPath=${originalPath}, currentLocale=${currentLocale}, result=${result}`
 			);
 		}

package/dist/utils/link.ts

@@ -1,4 +1,4 @@
-import { logger } from './logger';
+import { cosyLogger } from '../cosy';
 
 export class LinkUtil {
 	// 从 astro.config.ts 中获取基础路径
@@ -78,7 +78,7 @@ export class LinkUtil {
 		const blogIdWithoutLang = blogId.replace(`${lang}/`, '');
 
 		if (debug) {
-			logger.info(`获取博客文档链接，博客文档ID: ${blogId}`);
+			cosyLogger.info(`获取博客文档链接，博客文档ID: ${blogId}`);
 		}
 
 		return `/${lang}/blogs/${blogIdWithoutLang}`;
@@ -90,7 +90,7 @@ export class LinkUtil {
 		const courseIdWithoutLang = courseId.replace(`${lang}/`, '');
 
 		if (debug) {
-			logger.info(`获取课程文档链接，课程文档ID: ${courseId}`);
+			cosyLogger.info(`获取课程文档链接，课程文档ID: ${courseId}`);
 		}
 
 		return LinkUtil.createUrl(`/${lang}/courses/${courseIdWithoutLang}`);

package/dist/utils/logger.ts

@@ -5,110 +5,126 @@ 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', // 灰色用于时间戳
+    reset: '\x1b[0m',
+    debug: '\x1b[36m', // 青色
+    info: '\x1b[32m', // 绿色
+    warn: '\x1b[33m', // 黄色
+    error: '\x1b[31m', // 红色
+    gray: '\x1b[90m', // 灰色用于时间戳
 };
 
-class Logger {
-	private formatArray(arr: any[]): string {
-		const MAX_LINES = 70;
-		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[]) {
-		// 使用本地时间，并格式化为 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];
-
-		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 class Logger {
+    private topic: string = '';
+
+    private formatArray(arr: any[]): string {
+        const MAX_LINES = 70;
+        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[], newLine: boolean = false) {
+        // 使用本地时间，并格式化为 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];
+
+        if (newLine) {
+            console.log("")
+        }
+
+        console.log(
+            timestampPart +
+            `${colors[level]}${emoji} ` +
+            this.getPrefix() +
+            `${level.toUpperCase()}${colors.reset} ` +
+            `${colors.gray}:${colors.reset} ` +
+            `${colors[level]}${formattedMessage}${colors.reset}`
+        );
+    }
+
+    private getPrefix() {
+        return this.topic ? `[${this.topic}] ` : '';
+    }
+
+    constructor(topic: string = '') {
+        this.topic = topic;
+    }
+
+    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, true);
+    }
+
+    array(title: string, arr: any[]) {
+        this.log('info', title + '\n' + this.formatArray(arr));
+    }
 }
 
-export const logger = new Logger();
+export const defaultLogger = new Logger();

package/dist/utils/path.ts

@@ -1,4 +1,4 @@
-import { logger } from './logger';
+import { cosyLogger } from '../cosy';
 
 /**
  * 判断当前路径是否匹配目标路径
@@ -10,13 +10,13 @@ export function isPathMatch(currentPath: string, targetPath: string): boolean {
 	const debug = false;
 
 	if (debug) {
-		logger.info(`判断 ${currentPath} 是否匹配 ${targetPath}`);
+		cosyLogger.info(`判断 ${currentPath} 是否匹配 ${targetPath}`);
 	}
 
 	// 如果完全匹配，直接返回
 	if (currentPath === targetPath) {
 		if (debug) {
-			logger.info(`${currentPath} 完全匹配 ${targetPath}`);
+			cosyLogger.info(`${currentPath} 完全匹配 ${targetPath}`);
 		}
 		return true;
 	}