@para-ui/core 5.0.0-beta.11 → 5.0.0-beta.13

package/es/OperateBtn/index.d.ts

@@ -21,10 +21,10 @@ export interface OperateBtnListProps {
     /** 设置危险按钮 */
     danger?: boolean;
     /** 点击事件 */
-    onClick?: (item: OperateBtnListProps, e: any) => void | Promise<boolean | any>;
+    onClick?: (item: OperateBtnListProps, e: React.MouseEvent) => void | Promise<boolean | void>;
     /** 气泡确认框参数 */
     popConfirmProps?: PopConfirmProps;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 export interface OperateBtnProps {
     /** 样式class */
@@ -50,7 +50,7 @@ export interface OperateBtnProps {
     /** 点击是否关闭更多 */
     clickCloseMore?: boolean;
     /** 点击事件, 如果listItem里面存在onClick事件,则不触发改事件 */
-    onClick?: (item: OperateBtnListProps, e: any) => void | Promise<boolean | any>;
+    onClick?: (item: OperateBtnListProps, e: React.MouseEvent) => void | Promise<boolean | void>;
 }
 declare const OperateBtn: FunctionComponent<OperateBtnProps>;
 export default OperateBtn;

package/es/PageHeader/component.json

@@ -0,0 +1,112 @@
+{
+    "name": "PageHeader",
+    "category": "Navigation",
+    "description": "页头(应用级顶部导航条):左侧 logo/标题 + 中间横向菜单 + 右侧用户/语言/帮助/按钮区",
+    "semantic": {
+        "intent": [
+            "应用顶部导航",
+            "横向菜单展示",
+            "用户/语言/帮助入口聚合"
+        ],
+        "useCases": [
+            "应用主页头",
+            "管理后台顶栏",
+            "工作台首屏"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "标准页头(横向菜单 + 右侧功能区)"
+        }
+    },
+    "states": [
+        "default"
+    ],
+    "idealProps": {
+        "leftRender": {
+            "type": "ReactNode",
+            "description": "左侧自定义内容(放 logo / 应用标题 / 返回按钮等);**支持纯文本 / 单行 JSX / 多行复合 JSX**(标题+副标题、返回按钮+标题、面包屑+标题、标题+状态彩标);**注意:不是 title / subTitle / backIcon / breadcrumb / onBack prop**(这些 Ant Design PageHeader 命名本组件均不存在,需要时全部组合进 leftRender ReactNode);典型场景见 docs/view/pageHeader/codeString.ts 注释 7a/7b/7c/7d"
+        },
+        "menuListProps": {
+            "type": "MenuListProps",
+            "description": "横向菜单配置对象;MenuListProps = { list?: MenuChildrenProps[]; selectMenu?: string; onClickMenu?: (item: MenuChildrenProps | false) => void; className?: string; moreCustomize?: ReactNode };src/PageHeader/interface.ts:38"
+        },
+        "footerProps": {
+            "type": "FooterProps",
+            "description": "**右侧功能区聚合对象**(放语言切换 / 用户菜单 / 帮助 / 按钮列表 / 自助跳转 / 自定义);FooterProps = { backSelfcareProps?: BackSelfcareProps; languageProps?: LanguageProps; btnListProps?: BtnListProps; userProps?: UserProps; helpProps?: HelpProps; render?: ReactNode; className?: string };**所有右侧功能都在这个对象里嵌套配置,不是顶层独立 prop**;**helpProps 结构同 BackSelfcareProps**(label/icon/render/onClick/className);**render 是「替换」语义**,传入后整个右侧被替换,其他 5 widget 字段都不渲染(无追加模式);src/PageHeader/interface.ts:162"
+        },
+        "selectMenu": {
+            "type": "string",
+            "description": "当前选中菜单(匹配 menuListProps.list[].path);顶层 selectMenu 会下传到 MenuListProps.selectMenu;src/PageHeader/index.tsx:14"
+        },
+        "onClickMenu": {
+            "type": "(item: MenuChildrenProps | false) => void",
+            "description": "菜单点击回调;**回参 item 是 MenuChildrenProps 对象或 false**(false 表示选中态被清空);MenuChildrenProps = { label?, type?, path?, icon?, children?, ... },典型用法 `item.path` 取菜单路径"
+        },
+        "className": {
+            "type": "string",
+            "description": "外层容器样式 class"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "外层容器内联样式"
+        }
+    },
+    "do": [
+        "logo / 应用名放 leftRender",
+        "横向菜单走 menuListProps.list(树形结构通过 children 嵌套)",
+        "右侧功能(语言 / 用户 / 帮助 / 按钮)统一在 footerProps 对象里嵌套配置",
+        "selectMenu 受控 — 父维护 string 匹配 list[].path"
+    ],
+    "dont": [
+        "把 title / subTitle / extra / onBack / backIcon / breadcrumb / footer 当作顶层 prop 传(全部 Ant Design 命名,**本组件均不存在**)",
+        "把右侧功能字段(languageProps / userProps / btnListProps / helpProps / backSelfcareProps)拆到顶层(必须嵌套在 footerProps 对象里)",
+        "在 menuListProps.list[].type 上随意填值(仅支持 'redirect' | 'router' | 'iframe' | 'snack' | 'snackPage' 五种)",
+        "传 footerProps.render 同时配其他 widget 字段(render 是**替换语义**,会覆盖整个右侧,languageProps/userProps 等都不渲染;无追加模式)",
+        "期望 PageHeader 顶层有 bottomRender / footerRender / statsRender / extraBottom 下方内容区(**本组件不支持下方扩展插槽**;如需统计条/标签栏在 PageHeader 外层 div 包装)",
+        "把「标题 + 副标题」/「返回按钮 + 标题」/「面包屑 + 标题」拆成多个顶层 prop(本组件这类复合内容**全部塞进 leftRender ReactNode**;见 docs/view/pageHeader/codeString.ts 注释 7a/7b/7c)"
+    ],
+    "events": {
+        "onClickMenu": {
+            "signature": "(item: MenuChildrenProps | false) => void",
+            "asyncSupported": false,
+            "examples": [
+                "获取路由路径：onClickMenu={(item) => { if (item) navigate(item.path); }}",
+                "清空选中：onClickMenu={(item) => { if (!item) setSelectMenu(''); else setSelectMenu(item.path); }}",
+                "嵌套子菜单点击：回参 item.children 可能有子项，item.path 是当前点击项的路径，非父级路径"
+            ],
+            "commonMistakes": [
+                "假设 item 永远是对象——回参可能是 false（表示选中态被清空），使用前需判断 if (item)",
+                "直接用 item.label 作路由——应用 item.path；item.label 是显示文案",
+                "不更新 selectMenu 导致菜单高亮不同步——onClickMenu 触发后需 setState(item.path) 回写 selectMenu"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "footerProps 内字段不能拆到 PageHeader 顶层，TS 会报未知 prop",
+            "wrong": "<PageHeader userProps={{ label: '张三' }} languageProps={{ ... }} />  // 这些不是顶层 prop",
+            "right": "<PageHeader footerProps={{ userProps: { label: '张三' }, languageProps: { ... } }} />"
+        },
+        {
+            "issue": "MenuChildrenProps.type 是菜单行为类型，有严格枚举，传错值 TS 不会报错但菜单不响应",
+            "wrong": "list={[{ label: '首页', type: 'link', path: '/home' }]}  // 'link' 不在联合类型",
+            "right": "list={[{ label: '首页', type: 'router', path: '/home' }]}  // 合法值: 'redirect' | 'router' | 'iframe' | 'snack' | 'snackPage'"
+        },
+        {
+            "issue": "onClickMenu 回参是 MenuChildrenProps | false，直接访问属性前需判空",
+            "wrong": "onClickMenu={(item) => navigate(item.path)}  // item 可能是 false，访问 .path 会 TypeError",
+            "right": "onClickMenu={(item) => { if (item && item.path) navigate(item.path); }}"
+        },
+        {
+            "issue": "不要从 @para-ui/core 导入 MenuChildrenProps 用于 onClickMenu 类型标注——PageHeader/interface.ts 和 Menu/interface.ts 各有一个同名 MenuChildrenProps，两者互不兼容，强行标注会导致 TS2322",
+            "wrong": "import { PageHeader, MenuChildrenProps } from '@para-ui/core';\nonClickMenu={(item: MenuChildrenProps | false) => ...}  // MenuChildrenProps 来自 Menu 不来自 PageHeader，类型冲突",
+            "right": "import { PageHeader } from '@para-ui/core';\n// 不标注类型，让 TS 推断，或使用 Parameters<typeof PageHeader>[0]['onClickMenu']\nonClickMenu={(item) => { if (item && item.path) navigate(item.path); }}"
+        }
+    ],
+    "mapping": {
+        "realComponent": "PageHeader",
+        "adapter": null
+    }
+}

package/es/PageHeader/horizontalMeun.js

@@ -4,7 +4,7 @@ import { Popover as U } from "../Popover/index.js";
 import { Down as Y } from "../node_modules/@para-ui/icons/Down/index.js";
 import * as Z from "../node_modules/@para-ui/icons/index.js";
 import { More as me } from "../node_modules/@para-ui/icons/More/index.js";
-import { DeepClone as de } from "@paraview/lib";
+import { DeepClone as de } from "@snack-kit/lib";
 import { $prefixCls as W } from "../GlobalContext/constant.js";
 const ee = (p) => {
   let r = "div";

package/es/PageHeader/horizontalMeunRight.js

@@ -6,7 +6,7 @@ import X from "../AutoTips/index.js";
 import { Down as Y } from "../node_modules/@para-ui/icons/Down/index.js";
 import { Right as Z } from "../node_modules/@para-ui/icons/Right/index.js";
 import { $prefixCls as y } from "../GlobalContext/constant.js";
-import { UUID as ee, DeepClone as ne } from "@paraview/lib";
+import { UUID as ee, DeepClone as ne } from "@snack-kit/lib";
 const se = (x) => {
   const { icon: n, label: d, render: a, onClick: m, className: l } = x, t = (s) => {
     m && m(s);

package/es/Pagination/component.json

@@ -0,0 +1,181 @@
+{
+    "name": "Pagination",
+    "category": "Navigation",
+    "description": "分页组件，支持 simple / complex 双模式及自定义布局组合",
+    "semantic": {
+        "intent": [
+            "展示数据",
+            "分批加载",
+            "导航"
+        ],
+        "useCases": [
+            "数据列表",
+            "搜索结果",
+            "评论区"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "simple": {
+            "meaning": "简单模式（仅翻页按钮/数字页码）"
+        },
+        "complex": {
+            "meaning": "复杂模式（含总数 + 每页行数 + 页码 + 跳转）"
+        }
+    },
+    "states": [
+        "default",
+        "disabled"
+    ],
+    "idealProps": {
+        "total": {
+            "type": "number",
+            "default": 0,
+            "description": "数据总数"
+        },
+        "page": {
+            "type": "number",
+            "default": 1,
+            "description": "当前页码(受控)"
+        },
+        "rowsPerPage": {
+            "type": "number[]",
+            "default": [10, 20, 50, 100],
+            "description": "每页行数候选项列表(下拉选项)"
+        },
+        "currentRowsPerPage": {
+            "type": "number",
+            "default": 10,
+            "description": "当前选中的每页行数"
+        },
+        "type": {
+            "type": "enum",
+            "values": [
+                "simple",
+                "complex",
+                "PaginationLayout[]"
+            ],
+            "default": "simple",
+            "description": "分页类型;**'simple'** = 仅翻页按钮/数字(sizes/pageRow/jumper 均不显示);**'complex'** = 完整布局(总数+每页行数+页码+跳转,支持 autoType 响应式收叠);**PaginationLayout[]** = 自定义组合，合法值 'sizes'|'pageRow'|'pager'|'jumper'"
+        },
+        "pagerType": {
+            "type": "enum",
+            "values": [
+                "btn",
+                "num"
+            ],
+            "default": "num",
+            "description": "页码显示模式 btn=上下页按钮 / num=数字页码列表"
+        },
+        "flippingArrow": {
+            "type": "PaginationFlippingArrow[]",
+            "values": [
+                "prev",
+                "next"
+            ],
+            "default": ["prev", "next"],
+            "description": "方向键 layout;传空数组隐藏全部箭头"
+        },
+        "autoType": {
+            "type": "boolean",
+            "default": true,
+            "description": "type=complex 自适应模式(响应宽度自动收叠)"
+        },
+        "resizeLine": {
+            "type": "string | number",
+            "description": "type=complex 时重新计算换行(传值变化触发自适应)"
+        },
+        "pageMaxLimit": {
+            "type": "boolean",
+            "default": true,
+            "description": "当前页超过总页数时自动回落到最大页"
+        },
+        "skipFunc": {
+            "type": "function",
+            "signature": "(num?: number, skipValue?: number) => void",
+            "description": "回车跳页回调；num 是校正后目标页（已 clamp 到 1~totalPage），skipValue 是输入框原始值（未校正）"
+        },
+        "changePage": {
+            "type": "function",
+            "signature": "(num?: number) => void",
+            "description": "页码改变回调（点击页码 / prev / next / 回车跳转时均触发）；num 是目标页码"
+        },
+        "changeRowsPerPage": {
+            "type": "function",
+            "signature": "(num: number) => void",
+            "description": "每页行数改变回调；num 是新选中行数（非下标，是实际数值）"
+        },
+        "getPopupContainer": {
+            "type": "function",
+            "description": "rowsPerPage 下拉的渲染父节点 (triggerNode) => HTMLElement"
+        },
+        "className": {
+            "type": "string",
+            "description": "自定义类名（src/Pagination/index.tsx:33 interface 实证，追加到根容器 div）"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "自定义样式（src/Pagination/index.tsx:35 interface 实证，透传到根容器 div）"
+        }
+    },
+    "do": [
+        "Table 独立分页时：changePage 里更新父组件 page state 并重新请求数据，将最新 page 回传给 Pagination 维持受控",
+        "展示总记录数 + 每页行数切换：使用 type='complex'，changeRowsPerPage 里同时重置 page=1 再发请求",
+        "在数据量较大时使用服务端分页——本地分页仅适合 <200 条",
+        "保持每页数量适中（10-50）"
+    ],
+    "dont": [
+        "在极少量数据（<20）时使用 Pagination",
+        "隐藏当前页码标识",
+        "changePage/changeRowsPerPage 里不更新父组件 page state——Pagination 是受控组件，不回写 page prop 会导致翻页后页码回弹"
+    ],
+    "events": {
+        "changePage": {
+            "signature": "(num?: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "受控翻页：changePage={(num) => { setPage(num ?? 1); fetchData(num ?? 1, currentRowsPerPage); }}",
+                "配合 Table：changePage={(num) => { tableRef.current.reload({ page: num }); }}",
+                "防止 undefined：changePage={(num) => setPage(num ?? 1)}  // num 在正常翻页时有值，极端情况下可能 undefined"
+            ],
+            "commonMistakes": [
+                "收到 changePage 后不更新 page prop——Pagination 是受控组件，不回写会导致页码状态不一致",
+                "期望 changePage 在组件内部状态已更新后触发——组件内部先 setPageCom(num) 再触发 changePage，父组件需自行维护独立的 page state",
+                "changeRowsPerPage 里忘记重置 page=1——切换每页条数后通常应回到第一页"
+            ]
+        },
+        "changeRowsPerPage": {
+            "signature": "(num: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "切换每页行数并重置页码：changeRowsPerPage={(num) => { setCurrentRowsPerPage(num); setPage(1); fetchData(1, num); }}",
+                "受控写法：currentRowsPerPage={currentRowsPerPage} changeRowsPerPage={(num) => setCurrentRowsPerPage(num)}"
+            ],
+            "commonMistakes": [
+                "忘记同步更新 currentRowsPerPage prop——不回写 prop 导致下拉显示旧值",
+                "假设 num 是下标而非实际行数值——num 是 rowsPerPage 数组里选中的那个数字本身"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "type prop 接受 PaginationLayout[] 数组，但内部枚举是 'sizes'|'pageRow'|'pager'|'jumper'，不是 'complex'|'simple'",
+            "wrong": "type={['simple', 'pager']}  // 'simple' 不在 PaginationLayout 联合类型",
+            "right": "type={['pager', 'jumper']}  // 自定义布局组合只能用 PaginationLayout 枚举值"
+        },
+        {
+            "issue": "changeRowsPerPage 回参 num 是 number，不是可选 number | undefined",
+            "wrong": "(num?: number) => setCurrentRowsPerPage(num ?? 10)  // 多余的 ?? 语法噪音",
+            "right": "(num: number) => setCurrentRowsPerPage(num)  // num 保证有值"
+        },
+        {
+            "issue": "skipFunc 与 changePage 在回车跳页时都会触发，不要做重复请求",
+            "wrong": "skipFunc={(num) => fetchData(num)} changePage={(num) => fetchData(num)}  // 回车时两个都触发，重复请求",
+            "right": "// 只需 changePage 处理翻页逻辑；skipFunc 是可选补充，跳页专用（例如记录跳转日志）"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Pagination",
+        "adapter": null
+    }
+}

package/es/Pagination/index.js

@@ -1,8 +1,8 @@
 import { j as r } from "../_virtual/jsx-runtime.js";
 import de, { useState as g, useRef as q, useEffect as u, useMemo as w } from "react";
 import xe from "../GlobalContext/index.js";
-import { $prefixCls as z, $rcPrefixCls as he } from "../GlobalContext/constant.js";
-import { TextField as ve } from "../TextField/index.js";
+import { $prefixCls as z, $rcPrefixCls as ve } from "../GlobalContext/constant.js";
+import { TextField as he } from "../TextField/index.js";
 import Pe from "../GlobalContext/useFormatMessage.js";
 import je from "./lang/index.js";
 import be from "../Select/index.js";
@@ -35,7 +35,7 @@ const Oe = (y) => {
     layoutArr: ["jumper", "pageRow", "pager-btn", "sizes", "pager-num"]
   });
   a.current.type = l, a.current.autoType = M, u(() => () => {
-    window.removeEventListener("resize", h), clearTimeout(a.current.timer), clearTimeout(a.current.changePagination);
+    window.removeEventListener("resize", v), clearTimeout(a.current.timer ?? void 0), clearTimeout(a.current.changePagination ?? void 0);
   }, []), u(() => {
     R(S);
   }, [S]), u(() => {
@@ -57,12 +57,12 @@ const Oe = (y) => {
     const e = Math.ceil(m / c);
     Y(e || y.page || 1);
   }, [c, m]), u(() => {
-    l === "complex" && M ? (h(), window.addEventListener("resize", h)) : window.removeEventListener("resize", h);
+    l === "complex" && M ? (v(), window.addEventListener("resize", v)) : window.removeEventListener("resize", v);
   }, [l, M]), u(() => {
-    a.current.type === "complex" && a.current.autoType && h();
+    a.current.type === "complex" && a.current.autoType && v();
   }, [m, c, n, k, W]);
-  const h = () => {
-    clearTimeout(a.current.timer);
+  const v = () => {
+    clearTimeout(a.current.timer ?? void 0);
     const e = x.current;
     e && (e.classList.add(`${z}-pagination-over`), a.current.timer = setTimeout(() => {
       U(a.current.layoutArr.length), a.current.layoutArr.length > 1 && _();
@@ -87,7 +87,7 @@ const Oe = (y) => {
         U(t), t > 3 ? _(t) : x.current.classList.remove(`${z}-pagination-over`);
       } else
         x.current.classList.remove(`${z}-pagination-over`);
-  }, v = (e) => a.current.type instanceof Array && a.current.type.indexOf(e) === -1, P = (e) => {
+  }, h = (e) => a.current.type instanceof Array && a.current.type.indexOf(e) === -1, P = (e) => {
     if (o === null) return !1;
     switch (e) {
       case "jumper":
@@ -144,11 +144,11 @@ const Oe = (y) => {
     const t = /(?=(\B)(\d{3})+$)/g;
     return e.toString().replace(t, ",");
   }, oe = w(() => {
-    if (l === "simple" || v("sizes") || P("sizes"))
+    if (l === "simple" || h("sizes") || P("sizes"))
       return null;
     const e = ae(m);
     return /* @__PURE__ */ r.jsx("div", { className: "total-num pagination-space", children: p({ id: "total" }, { total: e }) });
-  }, [m, k, f, o]), ie = w(() => v("pageRow") || P("pageRow") ? null : /* @__PURE__ */ r.jsx("div", { className: "page-line-memo pagination-space", children: /* @__PURE__ */ r.jsx(
+  }, [m, k, f, o]), ie = w(() => h("pageRow") || P("pageRow") ? null : /* @__PURE__ */ r.jsx("div", { className: "page-line-memo pagination-space", children: /* @__PURE__ */ r.jsx(
     be,
     {
       className: "page-line-select",
@@ -166,7 +166,7 @@ const Oe = (y) => {
   ] }), le = () => /* @__PURE__ */ r.jsxs("div", { className: "jump-next-icon", children: [
     /* @__PURE__ */ r.jsx("span", { children: "..." }),
     /* @__PURE__ */ r.jsx(Ce, {})
-  ] }), ce = () => C !== "num" || l === "simple" ? !0 : l === "complex" ? P("pager-num") : v("pager"), ue = w(() => ce() ? null : /* @__PURE__ */ r.jsxs("div", { className: "pagination-content pagination-space", children: [
+  ] }), ce = () => C !== "num" || l === "simple" ? !0 : l === "complex" ? P("pager-num") : h("pager"), ue = w(() => ce() ? null : /* @__PURE__ */ r.jsxs("div", { className: "pagination-content pagination-space", children: [
     I.indexOf("prev") !== -1 && /* @__PURE__ */ r.jsx("div", { className: "left-page", children: /* @__PURE__ */ r.jsx(
       "div",
       {
@@ -178,7 +178,7 @@ const Oe = (y) => {
     /* @__PURE__ */ r.jsx(
       we,
       {
-        prefixCls: `${he}-pagination`,
+        prefixCls: `${ve}-pagination`,
         current: n,
         pageSize: c,
         total: m,
@@ -196,7 +196,7 @@ const Oe = (y) => {
         children: /* @__PURE__ */ r.jsx(H, {})
       }
     ) })
-  ] }), [m, n, i, c, y.flippingArrow, C, o]), me = () => C === "btn" || l === "simple" ? !1 : l === "complex" ? P("pager-btn") : v("pager"), pe = w(() => me() ? null : /* @__PURE__ */ r.jsxs("div", { className: "pagination-btn-content pagination-space", children: [
+  ] }), [m, n, i, c, y.flippingArrow, C, o]), me = () => C === "btn" || l === "simple" ? !1 : l === "complex" ? P("pager-btn") : h("pager"), pe = w(() => me() ? null : /* @__PURE__ */ r.jsxs("div", { className: "pagination-btn-content pagination-space", children: [
     /* @__PURE__ */ r.jsx(
       G,
       {
@@ -219,10 +219,10 @@ const Oe = (y) => {
         children: p({ id: "nextPage" })
       }
     )
-  ] }), [n, i, C, f, o]), ge = w(() => v("jumper") || P("jumper") ? null : /* @__PURE__ */ r.jsxs("div", { className: "skip-page-memo pagination-space", children: [
+  ] }), [n, i, C, f, o]), ge = w(() => h("jumper") || P("jumper") ? null : /* @__PURE__ */ r.jsxs("div", { className: "skip-page-memo pagination-space", children: [
     /* @__PURE__ */ r.jsx("span", { children: p({ id: "jumpTo" }) }),
     /* @__PURE__ */ r.jsx(
-      ve,
+      he,
       {
         className: "skip-page-text-field",
         size: "large",

package/es/ParauiProvider/index.js

@@ -1,7 +1,7 @@
 import { j as m } from "../_virtual/jsx-runtime.js";
 import u from "react";
 import f from "../GlobalContext/index.js";
-import { GetLanguage as n } from "@paraview/lib";
+import { GetLanguage as n } from "../Utils/snack-kit-shims.js";
 import { i18nIntl as s } from "../GlobalContext/intl.js";
 import '../Styles/index.css';/* empty css                   */
 import { changeConfirmLocale as d } from "../GlobalContext/confirmLocale.js";

package/es/PasswordRules/component.json

@@ -0,0 +1,105 @@
+{
+    "name": "PasswordRules",
+    "category": "Data Display",
+    "description": "密码规则校验器，实时显示密码强度及各项规则通过/失败状态",
+    "semantic": {
+        "intent": [
+            "密码验证",
+            "规则提示",
+            "安全引导"
+        ],
+        "useCases": [
+            "注册",
+            "修改密码",
+            "安全设置"
+        ],
+        "riskLevel": "high"
+    },
+    "variants": {
+        "icon": {
+            "meaning": "图标模式（✓/✗ 图标指示每条规则）"
+        },
+        "order": {
+            "meaning": "序列模式（1. 2. 3. 数字序号）"
+        }
+    },
+    "states": [
+        "pass",
+        "fail"
+    ],
+    "idealProps": {
+        "value": {
+            "type": "string",
+            "description": "需要校验的密码值；每次 value 变化组件自动重新对所有规则校验并触发 onCheckAll"
+        },
+        "config": {
+            "type": "PasswordRulesConfigProps | PasswordRulesConfigProps[]",
+            "description": "规则配置，单组或多组。**PasswordRulesConfigProps** = { title?: ReactNode; type?: 'icon'|'order'; list?: PasswordRulesConfigItemProps[] }；**PasswordRulesConfigItemProps** = { label?: ReactNode; reg?: RegExp（正则校验）; validator?: (item, value) => boolean | ReactNode（自定义校验，返回 true 表示通过，false 或 ReactNode 表示失败，ReactNode 会替换显示文案）; result?: boolean | ReactNode }；⚠️ validator 优先级高于 reg"
+        },
+        "onCheckAll": {
+            "type": "(bol: boolean | undefined) => void",
+            "description": "全部规则校验结果回调：**true** = 所有规则全部通过；**false** = 所有规则全部未通过；**undefined** = 部分通过（非全通过也非全失败）；value 为 undefined 时也回调 undefined"
+        },
+        "boxShadow": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否带有边框阴影（src/PasswordRules/index.tsx:51 interface 实证）"
+        },
+        "className": {
+            "type": "string",
+            "description": "自定义类名"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "自定义样式"
+        }
+    },
+    "do": [
+        "在密码输入旁实时显示校验结果——value 受控绑定 TextField 的 onChange",
+        "列出所有规则及其状态，配合 onCheckAll 控制提交按钮的 disabled 状态（true 时才允许提交）",
+        "使用 validator 函数处理复杂规则（如「密码不能包含用户名」），返回 ReactNode 可自定义失败文案",
+        "多组规则（如「格式要求」+「强度要求」）传 config 数组，每组可设置独立 title"
+    ],
+    "dont": [
+        "规则不明确——每条 label 应简短描述具体要求（如「至少 8 位字符」）",
+        "规则过于复杂导致用户无法满足——不超过 6 条主要规则",
+        "只用 reg 不提供 validator——复杂规则如「必须包含大小写」建议用 validator 加更友好的提示"
+    ],
+    "events": {
+        "onCheckAll": {
+            "signature": "(bol: boolean | undefined) => void",
+            "asyncSupported": false,
+            "examples": [
+                "控制提交按钮：onCheckAll={(bol) => setCanSubmit(bol === true)}",
+                "显示强度文案：onCheckAll={(bol) => setStrengthText(bol === true ? '强' : bol === false ? '弱' : '中')}",
+                "value 为空时 onCheckAll(undefined)：onCheckAll={(bol) => { if (bol === undefined) { clearStrengthUI(); return; } setValid(bol); }}"
+            ],
+            "commonMistakes": [
+                "把 bol === false 当「有错误」——false 是「全部失败」；undefined 才是「部分通过」（最常见的进行时状态）",
+                "用 onCheckAll 直接控制表单 submit——建议只用它更新 UI 状态，表单提交时再做一次完整校验",
+                "假设 value 初始化时不触发 onCheckAll——组件 mount 后 value 变化（包括 undefined→string）每次都触发"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "PasswordRulesConfigItemProps.validator 返回值类型是 boolean | ReactNode，不能返回 string 以外的 falsy",
+            "wrong": "validator: (item, value) => value.length >= 8  // 返回 false 表示失败，符合要求",
+            "right": "validator: (item, value) => value.length >= 8 ? true : false  // 显式返回 boolean；返回 ReactNode 可自定义失败文案"
+        },
+        {
+            "issue": "config 可以是单对象或数组，直接传数组字面量时类型推断正确，动态构建时需显式标注",
+            "wrong": "const cfg = { title: '格式', list: [...] }; <PasswordRules config={cfg} />  // 单对象 ok\nconst cfgs = [cfg1, cfg2]; <PasswordRules config={cfgs} />  // 数组 ok，但动态 push 时注意类型",
+            "right": "const cfgs: PasswordRulesConfigProps[] = [cfg1, cfg2]; <PasswordRules config={cfgs} />"
+        },
+        {
+            "issue": "onCheckAll 回参 bol 是三值逻辑，用 === 严格比较而非 truthy/falsy",
+            "wrong": "onCheckAll={(bol) => setValid(!!bol)}  // undefined 被 coerce 成 false，与「全部失败」混淆",
+            "right": "onCheckAll={(bol) => setValid(bol === true)}  // 只有全部通过才为 true"
+        }
+    ],
+    "mapping": {
+        "realComponent": "PasswordRules",
+        "adapter": null
+    }
+}

package/es/PasswordRules/index.d.ts

@@ -3,7 +3,7 @@ export interface PasswordRulesConfigItemProps {
     /** 文案 */
     label?: ReactNode;
     /** 正则 正则表达式 */
-    reg?: any;
+    reg?: RegExp;
     /** 自定义校验方法
      *    item: 当前项配置
      *    value: 校验值
@@ -14,7 +14,7 @@ export interface PasswordRulesConfigItemProps {
     validator?: (item: PasswordRulesConfigItemProps, value: string) => boolean | ReactNode;
     /** 校验结果 */
     result?: boolean | ReactNode;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 export interface PasswordRulesConfigProps {
     /** 标题 */
@@ -23,7 +23,7 @@ export interface PasswordRulesConfigProps {
     type?: 'icon' | 'order';
     /** 规则列表 */
     list?: PasswordRulesConfigItemProps[];
-    [name: string]: any;
+    [name: string]: unknown;
 }
 export interface PasswordRulesProps {
     /** 样式class */
@@ -43,7 +43,7 @@ export interface PasswordRulesProps {
      * undefined: 未全部通过
      * */
     onCheckAll?: (bol: boolean | undefined) => void;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 declare const PasswordRules: FunctionComponent<PasswordRulesProps>;
 export default PasswordRules;