@_tc/template-core 0.0.1-bate.37 → 0.0.1-bate.39

package/fe/frontend/widgets/defaultPages/SidebarSlotPage/SidebarSlotContainer.js

@@ -10,7 +10,12 @@ const SidebarSlotContainer = (props) => {
     const params = useRouterParams();
     const [SK, uSK] = useState(params[QK.sk]);
     const nav = useNavigate();
+    //  menu 初始化选中
     useEffect(() => {
+        /**
+         * 如果没有 sidebar key 说明当前是 自定义路由
+         * 则需要获取 query 中的 ck 来查找 menuinfo
+         */
         if (!params[QK.sk]) {
             if (params[QK.ck]) {
                 const m = findMenuItem(rawMenuData, params[QK.ck]);
@@ -19,6 +24,8 @@ const SidebarSlotContainer = (props) => {
                     return;
                 }
             }
+            // 运行到这 说明
+            // 异常路径
             logPageNotFound();
         }
     }, [rawMenuData, params]);

package/fe/frontend/widgets/defaultPages/SidebarSlotPage/index.js

@@ -7,6 +7,7 @@ import { useParams } from "react-router-dom";
 import SidebarSlotContainer from "./SidebarSlotContainer";
 const SidebarSlotPage = () => {
     const params = useParams();
+    // top left 从当前路由中获取到 sidebarConfig中的数据
     const { menu: parentMenuInfo } = useCurrentMenuData();
     const prefixPath = useMemo(() => `/${params[QK.k]}`, [params[QK.k]]);
     const menuItem = generateMenuItemData(parentMenuInfo?.sidebarConfig?.menu ?? []);

package/fe/frontend/widgets/defaultPages/SlotPage/index.js

@@ -14,6 +14,8 @@ const SlotPage = memo(() => {
             return _jsx(Schema, {});
         }
         else {
+            // 运行到这 说明异常路径
+            // 自定义路径会在进入这之前被拦截;
             logPageNotFound();
             return _jsx("div", { children: "404" });
         }

package/fe/frontend/widgets/hooks/useCurrentMenuData.d.ts

@@ -1,4 +1,12 @@
 import { BasicModuleType, SidebarModuleType } from "../../../model/types/menuType";
+/**
+ *
+ * 自定义路由直接交由路由器渲染
+ *
+ * 也就是说 这里找不到 自定义相关的菜单数据
+ *
+ * @param useSibe 使用侧边数据
+ */
 declare const useCurrentMenuData: <T = {
     moduleType: BasicModuleType["moduleType"];
     sidebarConfig: SidebarModuleType["sidebarConfig"];

package/fe/frontend/widgets/hooks/useCurrentMenuData.js

@@ -2,6 +2,14 @@ import { findMenuItem, QK } from "../../widgets/common/menu";
 import { useModeStore } from "../../widgets/store/mode";
 import { useMemo } from "react";
 import { useParams } from "react-router-dom";
+/**
+ *
+ * 自定义路由直接交由路由器渲染
+ *
+ * 也就是说 这里找不到 自定义相关的菜单数据
+ *
+ * @param useSibe 使用侧边数据
+ */
 const useCurrentMenuData = (useSibe = false) => {
     const params = useParams();
     const projestInfo = useModeStore((s) => s.projestInfo);

package/fe/frontend/widgets/store/mode.d.ts

@@ -2,6 +2,9 @@ import { type ModelInfo, type ProjectInfo } from '../../widgets/api/baseInfo';
 interface ModeState {
     modeList: ModelInfo[];
     projestInfo: ProjectInfo | null;
+    /**
+     * 是否初始化过
+     */
     initData: boolean;
 }
 interface ModeAction {

package/fe/frontend/widgets/store/mode.js

@@ -3,6 +3,7 @@ import { deserializationUrlSearch } from '../../widgets/common/menu';
 import { createStoreHook } from '../../../packages/ui/react/lib/createStoreHook';
 import { createStore } from 'zustand';
 import { setApiAuth } from '../common/auth';
+// create Store 可在任意地方使用
 export const modeStore = createStore((set, get) => ({
     modeList: [],
     projestInfo: null,

package/fe/model/types/data/button.d.ts

@@ -1,13 +1,22 @@
 import type { ButtonProps } from '../../../packages/ui/react';
 import { ComponentNames } from './component';
 type ButtonTemplates = {
+    /**
+     * 按钮名
+     */
     label?: string;
 } & ButtonProps;
 type ParamsValueData = 'schema::tableKey' | string | number;
 type RemoveBtn = {
     eventKey: 'remove';
+    /**
+     * 事件配置 (参数配置)
+     */
     eventOption: {
         params: {
+            /**
+             *  @example user_id: 'schema::tableKey' | '123' | 123
+             */
             [paramKey: string]: ParamsValueData;
         };
     };

package/fe/model/types/data/button.js

@@ -1 +1,16 @@
 export {};
+// & {
+// 	/**
+// 	 * 按钮事件名
+// 	 */
+// 	eventKey: 'romve' | 'showComponent';
+// 	/**
+// 	 * 事件配置 (参数配置)
+// 	 */
+// 	params: {
+// 		/**
+// 		 *  @example user_id: 'schema::tableKey' | '123' | 123
+// 		 */
+// 		[paramKey: string]: ParamsValueData;
+// 	};
+// };

package/fe/model/types/data/component.d.ts

@@ -2,22 +2,46 @@ import { FormItemProps, InputNumberProps, InputProps, SelectProps } from '../../
 import { FetchInfo } from './fetchInfo';
 export type ComponentConfig = {
     createForm?: {
+        /**
+         * 表单标题
+         */
         title: string;
+        /**
+         *  保存按钮文案
+         */
         saveBtnText?: string;
     } & Pick<FetchInfo, 'fetchConfig'>;
     editForm?: {
+        /**
+         * 表单标题
+         */
         title: string;
+        /**
+         *  保存按钮文案
+         */
         saveBtnText?: string;
     } & FetchInfo;
     detailPanel?: {
+        /**
+         * 表单标题
+         */
         title: string;
     } & FetchInfo;
 };
 export type ComponentNames = keyof ComponentConfig;
 export type ComponentsOption = {
     createForm: FormItemProps & {
+        /**
+         * 是否展示 默认为true
+         */
         visible?: boolean;
+        /**
+         * 是否禁用
+         */
         disbaled?: boolean;
+        /**
+         * 默认值
+         */
         default?: any;
     } & ComponentOption;
     editForm: ComponentsOption['createForm'];

package/fe/model/types/data/component.js

@@ -1 +1,11 @@
 export {};
+// type DynamicSelect = {
+// 	comType: 'dynamicSelect';
+// 	/**
+// 	 * 请求动态列表地址
+// 	 */
+// 	api: string;
+// } & SelectProps;
+// type DateRange = {
+// 	comType: 'dateRange';
+// };

package/fe/model/types/data/fetchInfo.d.ts

@@ -1,7 +1,19 @@
 export type FetchInfo = {
+    /**
+     * 表单主键，  获取数据源的key
+     */
     fetchKey: string;
+    /**
+     * 请求配置 如果不配置则使用 统一的 [get] api 内容
+     */
     fetchConfig?: {
+        /**
+         * 获取数据的
+         */
         url: string;
+        /**
+         * 请求方式
+         */
         method?: 'get' | 'post';
     };
 };

package/fe/model/types/data/schema.d.ts

@@ -6,17 +6,35 @@ import { ComponentConfig, ComponentNames, ComponentsOption } from './component';
 import { SearchOption } from './search';
 export type TableColumnsSchema = {
     tableOption?: MOmit<TableColumnDef, 'key' | 'title'> & {
+        /**
+         * 是否显示
+         */
         visible?: boolean;
+        /**
+         * 	保留几位小数
+         */
         toFixed?: number;
     };
 };
 export type TableSearchOption = {
+    /**
+     * 不配置则不在 search 中显示
+     */
     searchOption?: {
+        /**
+         * 控件默认值
+         */
         default?: any;
     } & SearchOption;
 };
 export type TableConfig = {
+    /**
+     * table 头部按钮
+     */
     headerButtons?: BaseButton[];
+    /**
+     * 每一行的按钮
+     */
     rowButtons?: BaseButton[];
 };
 export type SearchConfig = {};
@@ -26,8 +44,19 @@ export type BaseOption<O> = {
 export type UsedConfigSchema<T = {}> = {
     type: 'object' | 'string' | 'array' | 'number' | 'boolean';
     properties: {
+        /**
+         * [字段 key]: 字段描述
+         */
         [key: string]: T & MOmit<UsedConfigSchema, 'properties'> & {
+            /**
+             * 展示 字符
+             */
             label: string;
+            /**
+             *  原数据 序列化后 会丢失编写时的顺序
+             * 	字段层级  默认10
+             *
+             */
             level?: number;
         };
     };
@@ -38,10 +67,32 @@ export type TableComponentConfig = {
 };
 export type ConfigSchema = UsedConfigSchema<TableColumnsSchema & TableSearchOption & TableComponentConfig>;
 export interface SchemaDataType {
+    /**
+     * 数据源地址  遵循 RESTFUL 规范
+     * *[参考地址](https://www.ruanyifeng.com/blog/2014/05/restful_api.html)*
+     *
+     * 即:
+     *
+     * - 获取数据 GET [api]
+     * - 新增数据 POST [api]
+     * - ...
+     */
     api: string;
+    /**
+     * 板块数据结构
+     */
     schema?: ConfigSchema;
+    /**
+     * 表格 (展示) 配置
+     */
     tableConfig?: TableConfig;
+    /**
+     * 搜索 配置
+     */
     searchConfig?: SearchConfig;
+    /**
+     * 模块组件
+     */
     componentConfig?: ComponentConfig;
 }
 //# sourceMappingURL=schema.d.ts.map

package/fe/model/types/menuType.d.ts

@@ -1,8 +1,17 @@
 import { SchemaDataType } from "./data/schema";
+/**
+ *  - parent menuLaout === 'top'
+ *    - child menuLayout === 'top' | 'left'
+ *  - parent menuLayout === 'left'
+ *    - child menuLayout === 'left'
+ */
 export type MenuLayout = "left" | "top";
 interface BaseMenu {
     key: string;
     icon?: string;
+    /**
+     * 菜单名称
+     */
     name: string;
 }
 interface GroupMenuType<T extends MenuLayout> extends BaseMenu {
@@ -12,15 +21,26 @@ interface GroupMenuType<T extends MenuLayout> extends BaseMenu {
 interface ModuleMenuType extends BaseMenu {
     menuType: "module";
 }
+/**
+ *
+ * ----------------------------- moduletype -----------------------------
+ *
+ */
 interface IframeModuleType {
     moduleType: "iframe";
     iframeConfig: {
+        /**
+         * iframe 路径
+         */
         path: string;
     };
 }
 interface CustomModuleType {
     moduleType: "custom";
     customConfig: {
+        /**
+         * 自定义路由路径
+         */
         path: string;
     };
 }
@@ -32,13 +52,22 @@ export interface SidebarModuleType {
     moduleType: "sidebar";
     sidebarConfig: {
         menu: BaseMenuType[];
+        /**
+         * 只能为left
+         */
         menuLayout?: "left";
     };
 }
 export type BasicModuleType = SchemaModuleType | CustomModuleType | IframeModuleType;
 export type BaseMenuType = GroupMenuType<"left"> | (ModuleMenuType & BasicModuleType);
 type ModuleType = BasicModuleType | SidebarModuleType;
+/**
+ * top 包含所有
+ */
 export type TopMenuType = GroupMenuType<"top"> | (ModuleMenuType & ModuleType);
+/**
+ * left 不包含 sidebar
+ */
 export type LeftMenuType = GroupMenuType<"left"> | BaseMenuType;
 export {};
 //# sourceMappingURL=menuType.d.ts.map

package/fe/model/types/model.d.ts

@@ -1,19 +1,32 @@
 import { TopMenuType, LeftMenuType } from "./menuType";
 type MTopMenuType = {
+    /**
+     * 默认为 left
+     */
     menuLayout: "top";
     menu: TopMenuType[];
 };
 type MLeftMenuType = {
+    /**
+     * 默认为 left
+     */
     menuLayout?: "left";
     menu: LeftMenuType[];
 };
 export type ModeMenuType = MTopMenuType | MLeftMenuType;
 export type ModelDataType = {
+    /**
+     * - 使用哪一块的模型数据 内置 MB
+     * 	- MB = 管理后台
+     */
     mode: "MB";
     key?: string;
     name: string;
     desc: string;
     icon: string;
+    /**
+     * 首页(项目配置)
+     */
     homePage: string;
 } & ModeMenuType;
 export {};

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

@@ -1,3 +1,8 @@
+/**
+ * UI 组件库默认中文语言资源。
+ *
+ * 这里只放组件内置文案，业务项目可以通过 I18nProvider.resources 覆盖或追加。
+ */
 export declare const defaultLanguageResources: {
     readonly common: {
         readonly tip: "提示";

package/fe/packages/common/i18n/default.js

@@ -1,3 +1,8 @@
+/**
+ * UI 组件库默认中文语言资源。
+ *
+ * 这里只放组件内置文案，业务项目可以通过 I18nProvider.resources 覆盖或追加。
+ */
 export const defaultLanguageResources = {
     common: {
         tip: '提示',

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

@@ -1,3 +1,8 @@
+/**
+ * UI component library default English language resources.
+ *
+ * Only built-in component copy belongs here. Applications can override or extend it with I18nProvider.resources.
+ */
 export declare const defaultEnglishResources: {
     readonly common: {
         readonly tip: "Prompt";

package/fe/packages/common/i18n/en-US.js

@@ -1,3 +1,8 @@
+/**
+ * UI component library default English language resources.
+ *
+ * Only built-in component copy belongs here. Applications can override or extend it with I18nProvider.resources.
+ */
 export const defaultEnglishResources = {
     common: {
         tip: 'Prompt',

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

@@ -2,10 +2,30 @@ import type { I18nDictionary, I18nInterpolationValues, I18nMessage, I18nResource
 export * from './types';
 export * from './locales';
 export declare const isPlainI18nDictionary: (value: I18nMessage) => value is I18nDictionary;
+/**
+ * 深合并单个语言包。
+ * 嵌套对象递归合并，字符串、数组、数字等叶子节点直接以 patch 覆盖 base。
+ */
 export declare const mergeI18nDictionary: (base?: I18nDictionary, patch?: I18nDictionary) => I18nDictionary;
+/**
+ * 合并多语言资源。
+ * 结构示例：{ 'zh-CN': { common: { ok: '确定' } }, 'en-US': { common: { ok: 'OK' } } }
+ */
 export declare const mergeI18nResources: (base?: I18nResources, patch?: I18nResources) => I18nResources;
+/**
+ * 根据点分 key 从语言包中取值。
+ * 例如 common.submit 会读取 resources[language].common.submit。
+ */
 export declare const getI18nPathValue: (dictionary: I18nDictionary | undefined, key: string) => I18nMessage | undefined;
+/**
+ * 替换文案中的插值占位符。
+ * 例如 "Hello, {name}" + { name: "Tom" } => "Hello, Tom"。
+ */
 export declare const interpolateI18nMessage: (value: string, data?: I18nInterpolationValues) => string;
+/**
+ * 纯翻译函数：只依赖传入的 state。
+ * 优先级：指定语言 -> 兜底语言 -> options.fallback -> 原 key。
+ */
 export declare const translate: <T = string>(state: I18nTranslateState, key: string, fillingData?: I18nInterpolationValues, options?: I18nTranslateOptions) => T | string;
 export declare const i18nStore: {
     getState: () => I18nStore;
@@ -13,6 +33,10 @@ export declare const i18nStore: {
     setState: (partial: Partial<I18nStore> | ((state: I18nStore) => Partial<I18nStore>)) => void;
     subscribe: (listener: I18nStoreListener) => () => void;
 };
+/**
+ * 对外使用的 i18n 函数。
+ * 每次调用都会读取最新 state，适合在非 React 代码中直接使用。
+ */
 export declare const i18n: <T = string>(key: string, fillingData?: I18nInterpolationValues, options?: I18nTranslateOptions) => string | T;
 export declare const t: <T = string>(key: string, fillingData?: I18nInterpolationValues, options?: I18nTranslateOptions) => string | T;
 export declare const getLanguage: <T = string>(key: string, fillingData?: I18nInterpolationValues, options?: I18nTranslateOptions) => string | T;

package/fe/packages/common/i18n/index.js

@@ -4,6 +4,10 @@ export * from './locales';
 export const isPlainI18nDictionary = (value) => {
     return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 };
+/**
+ * 深合并单个语言包。
+ * 嵌套对象递归合并，字符串、数组、数字等叶子节点直接以 patch 覆盖 base。
+ */
 export const mergeI18nDictionary = (base = {}, patch = {}) => {
     const next = { ...base };
     Object.entries(patch).forEach(([key, value]) => {
@@ -16,6 +20,10 @@ export const mergeI18nDictionary = (base = {}, patch = {}) => {
     });
     return next;
 };
+/**
+ * 合并多语言资源。
+ * 结构示例：{ 'zh-CN': { common: { ok: '确定' } }, 'en-US': { common: { ok: 'OK' } } }
+ */
 export const mergeI18nResources = (base = {}, patch = {}) => {
     const next = { ...base };
     Object.entries(patch).forEach(([language, messages]) => {
@@ -25,6 +33,10 @@ export const mergeI18nResources = (base = {}, patch = {}) => {
     });
     return next;
 };
+/**
+ * 根据点分 key 从语言包中取值。
+ * 例如 common.submit 会读取 resources[language].common.submit。
+ */
 export const getI18nPathValue = (dictionary, key) => {
     if (!dictionary)
         return undefined;
@@ -34,6 +46,10 @@ export const getI18nPathValue = (dictionary, key) => {
         return value[currentKey];
     }, dictionary);
 };
+/**
+ * 替换文案中的插值占位符。
+ * 例如 "Hello, {name}" + { name: "Tom" } => "Hello, Tom"。
+ */
 export const interpolateI18nMessage = (value, data) => {
     if (!data)
         return value;
@@ -42,6 +58,10 @@ export const interpolateI18nMessage = (value, data) => {
         return typeof nextValue === 'undefined' || nextValue === null ? match : String(nextValue);
     });
 };
+/**
+ * 纯翻译函数：只依赖传入的 state。
+ * 优先级：指定语言 -> 兜底语言 -> options.fallback -> 原 key。
+ */
 export const translate = (state, key, fillingData, options) => {
     const language = options?.language || state.language;
     const fallbackLanguage = options?.fallbackLanguage || state.fallbackLanguage;
@@ -54,6 +74,10 @@ export const translate = (state, key, fillingData, options) => {
 const getBrowserWindow = () => {
     return globalThis.window;
 };
+/**
+ * 初始化时优先读取本地缓存语言。
+ * SSR 环境没有 window，直接回退到默认语言。
+ */
 const getStoredLanguage = (storageKey) => {
     const windowRef = getBrowserWindow();
     if (!windowRef) {
@@ -61,6 +85,9 @@ const getStoredLanguage = (storageKey) => {
     }
     return windowRef.localStorage.getItem(storageKey) || defaultLanguage;
 };
+/**
+ * 持久化当前语言，用于刷新页面后保持用户选择。
+ */
 const persistLanguage = (storageKey, language) => {
     const windowRef = getBrowserWindow();
     if (!windowRef)
@@ -135,6 +162,10 @@ const createI18nStore = () => {
     };
 };
 export const i18nStore = createI18nStore();
+/**
+ * 对外使用的 i18n 函数。
+ * 每次调用都会读取最新 state，适合在非 React 代码中直接使用。
+ */
 export const i18n = (key, fillingData, options) => {
     return translate(i18nStore.getState(), key, fillingData, options);
 };

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

@@ -12,28 +12,52 @@ export interface I18nTranslateState {
     resources: I18nResources;
 }
 export interface I18nState extends I18nTranslateState {
+    /** 持久化语言时使用的 localStorage key。 */
     storageKey: string;
+    /** 是否把 setLanguage 的结果写入 localStorage。 */
     persist: boolean;
 }
 export interface I18nTranslateOptions {
+    /**
+     * 指定本次翻译使用的语言，不传则使用全局 language。
+     */
     language?: I18nLanguage;
+    /**
+     * 当前语言未命中时使用的兜底语言，不传则使用全局 fallbackLanguage。
+     */
     fallbackLanguage?: I18nLanguage;
+    /**
+     * 当前语言和兜底语言都未命中时返回的兜底值。
+     */
     fallback?: I18nMessage;
 }
 export interface I18nSetResourcesOptions {
+    /**
+     * 是否和现有资源深合并。默认 false，直接替换 resources。
+     */
     merge?: boolean;
 }
 export interface I18nAddResourcesOptions {
+    /**
+     * 是否和当前语言资源深合并。默认 true。
+     */
     merge?: boolean;
 }
 export type I18nTranslator = <T = string>(key: string, fillingData?: I18nInterpolationValues, options?: I18nTranslateOptions) => T | string;
 export interface I18nActions {
+    /** 设置当前展示语言。 */
     setLanguage: (language: I18nLanguage) => void;
+    /** 设置兜底语言。 */
     setFallbackLanguage: (language: I18nLanguage) => void;
+    /** 批量设置多语言资源，可选择替换或合并。 */
     setResources: (resources: I18nResources, options?: I18nSetResourcesOptions) => void;
+    /** 为指定语言追加资源，默认和已有资源深合并。 */
     addResources: (language: I18nLanguage, messages: I18nDictionary, options?: I18nAddResourcesOptions) => void;
+    /** 配置存储行为，主要由 I18nProvider 同步外部 props 使用。 */
     configureI18n: (config: Partial<Pick<I18nState, 'storageKey' | 'persist'>>) => void;
+    /** 重置为默认语言、默认资源和默认存储配置。 */
     resetI18n: () => void;
+    /** 挂在 store 上的翻译函数，方便直接读取。 */
     t: I18nTranslator;
 }
 export type I18nStore = I18nState & I18nActions;

package/fe/packages/ui/react/components/Button/Button.d.ts

@@ -3,21 +3,54 @@ export type ButtonVariant = 'default' | 'primary' | 'dashed' | 'text' | 'link';
 export type ButtonState = 'danger' | 'ghost';
 export type ButtonSize = 'sm' | 'md' | 'lg';
 type ButtonCommonProps = {
+    /**
+     * 按钮尺寸
+     * @default 'md'
+     */
     size?: ButtonSize;
+    /**
+     * 按钮状态
+     */
     state?: ButtonState;
+    /**
+     * 是否禁用
+     */
     disabled?: boolean;
+    /**
+     * 是否显示加载状态
+     */
     loading?: boolean;
+    /**
+     * 左侧图标
+     */
     leftIcon?: ReactNode;
+    /**
+     * 右侧图标
+     */
     rightIcon?: ReactNode;
+    /**
+     * 是否去除下划线（仅对 variant="link" 有效）
+     * @default false
+     */
     noUnderline?: boolean;
+    /**
+     * 作为子元素，用于更灵活的布局
+     */
     children?: ReactNode;
 };
 type ButtonElementVariant = Exclude<ButtonVariant, 'link'>;
 export type ButtonProps = ButtonElementProps | ButtonLinkProps;
 export type ButtonElementProps = ButtonCommonProps & Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'disabled'> & {
+    /**
+     * 按钮变体
+     * @default 'default'
+     */
     variant?: ButtonElementVariant;
 };
 export type ButtonLinkProps = ButtonCommonProps & AnchorHTMLAttributes<HTMLAnchorElement> & {
+    /**
+     * 链接变体，渲染为 a 标签
+     */
     variant: 'link';
 };
 declare const Button: import("react").ForwardRefExoticComponent<ButtonProps & import("react").RefAttributes<HTMLButtonElement | HTMLAnchorElement>>;