@_tc/template-core 0.2.0 → 0.2.1-bate.1

package/types/config/config.default.d.ts

@@ -40,6 +40,11 @@ export interface DefaultAppConfig {
     viewsPath?: string;
     nunjucks?: import('nunjucks').ConfigureOptions;
     notFoundRedirectCount?: number;
+    /**
+     * 静态资源缓存时间，单位 ms。
+     * @default 5 * 60 * 1000
+     */
+    resourceCacheTimeMs?: number;
     /**
      * 登陆验证相关
      */
@@ -67,5 +72,6 @@ declare const _default: {
         RTKey: string;
     };
     notFoundRedirectCount: number;
+    resourceCacheTimeMs: number;
 };
 export default _default;

package/types/packages/common/i18n/default.d.ts

@@ -4,6 +4,7 @@
  * 这里只放组件内置文案，业务项目可以通过 I18nProvider.resources 覆盖或追加。
  */
 export declare const defaultLanguageResources: {
+    /** 通用操作文案。 */
     readonly common: {
         readonly tip: "提示";
         readonly confirm: "确认";
@@ -12,6 +13,22 @@ export declare const defaultLanguageResources: {
         readonly submit: "提交";
         readonly reset: "重置";
     };
+    readonly server: {
+        readonly errors: {
+            readonly network: "网络错误";
+            readonly invalidRequest: "请求不合法";
+            readonly getProjectFailed: "获取项目异常";
+            readonly dbNodeSqliteUnavailable: "[db] 默认数据库依赖 Node.js 内置 {sqliteSpecifier}，当前运行环境不可用。请升级 Node.js，或在业务项目覆盖 app/extends/db.ts。{cause}";
+            readonly dbDatabaseSyncUnavailable: "[db] {sqliteSpecifier} 未提供 DatabaseSync，无法初始化默认 SQLite 数据库。";
+            readonly dbNamespaceRequired: "[db] namespace 不能为空";
+            readonly dbKeyRequired: "[db] key 不能为空";
+            readonly dbLimitInvalid: "[db] limit 必须是大于 0 的整数";
+            readonly dbOffsetInvalid: "[db] offset 必须是大于等于 0 的整数";
+            readonly dbValueNotSerializable: "[db] value 必须可以被 JSON.stringify 序列化。{cause}";
+            readonly dbClosed: "[db] SQLite 数据库连接已关闭";
+        };
+    };
+    /** UI 组件内置文案，按组件名分组。 */
     readonly components: {
         readonly breadcrumb: {
             readonly close: "关闭";
@@ -59,6 +76,7 @@ export declare const defaultLanguageResources: {
             readonly rotateRight: "右旋转";
             readonly flipHorizontal: "左右镜像";
             readonly flipVertical: "上下镜像";
+            /** {index} 会在运行时由调用方传入的插值数据替换。 */
             readonly previewImage: "预览第{index}张";
         };
         readonly modal: {
@@ -88,4 +106,5 @@ export declare const defaultLanguageResources: {
         };
     };
 };
+/** 默认中文语言资源类型，供调用方推导 key 结构使用。 */
 export type DefaultLanguageResources = typeof defaultLanguageResources;

package/types/packages/common/i18n/en-US.d.ts

@@ -1,9 +1,10 @@
 /**
- * UI component library default English language resources.
+ * UI 组件库默认英文语言资源。
  *
- * Only built-in component copy belongs here. Applications can override or extend it with I18nProvider.resources.
+ * 这里只放组件内置文案，业务项目可以通过 I18nProvider.resources 覆盖或追加。
  */
 export declare const defaultEnglishResources: {
+    /** 通用操作文案。 */
     readonly common: {
         readonly tip: "Prompt";
         readonly confirm: "Confirm";
@@ -12,6 +13,22 @@ export declare const defaultEnglishResources: {
         readonly submit: "Submit";
         readonly reset: "Reset";
     };
+    readonly server: {
+        readonly errors: {
+            readonly network: "Network error";
+            readonly invalidRequest: "Invalid request";
+            readonly getProjectFailed: "Failed to get project";
+            readonly dbNodeSqliteUnavailable: "[db] The default database depends on Node.js built-in {sqliteSpecifier}, which is unavailable in the current runtime. Upgrade Node.js or override app/extends/db.ts in the business project.{cause}";
+            readonly dbDatabaseSyncUnavailable: "[db] {sqliteSpecifier} does not provide DatabaseSync, so the default SQLite database cannot be initialized.";
+            readonly dbNamespaceRequired: "[db] namespace cannot be empty";
+            readonly dbKeyRequired: "[db] key cannot be empty";
+            readonly dbLimitInvalid: "[db] limit must be an integer greater than 0";
+            readonly dbOffsetInvalid: "[db] offset must be an integer greater than or equal to 0";
+            readonly dbValueNotSerializable: "[db] value must be serializable by JSON.stringify.{cause}";
+            readonly dbClosed: "[db] SQLite database connection is closed";
+        };
+    };
+    /** UI 组件内置文案，按组件名分组。 */
     readonly components: {
         readonly breadcrumb: {
             readonly close: "Close";
@@ -59,6 +76,7 @@ export declare const defaultEnglishResources: {
             readonly rotateRight: "Rotate right";
             readonly flipHorizontal: "Flip horizontal";
             readonly flipVertical: "Flip vertical";
+            /** {index} 会在运行时由调用方传入的插值数据替换。 */
             readonly previewImage: "Preview image {index}";
         };
         readonly modal: {
@@ -88,4 +106,5 @@ export declare const defaultEnglishResources: {
         };
     };
 };
+/** 默认英文语言资源类型，供调用方推导 key 结构使用。 */
 export type DefaultEnglishResources = typeof defaultEnglishResources;

package/types/packages/common/i18n/index.d.ts

@@ -1,6 +1,24 @@
+/**
+ * @module @tc/common/i18n
+ *
+ * 轻量 i18n 运行时，负责维护当前语言、兜底语言、语言资源、翻译函数和订阅通知。
+ *
+ * 设计说明：
+ * 1. 该模块位于 @tc/common，需要同时服务浏览器、Node、SSR 和非 React 代码。
+ * 2. 这里没有使用 zustand 是为了保持 common 层轻依赖。zustand/vanilla 可以在 Node 运行，
+ *    但当前 i18n 只需要 getState / setState / subscribe 这几个最小能力。
+ * 3. React 层通过 @tc/ui-react/i18n 适配这个 store，通用层不直接依赖 React 或 UI 状态库。
+ *
+ * 运行步骤：
+ * 1. 初始化 state：读取本地缓存语言，注入默认语言、兜底语言和内置语言包。
+ * 2. 翻译文本：按 key 从当前语言读取，缺失时读取兜底语言，再回退到 options.fallback 或原 key。
+ * 3. 资源更新：setResources 可替换或批量合并资源，addResources 可追加或替换单个语种资源。
+ * 4. 状态通知：语言或资源变更后通知订阅方，React hook 和非 React 代码都可复用同一个运行时。
+ */
 import type { I18nDictionary, I18nInterpolationValues, I18nMessage, I18nResources, I18nStore, I18nStoreListener, I18nTranslateOptions, I18nTranslateState } from "./types";
 export * from "./types";
 export * from "./locales";
+/** 判断某个消息节点是否是可继续递归访问的普通字典。 */
 export declare const isPlainI18nDictionary: (value: I18nMessage) => value is I18nDictionary;
 /**
  * 深合并单个语言包。
@@ -27,6 +45,7 @@ export declare const interpolateI18nMessage: (value: string, data?: I18nInterpol
  * 优先级：指定语言 -> 兜底语言 -> options.fallback -> 原 key。
  */
 export declare const translate: <T = string>(state: I18nTranslateState, key: string, fillingData?: I18nInterpolationValues, options?: I18nTranslateOptions) => T | string;
+/** 全局 i18n store，React 适配层和非 React 代码共享这一份状态。 */
 export declare const i18nStore: {
     getState: () => I18nStore;
     getInitialState: () => I18nStore;
@@ -38,5 +57,7 @@ export declare const i18nStore: {
  * 每次调用都会读取最新 state，适合在非 React 代码中直接使用。
  */
 export declare const i18n: <T = string>(key: string, fillingData?: I18nInterpolationValues, options?: I18nTranslateOptions) => string | T;
+/** i18n 的简写别名。 */
 export declare const t: <T = string>(key: string, fillingData?: I18nInterpolationValues, options?: I18nTranslateOptions) => string | T;
+/** 兼容历史调用的别名，行为等同于 i18n。 */
 export declare const getLanguage: <T = string>(key: string, fillingData?: I18nInterpolationValues, options?: I18nTranslateOptions) => string | T;

package/types/packages/common/i18n/locales.d.ts

@@ -1,7 +1,17 @@
 import type { I18nResources } from "./types";
+/** 默认语言，作为初始化语言和翻译兜底语言使用。 */
 export declare const defaultLanguage: "zh-CN";
+/** 默认保存用户语言偏好的 localStorage key。 */
 export declare const languageLocalKey = "tc_language";
+/**
+ * 内置语言资源。
+ *
+ * 业务项目可以通过 I18nProvider.resources、setResources 或 addResources 覆盖和追加。
+ */
 export declare const translations: I18nResources;
+/**
+ * 内置语言联合类型，同时允许业务侧扩展自定义语言码。
+ */
 export type Language = keyof typeof translations | (string & {});
 export * from "./default";
 export * from "./en-US";

package/types/packages/common/i18n/types.d.ts

@@ -1,16 +1,39 @@
+/**
+ * 语言标识。
+ *
+ * 推荐使用 BCP 47 风格的语言码，例如 zh-CN、en-US；业务侧也可以传入自定义语言码。
+ */
 export type I18nLanguage = string;
+/** 插值和叶子文案允许使用的基础值。 */
 export type I18nPrimitive = string | number | boolean | null | undefined;
+/**
+ * 单条翻译消息。
+ *
+ * 可以是字符串、基础值、数组，也可以继续嵌套为字典，便于通过 common.ok 这类点分路径访问。
+ */
 export type I18nMessage = I18nPrimitive | I18nMessage[] | readonly I18nMessage[] | I18nDictionary;
+/** 单个语言包的字典结构。 */
 export interface I18nDictionary {
     [key: string]: I18nMessage;
 }
+/** 按语言码组织的多语言资源集合。 */
 export type I18nResources<Language extends I18nLanguage = I18nLanguage> = Partial<Record<Language, I18nDictionary>>;
+/**
+ * 文案插值数据。
+ *
+ * 例如 "Hello, {name}" 会从 { name: "Tom" } 中读取 name 并替换。
+ */
 export type I18nInterpolationValues = Record<string, I18nPrimitive>;
+/** 执行一次翻译所需的最小状态。 */
 export interface I18nTranslateState {
+    /** 当前展示语言。 */
     language: I18nLanguage;
+    /** 当前语言缺失文案时使用的兜底语言。 */
     fallbackLanguage: I18nLanguage;
+    /** 当前已注册的全部语言资源。 */
     resources: I18nResources;
 }
+/** i18n 运行时状态。 */
 export interface I18nState extends I18nTranslateState {
     /** 持久化语言时使用的 localStorage key。 */
     storageKey: string;
@@ -43,7 +66,13 @@ export interface I18nAddResourcesOptions {
      */
     merge?: boolean;
 }
+/**
+ * 翻译函数签名。
+ *
+ * T 用于调用方在非字符串资源场景下指定返回类型，例如数组或对象。
+ */
 export type I18nTranslator = <T = string>(key: string, fillingData?: I18nInterpolationValues, options?: I18nTranslateOptions) => T | string;
+/** i18n store 暴露的所有操作。 */
 export interface I18nActions {
     /** 设置当前展示语言。 */
     setLanguage: (language: I18nLanguage) => void;
@@ -60,11 +89,22 @@ export interface I18nActions {
     /** 挂在 store 上的翻译函数，方便直接读取。 */
     t: I18nTranslator;
 }
+/** 完整 i18n store，包含状态和操作。 */
 export type I18nStore = I18nState & I18nActions;
+/** store 状态变更订阅回调。 */
 export type I18nStoreListener = (state: I18nStore, previousState: I18nStore) => void;
+/**
+ * 最小 store API。
+ *
+ * 形状接近 zustand/vanilla，方便 React 适配层或非 React 代码订阅同一份状态。
+ */
 export interface I18nStoreApi {
+    /** 获取当前 store 状态。 */
     getState: () => I18nStore;
+    /** 获取创建 store 时的初始状态。 */
     getInitialState: () => I18nStore;
+    /** 局部更新 store 状态。 */
     setState: (partial: Partial<I18nStore> | ((state: I18nStore) => Partial<I18nStore>)) => void;
+    /** 订阅状态变化，返回取消订阅函数。 */
     subscribe: (listener: I18nStoreListener) => () => void;
 }