@yuku123/z-frontend-common 1.1.2 → 1.1.3

package/dist/index.js

@@ -1,43 +1,43 @@
-import { C as be, a as we, D as ke, E as Ie, b as Ce, F as Re, G as ve, L as ze, P as Me, c as Be, R as Le, S as Oe, d as je, e as Ee, T as Te, f as $e, g as Ke, h as De, l as Pe, n as qe, p as Fe, r as He, s as We, i as Ne } from "./ComponentDoc-C4XFElke.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-CJL2TB6b.js";
 import { jsxs as h, jsx as r } from "react/jsx-runtime";
-import { Layout as k, Spin as E, Menu as T, Dropdown as $, Avatar as K, Button as I, Tooltip as D, Card as P, Alert as q, Form as x, Input as z, message as S, Tag as F, Result as H } from "antd";
-import { MenuUnfoldOutlined as W, MenuFoldOutlined as N, DownOutlined as G, LoginOutlined as J, UserOutlined as Q, LockOutlined as V } from "@ant-design/icons";
-import { useNavigate as X, useLocation as Y, Outlet as Z } from "react-router-dom";
-import { useState as B, Component as _ } from "react";
-import U from "axios";
-const { Header: A, Sider: ee, Content: te } = k;
+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";
+import { useNavigate as Q, useLocation as U, Outlet as V } from "react-router-dom";
+import { useState as M, Component as X } from "react";
+import Y from "axios";
+const { Header: Z, Sider: ee, Content: te } = I;
 function re(e, t = 0.85) {
   const s = /^#?([0-9a-f]{6})$/i.exec(e || "");
   if (!s) return e;
-  const d = parseInt(s[1], 16), f = Math.max(0, Math.min(255, Math.round((d >> 16 & 255) * t))), n = Math.max(0, Math.min(255, Math.round((d >> 8 & 255) * t))), i = Math.max(0, Math.min(255, Math.round((d & 255) * t)));
-  return "#" + (f << 16 | n << 8 | i).toString(16).padStart(6, "0");
+  const d = parseInt(s[1], 16), u = Math.max(0, Math.min(255, Math.round((d >> 16 & 255) * t))), n = Math.max(0, Math.min(255, Math.round((d >> 8 & 255) * t))), i = Math.max(0, Math.min(255, Math.round((d & 255) * t)));
+  return "#" + (u << 16 | n << 8 | i).toString(16).padStart(6, "0");
 }
 function ne({
   menuItems: e = [],
   appTitle: t = "One Company",
   appShort: s = "OC",
   appVersion: d,
-  appIcon: f,
+  appIcon: u,
   appUser: n,
   loginPath: i,
   headerExtra: p,
   loading: m = !1
 }) {
-  const [o, g] = B(!1), y = X(), c = Y(), O = ({ key: u }) => {
-    y(u);
+  const [o, g] = M(!1), y = Q(), c = U(), O = ({ key: f }) => {
+    y(f);
   }, R = () => {
     if (i) return i;
-    const u = e && e[0], l = u && u.key;
+    const f = e && e[0], l = f && f.key;
     return typeof l == "string" && l.endsWith("/home") ? l.slice(0, -4) + "login" : "/login";
-  }, v = (u, l = []) => {
-    for (const a of u || [])
+  }, v = (f, l = []) => {
+    for (const a of f || [])
       a != null && a.key && l.push(a.key), a != null && a.children && v(a.children, l);
     return l;
-  }, j = (() => {
-    const u = v(e), l = c.pathname;
-    return u.filter((a) => l === a || l.startsWith(a + "/")).sort((a, w) => w.length - a.length)[0] || l;
+  }, T = (() => {
+    const f = v(e), l = c.pathname;
+    return f.filter((a) => l === a || l.startsWith(a + "/")).sort((a, w) => w.length - a.length)[0] || l;
   })();
-  return /* @__PURE__ */ h(k, { style: { minHeight: "100vh" }, children: [
+  return /* @__PURE__ */ h(I, { style: { minHeight: "100vh" }, children: [
     /* @__PURE__ */ h(ee, { trigger: null, collapsible: !0, collapsed: o, children: [
       /* @__PURE__ */ r("div", { style: {
         height: 64,
@@ -46,8 +46,8 @@ function ne({
         justifyContent: "center"
       }, children: (() => {
         if (o) {
-          if (f) {
-            const { icon: u, color: l = "#7c3aed", label: a = t } = f, w = /* @__PURE__ */ r("div", { style: {
+          if (u) {
+            const { icon: f, color: l = "#7c3aed", label: a = t } = u, w = /* @__PURE__ */ r("div", { style: {
               width: 36,
               height: 36,
               borderRadius: 9,
@@ -59,8 +59,8 @@ function ne({
               fontSize: 20,
               boxShadow: "0 2px 6px rgba(0,0,0,0.25)",
               overflow: "hidden"
-            }, children: u });
-            return /* @__PURE__ */ r(D, { title: a, placement: "right", children: w });
+            }, children: f });
+            return /* @__PURE__ */ r(K, { title: a, placement: "right", children: w });
           }
           return s;
         }
@@ -77,19 +77,19 @@ function ne({
           ] })
         ] });
       })() }),
-      m ? /* @__PURE__ */ r("div", { style: { padding: 16, textAlign: "center" }, children: /* @__PURE__ */ r(E, { size: "small" }) }) : /* @__PURE__ */ r(
-        T,
+      m ? /* @__PURE__ */ r("div", { style: { padding: 16, textAlign: "center" }, children: /* @__PURE__ */ r(j, { size: "small" }) }) : /* @__PURE__ */ r(
+        E,
         {
           theme: "dark",
           mode: "inline",
-          selectedKeys: [j],
+          selectedKeys: [T],
           items: e,
           onClick: O
         }
       )
     ] }),
-    /* @__PURE__ */ h(k, { children: [
-      /* @__PURE__ */ h(A, { style: {
+    /* @__PURE__ */ h(I, { children: [
+      /* @__PURE__ */ h(Z, { style: {
         height: 48,
         lineHeight: "48px",
         padding: "0 16px",
@@ -99,7 +99,7 @@ function ne({
         justifyContent: "space-between",
         borderBottom: "1px solid #f1f5f9"
       }, children: [
-        /* @__PURE__ */ r("span", { onClick: () => g(!o), style: { fontSize: 18, cursor: "pointer" }, children: o ? /* @__PURE__ */ r(W, {}) : /* @__PURE__ */ r(N, {}) }),
+        /* @__PURE__ */ r("span", { onClick: () => g(!o), style: { fontSize: 18, cursor: "pointer" }, children: o ? /* @__PURE__ */ r(N, {}) : /* @__PURE__ */ r(W, {}) }),
         /* @__PURE__ */ h("div", { style: { display: "flex", alignItems: "center", gap: 12 }, children: [
           n && /* @__PURE__ */ r(
             $,
@@ -119,14 +119,14 @@ function ne({
               },
               placement: "bottomRight",
               children: /* @__PURE__ */ h("span", { style: { cursor: "pointer", display: "inline-flex", alignItems: "center", gap: 6 }, children: [
-                /* @__PURE__ */ r(K, { size: 28, style: { background: "#7c3aed" }, children: (n.name || "?").slice(0, 1).toUpperCase() }),
+                /* @__PURE__ */ r(D, { size: 28, style: { background: "#7c3aed" }, children: (n.name || "?").slice(0, 1).toUpperCase() }),
                 /* @__PURE__ */ r("span", { style: { fontSize: 13, color: "#0f172a" }, children: n.name }),
                 /* @__PURE__ */ r(G, { style: { fontSize: 10, color: "#94a3b8" } })
               ] })
             }
           ),
           !n && /* @__PURE__ */ r(
-            I,
+            k,
             {
               type: "primary",
               size: "small",
@@ -140,7 +140,7 @@ function ne({
           p
         ] })
       ] }),
-      /* @__PURE__ */ r(te, { style: { margin: 16, padding: 24, background: "#fff", minHeight: 280 }, children: /* @__PURE__ */ r(Z, {}) })
+      /* @__PURE__ */ r(te, { style: { margin: 16, padding: 24, background: "#fff", minHeight: 280 }, children: /* @__PURE__ */ r(V, {}) })
     ] })
   ] });
 }
@@ -151,7 +151,7 @@ function se(e, t = {}) {
   const {
     tokenKey: s = "token",
     userInfoKey: d = "userInfo",
-    unauthorizedRedirect: f = "/login"
+    unauthorizedRedirect: u = "/login"
   } = t;
   return e.interceptors.request.use((n) => {
     const i = localStorage.getItem(s);
@@ -163,14 +163,14 @@ function se(e, t = {}) {
       const i = (p = n.response) == null ? void 0 : p.status;
       if (i === 401) {
         const g = (m = n.response) == null ? void 0 : m.data;
-        !!(g && typeof g == "object" && g.errorCode) ? console.warn(`[401] 业务鉴权失败（不是会话过期，不跳登录）: ${(o = n.config) == null ? void 0 : o.url} → ${g.errorCode}`) : (localStorage.removeItem(s), localStorage.removeItem(d), window.location.href = f);
+        !!(g && typeof g == "object" && g.errorCode) ? console.warn(`[401] 业务鉴权失败（不是会话过期，不跳登录）: ${(o = n.config) == null ? void 0 : o.url} → ${g.errorCode}`) : (localStorage.removeItem(s), localStorage.removeItem(d), window.location.href = u);
       } else i === 403 ? console.error("没有权限访问该资源") : i === 500 && console.error("服务器内部错误");
       return Promise.reject(n);
     }
   ), e;
 }
 function C(e = {}) {
-  const t = U.create({
+  const t = Y.create({
     baseURL: e.baseURL ?? "/api",
     timeout: e.timeout ?? 1e4
   });
@@ -186,10 +186,10 @@ function ie({
   mockAuth: t,
   loginApi: s = "/auth/login",
   redirectUrl: d = "/",
-  onSuccess: f
+  onSuccess: u
 }) {
-  const [n, i] = B(!1), p = (o) => {
-    localStorage.setItem("token", t ? "mock-" + t.username : (o == null ? void 0 : o.token) || "token"), localStorage.setItem("userInfo", JSON.stringify(o || {})), S.success("登录成功" + (t ? "（mock 模式，待 CTC/SSO 接入）" : "")), f ? f(o) : window.location.href = d;
+  const [n, i] = M(!1), p = (o) => {
+    localStorage.setItem("token", t ? "mock-" + t.username : (o == null ? void 0 : o.token) || "token"), localStorage.setItem("userInfo", JSON.stringify(o || {})), S.success("登录成功" + (t ? "（mock 模式，待 CTC/SSO 接入）" : "")), u ? u(o) : window.location.href = d;
   }, m = async (o) => {
     var g, y;
     i(!0);
@@ -199,7 +199,7 @@ function ie({
         return;
       }
       const c = await b.post(s, o);
-      c != null && c.token ? (localStorage.setItem("token", c.token), localStorage.setItem("userInfo", JSON.stringify(c.user || c)), S.success("登录成功"), f ? f(c) : window.location.href = d) : S.error("登录失败：未获取到 token");
+      c != null && c.token ? (localStorage.setItem("token", c.token), localStorage.setItem("userInfo", JSON.stringify(c.user || c)), S.success("登录成功"), u ? u(c) : window.location.href = d) : S.error("登录失败：未获取到 token");
     } catch (c) {
       S.error(((y = (g = c.response) == null ? void 0 : g.data) == null ? void 0 : y.message) || c.message || "登录失败");
     } finally {
@@ -212,9 +212,9 @@ function ie({
     justifyContent: "center",
     alignItems: "center",
     background: "#f0f2f5"
-  }, children: /* @__PURE__ */ h(P, { title: e, style: { width: 400 }, children: [
+  }, children: /* @__PURE__ */ h(F, { title: e, style: { width: 400 }, children: [
     t && /* @__PURE__ */ r(
-      q,
+      P,
       {
         type: "info",
         showIcon: !0,
@@ -223,13 +223,13 @@ function ie({
       }
     ),
     /* @__PURE__ */ h(x, { onFinish: m, size: "large", children: [
-      /* @__PURE__ */ r(x.Item, { name: "username", rules: [{ required: !0, message: "请输入用户名" }], children: /* @__PURE__ */ r(z, { prefix: /* @__PURE__ */ r(Q, {}), placeholder: "用户名" }) }),
-      /* @__PURE__ */ r(x.Item, { name: "password", rules: [{ required: !0, message: "请输入密码" }], children: /* @__PURE__ */ r(z.Password, { prefix: /* @__PURE__ */ r(V, {}), placeholder: "密码" }) }),
-      /* @__PURE__ */ r(x.Item, { children: /* @__PURE__ */ r(I, { type: "primary", htmlType: "submit", loading: n, block: !0, children: "登 录" }) })
+      /* @__PURE__ */ r(x.Item, { name: "username", rules: [{ required: !0, message: "请输入用户名" }], children: /* @__PURE__ */ r(L, { prefix: /* @__PURE__ */ r(_, {}), placeholder: "用户名" }) }),
+      /* @__PURE__ */ r(x.Item, { name: "password", rules: [{ required: !0, message: "请输入密码" }], children: /* @__PURE__ */ r(L.Password, { prefix: /* @__PURE__ */ r(A, {}), placeholder: "密码" }) }),
+      /* @__PURE__ */ r(x.Item, { children: /* @__PURE__ */ r(k, { type: "primary", htmlType: "submit", loading: n, block: !0, children: "登 录" }) })
     ] })
   ] }) });
 }
-const L = {
+const B = {
   1: { color: "green", text: "正常" },
   0: { color: "red", text: "禁用" },
   pending: { color: "orange", text: "待处理" },
@@ -237,10 +237,10 @@ const L = {
   rejected: { color: "red", text: "已拒绝" }
 };
 function le({ status: e, map: t }) {
-  const s = (t == null ? void 0 : t[e]) || L[e] || { color: "default", text: String(e) };
-  return /* @__PURE__ */ r(F, { color: s.color, children: s.text });
+  const s = (t == null ? void 0 : t[e]) || B[e] || { color: "default", text: String(e) };
+  return /* @__PURE__ */ r(q, { color: s.color, children: s.text });
 }
-class ce extends _ {
+class ce extends X {
   constructor(t) {
     super(t), this.state = { hasError: !1, error: null, errorInfo: null }, this.handleReset = () => {
       this.setState({ hasError: !1, error: null, errorInfo: null }), typeof this.props.onReset == "function" && this.props.onReset();
@@ -260,15 +260,15 @@ class ce extends _ {
         status: "error",
         title: "页面出错了",
         subTitle: String(((t = this.state.error) == null ? void 0 : t.message) || this.state.error),
-        extra: /* @__PURE__ */ r(I, { type: "primary", onClick: this.handleReset, children: "重试" })
+        extra: /* @__PURE__ */ r(k, { type: "primary", onClick: this.handleReset, children: "重试" })
       }
     ) : this.props.children;
   }
 }
-const de = ["get", "post", "put", "patch", "delete", "head", "options"], M = {
+const de = ["get", "post", "put", "patch", "delete", "head", "options"], z = {
   AppLayout: ne,
   StatusTag: le,
-  defaultStatusMap: L,
+  defaultStatusMap: B,
   LoginPage: ie,
   ErrorBoundary: ce,
   request: b,
@@ -276,41 +276,45 @@ const de = ["get", "post", "put", "patch", "delete", "head", "options"], M = {
   createRequest: C
 };
 for (const e of de)
-  typeof b[e] == "function" && !(e in M) && (M[e] = (...t) => b[e](...t));
+  typeof b[e] == "function" && !(e in z) && (z[e] = (...t) => b[e](...t));
 export {
   ne as AppLayout,
   be as CategoryDot,
   we as ComponentDoc,
+  Ie as DEFAULT_PAGINATION,
   ke as DarkBanner,
-  Ie as EmptyState,
+  Ce as EmptyState,
   ce as ErrorBoundary,
-  Ce as ErrorState,
-  Re as FeatureCard,
-  ve as GradientStatCard,
-  ze as LoadingState,
+  Re as ErrorState,
+  ve as FeatureCard,
+  Le as GradientStatCard,
+  ze as ListTable,
+  Me as LoadingState,
   ie as LoginPage,
-  Me as PageHeader,
-  Be as PagedTable,
-  Le as RefreshButton,
-  Oe as SearchInput,
-  je as SectionHeader,
-  Ee as StatusBadge,
+  Be as PageHeader,
+  Oe as PagedTable,
+  Te as RefreshButton,
+  je as SearchInput,
+  Ee as SectionHeader,
+  $e as StatusBadge,
   le as StatusTag,
-  Te as TableToolbar,
-  $e as antdTheme,
+  De as TableToolbar,
+  Ke as antdTheme,
   ae as authRequest,
-  Ke as brand,
+  Fe as brand,
   C as createRequest,
-  M as default,
-  L as defaultStatusMap,
-  De as fontSize,
-  Pe as lift,
-  qe as neutral,
-  Fe as palette,
-  He as radius,
+  z as default,
+  B as defaultStatusMap,
+  Pe as filterRows,
+  qe as fontSize,
+  He as lift,
+  Ne as neutral,
+  We as palette,
+  Ge as radius,
   b as request,
   se as setupInterceptors,
-  We as shadow,
-  Ne as space,
-  oe as unwrapResponse
+  Je as shadow,
+  _e as space,
+  oe as unwrapResponse,
+  Ae as useListFilter
 };

package/dist/ui.js

@@ -1,27 +1,31 @@
-import { C as s, a as t, D as r, E as o, b as n, F as d, G as S, L as i, P as l, c as p, R as g, S as u, d as b, e as c, T as f, f as h, g as C, h as T, l as m, n as D, p as B, r as E, s as P, i as y } from "./ComponentDoc-C4XFElke.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-CJL2TB6b.js";
 export {
-  s as CategoryDot,
+  e as CategoryDot,
   t as ComponentDoc,
-  r as DarkBanner,
-  o as EmptyState,
-  n as ErrorState,
-  d as FeatureCard,
-  S as GradientStatCard,
-  i as LoadingState,
-  l as PageHeader,
+  r as DEFAULT_PAGINATION,
+  o as DarkBanner,
+  n as EmptyState,
+  d as ErrorState,
+  i as FeatureCard,
+  l as GradientStatCard,
+  S as ListTable,
+  u as LoadingState,
+  T as PageHeader,
   p as PagedTable,
-  g as RefreshButton,
-  u as SearchInput,
-  b as SectionHeader,
+  b as RefreshButton,
+  f as SearchInput,
+  g as SectionHeader,
   c as StatusBadge,
-  f as TableToolbar,
-  h as antdTheme,
+  h as TableToolbar,
+  m as antdTheme,
   C as brand,
-  T as fontSize,
-  m as lift,
-  D as neutral,
-  B as palette,
-  E as radius,
-  P as shadow,
-  y as space
+  D as filterRows,
+  L as fontSize,
+  E as lift,
+  F as neutral,
+  P as palette,
+  A as radius,
+  B as shadow,
+  G as space,
+  I as useListFilter
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yuku123/z-frontend-common",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "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/ListTable.jsx

@@ -0,0 +1,94 @@
+import {Card, Table} from 'antd'
+import EmptyState from './EmptyState'
+import SearchInput from './SearchInput'
+import useListFilter from './useListFilter'
+
+/**
+ * ListTable —— 列表页的标准形态（lead 008 §2 强制规则 2/3/4 的成品件）。
+ *
+ * 为什么要有这个组件：
+ *   §2 要求每个 `<Table>` 渲染的列表页都必须凑齐三件套 ——
+ *     规则 2 分页（`pageSize` + `showSizeChanger` + `pageSizeOptions` + `showTotal`）
+ *     规则 3 查询（Card 的 extra 里一个过滤框，端侧过滤）
+ *     规则 4 空态用 `<EmptyState>`，不是 antd 默认空图
+ *   逐页手写这三样，分母是全库几百个 Table 元素 ⇒ 漏一处就是一处不一致，
+ *   而且每处都要自己决定「按哪个字段过滤」，很容易各写各的。
+ *   收进基座后，各仓只需要声明「按哪几个字段过滤」和「空态说什么」。
+ *
+ * 为什么搜索用基座自己的 SearchInput 而不是 antd 的 `Input.Search`：
+ *   两者都是 300ms 防抖 + allowClear，但 SearchInput 是基座实现，Esc 立即清空、
+ *   Enter 立即出结果，全仓口径一致；各仓不用再各自决定用哪个。
+ *
+ * 透传约定：
+ *   - `cardProps` → 传给外层 `<Card>`（如 `style` / `size` / `title`）
+ *   - `tableProps` → 传给内层 `<Table>`（如 `scroll` / `columns` 之外的表级属性）
+ *   - 其余 props → 直接给 `<Table>`（与 antd 一致）
+ *   - `pagination={false}` 仍然允许显式传（用于「数据已知 ≤10 行且不变」的豁免场景，
+ *     但按 §2 必须在该处注释豁免原因）。
+ */
+export const DEFAULT_PAGINATION = {
+    pageSize: 10,
+    showSizeChanger: true,
+    pageSizeOptions: ['10', '20', '50', '100'],
+    showTotal: (total) => `共 ${total} 条`,
+}
+
+export default function ListTable({
+                                  rows,
+                                  columns,
+                                  rowKey,
+                                  loading,
+                                  searchKeys,
+                                  searchPlaceholder = '过滤',
+                                  searchWidth = 220,
+                                  cardTitle,
+                                  cardExtra,
+                                  emptyTitle = '暂无数据',
+                                  emptyDescription,
+                                  emptyActionText,
+                                  emptyOnAction,
+                                  pagination = DEFAULT_PAGINATION,
+                                  cardProps = {},
+                                  tableProps = {},
+                                  ...rest
+                              }) {
+    const {keyword, setKeyword, filtered} = useListFilter(rows, searchKeys)
+
+    // searchKeys 为空 ⇒ 不渲染搜索框（过滤也是空操作）
+    const search = searchKeys
+        ? (
+            <SearchInput
+                allowClear
+                width={searchWidth}
+                placeholder={searchPlaceholder}
+                value={keyword}
+                onChange={setKeyword}
+            />
+        )
+        : null
+
+    return (
+        <Card title={cardTitle} extra={search || cardExtra} {...cardProps}>
+            <Table
+                rowKey={rowKey}
+                columns={columns}
+                dataSource={filtered}
+                loading={loading}
+                size="small"
+                pagination={pagination}
+                locale={{
+                    emptyText: (
+                        <EmptyState
+                            title={emptyTitle}
+                            description={emptyDescription}
+                            actionText={emptyActionText}
+                            onAction={emptyOnAction}
+                        />
+                    ),
+                }}
+                {...tableProps}
+                {...rest}
+            />
+        </Card>
+    )
+}

package/src/components/ui/index.js

@@ -26,6 +26,10 @@ export {default as EmptyState} from './EmptyState'
 export {default as ErrorState} from './ErrorState'
 export {default as LoadingState} from './LoadingState'
 export {default as SearchInput} from './SearchInput'
+// useListFilter —— §2 强制规则 3 的客户端过滤（各仓只声明按哪几个字段过滤，口径统一收在基座）
+export {default as useListFilter, filterRows} from './useListFilter'
+// ListTable —— §2 强制规则 2/3/4 的成品件（分页 + 过滤 + EmptyState 三件套一次到位）
+export {default as ListTable, DEFAULT_PAGINATION} from './ListTable'
 // EChartsChart 走 ./echarts 子路径: 它是本目录唯一引 echarts 的组件,
 export {default as PageHeader} from './PageHeader'
 export {default as TableToolbar, RefreshButton} from './TableToolbar'

package/src/components/ui/useListFilter.js

@@ -0,0 +1,74 @@
+/**
+ * useListFilter —— 列表页的客户端过滤（lead 008 §2 强制规则 3）。
+ *
+ * 为什么要有这个 hook：
+ *   §2 要求「任何列表页必须有查询」，而且明确「不要求走后端搜索（端侧过滤足够，
+ *   除非集合 >1k 行）」。这意味着每个列表页都要写一遍「关键字 → 过滤行」的逻辑。
+ *   分散写就会分裂出 N 种口径：有的大小写敏感、有的只匹配第一个字段、有的把
+ *   null 当成空串匹配到全部。统一收进基座，各仓只声明「按哪几个字段过滤」。
+ *
+ * 口径（与 §2 一致）：
+ *   - 大小写不敏感（用户按任意大小写输入都能命中）。
+ *   - 多字段「或」匹配：任一字段命中即保留该行。
+ *   - 字段值为 null / undefined 时跳过，不参与匹配（否则 `String(null)` = "null"
+ *     会把含 "null" 的关键字误命中到每一行）。
+ *   - 关键字为空（去掉首尾空白后）时**原样返回入参数组**，不过滤、不复制语义。
+ *
+ * 为什么过滤键用「字符串或数组都收」：
+ *   各仓调用时通常写 `useListFilter(rows, 'id,name')` 这种字面量。若把数组直接
+ *   放进 useMemo 依赖，每次渲染都是新数组 → 依赖永远不等 → memo 形同虚设。
+ *   这里把 keys 归一化成字符串再进依赖，保证引用稳定。
+ */
+import {useCallback, useMemo, useState} from 'react'
+
+/**
+ * 纯函数：按给定字段做大小写不敏感的「或」匹配过滤。
+ * @param {Array<object>} rows 待过滤的行
+ * @param {string|string[]} keys 参与匹配的字段名
+ * @param {string} keyword 关键字
+ * @returns {Array<object>} 过滤后的行（keyword 为空时返回入参本身）
+ */
+export function filterRows(rows, keys, keyword) {
+    const list = Array.isArray(rows) ? rows : []
+    const kw = String(keyword == null ? '' : keyword).trim().toLowerCase()
+    if (!kw) return list
+
+    const fields = (Array.isArray(keys) ? keys : String(keys || '').split(','))
+        .map((k) => String(k || '').trim())
+        .filter(Boolean)
+    if (!fields.length) return list
+
+    return list.filter((row) => {
+        if (!row || typeof row !== 'object') return false
+        return fields.some((field) => {
+            const v = row[field]
+            if (v === null || v === undefined) return false
+            return String(v).toLowerCase().includes(kw)
+        })
+    })
+}
+
+/**
+ * Hook 版：返回 {keyword, setKeyword, filtered, reset}。
+ *
+ * @param {Array<object>} rows 数据源
+ * @param {string|string[]} keys 参与匹配的字段名（逗号分隔字符串或数组）
+ * @returns {{keyword: string, setKeyword: Function, filtered: Array<object>, reset: Function}}
+ */
+export function useListFilter(rows, keys) {
+    const [keyword, setKeyword] = useState('')
+
+    // keys 归一成字符串再进依赖：调用方传字面量数组时也不会让 memo 失效
+    const keySig = (Array.isArray(keys) ? keys.join(',') : String(keys || '')).trim()
+
+    const filtered = useMemo(
+        () => filterRows(rows, keySig, keyword),
+        [rows, keySig, keyword],
+    )
+
+    const reset = useCallback(() => setKeyword(''), [])
+
+    return {keyword, setKeyword, filtered, reset}
+}
+
+export default useListFilter