@coffic/cosy-ui 0.5.8 → 0.5.14

package/dist/database/ExperimentDB.ts

@@ -0,0 +1,103 @@
+import { type CollectionEntry } from 'astro:content';
+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>;
+
+/**
+ * 实验数据库类，用于管理实验内容集合
+ *
+ * 目录结构：
+ * ```
+ * experiments/
+ * ├── safari_itp/           # 实验目录
+ * │   ├── 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 子模块独立管理
+ */
+class ExperimentDB extends BaseDB<typeof COLLECTION_NAME, ExperimentEntry, ExperimentDoc> {
+	protected collectionName = COLLECTION_NAME;
+
+	protected createDoc(entry: ExperimentEntry): ExperimentDoc {
+		return new ExperimentDoc(entry);
+	}
+
+	/**
+	 * 获取指定语言的所有课程
+	 *
+	 * @param {string} lang - 语言代码
+	 * @returns {Promise<ExperimentDoc[]>} 返回指定语言的所有课程
+	 */
+	async allExperiments(lang: string): Promise<ExperimentDoc[]> {
+		const docs = await this.getDocsByDepth(2);
+		return docs.filter((doc) => doc.getId().endsWith(lang));
+	}
+
+	/**
+	 * 获取用于 Astro 静态路由生成的路径参数
+	 *
+	 * @returns 返回路径参数数组
+	 */
+	async getStaticPaths() {
+		const debug = false;
+		const docs = await this.getEntries();
+
+		if (debug) {
+			logger.array('所有文档', docs);
+		}
+
+		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}/`, '');
+			}
+
+			return {
+				params: {
+					lang: lang,
+					slug: slug,
+				},
+			};
+		});
+
+		if (debug) {
+			logger.array('所有文档的路径', paths);
+		}
+
+		return paths;
+	}
+}
+
+// 创建并导出单例实例
+const experimentDB = new ExperimentDB();
+export default experimentDB;

package/dist/database/LessonDB.ts

@@ -0,0 +1,103 @@
+import { type CollectionEntry } from 'astro:content';
+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>;
+
+/**
+ * 课程数据库类，用于管理课程内容集合
+ *
+ * 目录结构：
+ * ```
+ * 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 子模块独立管理
+ */
+class LessonDB extends BaseDB<typeof COLLECTION_NAME, LessonEntry, LessonDoc> {
+	protected collectionName = COLLECTION_NAME;
+
+	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));
+	}
+
+	/**
+	 * 获取用于 Astro 静态路由生成的路径参数
+	 *
+	 * @returns 返回路径参数数组
+	 */
+	async getStaticPaths() {
+		const debug = false;
+		const docs = await this.getEntries();
+
+		if (debug) {
+			logger.array('所有文档', docs);
+		}
+
+		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}/`, '');
+			}
+
+			return {
+				params: {
+					lang: lang,
+					slug: slug,
+				},
+			};
+		});
+
+		if (debug) {
+			logger.array('所有文档的路径', paths);
+		}
+
+		return paths;
+	}
+}
+
+// 创建并导出单例实例
+const lessonDB = new LessonDB();
+export default lessonDB;

package/dist/database/MetaDB.ts

@@ -0,0 +1,75 @@
+import MetaDoc from '../entities/MetaDoc';
+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>;
+
+/**
+ * 元数据数据库类，用于管理网站的元数据内容集合（如"关于我们"等页面）
+ *
+ * 目录结构：
+ * ```
+ * meta/
+ * ├── zh-cn/                          # 中文内容
+ * │   ├── about.md                    # 关于我们
+ * │   ├── advice.md                   # 建议
+ * └── en/                             # 英文内容
+ *     ├── about.md
+ *     ├── privacy.md
+ *     └── terms.md
+ * ```
+ */
+class MetaDB extends BaseDB<typeof COLLECTION_NAME, MetaEntry, MetaDoc> {
+	protected collectionName = COLLECTION_NAME;
+
+	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 使用
+	 *
+	 * @returns 返回路径参数数组
+	 */
+	async getStaticPaths() {
+		const debug = false;
+		const docs = await this.getDescendantDocs('');
+
+		const paths = docs.map((doc) => {
+			return {
+				params: {
+					lang: doc.getLang(),
+					slug: doc.getSlug(),
+				},
+			};
+		});
+
+		if (debug) {
+			logger.array('所有元数据文档的路径', paths);
+		}
+
+		return paths;
+	}
+}
+
+// 创建并导出单例实例
+const metaDB = new MetaDB();
+export default metaDB;

package/dist/entities/BaseDoc.ts

@@ -0,0 +1,170 @@
+import { render, type RenderResult, type CollectionEntry, type DataEntryMap } from 'astro:content';
+import { SidebarItemEntity, type SidebarProvider } from './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<SidebarItemEntity> {
+		return new SidebarItemEntity({
+			text: 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<SidebarItemEntity> {
+		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} 的侧边栏项目`);
+			console.log(childItems);
+		}
+
+		return new SidebarItemEntity({
+			text: this.getTitle(),
+			items: childItems,
+			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

@@ -0,0 +1,53 @@
+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';
+
+export default class BlogDoc extends BaseDoc<typeof COLLECTION_NAME, BlogEntry> {
+	private constructor(entry: BlogEntry) {
+		super(entry);
+	}
+
+	static fromEntry(entry: BlogEntry) {
+		return new BlogDoc(entry);
+	}
+
+	getLink(): string {
+		return LinkUtil.getBlogLink(this.entry.id, this.getLang());
+	}
+
+	getTags(): Tag[] {
+		const tags = this.entry.data.tags as string[];
+
+		if (!tags || tags.length === 0) {
+			return [];
+		}
+
+		return tags.map((tag) => new Tag(tag, 0, this.getLang()));
+	}
+
+	getDate(): Date {
+		return 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';
+		}
+	}
+}

package/dist/entities/CourseDoc.ts

@@ -0,0 +1,56 @@
+import { logger } from '@/utils/logger';
+import { SidebarItemEntity } from './SidebarItem';
+import type { CourseEntry } from '../database/CourseDB';
+import courseDB from '../database/CourseDB';
+import { LinkUtil } from '../utils/link';
+import { HierarchicalDoc } from './BaseDoc';
+import { COLLECTION_NAME } from '../database/CourseDB';
+
+export default class CourseDoc extends HierarchicalDoc<typeof COLLECTION_NAME, CourseEntry> {
+	constructor(entry: CourseEntry) {
+		super(entry);
+	}
+
+	static fromEntry(entry: CourseEntry) {
+		return new CourseDoc(entry);
+	}
+
+	getLink(): string {
+		return LinkUtil.getCourseLink(this.entry.id);
+	}
+
+	async getTopDoc(): Promise<CourseDoc | null> {
+		const id = await this.getTopDocId();
+		const doc = await courseDB.find(id);
+		return doc;
+	}
+
+	async getChildren(): Promise<CourseDoc[]> {
+		return await courseDB.getChildren(this.entry.id);
+	}
+
+	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) {
+			logger.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;
+	}
+}

package/dist/entities/ExperimentDoc.ts

@@ -0,0 +1,117 @@
+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';
+
+export default class ExperimentDoc extends HierarchicalDoc<
+	typeof COLLECTION_NAME,
+	ExperimentEntry
+> {
+	constructor(entry: ExperimentEntry) {
+		super(entry);
+	}
+
+	isBook(): boolean {
+		return this.entry.id.split('/').length === 2;
+	}
+
+	async getBookId(): Promise<string> {
+		return await this.getTopDocId();
+	}
+
+	async getBook(): Promise<ExperimentDoc | null> {
+		const bookId = await this.getBookId();
+		return await experimentDB.find(bookId);
+	}
+
+	getLink(): string {
+		const debug = false;
+		const lang = this.getLang();
+		const link = LinkUtil.getExperimentLink(lang, this.getId());
+
+		if (debug) {
+			logger.info(`获取 ${this.entry.id} 的链接: ${link}`);
+		}
+
+		return link;
+	}
+
+	/**
+	 * 获取文档的语言
+	 *
+	 * 文档的 id 格式为 `book-id/zh-cn/chapter-id/lesson-id`
+	 *
+	 * @returns 语言
+	 */
+	override getLang(): string {
+		const debug = false;
+
+		const parts = this.entry.id.split('/');
+		const lang = parts[1];
+
+		if (debug) {
+			logger.info(`获取 ${this.entry.id} 的语言: ${lang}`);
+		}
+
+		return lang;
+	}
+
+	getHTML(): string {
+		const debug = false;
+
+		if (debug) {
+			logger.info(`获取 ${this.entry.id} 的 HTML`);
+		}
+
+		return this.entry.rendered?.html || '';
+	}
+
+	getHeadings(): Heading[] {
+		const debug = false;
+
+		if (debug) {
+			logger.info(`获取 ${this.entry.id} 的 headings`);
+		}
+
+		return (this.entry.rendered?.metadata?.headings as Heading[]) || [];
+	}
+
+	async getTopDoc(): Promise<ExperimentDoc | null> {
+		const bookId = await this.getBookId();
+		return await experimentDB.find(bookId);
+	}
+
+	async getChildren(): Promise<ExperimentDoc[]> {
+		return await experimentDB.getChildren(this.entry.id);
+	}
+
+	async getDescendants(): Promise<ExperimentDoc[]> {
+		return await experimentDB.getDescendantDocs(this.entry.id);
+	}
+
+	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) {
+			logger.info(`${this.entry.id} 的侧边栏项目`);
+			console.log(childItems);
+		}
+
+		return new SidebarItemEntity({
+			text: this.getTitle(),
+			items: childItems,
+			link: this.getLink(),
+		});
+	}
+}

package/dist/entities/Heading.ts

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