@wangcheng051/plugin-kit 0.1.1 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,63 @@
+# 更新日志
+
+版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+
+## [0.2.0] - 2026-11-09
+
+本版本的核心变化：**ag-grid 完全内置并做样式隔离**。宿主项目不需要安装 `ag-grid-community` /
+`ag-grid-react`，无论它自己装的是 25、31、32 还是完全不装，插件的表格都能正常工作，
+宿主已有的 ag-grid 表格也不受插件影响。
+
+### 破坏性变更
+
+- 表格容器类名由 `ag-theme-alpine` 改为 `pk-ag-grid`；`agGridClass()` 的返回值同步改为
+  `pk-ag-grid`，不再返回主题类名。
+- `ag-grid-community`、`ag-grid-react` 从 `peerDependencies` 移入 `dependencies`，
+  宿主无需再安装，也不再受宿主版本约束。
+- 只内置 `alpine` 浅色主题，`balham` / `material` / `quartz` / `classic` 不再提供。
+  `agGridClass('balham')` 不会报错，但返回的仍是 `pk-ag-grid`。
+
+### 新增
+
+- 内置 ag-grid 31 的 JS 实现，`dist/index.js` 从 55 KB 增至 1.45 MB（gzip 17.5 KB → 342 KB）。
+- 样式作用域隔离：构建期把 ag-grid 两个样式文件的全部选择器改写为 `.pk-ag-grid ...`，
+  宿主 `.ag-theme-alpine .ag-xxx` 规则不会命中插件表格，插件规则也不会漏到宿主表格上。
+- 图标字体改名为 `pkAgGridAlpine`，避免与宿主同名 `@font-face` 互相覆盖。
+- 暗色 / 自动暗色变体映射到不存在的类名，系统处于暗色模式时不会把表格染黑。
+- 新增导出 `AG_GRID_SCOPE_CLASS`（值为 `pk-ag-grid`）。
+- `dist/style.css` 内含 ag-grid 结构样式与 alpine 主题（288 KB / gzip 37.6 KB），
+  宿主只需 `import '@wangcheng051/plugin-kit/style.css'`。
+
+### 修复
+
+- **表格行高与表头高退化为 25px**。ag-grid 31 的行高并不由 CSS 变量驱动：
+  `Environment.getTheme()` 用 `/\bag-(material|theme-[\w-]*)\b/` 扫描容器 className，
+  匹配不到 `ag-theme-*` 时 `getSassVariable()` 直接返回 `undefined`，最终回退到硬编码的
+  `DEFAULT_ROW_HEIGHT = 25`，并以内联样式写到 `.ag-row` / `.ag-header-cell` 上，CSS 覆盖无效。
+  容器类名改为 `pk-ag-grid` 后正好落在这个盲区里。
+  修复方式：`TableList` 增加 `rowHeight` / `headerHeight` 两个 props，默认 `42` / `48`
+  （与 alpine 的 `--ag-row-height: 6px * 7`、`--ag-header-height: 6px * 8` 一致），
+  直接透传给 `AgGridReact`，不再依赖主题类名识别；`reset` 中的同名配置仍可覆盖。
+
+### 校验
+
+- `scripts/verify-dist.mjs` 增加断言：ag-grid 已内联且不在 peer 中、JS 产物无 ag-grid
+  样式子路径引用、`dist/style.css` 规则全部限定在 `.pk-ag-grid` 下、图标字体已改名。
+- `scripts/smoke-render.mjs` 容器断言同步为 `pk-ag-grid`。
+
+### 迁移指南
+
+1. 卸载 `ag-grid-community` / `ag-grid-react`（保留也不影响，插件不会使用它）。
+2. 删除插件相关的 ag-grid CSS 引入；宿主**自己**的 ag-grid 表格仍按原样引自己的样式。
+3. 业务中针对插件表格写的覆盖样式，选择器由 `.ag-theme-alpine .ag-xxx` 改为
+   `.pk-ag-grid .ag-xxx`。
+4. 若首屏体积敏感，改为懒加载：`const { TableList } = await import('@wangcheng051/plugin-kit')`。
+
+## [0.1.1]
+
+- 首个发布版本。
+- `TableList`：基于 ag-grid 31 + antd 5 的表格封装，支持列配置、字典渲染、分页、
+  自定义表头 `CustomHeader`（排序 + 列显示/隐藏）。
+- 主题与工具：`agGridClass`、`AG_GRID_THEMES`、`DEFAULT_AG_GRID_THEME`、`ROW_HEIGHT_PRESETS`
+  及 `formatMoney` / `formatPercent` 等格式化函数。
+- 产物形态：ESM / CJS / UMD 三格式，`react` / `react-dom` / `antd` / `react-redux` 保持 external。

package/README.md

@@ -10,35 +10,58 @@ CRM 后台 React 插件包，基于 **React 17 + antd 5 + ag-grid 31**。
 | --- | --- | --- |
 | react / react-dom | `^17.0.2` | React 17 无 `createRoot`，需使用 `ReactDOM.render` |
 | antd | `^5.21.6` | 二次封装基于 antd 5 API |
-| ag-grid-react / ag-grid-community | `^31.0.1` | 社区版，无列工具面板 / SetFilter |
-| @ant-design/icons | `^5.5.1` | 由 antd 引入，通常已随 antd 安装 |
 | react-redux | `^7.2.4` | 可选 peer；`TableList` 表头会读 `state.controller.language` |
 
+ag-grid 31、`@ant-design/icons` 均已**打包内置**，宿主无需安装：
+
+| 内置依赖 | 说明 |
+| --- | --- |
+| ag-grid-community / ag-grid-react 31 | JS 与样式都打进产物，样式限定在 `.pk-ag-grid` 作用域 |
+| @ant-design/icons | 只用两个图标，tree-shaking 后增量很小 |
+
+> 为什么 ag-grid 可以内置而 react / antd 不行：react / antd 一旦打包两份，
+> hooks 报错、`ConfigProvider` 主题与 locale 上下文都会断，必须共用宿主实例；
+> ag-grid 是自包含的，做成自带反而能摆脱宿主的版本约束。
+
 ## 安装
 
 ```bash
 npm i @wangcheng051/plugin-kit
 ```
 
-`react` / `react-dom` / `antd` / `ag-grid-*` / `@ant-design/icons` 为 peerDependencies，
-需由宿主项目自行安装；`react-redux` 为可选 peer，使用 `TableList` 时需确保应用被 `<Provider>` 包裹。
+宿主只需要 `react` / `react-dom` / `antd`（`react-redux` 可选，使用 `TableList` 时
+需确保应用被 `<Provider>` 包裹）。宿主项目里已有的 ag-grid 无论什么版本都不影响本包。
 
 ## 使用
 
-### 引入样式（ag-grid v31 使用经典 CSS 主题）
+### 引入样式
 
 ```js
-// 本包自身的样式（CSS Modules 已编译，必须引入，否则表头/列设置弹层无样式）
+// 必须引入：本包组件样式 + 内置的 ag-grid 31 基础样式与 alpine 主题
 import '@wangcheng051/plugin-kit/style.css';
 
-// ag-grid 的样式由宿主引入
-import 'ag-grid-community/styles/ag-grid.css';
-import 'ag-grid-community/styles/ag-theme-alpine.css';
+// antd 重置样式按宿主项目原有约定引入即可
 import 'antd/dist/reset.css';
 ```
 
-> ag-grid v31 尚未提供新的 Theming API（v32+ 才有），只能通过 CSS 主题类名切换。
-> 可选主题：`alpine`（默认）、`balham`、`material`、`quartz`、`classic`。
+`dist/style.css` 已包含 `ag-grid.css` 与 `ag-theme-alpine.css`，宿主**不需要**再
+单独 import ag-grid 的样式，也不需要在页面里额外挂 `ag-theme-alpine` 类。
+
+### 与宿主 ag-grid 版本共存
+
+内置样式在构建期被改写到 `.pk-ag-grid` 作用域下，容器只挂这个类：
+
+- 宿主的 `.ag-theme-alpine .ag-xxx` 规则不会命中插件表格；
+- 插件规则也不会漏到宿主自己的 ag-grid 表格上（含 `ag-row-odd` 等覆盖样式）；
+- 图标字体改名为 `pkAgGridAlpine`，不会与宿主的 `agGridAlpine` 互相覆盖。
+
+因此宿主可以是 ag-grid 25 / 31 / 32，甚至完全不装，插件都能正常渲染。
+
+**代价**：`dist/index.js` 从 55 kB 增至约 1.4 MB（gzip 从 17 kB 增至约 340 kB），
+这是把 ag-grid 完整打进产物的必然结果。介意体积时可在业务层按需 `import()` 懒加载表格。
+
+> 只内置 alpine 浅色主题。`agGridClass('balham')` 这类调用不会报错，但返回的仍是
+> `.pk-ag-grid`，不会切换到对应主题的视觉效果。
 
 ### TableList
 
@@ -158,7 +181,7 @@ npm run publish:public:confirm
 npm 账号启用 2FA 后，`npm publish` 会直接报：
 
 ```
-npm error 403 Forbidden - PUT https://registry.npmjs.org/@crm%2fplugin-kit
+npm error 403 Forbidden - PUT https://registry.npmjs.org/@wangcheng051%2fplugin-kit
 npm error Two-factor authentication or granular access token with bypass 2fa enabled is required
 ```
 
@@ -173,6 +196,22 @@ NPM_TOKEN=npm_xxxxxxxx npm run publish:public:confirm
 NPM_OTP=123456 npm run publish:public:confirm
 ```
 
+#### 确认 token 没问题但发布仍报 403
+
+报错仍是 `Two-factor authentication or granular access token with bypass 2fa enabled is required`
+时，多半是 token 没有真正落进 npm 配置（改了环境变量、或在别处生成后没写入）。
+用这条命令写入本机 `~/.npmrc` 后重新发布：
+
+```bash
+npm config set //registry.npmjs.org/:_authToken npm_你的token
+```
+
+排查要点：
+
+- 写完后 `~/.npmrc` 的修改时间会变化，可据此确认是否生效；
+- bypass 2FA 只能在**创建 token 时**勾选，已创建的 token 改不生效，需删掉重建；
+- token 只写本机 `~/.npmrc` 或 CI 环境变量，**不要写进仓库文件**（README 会随包公开发布）。
+
 脚本已把「校验」和「上传」拆开：先用约 1~2 分钟跑完 `prepublishOnly`，再以 `--ignore-scripts` 上传，
 这样 OTP 不会在构建期间过期。凭据均通过环境变量传入，不落命令行、不打印到日志。
 
@@ -225,7 +264,8 @@ npm version major    # 0.1.0 -> 1.0.0
 npm i @wangcheng051/plugin-kit
 ```
 
-`react` / `react-dom` / `antd` / `ag-grid-*` / `@ant-design/icons` 均为 peerDependencies，需由宿主项目自行安装（`react-redux` 为可选 peer）。
+宿主只需 `react` / `react-dom` / `antd`（`react-redux` 为可选 peer）；ag-grid 31 与
+`@ant-design/icons` 已打包内置，无需安装。
 
 ### 私有源的消费方配置