@yuku123/z-frontend-common 1.1.4 → 1.1.5

package/README.md

@@ -15,7 +15,7 @@
 |------|-----|
 | 仓 | `z-opc-foundation/z-frontend-common`（本仓） |
 | npm 包 | `@yuku123/z-frontend-common`（scope 沿用 yuku123，与 0.1.x/0.2.x 旧线连续） |
-| 当前版本 | `1.1.4` —— 1.0 语义：§1-§16 规范化起点；1.1.x 在其上追加扁平 ui 组件桶。0.1.x 是 pre-§16 形态；0.2.x 内嵌 react-dom 已废弃 |
+| 当前版本 | `1.1.5` —— 1.0 语义：§1-§16 规范化起点；1.1.x 在其上追加扁平 ui 组件桶。0.1.x 是 pre-§16 形态；0.2.x 内嵌 react-dom 已废弃 |
 | 技术栈 | React 19 + antd 6 + react-router-dom 7 + Vite 6（lead 005 §3.0 版本线单一尺子） |
 | 产物 | ESM **3 入口**（`formats: ['es']`）：`dist/index.js`（主桶）+ `dist/ui.js`（扁平 ui 桶）+ `dist/ui-echarts.js`（`ui/echarts` 子路径） |
 | 打包策略 | external 精确 **9** 个包 + **1** 条前缀规则（`echarts/*`）：react / react-dom / react-dom/client / react/jsx-runtime / react-router-dom / antd / @ant-design/icons / axios / echarts |
@@ -83,4 +83,5 @@ const MOCK_AUTH = { username: 'admin', password: '123456', user: { name: 'admin'
 - `1.1.1`：在 1.0.0 之上追加扁平 ui 组件桶（13 个 UI 组件 + design token）与 `ui/echarts` 子路径
 - `1.1.2`：ui 桶追加 `ComponentDoc`（§7 组件文档页：240px TOC + 正文两栏、滚动联动、锚点跳转、自带零依赖 markdown 引擎，宿主可注册 react-markdown 三件套升级为 GFM + Prism 高亮）
 - `1.1.4`：ui 桶的 `ListTable` 支持 `cardExtra`（Card 动作按钮）与 `searchKeys`（过滤框）**并排**渲染 —— 原实现二选一，会把其中一个静默吞掉（页面同时有「搜索」和「新增」按钮时按钮消失）。
+- `1.1.5`：`PagedTable`（**服务端分页**变体）补上 `pageSizeOptions` —— §2 强制规则 2 要求分页凑齐 `pageSize` + `showSizeChanger` + `pageSizeOptions` + `showTotal` 四件套，而 `PagedTable` 的分页参数是内联在组件里的（不走 `DEFAULT_PAGINATION`），此前漏了 `pageSizeOptions` ⇒ 全库 §2 元素级普查把 **8 个仓**的 `PagedTable` 拷贝一起判红（根因是这一处漏项被复制了 8 遍）。同版把 `showTotal` 的两支文案提成纯函数 `PAGED_TOTAL_TEXT` 并加 `test/paged-table.test.mjs`（含变异必须真红）—— antd Table 在空数据时整个分页块不渲染，闭包式文案没法被测到。
 - `1.1.3`：ui 桶追加 `useListFilter` / `filterRows`（§2 强制规则 3 的客户端过滤口径统一收在基座：大小写不敏感、多字段「或」匹配、null 字段不参与匹配、空关键字原样返回）与 `ListTable`（§2 规则 2/3/4 的成品件：分页三件套 + Card extra 过滤框 + EmptyState 空态一次到位）

package/dist/{ComponentDoc-22ujWxLE.js → ComponentDoc-rk9VdFSV.js}

@@ -1,8 +1,8 @@
-import { jsxs as m, jsx as t, Fragment as Ce } from "react/jsx-runtime";
-import { useState as B, useRef as N, useEffect as L, useMemo as q, useCallback as be, useLayoutEffect as Re, createElement as ae, Fragment as O } from "react";
-import { Button as V, Skeleton as _, Input as Te, Card as me, Table as ye, Breadcrumb as Ee, Space as se, Tag as ce } from "antd";
-import { InboxOutlined as Ie, ExclamationCircleOutlined as Ae, ReloadOutlined as re, SearchOutlined as ze, ReadOutlined as Be } from "@ant-design/icons";
-import { useNavigate as xe, useInRouterContext as De } from "react-router-dom";
+import { jsxs as m, jsx as t, Fragment as Re } from "react/jsx-runtime";
+import { useState as B, useRef as P, useEffect as L, useMemo as q, useCallback as me, useLayoutEffect as Te, createElement as ae, Fragment as O } from "react";
+import { Button as V, Skeleton as N, Input as Ee, Card as ye, Table as xe, Breadcrumb as Ae, Space as se, Tag as ce } from "antd";
+import { InboxOutlined as Ie, ExclamationCircleOutlined as ze, ReloadOutlined as re, SearchOutlined as Be, ReadOutlined as De } from "@ant-design/icons";
+import { useNavigate as ve, useInRouterContext as Le } from "react-router-dom";
 const T = {
   // 主色 (蓝紫) - 顶导/重点按钮/链接
   primary: "#7c3aed",
@@ -88,10 +88,10 @@ const T = {
   md: "0 2px 4px -1px rgba(15, 23, 42, 0.04), 0 4px 8px -1px rgba(15, 23, 42, 0.08)",
   lg: "0 4px 6px -2px rgba(15, 23, 42, 0.05), 0 12px 16px -4px rgba(15, 23, 42, 0.10)",
   xl: "0 8px 24px -6px rgba(15, 23, 42, 0.10), 0 24px 48px -12px rgba(15, 23, 42, 0.18)"
-}, at = {
+}, st = {
   rest: D.md,
   hover: "0 8px 16px -4px rgba(15, 23, 42, 0.08), 0 20px 32px -8px rgba(15, 23, 42, 0.14)"
-}, P = {
+}, _ = {
   1: 4,
   2: 8,
   3: 12,
@@ -189,7 +189,7 @@ const T = {
     }
   }
 };
-function st({
+function ct({
   icon: e,
   label: n,
   value: s,
@@ -200,7 +200,7 @@ function st({
   loading: l = !1,
   precision: i = 0
 }) {
-  const d = E[c] || E.blue, [f, g] = B(0), p = N(0);
+  const d = E[c] || E.blue, [f, g] = B(0), p = P(0);
   L(() => {
     if (l || s == null) return;
     const b = p.current, S = Number(s) || 0;
@@ -208,10 +208,10 @@ function st({
       g(S);
       return;
     }
-    const w = 600, A = performance.now();
+    const w = 600, I = performance.now();
     let $;
     const G = (U) => {
-      const j = Math.min(1, (U - A) / w), J = 1 - Math.pow(1 - j, 3), u = b + (S - b) * J;
+      const j = Math.min(1, (U - I) / w), J = 1 - Math.pow(1 - j, 3), u = b + (S - b) * J;
       g(u), j < 1 ? $ = requestAnimationFrame(G) : p.current = S;
     };
     return $ = requestAnimationFrame(G), () => $ && cancelAnimationFrame($);
@@ -221,7 +221,7 @@ function st({
   }, k = l ? "--" : Number(f).toLocaleString("zh-CN", {
     minimumFractionDigits: i,
     maximumFractionDigits: i
-  }), v = a != null ? Number(a) : null, I = v != null && v >= 0;
+  }), v = a != null ? Number(a) : null, A = v != null && v >= 0;
   return /* @__PURE__ */ m(
     "div",
     {
@@ -230,7 +230,7 @@ function st({
         position: "relative",
         background: d.gradient,
         borderRadius: C.lg,
-        padding: P[5],
+        padding: _[5],
         color: d.fg,
         cursor: r ? "pointer" : "default",
         boxShadow: D.md,
@@ -266,7 +266,7 @@ function st({
         /* @__PURE__ */ m("div", { style: {
           display: "flex",
           alignItems: "center",
-          gap: P[2],
+          gap: _[2],
           position: "relative"
         }, children: [
           /* @__PURE__ */ t("div", { style: {
@@ -289,9 +289,9 @@ function st({
         /* @__PURE__ */ m("div", { style: {
           display: "flex",
           alignItems: "baseline",
-          gap: P[2],
+          gap: _[2],
           position: "relative",
-          marginTop: P[3]
+          marginTop: _[3]
         }, children: [
           /* @__PURE__ */ t("div", { style: {
             fontSize: 30,
@@ -307,12 +307,12 @@ function st({
             fontWeight: 600,
             padding: "2px 8px",
             borderRadius: 999,
-            background: I ? "rgba(255, 255, 255, 0.22)" : "rgba(0, 0, 0, 0.18)",
+            background: A ? "rgba(255, 255, 255, 0.22)" : "rgba(0, 0, 0, 0.18)",
             display: "flex",
             alignItems: "center",
             gap: 2
           }, children: [
-            /* @__PURE__ */ t("span", { style: { fontSize: 10 }, children: I ? "▲" : "▼" }),
+            /* @__PURE__ */ t("span", { style: { fontSize: 10 }, children: A ? "▲" : "▼" }),
             Math.abs(v).toFixed(1),
             "%"
           ] })
@@ -321,7 +321,7 @@ function st({
     }
   );
 }
-function Le({ color: e = "blue", label: n, size: s = 8 }) {
+function $e({ color: e = "blue", label: n, size: s = 8 }) {
   const o = E[e] || E.blue;
   return /* @__PURE__ */ m("span", { style: {
     display: "inline-flex",
@@ -342,7 +342,7 @@ function Le({ color: e = "blue", label: n, size: s = 8 }) {
     n && /* @__PURE__ */ t("span", { children: n })
   ] });
 }
-function ct({
+function dt({
   color: e = "blue",
   title: n,
   subtitle: s,
@@ -357,7 +357,7 @@ function ct({
     marginBottom: 16
   }, children: [
     /* @__PURE__ */ m("div", { style: { display: "flex", alignItems: "baseline", gap: 12 }, children: [
-      /* @__PURE__ */ t(Le, { color: e, label: n, size: 10 }),
+      /* @__PURE__ */ t($e, { color: e, label: n, size: 10 }),
       s && /* @__PURE__ */ t("span", { style: {
         fontSize: 13,
         color: "#6b7280",
@@ -395,7 +395,7 @@ function ct({
     )
   ] });
 }
-function dt({
+function ft({
   title: e,
   description: n,
   icon: s,
@@ -469,10 +469,10 @@ function dt({
           }, children: i })
         ] }),
         /* @__PURE__ */ m("div", { style: {
-          padding: P[4],
+          padding: _[4],
           display: "flex",
           flexDirection: "column",
-          gap: P[2],
+          gap: _[2],
           flex: 1
         }, children: [
           a.length > 0 && /* @__PURE__ */ t("div", { style: {
@@ -523,7 +523,7 @@ function dt({
             fontSize: 11,
             color: "#9ca3af",
             marginTop: "auto",
-            paddingTop: P[2],
+            paddingTop: _[2],
             borderTop: "1px dashed #f1f5f9"
           }, children: r })
         ] })
@@ -531,7 +531,7 @@ function dt({
     }
   );
 }
-function ft({
+function gt({
   tag: e,
   title: n,
   description: s,
@@ -701,7 +701,7 @@ function ne({
     }
   );
 }
-function $e({
+function We({
   error: e,
   title: n = "加载失败",
   description: s,
@@ -741,7 +741,7 @@ function $e({
           color: "#dc2626",
           fontSize: l ? 28 : 18,
           flexShrink: 0
-        }, children: /* @__PURE__ */ t(Ae, {}) }),
+        }, children: /* @__PURE__ */ t(ze, {}) }),
         /* @__PURE__ */ m("div", { style: { flex: 1, minWidth: 0 }, children: [
           /* @__PURE__ */ t("div", { style: {
             fontSize: l ? 16 : 14,
@@ -772,7 +772,7 @@ function $e({
     }
   );
 }
-function gt({
+function ut({
   variant: e = "cards",
   rows: n = 4,
   active: s = !0,
@@ -801,13 +801,13 @@ function gt({
           },
           children: [
             /* @__PURE__ */ t(
-              _.Image,
+              N.Image,
               {
                 active: s,
                 style: { width: "100%", height: 140, borderRadius: 0 }
               }
             ),
-            /* @__PURE__ */ t("div", { style: { padding: 16 }, children: /* @__PURE__ */ t(_, { active: s, paragraph: { rows: 2 }, title: { width: "60%" } }) })
+            /* @__PURE__ */ t("div", { style: { padding: 16 }, children: /* @__PURE__ */ t(N, { active: s, paragraph: { rows: 2 }, title: { width: "60%" } }) })
           ]
         },
         a
@@ -825,7 +825,7 @@ function gt({
         borderRadius: C.md,
         ...o
       },
-      children: /* @__PURE__ */ t(_, { active: s, paragraph: { rows: n } })
+      children: /* @__PURE__ */ t(N, { active: s, paragraph: { rows: n } })
     }
   ) : e === "list" ? /* @__PURE__ */ t("div", { role: "status", "aria-busy": "true", "aria-label": "加载中", style: o, children: Array.from({ length: n }).map((c, a) => /* @__PURE__ */ m(
     "div",
@@ -838,8 +838,8 @@ function gt({
         borderBottom: a < n - 1 ? "1px solid #f1f5f9" : "none"
       },
       children: [
-        /* @__PURE__ */ t(_.Avatar, { active: s, size: "default" }),
-        /* @__PURE__ */ t(_, { active: s, paragraph: { rows: 1 }, title: { width: 120 }, style: { flex: 1 } })
+        /* @__PURE__ */ t(N.Avatar, { active: s, size: "default" }),
+        /* @__PURE__ */ t(N, { active: s, paragraph: { rows: 1 }, title: { width: 120 }, style: { flex: 1 } })
       ]
     },
     a
@@ -855,11 +855,11 @@ function gt({
         borderRadius: C.md,
         ...o
       },
-      children: /* @__PURE__ */ t(_, { active: s, title: { width: "40%" }, paragraph: { rows: n } })
+      children: /* @__PURE__ */ t(N, { active: s, title: { width: "40%" }, paragraph: { rows: n } })
     }
   );
 }
-function We({
+function Me({
   value: e,
   onChange: n,
   onSearch: s,
@@ -872,7 +872,7 @@ function We({
   enterButton: l,
   ...i
 }) {
-  const [d, f] = B(e || ""), g = N(null), p = N(e || "");
+  const [d, f] = B(e || ""), g = P(null), p = P(e || "");
   L(() => {
     e !== void 0 && e !== d && (f(e || ""), p.current = e || "");
   }, [e]), L(() => () => {
@@ -891,7 +891,7 @@ function We({
     g.current && clearTimeout(g.current), h(S), s && s(S);
   };
   return /* @__PURE__ */ t(
-    Te,
+    Ee,
     {
       ...i,
       value: d,
@@ -904,7 +904,7 @@ function We({
       allowClear: r ? { clearIcon: /* @__PURE__ */ t("span", { onClick: () => {
         f(""), v("");
       }, children: "×" }) } : !1,
-      prefix: /* @__PURE__ */ t(ze, { style: { color: "#9ca3af" } }),
+      prefix: /* @__PURE__ */ t(Be, { style: { color: "#9ca3af" } }),
       style: {
         width: a,
         borderRadius: C.md,
@@ -913,7 +913,7 @@ function We({
     }
   );
 }
-function Me(e, n, s) {
+function He(e, n, s) {
   const o = Array.isArray(e) ? e : [], c = String(s ?? "").trim().toLowerCase();
   if (!c) return o;
   const a = (Array.isArray(n) ? n : String(n || "").split(",")).map((r) => String(r || "").trim()).filter(Boolean);
@@ -922,20 +922,20 @@ function Me(e, n, s) {
     return i == null ? !1 : String(i).toLowerCase().includes(c);
   })) : o;
 }
-function He(e, n) {
+function Pe(e, n) {
   const [s, o] = B(""), c = (Array.isArray(n) ? n.join(",") : String(n || "")).trim(), a = q(
-    () => Me(e, c, s),
+    () => He(e, c, s),
     [e, c, s]
-  ), r = be(() => o(""), []);
+  ), r = me(() => o(""), []);
   return { keyword: s, setKeyword: o, filtered: a, reset: r };
 }
-const Ne = {
+const _e = {
   pageSize: 10,
   showSizeChanger: !0,
   pageSizeOptions: ["10", "20", "50", "100"],
   showTotal: (e) => `共 ${e} 条`
 };
-function ut({
+function pt({
   rows: e,
   columns: n,
   rowKey: s,
@@ -949,13 +949,13 @@ function ut({
   emptyDescription: f,
   emptyActionText: g,
   emptyOnAction: p,
-  pagination: h = Ne,
+  pagination: h = _e,
   cardProps: k = {},
   tableProps: v = {},
-  ...I
+  ...A
 }) {
-  const { keyword: b, setKeyword: S, filtered: w } = He(e, c), A = c ? /* @__PURE__ */ t(
-    We,
+  const { keyword: b, setKeyword: S, filtered: w } = Pe(e, c), I = c ? /* @__PURE__ */ t(
+    Me,
     {
       allowClear: !0,
       width: r,
@@ -964,11 +964,11 @@ function ut({
       onChange: S
     }
   ) : null;
-  return /* @__PURE__ */ t(me, { title: l, extra: A && i ? /* @__PURE__ */ m("span", { style: { display: "inline-flex", alignItems: "center", gap: 8 }, children: [
-    A,
+  return /* @__PURE__ */ t(ye, { title: l, extra: I && i ? /* @__PURE__ */ m("span", { style: { display: "inline-flex", alignItems: "center", gap: 8 }, children: [
+    I,
     i
-  ] }) : A || i, ...k, children: /* @__PURE__ */ t(
-    ye,
+  ] }) : I || i, ...k, children: /* @__PURE__ */ t(
+    xe,
     {
       rowKey: s,
       columns: n,
@@ -988,11 +988,11 @@ function ut({
         )
       },
       ...v,
-      ...I
+      ...A
     }
   ) });
 }
-function ve({
+function Se({
   title: e,
   subtitle: n,
   breadcrumb: s,
@@ -1000,7 +1000,7 @@ function ve({
   back: c,
   onBack: a
 }) {
-  const r = xe();
+  const r = ve();
   return /* @__PURE__ */ t("div", { style: {
     marginBottom: 12,
     paddingBottom: 10,
@@ -1051,7 +1051,7 @@ function ve({
         }
       ),
       s && s.length > 0 ? /* @__PURE__ */ t(
-        Ee,
+        Ae,
         {
           items: s.map((i, d) => {
             const f = d === s.length - 1;
@@ -1088,7 +1088,7 @@ function ve({
     }, children: o })
   ] }) });
 }
-function pt({ left: e, right: n, extra: s }) {
+function ht({ left: e, right: n, extra: s }) {
   return /* @__PURE__ */ m(
     "div",
     {
@@ -1110,57 +1110,64 @@ function pt({ left: e, right: n, extra: s }) {
     }
   );
 }
-function ht({ onClick: e, loading: n, title: s = "刷新" }) {
+function bt({ onClick: e, loading: n, title: s = "刷新" }) {
   return /* @__PURE__ */ t(V, { icon: /* @__PURE__ */ t(re, {}), onClick: e, loading: n, title: s, children: s });
 }
-const Pe = {
+const Ne = {
   0: { label: "待办", color: "default" },
   1: { label: "进行中", color: "blue" },
   2: { label: "已完成", color: "green" }
-}, _e = {
+}, Oe = {
   ACTIVE: { label: "正常", color: "green" },
   INACTIVE: { label: "禁用", color: "red" },
   ENABLED: { label: "启用", color: "green" },
   DISABLED: { label: "禁用", color: "red" }
-}, Oe = {
+}, Fe = {
   low: { label: "低", color: "default" },
   medium: { label: "中", color: "orange" },
   high: { label: "高", color: "red" },
   1: { label: "低", color: "default" },
   2: { label: "中", color: "orange" },
   3: { label: "高", color: "red" }
-}, Fe = {
+}, je = {
   PENDING: { label: "待审批", color: "orange" },
   APPROVED: { label: "已通过", color: "green" },
   REJECTED: { label: "已拒绝", color: "red" },
   CANCELLED: { label: "已撤回", color: "default" }
-}, je = {
+}, qe = {
   RUNNING: { label: "运行中", color: "green" },
   PAUSED: { label: "已暂停", color: "orange" },
   STOPPED: { label: "已停止", color: "default" },
   FAILED: { label: "失败", color: "red" },
   SUCCESS: { label: "成功", color: "green" }
-}, qe = {
-  task: Pe,
-  model: _e,
-  priority: Oe,
-  approval: Fe,
-  schedule: je
+}, Ge = {
+  task: Ne,
+  model: Oe,
+  priority: Fe,
+  approval: je,
+  schedule: qe
 };
-function bt({ status: e, type: n = "task", mapping: s, ...o }) {
-  const a = (s || qe[n] || {})[e];
+function mt({ status: e, type: n = "task", mapping: s, ...o }) {
+  const a = (s || Ge[n] || {})[e];
   return a ? /* @__PURE__ */ t(ce, { color: a.color, ...o, children: a.label }) : /* @__PURE__ */ t(ce, { ...o, children: String(e) });
 }
-function mt({ title: e, description: n, load: s, columns: o, rowKey: c = "id", extra: a, expandable: r }) {
-  const [l, i] = B([]), [d, f] = B({ current: 1, size: 10, total: null }), [g, p] = B(!1), [h, k] = B(null), v = be(async (b = d.current, S = d.size) => {
+const fe = {
+  // total 有效 ⇒ 标准口径
+  known: (e) => `共 ${e} 条`,
+  // total 缺失/为 0 —— 后端 z-meta 的分页 count 有缺陷（records 有值但 total 返回 "0"），
+  // 这时不能显示「共 0 条」（页面上会出现"有数据却说没有数据"的假象）
+  unknown: (e) => `本页 ${e} 条（接口 total 未返回有效值）`
+};
+function yt({ title: e, description: n, load: s, columns: o, rowKey: c = "id", extra: a, expandable: r }) {
+  const [l, i] = B([]), [d, f] = B({ current: 1, size: 10, total: null }), [g, p] = B(!1), [h, k] = B(null), v = me(async (b = d.current, S = d.size) => {
     p(!0), k(null);
     try {
       const w = await s(b, S);
       if (Array.isArray(w))
         i(w || []), f({ current: b, size: S, total: w.length });
       else {
-        const A = (w == null ? void 0 : w.records) || [];
-        i(A), f({ current: b, size: S, total: (w == null ? void 0 : w.total) == null ? null : Number(w.total) });
+        const I = (w == null ? void 0 : w.records) || [];
+        i(I), f({ current: b, size: S, total: (w == null ? void 0 : w.total) == null ? null : Number(w.total) });
       }
     } catch (w) {
       i([]), k(w);
@@ -1171,11 +1178,11 @@ function mt({ title: e, description: n, load: s, columns: o, rowKey: c = "id", e
   L(() => {
     v(1);
   }, []);
-  const I = d.total != null && d.total > 0;
+  const A = d.total != null && d.total > 0;
   return /* @__PURE__ */ m("div", { children: [
-    /* @__PURE__ */ t(ve, { title: e, subtitle: n }),
+    /* @__PURE__ */ t(Se, { title: e, subtitle: n }),
     /* @__PURE__ */ m(
-      me,
+      ye,
       {
         extra: /* @__PURE__ */ t(
           V,
@@ -1188,8 +1195,8 @@ function mt({ title: e, description: n, load: s, columns: o, rowKey: c = "id", e
         ),
         children: [
           a,
-          h ? /* @__PURE__ */ t($e, { error: h, onRetry: () => v(d.current, d.size), type: "inline" }) : /* @__PURE__ */ t(
-            ye,
+          h ? /* @__PURE__ */ t(We, { error: h, onRetry: () => v(d.current, d.size), type: "inline" }) : /* @__PURE__ */ t(
+            xe,
             {
               size: "small",
               columns: o,
@@ -1199,9 +1206,17 @@ function mt({ title: e, description: n, load: s, columns: o, rowKey: c = "id", e
               pagination: {
                 current: d.current,
                 pageSize: d.size,
-                total: I ? d.total : l.length,
+                total: A ? d.total : l.length,
                 showSizeChanger: !0,
-                showTotal: () => I ? `共 ${d.total} 条` : `本页 ${l.length} 条（接口 total 未返回有效值）`
+                // §2 强制规则 2：分页必须凑齐 pageSize + showSizeChanger
+                // + pageSizeOptions + showTotal 四件套。只给 showSizeChanger
+                // 而不给 pageSizeOptions，antd 会用默认的 ['10','20','50','100']
+                // 之外的行为渲染（实际 antd 默认也是这组，但那是**默认值**不是
+                // **声明值**）—— 规范要的是声明，不是碰巧对。
+                // 少这一项时，全库尺子（lead 008 §2 元素级普查）会把本页判成
+                // 「分页参数不全」⇒ 8 个仓的 PagedTable 拷贝全部误红。
+                pageSizeOptions: ["10", "20", "50", "100"],
+                showTotal: () => A ? fe.known(d.total) : fe.unknown(l.length)
               },
               onChange: (b) => v(b.current, b.pageSize),
               expandable: r,
@@ -1213,19 +1228,19 @@ function mt({ title: e, description: n, load: s, columns: o, rowKey: c = "id", e
     )
   ] });
 }
-const Ge = 240, fe = 96, Ue = { behavior: "smooth", block: "start" }, Ye = `
+const Ue = 240, ge = 96, Ye = { behavior: "smooth", block: "start" }, Ke = `
 .zfc-doc-table-wrap { max-width: 100%; overflow-x: auto; -webkit-overflow-scrolling: touch; }
 @media (max-width: 800px) { .zfc-doc-table-wrap > table { min-width: 520px; } }
-`, Ke = (e) => String(e || "").trim().toLowerCase().replace(/\s+/g, "-").replace(/[^\p{L}\p{N}\p{M}\p{Pc}-]/gu, "").replace(/-+/g, "-").replace(/^-|-$/g, ""), ie = (e) => String(e || "").replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/`([^`]*)`/g, "$1").replace(/\*\*([^*]+)\*\*/g, "$1").replace(/__([^_]+)__/g, "$1").replace(/\*([^*]+)\*/g, "$1").trim(), Se = () => {
+`, Ve = (e) => String(e || "").trim().toLowerCase().replace(/\s+/g, "-").replace(/[^\p{L}\p{N}\p{M}\p{Pc}-]/gu, "").replace(/-+/g, "-").replace(/^-|-$/g, ""), ie = (e) => String(e || "").replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/`([^`]*)`/g, "$1").replace(/\*\*([^*]+)\*\*/g, "$1").replace(/__([^_]+)__/g, "$1").replace(/\*([^*]+)\*/g, "$1").trim(), we = () => {
   const e = /* @__PURE__ */ new Map();
   let n = 0;
   return (s) => {
     n += 1;
-    const o = Ke(s) || `section-${n}`, c = e.get(o) || 0;
+    const o = Ve(s) || `section-${n}`, c = e.get(o) || 0;
     return e.set(o, c + 1), c > 0 ? `${o}-${c}` : o;
   };
-}, Ve = (e) => {
-  const n = [], s = Se();
+}, Je = (e) => {
+  const n = [], s = we();
   let o = !1;
   for (const c of String(e || "").split(`
 `)) {
@@ -1243,17 +1258,17 @@ const Ge = 240, fe = 96, Ue = { behavior: "smooth", block: "start" }, Ye = `
     i && n.push({ level: l, text: i, id: s(i) });
   }
   return n;
-}, X = (e) => e == null || typeof e == "boolean" ? "" : typeof e == "string" || typeof e == "number" ? String(e) : Array.isArray(e) ? e.map(X).join("") : e.props ? X(e.props.children) : "", ge = (e) => String(e).replace(/["\\]/g, "\\$&"), ue = (e, n = Ue) => !e || typeof e.scrollIntoView != "function" ? !1 : (e.scrollIntoView(n), !0), Z = /^\s*(`{3,}|~{3,})\s*([\w+#-]*)\s*$/, ee = /^(#{1,6})\s+(.*?)\s*#*$/, te = /^\s*([-*_])\s*(\1\s*){2,}$/, F = /^(\s*)([-*+]|\d+[.)])(\s+)(.*)$/, Y = /^\s*>\s?(.*)$/, Je = /(!?\[([^\]]*)\]\(([^)\s]+)(?:\s+"[^"]*")?\)|`([^`]+)`|\*\*([^*]+)\*\*|__([^_]+)__|~~([^~]+)~~|\*([^*\n]+)\*|<((?:https?:\/\/|mailto:)[^>\s]+)>)/g, K = (e) => {
+}, Q = (e) => e == null || typeof e == "boolean" ? "" : typeof e == "string" || typeof e == "number" ? String(e) : Array.isArray(e) ? e.map(Q).join("") : e.props ? Q(e.props.children) : "", ue = (e) => String(e).replace(/["\\]/g, "\\$&"), pe = (e, n = Ye) => !e || typeof e.scrollIntoView != "function" ? !1 : (e.scrollIntoView(n), !0), Z = /^\s*(`{3,}|~{3,})\s*([\w+#-]*)\s*$/, ee = /^(#{1,6})\s+(.*?)\s*#*$/, te = /^\s*([-*_])\s*(\1\s*){2,}$/, F = /^(\s*)([-*+]|\d+[.)])(\s+)(.*)$/, Y = /^\s*>\s?(.*)$/, Xe = /(!?\[([^\]]*)\]\(([^)\s]+)(?:\s+"[^"]*")?\)|`([^`]+)`|\*\*([^*]+)\*\*|__([^_]+)__|~~([^~]+)~~|\*([^*\n]+)\*|<((?:https?:\/\/|mailto:)[^>\s]+)>)/g, K = (e) => {
   let n = String(e).trim();
   return n.startsWith("|") && (n = n.slice(1)), n.endsWith("|") && (n = n.slice(0, -1)), n.split("|").map((s) => s.trim());
 }, Qe = (e) => {
   if (!String(e).includes("-")) return !1;
   const n = K(e);
   return n.length > 0 && n.every((s) => /^:?-+:?$/.test(s));
-}, Xe = (e) => {
+}, Ze = (e) => {
   const n = e.startsWith(":"), s = e.endsWith(":");
   return n && s ? "center" : s ? "right" : "left";
-}, Ze = (e, n) => {
+}, et = (e, n) => {
   const s = F.exec(e[n]), o = /\d/.test(s[2]), c = [];
   let a = n;
   for (; a < e.length; ) {
@@ -1288,11 +1303,11 @@ const Ge = 240, fe = 96, Ue = { behavior: "smooth", block: "start" }, Ye = `
       }
       break;
     }
-    c.push({ blocks: we(d, !0) });
+    c.push({ blocks: ke(d, !0) });
   }
   return { block: { type: "list", ordered: o, items: c }, next: a };
 };
-function we(e, n = !1) {
+function ke(e, n = !1) {
   const s = [];
   let o = 0;
   for (; o < e.length; ) {
@@ -1327,7 +1342,7 @@ function we(e, n = !1) {
       continue;
     }
     if (c.includes("|") && o + 1 < e.length && Qe(e[o + 1])) {
-      const i = K(c), d = K(e[o + 1]).map(Xe);
+      const i = K(c), d = K(e[o + 1]).map(Ze);
       o += 2;
       const f = [];
       for (; o < e.length && e[o].trim() && e[o].includes("|"); )
@@ -1346,7 +1361,7 @@ function we(e, n = !1) {
       continue;
     }
     if (F.test(c)) {
-      const i = Ze(e, o);
+      const i = et(e, o);
       s.push(i.block), o = i.next;
       continue;
     }
@@ -1364,7 +1379,7 @@ const z = (e, n) => {
   const s = [];
   let o = 0, c = 0;
   const a = (r) => s.push(/* @__PURE__ */ t(O, { children: r }, `i${c++}`));
-  for (const r of e.matchAll(Je)) {
+  for (const r of e.matchAll(Xe)) {
     if (r.index > o && a(e.slice(o, r.index)), r[1] !== void 0)
       if (r[0].startsWith("!"))
         a(n.img ? n.img({ src: r[3], alt: r[2] }) : /* @__PURE__ */ t("img", { src: r[3], alt: r[2] || "" }));
@@ -1376,7 +1391,7 @@ const z = (e, n) => {
     o = r.index + r[0].length;
   }
   return o < e.length && a(e.slice(o)), s;
-}, ke = (e, n, s) => {
+}, Ce = (e, n, s) => {
   const o = [];
   return e.forEach((c, a) => {
     const r = `b${a}`, l = (i) => o.push(/* @__PURE__ */ t(O, { children: i }, r));
@@ -1391,7 +1406,7 @@ const z = (e, n) => {
       l(n.pre ? n.pre({ children: i }) : /* @__PURE__ */ t("pre", { children: i }));
     } else if (c.type === "list") {
       const i = c.ordered ? "ol" : "ul", d = n[i], f = c.items.map((g, p) => {
-        const h = ke(g.blocks, n, s), k = n.li ? n.li({ children: h }) : /* @__PURE__ */ t("li", { children: h });
+        const h = Ce(g.blocks, n, s), k = n.li ? n.li({ children: h }) : /* @__PURE__ */ t("li", { children: h });
         return /* @__PURE__ */ t(O, { children: k }, `li${p}`);
       });
       l(d ? d({ children: f }) : ae(i, null, f));
@@ -1412,10 +1427,10 @@ const z = (e, n) => {
       l(n.blockquote ? n.blockquote({ children: i }) : /* @__PURE__ */ t("blockquote", { children: i }));
     } else c.type === "hr" && l(n.hr ? n.hr({}) : /* @__PURE__ */ t("hr", {}));
   }), o;
-}, et = (e, n = {}) => ke(we(String(e || "").split(`
-`)), n, Se());
-let pe = null;
-const he = /* @__PURE__ */ new Set(), tt = ({ navigate: e, Prism: n, oneDark: s, onAnchorClick: o }) => {
+}, tt = (e, n = {}) => Ce(ke(String(e || "").split(`
+`)), n, we());
+let he = null;
+const be = /* @__PURE__ */ new Set(), rt = ({ navigate: e, Prism: n, oneDark: s, onAnchorClick: o }) => {
   const c = {
     background: T.primarySoft,
     color: T.primary,
@@ -1482,7 +1497,7 @@ const he = /* @__PURE__ */ new Set(), tt = ({ navigate: e, Prism: n, oneDark: s,
     pre: ({ node: a, children: r }) => {
       const l = Array.isArray(r) ? r[0] : r;
       l && l.props && l.props.className;
-      const i = X(l).replace(/\n$/, "");
+      const i = Q(l).replace(/\n$/, "");
       return /* @__PURE__ */ t("pre", { style: {
         margin: "12px 0",
         padding: "12px 14px",
@@ -1530,23 +1545,23 @@ const he = /* @__PURE__ */ new Set(), tt = ({ navigate: e, Prism: n, oneDark: s,
     }
   };
 };
-function yt({
+function xt({
   markdown: e,
   title: n,
-  tocWidth: s = Ge,
+  tocWidth: s = Ue,
   tocLevels: o = [2],
   height: c = "calc(100vh - 120px)",
   markdownComponents: a,
   renderMarkdown: r
 }) {
-  const i = De() ? xe() : null, d = N(null), f = N(null), g = N(""), p = N(null), [h, k] = B(""), [v, I] = B(0), b = q(() => Ve(e), [e]), S = q(
+  const i = Le() ? ve() : null, d = P(null), f = P(null), g = P(""), p = P(null), [h, k] = B(""), [v, A] = B(0), b = q(() => Je(e), [e]), S = q(
     () => b.filter((u) => o.includes(u.level)),
     [b, o]
   );
   L(() => {
-    const u = () => I((y) => y + 1);
-    return he.add(u), () => {
-      he.delete(u);
+    const u = () => A((y) => y + 1);
+    return be.add(u), () => {
+      be.delete(u);
     };
   }, []);
   const w = (u) => {
@@ -1556,7 +1571,7 @@ function yt({
   };
   L(() => () => {
     p.current && clearTimeout(p.current);
-  }, []), Re(() => {
+  }, []), Te(() => {
     const u = d.current;
     if (!u) return;
     const y = Array.from(u.querySelectorAll("h1, h2, h3"));
@@ -1570,18 +1585,18 @@ function yt({
     const y = Array.from(u.querySelectorAll("h1, h2, h3"));
     if (!y.length) return;
     const R = () => {
-      const Q = u.getBoundingClientRect().top;
+      const X = u.getBoundingClientRect().top;
       let oe = y[0];
       for (const le of y)
-        if (le.getBoundingClientRect().top - Q <= fe) oe = le;
+        if (le.getBoundingClientRect().top - X <= ge) oe = le;
         else break;
       g.current || k(oe.id);
     }, W = new IntersectionObserver(R, {
       root: u,
-      rootMargin: `-${fe}px 0px 0px 0px`,
+      rootMargin: `-${ge}px 0px 0px 0px`,
       threshold: 0
     });
-    y.forEach((Q) => W.observe(Q)), R();
+    y.forEach((X) => W.observe(X)), R();
     const M = () => {
       g.current = "";
     };
@@ -1591,23 +1606,23 @@ function yt({
   }, [b, v, r]), L(() => {
     const u = f.current;
     if (!u || !h) return;
-    const y = u.querySelector(`[data-toc-id="${ge(h)}"]`);
+    const y = u.querySelector(`[data-toc-id="${ue(h)}"]`);
     if (!y) return;
     const R = u.getBoundingClientRect(), W = y.getBoundingClientRect();
     (W.top < R.top + 24 || W.bottom > R.bottom - 24) && y.scrollIntoView({ block: "nearest", behavior: "smooth" });
   }, [h]);
-  const A = (u) => {
+  const I = (u) => {
     const y = d.current;
-    return y && y.querySelector(`[data-anchor="${ge(u)}"]`) || (typeof document < "u" ? document.getElementById(u) : null);
+    return y && y.querySelector(`[data-anchor="${ue(u)}"]`) || (typeof document < "u" ? document.getElementById(u) : null);
   }, $ = (u, y) => {
-    u.preventDefault(), w(y), ue(A(y)), k(y);
+    u.preventDefault(), w(y), pe(I(y)), k(y);
   }, G = (u, y) => {
-    u.preventDefault(), w(y), ue(A(y)), k(y);
+    u.preventDefault(), w(y), pe(I(y)), k(y);
   }, U = q(
-    () => tt({
+    () => rt({
       navigate: i,
-      Prism: pe,
-      oneDark: pe,
+      Prism: he,
+      oneDark: he,
       onAnchorClick: G
     }),
     // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -1621,10 +1636,10 @@ function yt({
       title: "暂无文档",
       description: "把组件说明写成 DOC.md，用编译期 import 的字符串传给 ComponentDoc 即可"
     }
-  ) : r ? r({ markdown: e, components: j }) : /* @__PURE__ */ t(Ce, { children: et(e, j) });
+  ) : r ? r({ markdown: e, components: j }) : /* @__PURE__ */ t(Re, { children: tt(e, j) });
   return /* @__PURE__ */ m("div", { style: { display: "flex", flexDirection: "column", minHeight: 0, flex: 1 }, children: [
-    /* @__PURE__ */ t("style", { children: Ye }),
-    n ? /* @__PURE__ */ t(ve, { title: n }) : null,
+    /* @__PURE__ */ t("style", { children: Ke }),
+    n ? /* @__PURE__ */ t(Se, { title: n }) : null,
     /* @__PURE__ */ m("div", { style: { display: "flex", gap: 16, alignItems: "flex-start", minHeight: 0 }, children: [
       /* @__PURE__ */ m(
         "aside",
@@ -1653,7 +1668,7 @@ function yt({
               marginBottom: 8,
               padding: "0 4px"
             }, children: [
-              /* @__PURE__ */ t(Be, {}),
+              /* @__PURE__ */ t(De, {}),
               /* @__PURE__ */ t("span", { style: { fontWeight: 600 }, children: "本文目录" })
             ] }),
             /* @__PURE__ */ t("ul", { style: { listStyle: "none", margin: 0, padding: 0 }, children: S.map((u) => {
@@ -1709,32 +1724,32 @@ function yt({
   ] });
 }
 export {
-  Le as C,
-  Ne as D,
+  $e as C,
+  _e as D,
   ne as E,
-  dt as F,
-  st as G,
-  ut as L,
-  ve as P,
-  ht as R,
-  We as S,
-  pt as T,
-  yt as a,
-  ft as b,
-  $e as c,
-  gt as d,
-  mt as e,
-  ct as f,
-  bt as g,
+  ft as F,
+  ct as G,
+  pt as L,
+  Se as P,
+  bt as R,
+  Me as S,
+  ht as T,
+  xt as a,
+  gt as b,
+  We as c,
+  ut as d,
+  yt as e,
+  dt as f,
+  mt as g,
   H as h,
   T as i,
-  Me as j,
+  He as j,
   de as k,
-  at as l,
-  P as m,
+  st as l,
+  _ as m,
   x as n,
   E as p,
   C as r,
   D as s,
-  He as u
+  Pe as u
 };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { C as be, a as we, D as Ie, b as ke, E as Ce, c as Re, F as ve, G as Le, L as ze, d as Me, P as Be, e as Oe, R as Te, S as je, f as Ee, g as $e, T as De, h as Ke, i as Fe, j as Pe, k as qe, l as He, n as Ne, p as We, r as Ge, s as Je, m as _e, u as Ae } from "./ComponentDoc-22ujWxLE.js";
+import { C as be, a as we, D as Ie, b as ke, E as Ce, c as Re, F as ve, G as Le, L as ze, d as Me, P as Be, e as Oe, R as Te, S as je, f as Ee, g as $e, T as De, h as Ke, i as Fe, j as Pe, k as qe, l as He, n as Ne, p as We, r as Ge, s as Je, m as _e, u as Ae } from "./ComponentDoc-rk9VdFSV.js";
 import { jsxs as h, jsx as r } from "react/jsx-runtime";
 import { Layout as I, Spin as j, Menu as E, Dropdown as $, Avatar as D, Button as k, Tooltip as K, Card as F, Alert as P, Form as x, Input as L, message as S, Tag as q, Result as H } from "antd";
 import { MenuUnfoldOutlined as N, MenuFoldOutlined as W, DownOutlined as G, LoginOutlined as J, UserOutlined as _, LockOutlined as A } from "@ant-design/icons";

package/dist/ui.js

@@ -1,4 +1,4 @@
-import { C as e, a as t, D as r, b as o, E as n, c as d, F as i, G as l, L as S, d as u, P as T, e as p, R as b, S as f, f as g, g as c, T as h, h as m, i as C, j as D, k as L, l as E, n as F, p as P, r as A, s as B, m as G, u as I } from "./ComponentDoc-22ujWxLE.js";
+import { C as e, a as t, D as r, b as o, E as n, c as d, F as i, G as l, L as S, d as u, P as T, e as p, R as b, S as f, f as g, g as c, T as h, h as m, i as C, j as D, k as L, l as E, n as F, p as P, r as A, s as B, m as G, u as I } from "./ComponentDoc-rk9VdFSV.js";
 export {
   e as CategoryDot,
   t as ComponentDoc,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yuku123/z-frontend-common",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "description": "z-opc 全仓共享前端基座 — AppLayout(§1/§11/§12/§15/§16) + LoginPage(mockAuth 双模式) + EmptyState/StatusTag/ErrorBoundary + createRequest 工厂。lead 008 前端开发规范唯一承载仓",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/ui/PagedTable.jsx

@@ -10,6 +10,22 @@ import {EmptyState, ErrorState, PageHeader} from './index'
  * 后端 z-meta 的分页 count 有缺陷（records 有值但 total 返回 "0"），这里不把 0 当"共 0 条"显示，
  * 而是显式标出接口给的总数，避免页面上出现"有数据却说没有数据"的假象。
  */
+/**
+ * 分页总数文案 —— 提成导出是为了让它**可单测**。
+ *
+ * 为什么必须提成导出：antd 的 Table 在**数据为空**时不渲染整个分页块
+ * （实测 SSR 空数据产物里连 `ant-pagination` 容器都没有）⇒
+ * `showTotal` 那个闭包在 SSR 下**永远不会被执行**，任何针对文案本身的断言都无从下手。
+ * 提成纯函数后，文案口径就能被直接测到，而不用去构造「有数据」的场景。
+ */
+export const PAGED_TOTAL_TEXT = {
+    // total 有效 ⇒ 标准口径
+    known: (total) => `共 ${total} 条`,
+    // total 缺失/为 0 —— 后端 z-meta 的分页 count 有缺陷（records 有值但 total 返回 "0"），
+    // 这时不能显示「共 0 条」（页面上会出现"有数据却说没有数据"的假象）
+    unknown: (rowsLength) => `本页 ${rowsLength} 条（接口 total 未返回有效值）`,
+}
+
 export default function PagedTable({title, description, load, columns, rowKey = 'id', extra, expandable}) {
     const [rows, setRows] = useState([])
     const [page, setPage] = useState({current: 1, size: 10, total: null})
@@ -67,10 +83,18 @@ export default function PagedTable({title, description, load, columns, rowKey =
                             pageSize: page.size,
                             total: totalKnown ? page.total : rows.length,
                             showSizeChanger: true,
+                            // §2 强制规则 2：分页必须凑齐 pageSize + showSizeChanger
+                            // + pageSizeOptions + showTotal 四件套。只给 showSizeChanger
+                            // 而不给 pageSizeOptions，antd 会用默认的 ['10','20','50','100']
+                            // 之外的行为渲染（实际 antd 默认也是这组，但那是**默认值**不是
+                            // **声明值**）—— 规范要的是声明，不是碰巧对。
+                            // 少这一项时，全库尺子（lead 008 §2 元素级普查）会把本页判成
+                            // 「分页参数不全」⇒ 8 个仓的 PagedTable 拷贝全部误红。
+                            pageSizeOptions: ['10', '20', '50', '100'],
                             showTotal: () =>
                                 totalKnown
-                                    ? `共 ${page.total} 条`
-                                    : `本页 ${rows.length} 条（接口 total 未返回有效值）`,
+                                    ? PAGED_TOTAL_TEXT.known(page.total)
+                                    : PAGED_TOTAL_TEXT.unknown(rows.length),
                         }}
                         onChange={(p) => fetch(p.current, p.pageSize)}
                         expandable={expandable}