@coffic/cosy-ui 0.6.36 → 0.6.40

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/index_collection.ts

@@ -2,103 +2,103 @@ import { defineCollection, z } from 'astro:content';
 import { glob } from 'astro/loaders';
 
 export const makeArticleCollection = (base: string) => {
-	return defineCollection({
-		loader: glob({
-			pattern: '**/*.{md,mdx}',
-			base,
-		}),
-		schema: z.object({
-			title: z.string(),
-			folder: z.boolean(),
-			order: z.number(),
-			description: z.string().optional(),
-		}),
-	});
+    return defineCollection({
+        loader: glob({
+            pattern: '**/*.{md,mdx}',
+            base,
+        }),
+        schema: z.object({
+            title: z.string().optional(),
+            folder: z.boolean().optional(),
+            order: z.number().optional(),
+            description: z.string().optional(),
+        }),
+    });
 };
 
 export const makeBlogCollection = (base: string) => {
-	return defineCollection({
-		loader: glob({
-			pattern: '**/*.{md,mdx}',
-			base,
-		}),
-		schema: z.object({
-			title: z.string(),
-			description: z.string().optional(),
-			tags: z.array(z.string()).optional(),
-			date: z.date().optional(),
-			authors: z
-				.array(
-					z.object({
-						name: z.string(),
-						picture: z.string().optional(),
-						url: z.string().optional(),
-					})
-				)
-				.optional(),
-		}),
-	});
+    return defineCollection({
+        loader: glob({
+            pattern: '**/*.{md,mdx}',
+            base,
+        }),
+        schema: z.object({
+            title: z.string(),
+            description: z.string().optional(),
+            tags: z.array(z.string()).optional(),
+            date: z.date().optional(),
+            authors: z
+                .array(
+                    z.object({
+                        name: z.string(),
+                        picture: z.string().optional(),
+                        url: z.string().optional(),
+                    })
+                )
+                .optional(),
+        }),
+    });
 };
 
 export const makeCourseCollection = (base: string) => {
-	return defineCollection({
-		loader: glob({
-			pattern: '**/*.{md,mdx}',
-			base,
-		}),
-		schema: z.object({
-			title: z.string(),
-			description: z.string().optional(),
-			folder: z.boolean(),
-			order: z.number(),
-		}),
-	});
+    return defineCollection({
+        loader: glob({
+            pattern: '**/*.{md,mdx}',
+            base,
+        }),
+        schema: z.object({
+            title: z.string().optional(),
+            description: z.string().optional(),
+            folder: z.boolean().optional(),
+            order: z.number().optional(),
+        }),
+    });
 };
 
 export const makeExperimentCollection = (base: string) => {
-	return defineCollection({
-		loader: glob({
-			pattern: '**/*.{md,mdx}',
-			base,
-		}),
-		schema: z.object({
-			title: z.string(),
-			description: z.string().optional(),
-			pubDate: z.date().optional(),
-		}),
-	});
+    return defineCollection({
+        loader: glob({
+            pattern: '**/*.{md,mdx}',
+            base,
+        }),
+        schema: z.object({
+            title: z.string().optional(),
+            description: z.string().optional(),
+            pubDate: z.date().optional(),
+        }),
+    });
 };
 
 export const makeLessonCollection = (base: string) => {
-	return defineCollection({
-		loader: glob({
-			pattern: '**/*.{md,mdx}',
-			base,
-		}),
-		schema: z.object({
-			title: z.string(),
-			description: z.string().optional(),
-			authors: z
-				.array(
-					z.object({
-						name: z.string(),
-						picture: z.string().optional(),
-					})
-				)
-				.optional(),
-		}),
-	});
+    return defineCollection({
+        loader: glob({
+            pattern: '**/*.{md,mdx}',
+            base,
+        }),
+        schema: z.object({
+            title: z.string().optional(),
+            description: z.string().optional(),
+            authors: z
+                .array(
+                    z.object({
+                        name: z.string(),
+                        picture: z.string().optional(),
+                    })
+                )
+                .optional(),
+        }),
+    });
 };
 
 export const makeMetaCollection = (base: string) => {
-	return defineCollection({
-		loader: glob({
-			pattern: '**/*.{md,mdx}',
-			base,
-		}),
-		schema: z.object({
-			title: z.string(),
-			description: z.string().optional(),
-		}),
-	});
+    return defineCollection({
+        loader: glob({
+            pattern: '**/*.{md,mdx}',
+            base,
+        }),
+        schema: z.object({
+            title: z.string().optional(),
+            description: z.string().optional(),
+        }),
+    });
 };