@wangcheng051/plugin-kit 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# 更新日志
+
+版本号遵循 [语义化版本](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'`。
+
+### 校验
+
+- `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