@coffic/cosy-ui 0.6.36 → 0.6.38

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(),
+        }),
+    });
 };

package/dist/utils/lang_entry.ts

@@ -0,0 +1,240 @@
+/**
+ * 多语言工具类
+ * 
+ * 这个类提供了一套完整的多语言文本管理工具，用于在组件库中处理国际化需求。
+ * 主要特点：
+ * - 提供链式API来创建和管理多语言文本
+ * - 支持动态添加和获取不同语言的文本
+ * - 可以通过属性访问器直接获取特定语言的文本
+ * - 支持合并多个语言条目
+ * 
+ * 使用示例：
+ * ```typescript
+ * // 创建并设置多语言文本
+ * const entry = new LangEntry()
+ *   .setZh('你好')
+ *   .setEn('Hello')
+ *   .setJa('こんにちは');
+ * 
+ * // 获取特定语言的文本
+ * console.log(entry.get('zh-cn')); // 你好
+ * 
+ * // 使用代理后可以通过属性访问
+ * // 需要通过 langEntryHandler 创建代理
+ * const proxiedEntry = new Proxy(entry, langEntryHandler);
+ * console.log(proxiedEntry.en);      // Hello
+ * console.log(proxiedEntry['zh-cn']); // 你好
+ * ```
+ */
+export class LangEntry {
+    private translations: Record<string, string> = {};
+
+    /**
+     * 设置中文文本
+     * 
+     * @param text 中文文本
+     * @returns 返回当前实例，支持链式调用
+     * @example
+     * const entry = new LangEntry().setZh('你好');
+     */
+    setZh(text: string): LangEntry {
+        this.translations['zh-cn'] = text;
+        return this;
+    }
+
+    /**
+     * 设置英文文本
+     * 
+     * @param text 英文文本
+     * @returns 返回当前实例，支持链式调用
+     * @example
+     * const entry = new LangEntry().setEn('Hello');
+     */
+    setEn(text: string): LangEntry {
+        this.translations['en'] = text;
+        return this;
+    }
+
+    /**
+     * 设置日文文本
+     * 
+     * @param text 日文文本
+     * @returns 返回当前实例，支持链式调用
+     * @example
+     * const entry = new LangEntry().setJa('こんにちは');
+     */
+    setJa(text: string): LangEntry {
+        this.translations['ja'] = text;
+        return this;
+    }
+
+    /**
+     * 设置任意语言的文本
+     * 
+     * @param lang 语言代码，如 'fr' 表示法语，'de' 表示德语等
+     * @param text 文本内容
+     * @returns 返回当前实例，支持链式调用
+     * @example
+     * const entry = new LangEntry().set('fr', 'Bonjour').set('de', 'Hallo');
+     */
+    set(lang: string, text: string): LangEntry {
+        this.translations[lang] = text;
+        return this;
+    }
+
+    /**
+     * 设置所有语言为相同的文本值
+     * 适用于不需要翻译的品牌名、专有名词等
+     * 
+     * @param text 所有语言共用的文本
+     * @returns 返回当前实例，支持链式调用
+     * @example
+     * const brandName = new LangEntry().setAll('Cosy UI');
+     */
+    setAll(text: string): LangEntry {
+        // 如果已有语言，则更新它们
+        if (Object.keys(this.translations).length > 0) {
+            for (const lang of Object.keys(this.translations)) {
+                this.translations[lang] = text;
+            }
+        } else {
+            // 默认至少设置中英文
+            this.translations['zh-cn'] = text;
+            this.translations['en'] = text;
+        }
+        return this;
+    }
+
+    /**
+     * 获取指定语言的文本
+     * 
+     * @param lang 语言代码
+     * @param defaultValue 默认值，如果未找到翻译则返回此值
+     * @returns 指定语言的文本，如果不存在则返回默认值或第一个可用的翻译或空字符串
+     * @example
+     * const entry = new LangEntry().setZh('你好').setEn('Hello');
+     * console.log(entry.get('zh-cn'));        // 你好
+     * console.log(entry.get('fr', 'Default')); // Default
+     */
+    get(lang: string, defaultValue?: string): string {
+        return this.translations[lang] || defaultValue || this.getFirst() || '';
+    }
+
+    /**
+     * 获取第一个可用的翻译文本
+     * 
+     * @returns 第一个可用的翻译文本，如果没有任何翻译则返回 undefined
+     * @example
+     * const entry = new LangEntry().setEn('Hello').setZh('你好');
+     * console.log(entry.getFirst()); // 取决于对象属性顺序，可能是 'Hello' 或 '你好'
+     */
+    getFirst(): string | undefined {
+        const keys = Object.keys(this.translations);
+        return keys.length > 0 ? this.translations[keys[0]] : undefined;
+    }
+
+    /**
+     * 获取所有可用的语言代码
+     * 
+     * @returns 所有已设置翻译的语言代码数组
+     * @example
+     * const entry = new LangEntry().setZh('你好').setEn('Hello');
+     * console.log(entry.getLanguages()); // ['zh-cn', 'en']
+     */
+    getLanguages(): string[] {
+        return Object.keys(this.translations);
+    }
+
+    /**
+     * 获取所有翻译
+     * 
+     * @returns 包含所有语言翻译的对象副本
+     * @example
+     * const entry = new LangEntry().setZh('你好').setEn('Hello');
+     * console.log(entry.getAll()); // { 'zh-cn': '你好', 'en': 'Hello' }
+     */
+    getAll(): Record<string, string> {
+        return { ...this.translations };
+    }
+
+    /**
+     * 合并另一个语言条目
+     * 如果两个条目有相同的语言，则后者会覆盖前者
+     * 
+     * @param other 要合并的语言条目
+     * @returns 返回当前实例，支持链式调用
+     * @example
+     * const entry1 = new LangEntry().setZh('你好').setEn('Hello');
+     * const entry2 = new LangEntry().setJa('こんにちは').setEn('Hi');
+     * entry1.merge(entry2);
+     * console.log(entry1.getAll()); // { 'zh-cn': '你好', 'en': 'Hi', 'ja': 'こんにちは' }
+     */
+    merge(other: LangEntry): LangEntry {
+        Object.assign(this.translations, other.getAll());
+        return this;
+    }
+
+    /**
+     * 检查是否包含指定语言
+     * 
+     * @param lang 语言代码
+     * @returns 如果包含指定语言则返回 true，否则返回 false
+     * @example
+     * const entry = new LangEntry().setZh('你好').setEn('Hello');
+     * console.log(entry.has('zh-cn')); // true
+     * console.log(entry.has('ja'));    // false
+     */
+    has(lang: string): boolean {
+        return lang in this.translations;
+    }
+
+    /**
+     * 转换为普通对象
+     * 
+     * @returns 包含所有语言翻译的对象副本
+     * @example
+     * const entry = new LangEntry().setZh('你好').setEn('Hello');
+     * const obj = entry.toObject();
+     * console.log(obj); // { 'zh-cn': '你好', 'en': 'Hello' }
+     */
+    toObject(): Record<string, string> {
+        return { ...this.translations };
+    }
+
+    /**
+     * 允许以对象属性方式访问翻译
+     * 例如: entry['zh-cn'] 或 entry.en
+     * 
+     * 注意：这个索引签名本身不提供功能，实际的属性访问是通过 langEntryHandler 代理实现的
+     */
+    [key: string]: any;
+}
+
+/**
+ * 创建索引访问器的Proxy处理程序
+ * 
+ * 这个处理程序允许通过属性访问方式获取语言翻译，例如：
+ * - entry.en 代替 entry.get('en')
+ * - entry['zh-cn'] 代替 entry.get('zh-cn')
+ * 
+ * @example
+ * const entry = new LangEntry().setZh('你好').setEn('Hello');
+ * const proxiedEntry = new Proxy(entry, langEntryHandler);
+ * console.log(proxiedEntry.en);      // Hello
+ * console.log(proxiedEntry['zh-cn']); // 你好
+ */
+export const langEntryHandler: ProxyHandler<LangEntry> = {
+    get(target: LangEntry, prop: string | symbol): any {
+        // 如果是字符串属性并且不是LangEntry的方法，则尝试作为语言代码获取翻译
+        if (
+            typeof prop === 'string' &&
+            !(prop in Object.getPrototypeOf(target)) &&
+            prop !== 'translations'
+        ) {
+            return target.get(prop);
+        }
+
+        // 否则返回原始属性
+        return (target as any)[prop];
+    },
+};

package/dist/utils/lang_package.ts

@@ -1,221 +1,150 @@
-/**
- * 多语言工具类
- * 提供链式API来创建和管理多语言文本
- */
-export class LangEntry {
-	private translations: Record<string, string> = {};
-
-	/**
-	 * 设置中文文本
-	 * @param text 中文文本
-	 */
-	setZh(text: string): LangEntry {
-		this.translations['zh-cn'] = text;
-		return this;
-	}
-
-	/**
-	 * 设置英文文本
-	 * @param text 英文文本
-	 */
-	setEn(text: string): LangEntry {
-		this.translations['en'] = text;
-		return this;
-	}
-
-	/**
-	 * 设置日文文本
-	 * @param text 日文文本
-	 */
-	setJa(text: string): LangEntry {
-		this.translations['ja'] = text;
-		return this;
-	}
-
-	/**
-	 * 设置任意语言的文本
-	 * @param lang 语言代码
-	 * @param text 文本内容
-	 */
-	set(lang: string, text: string): LangEntry {
-		this.translations[lang] = text;
-		return this;
-	}
-
-	/**
-	 * 设置所有语言为相同的文本值
-	 * 适用于不需要翻译的品牌名、专有名词等
-	 * @param text 所有语言共用的文本
-	 */
-	setAll(text: string): LangEntry {
-		// 如果已有语言，则更新它们
-		if (Object.keys(this.translations).length > 0) {
-			for (const lang of Object.keys(this.translations)) {
-				this.translations[lang] = text;
-			}
-		} else {
-			// 默认至少设置中英文
-			this.translations['zh-cn'] = text;
-			this.translations['en'] = text;
-		}
-		return this;
-	}
-
-	/**
-	 * 获取指定语言的文本
-	 * @param lang 语言代码
-	 * @param defaultValue 默认值，如果未找到翻译则返回此值
-	 */
-	get(lang: string, defaultValue?: string): string {
-		return this.translations[lang] || defaultValue || this.getFirst() || '';
-	}
-
-	/**
-	 * 获取第一个可用的翻译文本
-	 */
-	getFirst(): string | undefined {
-		const keys = Object.keys(this.translations);
-		return keys.length > 0 ? this.translations[keys[0]] : undefined;
-	}
-
-	/**
-	 * 获取所有可用的语言代码
-	 */
-	getLanguages(): string[] {
-		return Object.keys(this.translations);
-	}
-
-	/**
-	 * 获取所有翻译
-	 */
-	getAll(): Record<string, string> {
-		return { ...this.translations };
-	}
-
-	/**
-	 * 合并另一个语言条目
-	 * @param other 要合并的语言条目
-	 */
-	merge(other: LangEntry): LangEntry {
-		Object.assign(this.translations, other.getAll());
-		return this;
-	}
-
-	/**
-	 * 检查是否包含指定语言
-	 * @param lang 语言代码
-	 */
-	has(lang: string): boolean {
-		return lang in this.translations;
-	}
-
-	/**
-	 * 转换为普通对象
-	 */
-	toObject(): Record<string, string> {
-		return { ...this.translations };
-	}
-
-	/**
-	 * 允许以对象属性方式访问翻译
-	 * 例如: entry['zh-cn'] 或 entry.en
-	 */
-	[key: string]: any;
-}
-
-// 创建索引访问器的Proxy处理程序
-const langEntryHandler: ProxyHandler<LangEntry> = {
-	get(target: LangEntry, prop: string | symbol): any {
-		// 如果是字符串属性并且不是LangEntry的方法，则尝试作为语言代码获取翻译
-		if (
-			typeof prop === 'string' &&
-			!(prop in Object.getPrototypeOf(target)) &&
-			prop !== 'translations'
-		) {
-			return target.get(prop);
-		}
-
-		// 否则返回原始属性
-		return (target as any)[prop];
-	},
-};
+import { LangEntry, langEntryHandler } from "./lang_entry";
 
 /**
  * 提供快捷访问的LangPackage
- * 可以直接通过静态方法创建和配置语言条目
+ * 
+ * 这个类提供了一系列静态方法，用于快速创建和配置多语言文本条目。
+ * 它是对 LangEntry 类的便捷封装，简化了多语言文本的创建和管理过程。
+ * 
+ * 使用示例：
+ * ```typescript
+ * // 创建一个空的语言条目并逐步添加翻译
+ * const emptyEntry = LangPackage.make();
+ * emptyEntry.setZh('你好').setEn('Hello');
+ * 
+ * // 从对象创建语言条目
+ * const fromObj = LangPackage.from({
+ *   'zh-cn': '你好',
+ *   'en': 'Hello',
+ *   'ja': 'こんにちは'
+ * });
+ * 
+ * // 创建只包含中英文的语言条目
+ * const zhEnEntry = LangPackage.zhEn('你好', 'Hello');
+ * 
+ * // 创建所有语言都使用相同文本的条目（适用于品牌名等）
+ * const brandName = LangPackage.common('Cosy UI');
+ * 
+ * // 访问翻译的方式
+ * console.log(zhEnEntry.get('zh-cn')); // 你好
+ * console.log(zhEnEntry['zh-cn']);     // 你好 (通过代理实现的属性访问)
+ * console.log(zhEnEntry.en);           // Hello (简写形式)
+ * ```
  */
 export class LangPackage {
-	/**
-	 * 创建一个新的语言条目
-	 */
-	static make(): LangEntry {
-		return new Proxy(new LangEntry(), langEntryHandler);
-	}
-
-	/**
-	 * 从对象创建语言条目
-	 * @param obj 包含语言翻译的对象
-	 */
-	static from(obj: Record<string, string>): LangEntry {
-		const entry = new LangEntry();
-		Object.entries(obj).forEach(([lang, text]) => {
-			entry.set(lang, text);
-		});
-		return new Proxy(entry, langEntryHandler);
-	}
-
-	/**
-	 * 创建只包含中文和英文的语言条目
-	 * @param zh 中文文本
-	 * @param en 英文文本
-	 */
-	static zhEn(zh: string, en: string): LangEntry {
-		return new Proxy(new LangEntry().setZh(zh).setEn(en), langEntryHandler);
-	}
-
-	/**
-	 * 创建所有语言都使用相同文本的语言条目
-	 * 适用于品牌名、产品名等不需要翻译的文本
-	 * @param text 所有语言共用的文本
-	 */
-	static common(text: string): LangEntry {
-		return new Proxy(new LangEntry().setAll(text), langEntryHandler);
-	}
-
-	/**
-	 * 设置中文文本
-	 * 快捷方法，直接返回一个新的LangEntry实例
-	 * @param text 中文文本
-	 */
-	static setZh(text: string): LangEntry {
-		return new Proxy(new LangEntry().setZh(text), langEntryHandler);
-	}
-
-	/**
-	 * 设置英文文本
-	 * 快捷方法，直接返回一个新的LangEntry实例
-	 * @param text 英文文本
-	 */
-	static setEn(text: string): LangEntry {
-		return new Proxy(new LangEntry().setEn(text), langEntryHandler);
-	}
-
-	/**
-	 * 设置日文文本
-	 * 快捷方法，直接返回一个新的LangEntry实例
-	 * @param text 日文文本
-	 */
-	static setJa(text: string): LangEntry {
-		return new Proxy(new LangEntry().setJa(text), langEntryHandler);
-	}
-
-	/**
-	 * 设置任意语言的文本
-	 * 快捷方法，直接返回一个新的LangEntry实例
-	 * @param lang 语言代码
-	 * @param text 文本内容
-	 */
-	static set(lang: string, text: string): LangEntry {
-		return new Proxy(new LangEntry().set(lang, text), langEntryHandler);
-	}
+    /**
+     * 创建一个新的空语言条目
+     * 
+     * @returns 返回一个代理包装的 LangEntry 实例，可以通过属性方式访问翻译
+     * @example
+     * const entry = LangPackage.make();
+     * entry.setZh('你好').setEn('Hello');
+     */
+    static make(): LangEntry {
+        return new Proxy(new LangEntry(), langEntryHandler);
+    }
+
+    /**
+     * 从对象创建语言条目
+     * 
+     * @param obj 包含语言翻译的对象，键为语言代码，值为对应的翻译文本
+     * @returns 返回一个代理包装的 LangEntry 实例
+     * @example
+     * const entry = LangPackage.from({
+     *   'zh-cn': '你好',
+     *   'en': 'Hello',
+     *   'ja': 'こんにちは'
+     * });
+     */
+    static from(obj: Record<string, string>): LangEntry {
+        const entry = new LangEntry();
+        Object.entries(obj).forEach(([lang, text]) => {
+            entry.set(lang, text);
+        });
+        return new Proxy(entry, langEntryHandler);
+    }
+
+    /**
+     * 创建只包含中文和英文的语言条目
+     * 
+     * @param zh 中文文本
+     * @param en 英文文本
+     * @returns 返回一个代理包装的 LangEntry 实例
+     * @example
+     * const entry = LangPackage.zhEn('你好', 'Hello');
+     * console.log(entry.zh-cn); // 你好
+     * console.log(entry.en);    // Hello
+     */
+    static zhEn(zh: string, en: string): LangEntry {
+        return new Proxy(new LangEntry().setZh(zh).setEn(en), langEntryHandler);
+    }
+
+    /**
+     * 创建所有语言都使用相同文本的语言条目
+     * 适用于品牌名、产品名等不需要翻译的文本
+     * 
+     * @param text 所有语言共用的文本
+     * @returns 返回一个代理包装的 LangEntry 实例
+     * @example
+     * const brandName = LangPackage.common('Cosy UI');
+     * // 所有语言都会返回相同的值
+     * console.log(brandName.zh-cn); // Cosy UI
+     * console.log(brandName.en);    // Cosy UI
+     */
+    static common(text: string): LangEntry {
+        return new Proxy(new LangEntry().setAll(text), langEntryHandler);
+    }
+
+    /**
+     * 设置中文文本
+     * 快捷方法，直接返回一个新的LangEntry实例
+     * 
+     * @param text 中文文本
+     * @returns 返回一个代理包装的 LangEntry 实例，只包含中文翻译
+     * @example
+     * const entry = LangPackage.setZh('你好');
+     */
+    static setZh(text: string): LangEntry {
+        return new Proxy(new LangEntry().setZh(text), langEntryHandler);
+    }
+
+    /**
+     * 设置英文文本
+     * 快捷方法，直接返回一个新的LangEntry实例
+     * 
+     * @param text 英文文本
+     * @returns 返回一个代理包装的 LangEntry 实例，只包含英文翻译
+     * @example
+     * const entry = LangPackage.setEn('Hello');
+     */
+    static setEn(text: string): LangEntry {
+        return new Proxy(new LangEntry().setEn(text), langEntryHandler);
+    }
+
+    /**
+     * 设置日文文本
+     * 快捷方法，直接返回一个新的LangEntry实例
+     * 
+     * @param text 日文文本
+     * @returns 返回一个代理包装的 LangEntry 实例，只包含日文翻译
+     * @example
+     * const entry = LangPackage.setJa('こんにちは');
+     */
+    static setJa(text: string): LangEntry {
+        return new Proxy(new LangEntry().setJa(text), langEntryHandler);
+    }
+
+    /**
+     * 设置任意语言的文本
+     * 快捷方法，直接返回一个新的LangEntry实例
+     * 
+     * @param lang 语言代码
+     * @param text 文本内容
+     * @returns 返回一个代理包装的 LangEntry 实例，包含指定语言的翻译
+     * @example
+     * const entry = LangPackage.set('fr', 'Bonjour');
+     */
+    static set(lang: string, text: string): LangEntry {
+        return new Proxy(new LangEntry().set(lang, text), langEntryHandler);
+    }
 }

package/package.json

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