@coffic/cosy-ui 0.7.2 → 0.8.6

package/dist/{database → src-astro/database}/LessonDB.ts

@@ -40,62 +40,66 @@ export type LessonEntry = CollectionEntry<typeof COLLECTION_LESSON>;
  * - 每个语言版本包含完整的课程内容
  * - 课程目录可以作为 git 子模块独立管理
  */
-class LessonDB extends BaseDB<typeof COLLECTION_LESSON, LessonEntry, LessonDoc> {
-	protected collectionName = COLLECTION_LESSON;
+class LessonDB extends BaseDB<
+  typeof COLLECTION_LESSON,
+  LessonEntry,
+  LessonDoc
+> {
+  protected collectionName = COLLECTION_LESSON;
 
-	protected createDoc(entry: LessonEntry): LessonDoc {
-		return new LessonDoc(entry);
-	}
+  protected createDoc(entry: LessonEntry): LessonDoc {
+    return new LessonDoc(entry);
+  }
 
-	/**
-	 * 获取指定语言的所有课程
-	 *
-	 * @param {string} lang - 语言代码
-	 * @returns {Promise<LessonDoc[]>} 返回指定语言的所有课程
-	 */
-	async allLessons(lang: string): Promise<LessonDoc[]> {
-		const docs = await this.getDocsByDepth(2);
-		return docs.filter((doc) => doc.getId().endsWith(lang));
-	}
+  /**
+   * 获取指定语言的所有课程
+   *
+   * @param {string} lang - 语言代码
+   * @returns {Promise<LessonDoc[]>} 返回指定语言的所有课程
+   */
+  async allLessons(lang: string): Promise<LessonDoc[]> {
+    const docs = await this.getDocsByDepth(2);
+    return docs.filter((doc) => doc.getId().endsWith(lang));
+  }
 
-	/**
-	 * 获取用于 Astro 静态路由生成的路径参数
-	 * 
-	 * @param debug - 是否开启调试模式
-	 * @returns 返回路径参数数组
-	 */
-	async getStaticPaths(debug: boolean = false) {
-		const docs = await this.getEntries();
+  /**
+   * 获取用于 Astro 静态路由生成的路径参数
+   *
+   * @param debug - 是否开启调试模式
+   * @returns 返回路径参数数组
+   */
+  async getStaticPaths(debug: boolean = false) {
+    const docs = await this.getEntries();
 
-		if (debug) {
-			cosyLogger.array('所有文档', docs);
-		}
+    if (debug) {
+      cosyLogger.array('所有文档', docs);
+    }
 
-		const paths = docs.map((doc) => {
-			const id = doc.id;
-			const lang = id.split('/')[1];
+    const paths = docs.map((doc) => {
+      const id = doc.id;
+      const lang = id.split('/')[1];
 
-			let slug = '';
-			if (id.endsWith(lang)) {
-				slug = id.replace(`${lang}`, '');
-			} else {
-				slug = id.replace(`${lang}/`, '');
-			}
+      let slug = '';
+      if (id.endsWith(lang)) {
+        slug = id.replace(`${lang}`, '');
+      } else {
+        slug = id.replace(`${lang}/`, '');
+      }
 
-			return {
-				params: {
-					lang: lang,
-					slug: slug,
-				},
-			};
-		});
+      return {
+        params: {
+          lang: lang,
+          slug: slug,
+        },
+      };
+    });
 
-		if (debug) {
-			cosyLogger.array('所有文档的路径', paths);
-		}
+    if (debug) {
+      cosyLogger.array('所有文档的路径', paths);
+    }
 
-		return paths;
-	}
+    return paths;
+  }
 }
 
 // 创建并导出单例实例

package/dist/src-astro/database/MetaDB.ts

@@ -0,0 +1,74 @@
+import MetaDoc from '../entities/MetaDoc';
+import { cosyLogger } from '../cosy';
+import { type CollectionEntry } from 'astro:content';
+import { BaseDB } from './BaseDB';
+
+export const COLLECTION_META = 'meta' as const;
+export type MetaEntry = CollectionEntry<typeof COLLECTION_META>;
+
+/**
+ * 元数据数据库类，用于管理网站的元数据内容集合（如"关于我们"等页面）
+ *
+ * 目录结构：
+ * ```
+ * meta/
+ * ├── zh-cn/                          # 中文内容
+ * │   ├── about.md                    # 关于我们
+ * │   ├── advice.md                   # 建议
+ * └── en/                             # 英文内容
+ *     ├── about.md
+ *     ├── privacy.md
+ *     └── terms.md
+ * ```
+ */
+class MetaDB extends BaseDB<typeof COLLECTION_META, MetaEntry, MetaDoc> {
+  protected collectionName = COLLECTION_META;
+
+  protected createDoc(entry: MetaEntry): MetaDoc {
+    return new MetaDoc(entry);
+  }
+
+  /**
+   * 获取指定文档的兄弟文档
+   * 例如：对于 'zh-cn/about'，会返回 'zh-cn' 下的文档
+   *
+   * @param targetId - 目标文档ID
+   * @returns 返回兄弟文档数组（包括目标文档本身）
+   */
+  async getSiblings(targetId: string): Promise<MetaDoc[]> {
+    const target = await this.find(targetId);
+    if (!target) {
+      return [];
+    }
+    const docs = await this.getDocsByDepth(2);
+    return docs.filter((doc) => doc.getLang() === target.getLang());
+  }
+
+  /**
+   * 获取用于 Astro 静态路由生成的路径参数，专门配合 [lang]/meta/[slug].astro 使用
+   *
+   * @param debug - 是否开启调试模式
+   * @returns 返回路径参数数组
+   */
+  async getStaticPaths(debug: boolean = false) {
+    const docs = await this.getDescendantDocs('');
+
+    const paths = docs.map((doc) => {
+      return {
+        params: {
+          lang: doc.getLang(),
+          slug: doc.getSlug(),
+        },
+      };
+    });
+
+    if (debug) {
+      cosyLogger.array('所有元数据文档的路径', paths);
+    }
+
+    return paths;
+  }
+}
+
+// 创建并导出单例实例
+export const metaDB = new MetaDB();

package/dist/src-astro/entities/BaseDoc.ts

@@ -0,0 +1,207 @@
+import {
+  render,
+  type RenderResult,
+  type CollectionEntry,
+  type DataEntryMap,
+} from 'astro:content';
+import { SidebarItemEntity, type SidebarProvider } from './SidebarItem';
+import { cosyLogger, ERROR_PREFIX } from '../cosy';
+
+/**
+ * 文档基类，提供所有文档类型共享的基本功能
+ */
+export abstract class BaseDoc<
+  Collection extends keyof DataEntryMap,
+  T extends CollectionEntry<Collection>,
+> implements SidebarProvider
+{
+  protected entry: T;
+
+  constructor(entry: T) {
+    this.entry = entry;
+  }
+
+  /**
+   * 获取顶级文档
+   * 子类应该实现此方法以提供正确的顶级文档
+   */
+  abstract getTopDoc(): Promise<BaseDoc<Collection, T> | null>;
+
+  /**
+   * 获取子文档
+   * 子类应该实现此方法以提供正确的子文档列表
+   */
+  abstract getChildren(): Promise<BaseDoc<Collection, T>[]>;
+
+  /**
+   * 获取文档的层级深度
+   * 例如：对于 ID 为 "zh-cn/blog/typescript" 的文档，深度为3
+   */
+  getLevel(): number {
+    return this.entry.id.split('/').length;
+  }
+
+  /**
+   * 获取所有祖先文档的ID
+   * 例如：对于 ID 为 "zh-cn/blog/typescript" 的文档，祖先ID为 ["zh-cn/blog", "zh-cn"]
+   * @returns 祖先文档的ID列表
+   */
+  getAncestorIds(): string[] {
+    const parts = this.entry.id.split('/');
+    return parts
+      .slice(0, -1)
+      .map((_part, index) => parts.slice(0, index + 1).join('/'));
+  }
+
+  /**
+   * 获取指定层级的祖先文档ID
+   * 例如：对于 ID 为 "zh-cn/blog/typescript" 的文档，level=2 的祖先ID为 "zh-cn/blog"
+   * @param level 层级深度，从1开始
+   * @returns 祖先文档的ID
+   */
+  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];
+  }
+
+  /**
+   * 获取顶级侧边栏项目
+   * 如果有顶级文档，返回顶级文档的侧边栏项目
+   * 否则返回当前文档的侧边栏项目
+   */
+  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(),
+    });
+  }
+
+  /**
+   * 获取父文档ID
+   * 例如：对于 ID 为 "zh-cn/blog/typescript" 的文档，父ID为 "zh-cn/blog"
+   *
+   * @returns 父文档ID，如果没有父文档则返回null
+   */
+  getParentId(): string | null {
+    return this.getAncestorId(this.getLevel() - 1);
+  }
+
+  /**
+   * 获取顶级文档的ID
+   * 例如：对于 ID 为 "zh-cn/blog/typescript" 的文档，顶级ID为 "zh-cn/blog"
+   *
+   * 默认实现假设顶级ID是前两部分
+   * 子类可以根据需要覆盖此方法
+   */
+  getTopDocId(): string {
+    const level = this.getLevel();
+
+    if (level <= 2) {
+      return this.entry.id;
+    }
+
+    return this.getAncestorId(2);
+  }
+
+  /**
+   * 获取文档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);
+  }
+
+  /**
+   * 转换为侧边栏项目
+   * 如果文档有子文档，会包含子文档的侧边栏项目
+   */
+  async toSidebarItem(): Promise<SidebarItemEntity> {
+    const debug = false;
+
+    const children = await this.getChildren();
+    const childItems = await Promise.all(
+      children.map((child) => child.toSidebarItem())
+    );
+
+    if (debug) {
+      cosyLogger.info(`${this.entry.id} 的侧边栏项目`);
+      console.log(childItems);
+    }
+
+    return new SidebarItemEntity({
+      text: this.getTitle(),
+      items: childItems,
+      link: this.getLink(),
+    });
+  }
+}

package/dist/{entities → src-astro/entities}/BlogDoc.ts

@@ -7,7 +7,7 @@ import { blogDB } from '../database/BlogDB';
 
 /**
  * 博客文档类，配合 BlogDB 使用
- * 
+ *
  * 目录结构：
  * ```
  * blogs/
@@ -45,60 +45,63 @@ import { blogDB } from '../database/BlogDB';
  * ```
  */
 
-export default class BlogDoc extends BaseDoc<typeof COLLECTION_BLOG, BlogEntry> {
-	private constructor(entry: BlogEntry) {
-		super(entry);
-	}
+export default class BlogDoc extends BaseDoc<
+  typeof COLLECTION_BLOG,
+  BlogEntry
+> {
+  private constructor(entry: BlogEntry) {
+    super(entry);
+  }
 
-	static fromEntry(entry: BlogEntry) {
-		return new BlogDoc(entry);
-	}
+  static fromEntry(entry: BlogEntry) {
+    return new BlogDoc(entry);
+  }
 
-	async getTopDoc(): Promise<BlogDoc | null> {
-		const id = this.getTopDocId();
-		const doc = await blogDB.find(id);
-		return doc;
-	}
+  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);
-	}
+  async getChildren(): Promise<BlogDoc[]> {
+    return await blogDB.getChildren(this.entry.id);
+  }
 
-	getLink(): string {
-		return LinkUtil.getBlogLink(this.entry.id, this.getLang());
-	}
+  getLink(): string {
+    return LinkUtil.getBlogLink(this.entry.id, this.getLang());
+  }
 
-	getTags(): Tag[] {
-		const tags = this.entry.data.tags as string[];
+  getTags(): Tag[] {
+    const tags = this.entry.data.tags as string[];
 
-		if (!tags || tags.length === 0) {
-			return [];
-		}
+    if (!tags || tags.length === 0) {
+      return [];
+    }
 
-		return tags.map((tag) => new Tag(tag, 0, this.getLang()));
-	}
+    return tags.map((tag) => new Tag(tag, 0, this.getLang()));
+  }
 
-	getDate(): Date {
-		return new Date(this.entry.data.date as Date);
-	}
+  getDate(): Date {
+    return new Date(this.entry.data.date as Date);
+  }
 
-	getDateForDisplay() {
-		try {
-			const dateObj = new Date(this.entry.data.date as Date);
+  getDateForDisplay() {
+    try {
+      const dateObj = new Date(this.entry.data.date as Date);
 
-			// Check if date is valid
-			if (isNaN(dateObj.getTime())) {
-				console.warn(`Invalid date format: ${this.entry.data.date}`);
-				return 'Date unavailable: ' + this.getTitle() + ' ' + this.getLink();
-			}
-			return dateObj.toLocaleDateString('zh-CN', {
-				year: 'numeric',
-				month: 'long',
-				day: 'numeric',
-			});
-		} catch (error) {
-			console.error(`Error formatting date: ${this.entry.data.date}`, error);
-			return 'Date unavailable';
-		}
-	}
+      // Check if date is valid
+      if (isNaN(dateObj.getTime())) {
+        console.warn(`Invalid date format: ${this.entry.data.date}`);
+        return 'Date unavailable: ' + this.getTitle() + ' ' + this.getLink();
+      }
+      return dateObj.toLocaleDateString('zh-CN', {
+        year: 'numeric',
+        month: 'long',
+        day: 'numeric',
+      });
+    } catch (error) {
+      console.error(`Error formatting date: ${this.entry.data.date}`, error);
+      return 'Date unavailable';
+    }
+  }
 }

package/dist/src-astro/entities/CourseDoc.ts

@@ -0,0 +1,101 @@
+import { cosyLogger } from '../cosy';
+import { SidebarItemEntity } from './SidebarItem';
+import type { CourseEntry } from '../database/CourseDB';
+import { courseDB } from '../database/CourseDB';
+import { LinkUtil } from '../utils/link';
+import { COLLECTION_COURSE } from '../database/CourseDB';
+import { BaseDoc } from './BaseDoc';
+
+export default class CourseDoc extends BaseDoc<
+  typeof COLLECTION_COURSE,
+  CourseEntry
+> {
+  constructor(entry: CourseEntry) {
+    super(entry);
+  }
+
+  static fromEntry(entry: CourseEntry) {
+    return new CourseDoc(entry);
+  }
+
+  getLink(): string {
+    return LinkUtil.getCourseLink(this.entry.id);
+  }
+
+  getOrder(): number {
+    return this.entry.data.order ?? 0;
+  }
+
+  isFolder(): boolean {
+    return this.entry.data.folder ?? false;
+  }
+
+  async getTopDoc(): Promise<CourseDoc | null> {
+    const id = this.getTopDocId();
+    const doc = await courseDB.find(id);
+    return doc;
+  }
+
+  async getAncestor(level: number): Promise<CourseDoc | null> {
+    const debug = false;
+    if (debug) {
+      cosyLogger.info(`获取 ${this.entry.id} 的祖先文档，level: ${level}`);
+    }
+
+    if (level >= this.getLevel()) {
+      if (debug) {
+        cosyLogger.info(`祖先文档为自身`);
+      }
+      return this;
+    }
+
+    const id = this.getAncestorId(level);
+    const doc = await courseDB.find(id);
+    return doc;
+  }
+
+  /**
+   * 获取子文档
+   * @returns 子文档列表
+   */
+  async getChildren(): Promise<CourseDoc[]> {
+    const debug = false;
+    const children = (await courseDB.getChildren(this.entry.id)).sort(
+      (a, b) => a.getOrder() - b.getOrder()
+    );
+    if (debug && children.length > 0) {
+      cosyLogger.array(
+        `${this.entry.id} 的子文档(${children.length})`,
+        children.map((child) => `#${child.getOrder()} ${child.entry.id}`)
+      );
+    }
+    return children;
+  }
+
+  override async toSidebarItem(): Promise<SidebarItemEntity> {
+    const debug = false;
+    const children = await this.getChildren();
+    let childItems = await Promise.all(
+      children.map((child) => child.toSidebarItem())
+    );
+
+    if (this.isBook()) {
+      childItems = [...childItems];
+    }
+
+    if (debug) {
+      cosyLogger.info(`${this.entry.id} 的侧边栏项目`);
+      console.log(childItems);
+    }
+
+    return new SidebarItemEntity({
+      text: this.getTitle(),
+      items: childItems,
+      link: this.getLink(),
+    });
+  }
+
+  isBook(): boolean {
+    return this.entry.id.split('/').length === 2;
+  }
+}