@coffic/cosy-ui 0.6.2 → 0.6.6

package/dist/database/BlogDB.ts

@@ -4,8 +4,8 @@ import { logger } from '../utils/logger';
 import { type CollectionEntry } from 'astro:content';
 import { BaseDB } from './BaseDB';
 
-export const COLLECTION_NAME = 'blogs' as const;
-export type BlogEntry = CollectionEntry<typeof COLLECTION_NAME>;
+export const COLLECTION_BLOG = 'blogs' as const;
+export type BlogEntry = CollectionEntry<typeof COLLECTION_BLOG>;
 
 /**
  * 博客数据库类，用于管理博客内容集合。
@@ -23,8 +23,8 @@ export type BlogEntry = CollectionEntry<typeof COLLECTION_NAME>;
  *     └── web-performance.md
  * ```
  */
-class BlogDB extends BaseDB<typeof COLLECTION_NAME, BlogEntry, BlogDoc> {
-	protected collectionName = COLLECTION_NAME;
+class BlogDB extends BaseDB<typeof COLLECTION_BLOG, BlogEntry, BlogDoc> {
+	protected collectionName = COLLECTION_BLOG;
 
 	protected createDoc(entry: BlogEntry): BlogDoc {
 		return BlogDoc.fromEntry(entry);

package/dist/database/CourseDB.ts

@@ -2,8 +2,8 @@ import CourseDoc from '../entities/CourseDoc';
 import { getCollection, type CollectionEntry } from 'astro:content';
 import { BaseDB } from './BaseDB';
 
-export const COLLECTION_NAME = 'courses' as const;
-export type CourseEntry = CollectionEntry<typeof COLLECTION_NAME>;
+export const COLLECTION_COURSE = 'courses' as const;
+export type CourseEntry = CollectionEntry<typeof COLLECTION_COURSE>;
 
 /**
  * 课程数据库类，用于管理课程内容集合。
@@ -29,8 +29,8 @@ export type CourseEntry = CollectionEntry<typeof COLLECTION_NAME>;
  *     └── ...
  * ```
  */
-class CourseDB extends BaseDB<typeof COLLECTION_NAME, CourseEntry, CourseDoc> {
-	protected collectionName = COLLECTION_NAME;
+class CourseDB extends BaseDB<typeof COLLECTION_COURSE, CourseEntry, CourseDoc> {
+	protected collectionName = COLLECTION_COURSE;
 
 	protected createDoc(entry: CourseEntry): CourseDoc {
 		return new CourseDoc(entry);
@@ -43,7 +43,7 @@ class CourseDB extends BaseDB<typeof COLLECTION_NAME, CourseEntry, CourseDoc> {
 	 * @returns 返回指定语言的顶级课程数组
 	 */
 	async allCoursesByLang(lang: string): Promise<CourseDoc[]> {
-		const entries = await getCollection(COLLECTION_NAME, ({ id }) => {
+		const entries = await getCollection(COLLECTION_COURSE, ({ id }) => {
 			return id.startsWith(lang) && id.split('/').length === 2;
 		});
 		return entries.map((entry) => new CourseDoc(entry));
@@ -55,7 +55,7 @@ class CourseDB extends BaseDB<typeof COLLECTION_NAME, CourseEntry, CourseDoc> {
 	 * @returns 返回路径参数数组
 	 */
 	async getStaticPaths(): Promise<{ params: { lang: string; slug: string } }[]> {
-		const entries = await getCollection(COLLECTION_NAME);
+		const entries = await getCollection(COLLECTION_COURSE);
 		return entries.map((entry) => {
 			const doc = new CourseDoc(entry);
 			return {
@@ -81,5 +81,4 @@ class CourseDB extends BaseDB<typeof COLLECTION_NAME, CourseEntry, CourseDoc> {
 }
 
 // 创建并导出单例实例
-const courseDB = new CourseDB();
-export default courseDB;
+export const courseDB = new CourseDB();

package/dist/database/ExperimentDB.ts

@@ -3,8 +3,8 @@ import { BaseDB } from './BaseDB';
 import ExperimentDoc from '../entities/ExperimentDoc';
 import { logger } from '../utils/logger';
 
-export const COLLECTION_NAME = 'experiments' as const;
-export type ExperimentEntry = CollectionEntry<typeof COLLECTION_NAME>;
+export const COLLECTION_EXPERIMENT = 'experiments' as const;
+export type ExperimentEntry = CollectionEntry<typeof COLLECTION_EXPERIMENT>;
 
 /**
  * 实验数据库类，用于管理实验内容集合
@@ -40,8 +40,8 @@ export type ExperimentEntry = CollectionEntry<typeof COLLECTION_NAME>;
  * - 每个语言版本包含完整的课程内容
  * - 课程目录可以作为 git 子模块独立管理
  */
-class ExperimentDB extends BaseDB<typeof COLLECTION_NAME, ExperimentEntry, ExperimentDoc> {
-	protected collectionName = COLLECTION_NAME;
+class ExperimentDB extends BaseDB<typeof COLLECTION_EXPERIMENT, ExperimentEntry, ExperimentDoc> {
+	protected collectionName = COLLECTION_EXPERIMENT;
 
 	protected createDoc(entry: ExperimentEntry): ExperimentDoc {
 		return new ExperimentDoc(entry);

package/dist/database/LessonDB.ts

@@ -3,8 +3,8 @@ import { BaseDB } from './BaseDB';
 import LessonDoc from '../entities/LessonDoc';
 import { logger } from '../utils/logger';
 
-export const COLLECTION_NAME = 'lessons' as const;
-export type LessonEntry = CollectionEntry<typeof COLLECTION_NAME>;
+export const COLLECTION_LESSON = 'lessons' as const;
+export type LessonEntry = CollectionEntry<typeof COLLECTION_LESSON>;
 
 /**
  * 课程数据库类，用于管理课程内容集合
@@ -40,8 +40,8 @@ export type LessonEntry = CollectionEntry<typeof COLLECTION_NAME>;
  * - 每个语言版本包含完整的课程内容
  * - 课程目录可以作为 git 子模块独立管理
  */
-class LessonDB extends BaseDB<typeof COLLECTION_NAME, LessonEntry, LessonDoc> {
-	protected collectionName = COLLECTION_NAME;
+class LessonDB extends BaseDB<typeof COLLECTION_LESSON, LessonEntry, LessonDoc> {
+	protected collectionName = COLLECTION_LESSON;
 
 	protected createDoc(entry: LessonEntry): LessonDoc {
 		return new LessonDoc(entry);

package/dist/database/MetaDB.ts

@@ -3,8 +3,8 @@ import { logger } from '../utils/logger';
 import { type CollectionEntry } from 'astro:content';
 import { BaseDB } from './BaseDB';
 
-export const COLLECTION_NAME = 'meta' as const;
-export type MetaEntry = CollectionEntry<typeof COLLECTION_NAME>;
+export const COLLECTION_META = 'meta' as const;
+export type MetaEntry = CollectionEntry<typeof COLLECTION_META>;
 
 /**
  * 元数据数据库类，用于管理网站的元数据内容集合（如"关于我们"等页面）
@@ -21,8 +21,8 @@ export type MetaEntry = CollectionEntry<typeof COLLECTION_NAME>;
  *     └── terms.md
  * ```
  */
-class MetaDB extends BaseDB<typeof COLLECTION_NAME, MetaEntry, MetaDoc> {
-	protected collectionName = COLLECTION_NAME;
+class MetaDB extends BaseDB<typeof COLLECTION_META, MetaEntry, MetaDoc> {
+	protected collectionName = COLLECTION_META;
 
 	protected createDoc(entry: MetaEntry): MetaDoc {
 		return new MetaDoc(entry);

package/dist/entities/BaseDoc.ts

@@ -17,81 +17,64 @@ export abstract class BaseDoc<
 	}
 
 	/**
-	 * 获取文档ID
-	 */
-	getId(): string {
-		return this.entry.id;
-	}
-
-	/**
-	 * 获取文档标题
+	 * 获取顶级文档
+	 * 子类应该实现此方法以提供正确的顶级文档
 	 */
-	getTitle(): string {
-		return this.entry.data.title as string;
-	}
+	abstract getTopDoc(): Promise<BaseDoc<Collection, T> | null>;
 
 	/**
-	 * 获取文档语言
+	 * 获取子文档
+	 * 子类应该实现此方法以提供正确的子文档列表
 	 */
-	getLang(): string {
-		return this.entry.id.split('/')[0];
-	}
+	abstract getChildren(): Promise<BaseDoc<Collection, T>[]>;
 
 	/**
-	 * 获取文档slug
+	 * 获取文档的层级深度
+	 * 例如：对于 ID 为 "zh-cn/blog/typescript" 的文档，深度为3
 	 */
-	getSlug(): string {
-		return this.getId().split('/').slice(1).join('/');
+	getLevel(): number {
+		return this.entry.id.split('/').length;
 	}
 
 	/**
-	 * 获取文档描述
+	 * 获取所有祖先文档的ID
+	 * 例如：对于 ID 为 "zh-cn/blog/typescript" 的文档，祖先ID为 ["zh-cn/blog", "zh-cn"]
+	 * @returns 祖先文档的ID列表
 	 */
-	getDescription(): string {
-		return this.entry.data.description as string;
+	getAncestorIds(): string[] {
+		const parts = this.entry.id.split('/');
+		return parts.slice(0, -1).map((part, index) => parts.slice(0, index + 1).join('/'));
 	}
 
 	/**
-	 * 获取文档链接
-	 * 每个子类必须实现此方法以提供正确的链接
-	 */
-	abstract getLink(): string;
-
-	/**
-	 * 渲染文档内容
+	 * 获取指定层级的祖先文档ID
+	 * 例如：对于 ID 为 "zh-cn/blog/typescript" 的文档，level=2 的祖先ID为 "zh-cn/blog"
+	 * @param level 层级深度，从1开始
+	 * @returns 祖先文档的ID
 	 */
-	async render(): Promise<RenderResult> {
-		return await render(this.entry);
+	getAncestorId(level: number): string {
+		const ancestorIds = this.getAncestorIds();
+		return ancestorIds[level - 1];
 	}
 
 	/**
-	 * 获取文档的层级深度
-	 * 例如：对于 ID 为 "zh-cn/blog/typescript" 的文档，深度为3
+	 * 获取顶级侧边栏项目
+	 * 如果有顶级文档，返回顶级文档的侧边栏项目
+	 * 否则返回当前文档的侧边栏项目
 	 */
-	getLevel(): number {
-		return this.entry.id.split('/').length;
-	}
+	async getTopSidebarItem(): Promise<SidebarItemEntity> {
+		const topDoc = await this.getTopDoc();
+		if (topDoc) {
+			return await topDoc.toSidebarItem();
+		}
 
-	/**
-	 * 转换为侧边栏项目
-	 * 基本实现，只包含当前文档
-	 */
-	async toSidebarItem(): Promise<SidebarItemEntity> {
 		return new SidebarItemEntity({
 			text: this.getTitle(),
+			items: [],
 			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"
@@ -99,8 +82,7 @@ export abstract class HierarchicalDoc<
 	 * @returns 父文档ID，如果没有父文档则返回null
 	 */
 	getParentId(): string | null {
-		const parts = this.entry.id.split('/');
-		return parts.length > 1 ? parts.slice(0, -1).join('/') : null;
+		return this.getAncestorId(this.getLevel() - 1);
 	}
 
 	/**
@@ -110,29 +92,63 @@ export abstract class HierarchicalDoc<
 	 * 默认实现假设顶级ID是前两部分
 	 * 子类可以根据需要覆盖此方法
 	 */
-	async getTopDocId(): Promise<string> {
-		const id = this.entry.id;
-		const parts = id.split('/');
-		return parts[0] + '/' + parts[1];
+	getTopDocId(): string {
+		return this.getAncestorId(2);
 	}
 
 	/**
-	 * 获取顶级文档
-	 * 子类应该实现此方法以提供正确的顶级文档
+	 * 获取文档ID
 	 */
-	abstract getTopDoc(): Promise<HierarchicalDoc<Collection, T> | null>;
+	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;
+
+	/**
+	 * 渲染文档内容
 	 */
-	abstract getChildren(): Promise<HierarchicalDoc<Collection, T>[]>;
+	async render(): Promise<RenderResult> {
+		return await render(this.entry);
+	}
 
 	/**
 	 * 转换为侧边栏项目
 	 * 如果文档有子文档，会包含子文档的侧边栏项目
 	 */
-	override async toSidebarItem(): Promise<SidebarItemEntity> {
+	async toSidebarItem(): Promise<SidebarItemEntity> {
 		const debug = false;
 
 		const children = await this.getChildren();
@@ -149,22 +165,4 @@ export abstract class HierarchicalDoc<
 			link: this.getLink(),
 		});
 	}
-
-	/**
-	 * 获取顶级侧边栏项目
-	 * 如果有顶级文档，返回顶级文档的侧边栏项目
-	 * 否则返回当前文档的侧边栏项目
-	 */
-	async getTopSidebarItem(): Promise<SidebarItemEntity> {
-		const topDoc = await this.getTopDoc();
-		if (topDoc) {
-			return await topDoc.toSidebarItem();
-		}
-
-		return new SidebarItemEntity({
-			text: this.getTitle(),
-			items: [],
-			link: this.getLink(),
-		});
-	}
 }

package/dist/entities/BlogDoc.ts

@@ -2,9 +2,10 @@ import type { BlogEntry } from '../database/BlogDB';
 import { LinkUtil } from '../utils/link';
 import Tag from './Tag';
 import { BaseDoc } from './BaseDoc';
-import { COLLECTION_NAME } from '../database/BlogDB';
+import { COLLECTION_BLOG } from '../database/BlogDB';
+import blogDB from '../database/BlogDB';
 
-export default class BlogDoc extends BaseDoc<typeof COLLECTION_NAME, BlogEntry> {
+export default class BlogDoc extends BaseDoc<typeof COLLECTION_BLOG, BlogEntry> {
 	private constructor(entry: BlogEntry) {
 		super(entry);
 	}
@@ -13,6 +14,16 @@ export default class BlogDoc extends BaseDoc<typeof COLLECTION_NAME, BlogEntry>
 		return new BlogDoc(entry);
 	}
 
+	async getTopDoc(): Promise<BlogDoc | null> {
+		const id = this.getTopDocId();
+		const doc = await blogDB.find(id);
+		return doc;
+	}
+
+	async getChildren(): Promise<BlogDoc[]> {
+		return await blogDB.getChildren(this.entry.id);
+	}
+
 	getLink(): string {
 		return LinkUtil.getBlogLink(this.entry.id, this.getLang());
 	}

package/dist/entities/CourseDoc.ts

@@ -1,12 +1,12 @@
-import { logger } from '@/utils/logger';
+import { logger } from '../utils/logger';
 import { SidebarItemEntity } from './SidebarItem';
 import type { CourseEntry } from '../database/CourseDB';
-import courseDB from '../database/CourseDB';
+import { courseDB } from '../database/CourseDB';
 import { LinkUtil } from '../utils/link';
-import { HierarchicalDoc } from './BaseDoc';
-import { COLLECTION_NAME } from '../database/CourseDB';
+import { COLLECTION_COURSE } from '../database/CourseDB';
+import { BaseDoc } from './BaseDoc';
 
-export default class CourseDoc extends HierarchicalDoc<typeof COLLECTION_NAME, CourseEntry> {
+export default class CourseDoc extends BaseDoc<typeof COLLECTION_COURSE, CourseEntry> {
 	constructor(entry: CourseEntry) {
 		super(entry);
 	}
@@ -19,14 +19,54 @@ export default class CourseDoc extends HierarchicalDoc<typeof COLLECTION_NAME, C
 		return LinkUtil.getCourseLink(this.entry.id);
 	}
 
+	getOrder(): number {
+		return this.entry.data.order;
+	}
+
+	isFolder(): boolean {
+		return this.entry.data.folder;
+	}
+
 	async getTopDoc(): Promise<CourseDoc | null> {
-		const id = await this.getTopDocId();
+		const id = this.getTopDocId();
+		const doc = await courseDB.find(id);
+		return doc;
+	}
+
+	async getAncestor(level: number): Promise<CourseDoc | null> {
+		const debug = false;
+		if (debug) {
+			logger.info(`获取 ${this.entry.id} 的祖先文档，level: ${level}`);
+		}
+
+		if (level >= this.getLevel()) {
+			if (debug) {
+				logger.info(`祖先文档为自身`);
+			}
+			return this;
+		}
+
+		const id = this.getAncestorId(level);
 		const doc = await courseDB.find(id);
 		return doc;
 	}
 
+	/**
+	 * 获取子文档
+	 * @returns 子文档列表
+	 */
 	async getChildren(): Promise<CourseDoc[]> {
-		return await courseDB.getChildren(this.entry.id);
+		const debug = false;
+		const children = (await courseDB.getChildren(this.entry.id)).sort(
+			(a, b) => a.getOrder() - b.getOrder()
+		);
+		if (debug && children.length > 0) {
+			logger.array(
+				`${this.entry.id} 的子文档(${children.length})`,
+				children.map((child) => `#${child.getOrder()} ${child.entry.id}`)
+			);
+		}
+		return children;
 	}
 
 	override async toSidebarItem(): Promise<SidebarItemEntity> {

package/dist/entities/ExperimentDoc.ts

@@ -2,15 +2,12 @@ import type { ExperimentEntry } from '../database/ExperimentDB';
 import experimentDB from '../database/ExperimentDB';
 import { logger } from '../utils/logger';
 import { SidebarItemEntity } from './SidebarItem';
-import type { Heading } from './Heading';
 import { LinkUtil } from '../utils/link';
-import { HierarchicalDoc } from './BaseDoc';
-import { COLLECTION_NAME } from '../database/ExperimentDB';
+import { COLLECTION_EXPERIMENT } from '../database/ExperimentDB';
+import { BaseDoc } from './BaseDoc';
+import type { IHeadingType } from '../types/heading';
 
-export default class ExperimentDoc extends HierarchicalDoc<
-	typeof COLLECTION_NAME,
-	ExperimentEntry
-> {
+export default class ExperimentDoc extends BaseDoc<typeof COLLECTION_EXPERIMENT, ExperimentEntry> {
 	constructor(entry: ExperimentEntry) {
 		super(entry);
 	}
@@ -70,14 +67,14 @@ export default class ExperimentDoc extends HierarchicalDoc<
 		return this.entry.rendered?.html || '';
 	}
 
-	getHeadings(): Heading[] {
+	getHeadings(): IHeadingType[] {
 		const debug = false;
 
 		if (debug) {
 			logger.info(`获取 ${this.entry.id} 的 headings`);
 		}
 
-		return (this.entry.rendered?.metadata?.headings as Heading[]) || [];
+		return (this.entry.rendered?.metadata?.headings as IHeadingType[]) || [];
 	}
 
 	async getTopDoc(): Promise<ExperimentDoc | null> {

package/dist/entities/LessonDoc.ts

@@ -2,12 +2,12 @@ import type { LessonEntry } from '../database/LessonDB';
 import lessonDB from '../database/LessonDB';
 import { logger } from '../utils/logger';
 import { SidebarItemEntity } from './SidebarItem';
-import type { Heading } from './Heading';
 import { LinkUtil } from '../utils/link';
-import { HierarchicalDoc } from './BaseDoc';
-import { COLLECTION_NAME } from '../database/LessonDB';
+import { COLLECTION_LESSON } from '../database/LessonDB';
+import { BaseDoc } from './BaseDoc';
+import type { IHeadingType } from '../types/heading';
 
-export default class LessonDoc extends HierarchicalDoc<typeof COLLECTION_NAME, LessonEntry> {
+export default class LessonDoc extends BaseDoc<typeof COLLECTION_LESSON, LessonEntry> {
 	constructor(entry: LessonEntry) {
 		super(entry);
 	}
@@ -67,14 +67,14 @@ export default class LessonDoc extends HierarchicalDoc<typeof COLLECTION_NAME, L
 		return this.entry.rendered?.html || '';
 	}
 
-	getHeadings(): Heading[] {
+	getHeadings(): IHeadingType[] {
 		const debug = false;
 
 		if (debug) {
 			logger.info(`获取 ${this.entry.id} 的 headings`);
 		}
 
-		return (this.entry.rendered?.metadata?.headings as Heading[]) || [];
+		return (this.entry.rendered?.metadata?.headings as IHeadingType[]) || [];
 	}
 
 	async getTopDoc(): Promise<LessonDoc | null> {

package/dist/entities/MetaDoc.ts

@@ -3,9 +3,9 @@ import type { MetaEntry } from '../database/MetaDB';
 import { LinkUtil } from '../utils/link';
 import { BaseDoc } from './BaseDoc';
 import metaDB from '../database/MetaDB';
-import { COLLECTION_NAME } from '../database/MetaDB';
+import { COLLECTION_META } from '../database/MetaDB';
 
-export default class MetaDoc extends BaseDoc<typeof COLLECTION_NAME, MetaEntry> {
+export default class MetaDoc extends BaseDoc<typeof COLLECTION_META, MetaEntry> {
 	constructor(entry: MetaEntry) {
 		super(entry);
 	}

package/dist/index.ts

@@ -7,14 +7,6 @@ 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';
 
-// Collections
-export * from './collections/ArticleCollection';
-export * from './collections/BlogCollection';
-export * from './collections/CourseCollection';
-export * from './collections/ExperimentCollection';
-export * from './collections/LessonCollection';
-export * from './collections/MetaCollection';
-
 // Navigation
 export { default as ThemeSwitcher } from './components/navigation/ThemeSwitcher.astro';
 export { default as TableOfContents } from './components/navigation/TableOfContents.astro';
@@ -110,7 +102,6 @@ export * from './entities/BaseDoc';
 export * from './entities/BlogDoc';
 export * from './entities/CourseDoc';
 export * from './entities/ExperimentDoc';
-export * from './entities/Heading';
 export * from './entities/LessonDoc';
 export * from './entities/MetaDoc';
 export * from './entities/SidebarItem';
@@ -118,3 +109,8 @@ export * from './entities/Tag';
 
 // Database
 export * from './database/BaseDB';
+export * from './database/BlogDB';
+export * from './database/CourseDB';
+export * from './database/ExperimentDB';
+export * from './database/LessonDB';
+export * from './database/MetaDB';

package/dist/utils/link.ts

@@ -93,7 +93,7 @@ export class LinkUtil {
 			logger.info(`获取课程文档链接，课程文档ID: ${courseId}`);
 		}
 
-		return `/${lang}/courses/${courseIdWithoutLang}`;
+		return LinkUtil.createUrl(`/${lang}/courses/${courseIdWithoutLang}`);
 	}
 
 	static getMetaLink(lang: string, slug: string): string {

package/dist/utils/logger.ts

@@ -15,7 +15,7 @@ const colors = {
 
 class Logger {
 	private formatArray(arr: any[]): string {
-		const MAX_LINES = 30;
+		const MAX_LINES = 70;
 		const MAX_LENGTH = 100;
 
 		const truncateString = (str: string): string => {