@coffic/cosy-ui 0.9.4 → 0.9.5

package/dist/src-astro/collection/repos/ExperimentRepo.ts

@@ -0,0 +1,121 @@
+import { defineCollection, z, type CollectionEntry } from 'astro:content';
+import { BaseDB } from './BaseRepo';
+import ExperimentDoc from '../entities/ExperimentDoc';
+import { cosyLogger } from '../../cosy';
+import { glob } from 'astro/loaders';
+
+export const COLLECTION_EXPERIMENT = 'experiments' as const;
+export type ExperimentEntry = CollectionEntry<typeof COLLECTION_EXPERIMENT>;
+
+/**
+ * 实验数据库类，用于管理实验内容集合
+ *
+ * 目录结构：
+ * ```
+ * 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 ExperimentRepo extends BaseDB<
+    typeof COLLECTION_EXPERIMENT,
+    ExperimentEntry,
+    ExperimentDoc
+> {
+    protected collectionName = COLLECTION_EXPERIMENT;
+
+    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 静态路由生成的路径参数
+     *
+     * @param debug - 是否开启调试模式
+     * @returns 返回路径参数数组
+     */
+    async getStaticPaths(debug: boolean = false) {
+        const docs = await this.getEntries();
+
+        if (debug) {
+            cosyLogger.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) {
+            cosyLogger.array('所有文档的路径', paths);
+        }
+
+        return paths;
+    }
+
+    makeExperimentCollection = (base: string) => {
+        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 experimentRepo = new ExperimentRepo();

package/dist/src-astro/collection/repos/LessonRepo.ts

@@ -0,0 +1,128 @@
+import { defineCollection, z, type CollectionEntry } from 'astro:content';
+import { BaseDB } from './BaseRepo';
+import LessonDoc from '../entities/LessonDoc';
+import { cosyLogger } from '../../cosy';
+import { glob } from 'astro/loaders';
+
+export const COLLECTION_LESSON = 'lessons' as const;
+export type LessonEntry = CollectionEntry<typeof COLLECTION_LESSON>;
+
+/**
+ * 课程数据库类，用于管理课程内容集合
+ *
+ * 目录结构：
+ * ```
+ * 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 LessonRepo extends BaseDB<
+    typeof COLLECTION_LESSON,
+    LessonEntry,
+    LessonDoc
+> {
+    protected collectionName = COLLECTION_LESSON;
+
+    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 静态路由生成的路径参数
+     *
+     * @param debug - 是否开启调试模式
+     * @returns 返回路径参数数组
+     */
+    async getStaticPaths(debug: boolean = false) {
+        const docs = await this.getEntries();
+
+        if (debug) {
+            cosyLogger.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) {
+            cosyLogger.array('所有文档的路径', paths);
+        }
+
+        return paths;
+    }
+
+    makeLessonCollection = (base: string) => {
+        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 lessonRepo = new LessonRepo();

package/dist/src-astro/collection/repos/MetaRepo.ts

@@ -0,0 +1,89 @@
+import MetaDoc from '../entities/MetaDoc';
+import { cosyLogger } from '../../cosy';
+import { defineCollection, z, type CollectionEntry } from 'astro:content';
+import { BaseDB } from './BaseRepo';
+import { glob } from 'astro/loaders';
+
+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 MetaRepo 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;
+    }
+
+    makeMetaCollection = (base: string) => {
+        return defineCollection({
+            loader: glob({
+                pattern: '**/*.{md,mdx}',
+                base,
+            }),
+            schema: z.object({
+                title: z.string().optional(),
+                description: z.string().optional(),
+            }),
+        });
+    };
+
+}
+
+// 创建并导出单例实例
+export const metaRepo = new MetaRepo();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffic/cosy-ui",
-  "version": "0.9.4",
+  "version": "0.9.5",
   "description": "An astro component library",
   "author": {
     "name": "nookery",

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

@@ -1,264 +0,0 @@
-import {
-  getCollection,
-  getEntry,
-  type CollectionEntry,
-  type DataEntryMap,
-} from 'astro:content';
-import { cosyLogger, ERROR_PREFIX } from '../cosy';
-import type { BaseDoc } from '../../index-astro';
-
-/**
- * BaseDB 是所有数据库类的基类，提供了通用的文档操作功能。
- *
- * 使用方法：
- * ```typescript
- * class MyDB extends BaseDB<'collection', MyEntry, MyDoc> {
- *     protected collectionName = 'collection' as const;
- *     protected createDoc(entry: MyEntry): MyDoc {
- *         return new MyDoc(entry);
- *     }
- * }
- *
- * // 使用单例模式获取实例
- * const db = MyDB.getInstance();
- * const docs = await db.allTopLevelDocs();
- * ```
- *
- * 类型参数说明：
- * @template Collection - Astro content collection 的名称，必须是 DataEntryMap 的键
- * @template Entry - Collection 对应的条目类型
- * @template Doc - 文档类型，通常是自定义的文档类
- */
-export abstract class BaseDB<
-  Collection extends keyof DataEntryMap,
-  Entry extends CollectionEntry<Collection>,
-  Doc extends BaseDoc<Collection, Entry>,
-> {
-  /** 集合名称，必须在子类中指定 */
-  protected abstract collectionName: Collection;
-
-  /**
-   * 创建文档实例的方法，必须在子类中实现
-   * @param entry - 集合条目
-   * @returns 文档实例
-   */
-  protected abstract createDoc(entry: Entry): Doc;
-
-  /**
-   * 获取所有文档的ID
-   * @returns 返回所有文档的ID数组
-   */
-  protected async getAllIds(): Promise<string[]> {
-    const entries = await getCollection(this.collectionName);
-    return entries.map((entry) => entry.id);
-  }
-
-  /**
-   * 获取集合中的所有条目
-   * @returns 返回所有条目的数组
-   */
-  protected async getEntries(): Promise<Entry[]> {
-    return await getCollection(this.collectionName);
-  }
-
-  /**
-   * 获取指定深度的文档
-   * 深度是指文档 ID 中斜杠的数量加1
-   * 例如：
-   * - "blog.md" 深度为1
-   * - "zh-cn/blog.md" 深度为2
-   * - "zh-cn/tech/blog.md" 深度为3
-   *
-   * @param depth - 文档深度
-   * @returns 返回指定深度的文档数组
-   */
-  protected async getDocsByDepth(depth: number): Promise<Doc[]> {
-    const entries = await getCollection(
-      this.collectionName,
-      ({ id }: { id: string }) => id.split('/').length === depth
-    );
-
-    if (entries.length === 0) {
-      cosyLogger.warn(
-        `[BaseDB] 没有找到深度为${depth}的文档(collection=${this.collectionName as string})`
-      );
-      const allEntries = await getCollection(this.collectionName);
-      cosyLogger.array(
-        '[BaseDB] 所有文档',
-        allEntries.map((entry) => entry.id)
-      );
-      return [];
-    }
-
-    return entries.map((entry) => this.createDoc(entry as Entry));
-  }
-
-  /**
-   * 根据ID查找单个文档
-   * @param id - 文档ID
-   * @param debug - 是否启用调试模式, 默认为false
-   * @throws 如果ID不是字符串类型，则抛出错误
-   * @throws 如果文档不存在，则返回null
-   * @throws 如果发生其他错误，则抛出错误
-   * @returns 返回找到的文档，如果不存在则返回null
-   */
-  async find(id: string, debug: boolean = false): Promise<Doc | null> {
-    if (debug) {
-      cosyLogger.info(`查找文档，ID: ${id}`);
-    }
-
-    if (id == undefined) {
-      cosyLogger.error('ID is undefined');
-      throw new Error(ERROR_PREFIX + 'ID is undefined');
-    }
-
-    if (typeof id !== 'string') {
-      cosyLogger.error('ID must be a string, but got ' + typeof id);
-      cosyLogger.debug(id);
-      throw new Error(
-        ERROR_PREFIX + 'ID must be a string, but got ' + typeof id
-      );
-    }
-
-    // 获取所有文档的ID并排好顺序
-    if (debug) {
-      const allIds = (await this.getAllIds()).sort();
-      cosyLogger.array('所有文档的ID', allIds);
-    }
-
-    // 根据ID查找文档
-    const entry = await getEntry(this.collectionName, id);
-    return entry ? this.createDoc(entry as Entry) : null;
-  }
-
-  /**
-   * 获取指定文档的直接子文档（不包括更深层级的文档）
-   * 例如对于文档 "zh-cn/blog"：
-   * - "zh-cn/blog/post1.md" 会被包含
-   * - "zh-cn/blog/2024/post2.md" 不会被包含
-   *
-   * @param parentId - 父文档ID
-   * @returns 返回子文档数组
-   */
-  async getChildren(parentId: string): Promise<Doc[]> {
-    const parentLevel = parentId.split('/').length;
-    const childrenLevel = parentLevel + 1;
-
-    const entries = await getCollection(
-      this.collectionName,
-      ({ id }: { id: string }) =>
-        id.startsWith(parentId) && id.split('/').length === childrenLevel
-    );
-
-    return entries.map((entry) => this.createDoc(entry as Entry));
-  }
-
-  /**
-   * 获取指定文档的所有后代文档（包括所有层级）
-   * 例如对于文档 "zh-cn/blog"，以下都会被包含：
-   * - "zh-cn/blog/post1.md"
-   * - "zh-cn/blog/2024/post2.md"
-   * - "zh-cn/blog/2024/tech/post3.md"
-   *
-   * @param parentId - 父文档ID
-   * @returns 返回所有后代文档数组
-   */
-  async getDescendantDocs(parentId: string): Promise<Doc[]> {
-    const entries = await getCollection(
-      this.collectionName,
-      ({ id }: { id: string }) => id.startsWith(parentId)
-    );
-    return entries.map((entry) => this.createDoc(entry as Entry));
-  }
-
-  /**
-   * 获取指定语言和级别的文档
-   * 通过检查文档ID是否以指定语言代码开头来筛选
-   *
-   * @param lang - 语言代码（如 'zh-cn', 'en'）
-   * @param level - 文档级别
-   * @returns 返回指定语言和级别的文档数组
-   */
-  protected async allDocsByLangAndLevel(
-    lang: string,
-    level: number = 1,
-    debug: boolean = false
-  ): Promise<Doc[]> {
-    const collectionName = this.collectionName as string;
-    const docs = await this.getDocsByDepth(level);
-
-    if (debug) {
-      cosyLogger.array(
-        `[BaseDB] 所有${level}级文档(lang=any,collection=${collectionName})`,
-        docs
-      );
-    }
-
-    if (docs.length === 0) {
-      cosyLogger.warn(
-        `[BaseDB] 没有找到${level}级文档(lang=any,collection=${collectionName})`
-      );
-      return [];
-    }
-
-    const filteredDocs = docs.filter((doc) => {
-      const id = (doc as any).getId();
-      return id && typeof id === 'string' && id.startsWith(lang);
-    });
-
-    if (debug) {
-      cosyLogger.array(
-        `[BaseDB] 所有${level}级文档(lang=${lang},collection=${collectionName})`,
-        filteredDocs
-      );
-    }
-
-    if (filteredDocs.length === 0) {
-      cosyLogger.warn(
-        `[BaseDB] 没有找到${level}级文档(lang=${lang},collection=${collectionName})`
-      );
-      cosyLogger.array(
-        `[BaseDB] 所有${level}级文档`,
-        docs.map((doc) => doc.getId())
-      );
-      return [];
-    }
-
-    return filteredDocs;
-  }
-
-  /**
-   * 获取用于 Astro 静态路由生成的路径参数
-   * 为每个文档生成包含语言和slug的路径参数
-   *
-   * @returns 返回路径参数数组，每个元素包含 lang 和 slug
-   * @example
-   * ```typescript
-   * const paths = await db.getStaticPaths();
-   * // 返回格式：
-   * // [
-   * //   { params: { lang: 'zh-cn', slug: 'post1' } },
-   * //   { params: { lang: 'en', slug: 'post1' } }
-   * // ]
-   * ```
-   */
-  async getStaticPaths() {
-    const debug = false;
-    const docs = await this.getDescendantDocs('');
-    const paths = docs.map((doc) => {
-      const docWithMethods = doc as any;
-      return {
-        params: {
-          lang: docWithMethods.getLang?.() || '',
-          slug: docWithMethods.getSlug?.() || '',
-        },
-      };
-    });
-
-    if (debug) {
-      cosyLogger.array('所有文档的路径', paths);
-    }
-
-    return paths;
-  }
-}