@agile-team/wl-skills-ui 1.10.2 → 1.10.3

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to **@agile-team/wl-skills-ui** will be documented in this f
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [1.10.3] - 2026-08-16
+
+### Added
+
+- 新增 R041 按钮尺寸扫描规则：`el-button` / `ElButton` / `BaseToolbar` 无显式 `size` 时报告 warning，默认建议 `small`；不自动修改，不覆盖显式其他或动态尺寸。
+- 新增 `runtime/ag-grid-empty-state`：测量 AG Grid 真实数据区并为完整空态保留 160px；支持上下/左右分屏受控撑高、动态挂载、Resize 合并、豁免区和卸载清理。
+- 新增完整空态 Node 行为测试与浏览器视觉基准，覆盖单层/分组表头、上下双空表滚动、数据区中心误差和数据恢复清理。
+
+### Fixed
+
+- 精准修正旧新 Element Plus MessageBox 状态图标定位差异，仅命中容器直属状态图标结构。
+- `jh-input-number` 内层文本起始位恢复 11px 间距，不改右侧步进按钮、单位和对齐配置。
+- AG Grid 编辑单元格仅退出普通文本 padding；列 `align/headerAlign` 改为函数式 `cellStyle/cellClass` 桥接，合并业务已有配置并使表头与内容共轴。
+- AG Grid 空态不再相对整张 Grid 居中或依赖 `top:36px/72px` 猜表头；插图、主文案和辅助说明始终完整同规格，低高度多表格不再压盖表头。
+
 ## [1.10.2] - 2026-08-15
 
 ### Fixed

package/README.md

@@ -104,9 +104,10 @@ wl-skills-ui/
 │   │   ├── common.ts             # 通用业务预设（enable/audit/verify + 起步包）
 │   │   └── index.ts
 │   ├── auto.ts                   # Skin/老项目包级保护自动入口
-│   ├── guards.ts                 # 主题锁 + 长文本 + 分屏表格尺寸保护聚合
+│   ├── guards.ts                 # 主题锁 + 长文本 + 分屏/空态表格保护聚合
 │   ├── overflow-tooltip.ts       # 普通表格真实溢出 Tooltip 兜底
 │   ├── split-grid-resize.ts      # jh-drag-row 内 AG Grid Resize/高度链守护
+│   ├── ag-grid-empty-state.ts    # AG Grid 完整空态定位与受控撑高
 │   └── index.ts                  # 公共 API 入口
 │
 ├── scanner/                      # 自动化扫描 / 修复
@@ -115,7 +116,7 @@ wl-skills-ui/
 │   │   ├── _shared.mjs           # 公共工具 + inferMeta(layer/vendor)
 │   │   ├── table.mjs             # R001 R002 R003 R014 R039
 │   │   ├── form.mjs              # R006 R007 R008
-│   │   ├── button.mjs            # R004 R005 R015 R038
+│   │   ├── button.mjs            # R004 R005 R015 R038 R041
 │   │   ├── componentStructure.mjs # R040 复合结构登记审查
 │   │   ├── tag.mjs               # R009 R010 R012
 │   │   ├── dialog.mjs            # R011
@@ -227,7 +228,14 @@ yarn add @agile-team/wl-skills-ui
 
 ## 版本亮点
 
-当前 v1.10.2：
+当前 v1.10.3：
+
+- **复合结构精准修复**：仅在 MessageBox 容器直接含状态图标时统一图标与文字布局；`jh-input-number` 仅给内层文本 wrapper 补 11px 左间距，不改步进按钮、单位后缀和对齐语义。
+- **AG Grid 编辑与对齐闭环**：仅对已标记编辑态的单元格退出普通文本 padding；`align/headerAlign` 桥接为共享适配层可执行的函数配置，表头与内容使用同一对齐轴，并合并保留业务 `cellStyle/cellClass` 返回值。
+- **AG Grid 完整空态闭环**：按真实 `.ag-body-viewport` 定位，数据区统一保留 160px；插图、主文案和辅助说明始终完整同规格。上下/左右多表格空间不足时由最近分屏受控滚动，数据恢复后自动清理全部标记。
+- **按钮尺寸可重现**：新增 R041，只报告未显式声明 `size` 的 `el-button` / `ElButton` / `BaseToolbar`；默认建议 `small`，已设置其他或动态尺寸的业务代码不受影响。
+
+上一版 v1.10.2：
 
 - **判色纪律收紧**：单字状态词锚定（`待`/`无`/`否`/`未` 仅按词头或整词命中），「招待费」「无票运输」类业务文案不再误判；「未X」先行拦截，`未完成/未通过` 不再被子串反向误命中；不使用后行断言（旧 Safari 兼容）。
 - **工程闭环补强（零运行时开销）**：`test:coverage` 内建覆盖率报告（零依赖）；`publish.yml` Release 触发的自动发布（tag 校验 + verify 门禁）。
@@ -276,7 +284,7 @@ yarn add @agile-team/wl-skills-ui
 
 - **输入附加段不再割裂**：`el-input-group` 由组合根统一 26px 高度、6px 外圆角和 default/hover/focus/error/disabled 描边；左侧 prefix、右侧 append 图标统一 14px，纯图标附加段 32px，文字/单位/按钮仍按内容宽度。
 - **新旧 DOM 同时覆盖**：兼容 jh-ui 配套旧版 input 直挂结构和新版 `.el-input__wrapper` 结构，内部输入不再重复描边；普通 input、普通按钮、登录页和显式豁免区保持原行为。
-- **分屏表格真正重布局**：`runtime/auto` 只观察 `jh-drag-row` 内真实 AG Grid pane，补齐可收缩高度链并按帧派发局部重布局事件；AG Grid 自身 ResizeObserver 生成内部滚动条，不给外层加滚动条、不广播全局 resize、不访问 Vue 私有实例。
+- **分屏表格真正重布局**：有数据时，`runtime/auto` 只观察 `jh-drag-row` 内真实 AG Grid pane，补齐可收缩高度链并由 AG Grid 自身生成内部滚动条；只有完整空态确实放不下时，最近分屏根才临时承担一个纵向滚动条，数据恢复后撤销。
 - **回归边界闭环**：结构清单新增 input-group 新旧 DOM 与 drag-row/AG Grid 契约；Node 行为测试覆盖动态挂载、批量 Resize、豁免区，真实浏览器验证附加段计算样式及 220px→120px 收缩后的内部滚动。
 
 上一版 v1.9.12：
@@ -399,7 +407,7 @@ yarn add @agile-team/wl-skills-ui
 - `standards/architecture/01-layer-boundaries.md` 固化 tokens、Element Plus、Project Vendors、layouts、runtime、scanner、skills 的扩展边界，明确 `Base*` / `jh-*` / `C_*` / AG Grid 是当前项目集群必覆盖层
 - `vendors/jh-components` 使用 `<jh-*>` 全量通配治理，当前只维护代表性基线和专项覆盖准入，避免遗漏新增 jh 封装
 - `npm run docs:check` 校验旧命名、旧命令、版本文案和编辑器配置，防止规则文档回退
-- 表格空状态改为对应表格区域内自适应居中，避免嵌套表格靠固定高度猜效果
+- 表格空状态按真实数据区居中；AG Grid 空间不足时受控撑高，完整插图与文案保持一致
 - 查询区/工具栏按钮补齐 token fallback，禁用按钮独立保留清晰禁用态
 - 表单控件圆角统一使用 `--wk-form-control-radius`，覆盖 input/select/date/textarea/upload 等控件家族
 - `wl-ui init/update` 会安装 Skill、触发提示、MCP 配置和 manifest 清单
@@ -456,7 +464,7 @@ npx wl-ui init --mode native
 // 4. src/main.ts
 import { installCommonPreset } from "@agile-team/wl-skills-ui/runtime/common-preset";
 installCommonPreset();
-// 已包含主题锁、普通表格长文本和分屏 AG Grid 尺寸保护，无需重复引入 runtime/auto。
+// 已包含主题锁、普通表格长文本、分屏尺寸和完整空态保护，无需重复引入 runtime/auto。
 ```
 
 ```vue
@@ -785,7 +793,7 @@ export const myRules = [
 
 ## 规范清单
 
-### UI 规则（R001-R040，按 layer 自动分组）
+### UI 规则（R001-R041，按 layer 自动分组）
 
 | Rule | Layer | Vendor    | 说明                                 |
 | ---- | ----- | --------- | ------------------------------------ |
@@ -819,6 +827,7 @@ export const myRules = [
 | R038 | L1    | element   | 创建类主按钮缺 primary 填充主题色    |
 | R039 | L1    | element   | 普通数据列缺省略与悬停完整提示       |
 | R040 | L2    | common-core | 未登记复合控件结构需人工评审       |
+| R041 | L1    | element   | 按钮未显式 size，默认应使用 small   |
 
 ### 维护者防回归
 
@@ -840,7 +849,8 @@ pnpm test:visual:update
 pnpm release:check
 ```
 
-机制与准入细则见 [复合控件结构契约](docs/composite-component-contracts.md) 和
+机制与准入细则见 [复合控件结构契约](docs/composite-component-contracts.md)、
+[AG Grid 完整空状态](docs/ag-grid-empty-state.md) 和
 [浏览器视觉回归](docs/visual-regression.md)。视觉基准依赖字体、浏览器与操作系统渲染，
 必须在相同环境中比较；当前项目基准由 Windows Edge Chromium 生成。
 

package/docs/ag-grid-empty-state.md

@@ -0,0 +1,89 @@
+# AG Grid 完整空状态布局
+
+## 目标
+
+所有接入 `wl-skills-ui` 的 BaseTable/AG Grid 在无数据时始终显示同一套完整空态：
+
+- 100×84px 插图；
+- 主文案“暂无数据”；
+- 辅助说明“未找到匹配数据，请调整筛选条件后重试”；
+- 相同字号、间距和视觉中心。
+
+不会因普通单表、上下分屏、左右分屏、单层表头或分组表头而缩小插图、隐藏文案或改变
+构图。空间不足时通过受控撑高和最近布局容器滚动解决。
+
+## 根因与禁止方案
+
+AG Grid 的 no-rows overlay 在不同版本中可能覆盖整张 Grid。直接使用 `inset:0` 会把表头
+计入居中区域；固定写 `top:36px` 或分组表头 `top:72px` 又依赖表头层数和固定行高，无法
+适配动态表头、滚动设施和分屏拖动。
+
+禁止：
+
+- 在业务项目硬编码 `.ag-overlay-no-rows-wrapper { top:36px/72px }`；
+- 按高度缩小插图、隐藏辅助说明或切换成文字版；
+- 给所有 pane 永久增加 `overflow:auto`；
+- 修改 common-core 或访问 Vue 私有实例、猜测 `gridApi`。
+
+## 包内机制
+
+`runtime/ag-grid-empty-state.ts` 随 `runtime/auto` 或 `installCommonPreset()` 安装：
+
+1. 只识别当前可见的 `.ag-overlay-no-rows-wrapper`。
+2. 优先读取 `.ag-body-viewport` 的真实矩形，兼容 AG Grid 29/32；缺少 viewport 时才回退
+   `.ag-body`。
+3. 把 overlay 的 `top/height` 对齐真实数据区，不计算固定表头高度。
+4. 数据区小于 160px 时，为 grid host 添加包内最小高度标记，保证完整空态可容纳。
+5. 上下分屏保留进入空态前两个 pane 的高度基线；空间不足时仅让 `.drager_row` 承担
+   纵向滚动。
+6. 左右分屏把两个 pane 撑到同一最小高度，仅让 `.drag-col-container` 承担纵向滚动。
+7. 弹窗内独立空表由 `.el-dialog__body` 承担滚动，不突破弹窗可视边界。
+8. 数据恢复、路由卸载或手动卸载守护时，包添加的属性和 CSS 变量全部清理。
+
+运行时只写 `data-wl-ui-empty-*` 和 `--wl-ui-empty-*` 私有标记，不修改行高、列配置、
+分屏比例或有数据时的 AG Grid 内部滚动。
+
+以下区域保持原定制样式：
+
+- `.lp-root`
+- `.session-login`
+- `.wl-ui-skin-exempt`
+- `[data-wl-ui-skin="off"]`
+
+## 接入
+
+Skin 项目：
+
+```scss
+@use "@agile-team/wl-skills-ui/styles/presets/skin" as *;
+```
+
+```ts
+import "@agile-team/wl-skills-ui/runtime/auto";
+```
+
+Native 项目调用一次 `installCommonPreset()`，无需重复引入 `runtime/auto`。
+
+常规场景不需要业务代码。特殊宿主主动变更尺寸后如需立即同步，可调用：
+
+```ts
+import { refreshAgGridEmptyStateLayout } from "@agile-team/wl-skills-ui/runtime";
+
+refreshAgGridEmptyStateLayout();
+```
+
+## 升级清理
+
+升级后删除业务项目中针对 `.ag-overlay-no-rows-wrapper` 的固定 `top`、`height`、
+`transform` 和插图缩放补丁，避免形成两套定位逻辑。不要新增业务侧 `!important` 覆盖。
+
+## 验收
+
+- 单层表头和分组表头的 overlay 顶部都从真实数据区开始；
+- 数据区高度不低于 160px，插图、主文案、辅助说明均完整显示；
+- 上下双空表出现一个分屏根滚动条，两个 pane 不互相压盖；
+- 左右空表保持同高；
+- overlay 中心与数据区中心误差不超过 1px；
+- 数据恢复后无 `data-wl-ui-empty-*` 和最小高度残留；
+- 登录页和显式豁免区域无新增标记；
+- `npm test` 与 `npm run test:visual` 全部通过。

package/docs/composite-component-contracts.md

@@ -51,4 +51,5 @@ wrapper 时，应先按上述流程确认，不能直接扩大全局 Element 选
 
 input-group 附加段保留文字、单位、按钮的内容驱动宽度，只有“直接子节点为唯一
 `.el-icon`”时才使用 32px 紧凑宽度；普通 input、普通按钮和非 input-group 不命中。
-分屏重布局的运行机制与接入方式见 `docs/split-grid-resize.md`。
+分屏重布局的运行机制与接入方式见 `docs/split-grid-resize.md`；多表格无数据时的完整
+空态定位、受控撑高与滚动边界见 `docs/ag-grid-empty-state.md`。

package/docs/split-grid-resize.md

@@ -29,9 +29,14 @@
 5. 同一动画帧内的连续 Resize 会合并，并在 grid host 上派发局部
    `wl-ui:split-grid-resize` 事件，供特殊平台封装按需调用公开 grid API。
 
-本实现不会给 `.drager_top/.drager_bottom` 增加 `overflow:auto`，不会访问 Vue 私有实例，
-不会遍历或猜测 `gridApi`，也不会广播全局 `window.resize`。卸载守护时，本包增加的结构
-标记会一并清理。
+有数据时，本实现不会给 `.drager_top/.drager_bottom` 或 `.drager_row` 增加
+`overflow:auto`。唯一例外是完整空状态：当 160px 数据区在当前上下分屏中放不下时，
+`runtime/ag-grid-empty-state` 会保留两个 pane 的高度基线，并让最近的 `.drager_row`
+临时承担一个纵向滚动条；数据恢复后立即撤销。pane 自身仍不滚动。
+
+两套守护都不会访问 Vue 私有实例，不会遍历或猜测 `gridApi`，也不会广播全局
+`window.resize`。卸载时，本包增加的结构标记会一并清理。完整机制见
+`docs/ag-grid-empty-state.md`。
 
 ## 接入
 
@@ -60,7 +65,8 @@ gridHost.addEventListener("wl-ui:split-grid-resize", () => {
 
 ## 验收
 
-- 拖动前后 `.drager_top/.drager_bottom` 仍为 `overflow:hidden`。
+- 有数据时，拖动前后 `.drager_top/.drager_bottom` 仍为 `overflow:hidden`；完整空态不足
+  160px 时仅 `.drager_row` 临时纵向滚动。
 - `.ag-grid-table` 的实际高度随 pane 收缩，并带
   `data-wl-ui-split-grid-host`。
 - `.ag-body-viewport` 的 `scrollHeight > clientHeight` 时出现内部纵向滚动条。

package/docs/visual-regression.md

@@ -15,6 +15,8 @@
 - common-core 复合多标签外壳自然增高、内层无双描边。
 - input-group 输入主体、前后附加段、左右图标的统一高度/尺寸/圆角与 focus 描边。
 - jh-drag-row 收缩后 AG Grid host 跟随变高，纵向滚动只发生在内部 viewport。
+- AG Grid 单层/分组表头下的完整空态均以真实数据区居中；上下双空表空间不足时由
+  分屏根统一滚动，插图和两行文案不缩小、不隐藏。
 - Element Table 长文本真实溢出、省略号与按需完整提示。
 - 表格选中行柔和状态色、BaseToolbar 分裂按钮与定制区域豁免。
 - common-core `jh-input-number` 与普通表单控件同高，保留 `textAlign` 和 controls，且只有

package/es/auto.js

@@ -1,4 +1,4 @@
-import { installUiRuntimeGuards } from './chunk-QLPJLXY6.js';
+import { installUiRuntimeGuards } from './chunk-KR4MHMFO.js';
 import './chunk-Q3N5QNRZ.js';
 
 // runtime/auto.ts

package/es/{chunk-KCVRDXIH.js → chunk-D5EPTQY5.js}

@@ -8,21 +8,53 @@ var HEADER_ALIGNMENT_CLASS = {
   center: "wl-ui-table-header-align--center",
   right: "wl-ui-table-header-align--right"
 };
+var CELL_ALIGNMENT_CLASS = {
+  left: "wl-ui-table-cell-align--left",
+  center: "wl-ui-table-cell-align--center",
+  right: "wl-ui-table-cell-align--right"
+};
 function isColumnAlignment(value) {
   return value === "left" || value === "center" || value === "right";
 }
+function mergeCellClass(current, alignmentClass, params) {
+  const value = typeof current === "function" ? current(params) : current;
+  if (value === void 0 || value === null || value === "") {
+    return alignmentClass;
+  }
+  return Array.isArray(value) ? [...value, alignmentClass] : [value, alignmentClass];
+}
+function mergeCellStyle(current, align, params) {
+  const value = typeof current === "function" ? current(params) : current;
+  return {
+    textAlign: align,
+    ...value ?? {}
+  };
+}
 function normalizeColumnAlignment(column) {
   const normalizedChildren = Array.isArray(column.children) ? normalizeColumnAlignments(column.children) : column.children;
   const align = isColumnAlignment(column.align) ? column.align : void 0;
   const headerAlign = isColumnAlignment(column.headerAlign) ? column.headerAlign : align;
   const needsChildren = normalizedChildren !== column.children;
-  const needsCellStyle = Boolean(align) && column.cellStyle === void 0;
+  const needsCellStyle = Boolean(align);
+  const needsCellClass = Boolean(align) && column.cellStyle === void 0;
   const needsHeaderClass = Boolean(headerAlign) && column.headerClass === void 0;
-  if (!needsChildren && !needsCellStyle && !needsHeaderClass) return column;
+  if (!needsChildren && !needsCellStyle && !needsCellClass && !needsHeaderClass)
+    return column;
   return {
     ...column,
     ...needsChildren ? { children: normalizedChildren } : {},
-    ...needsCellStyle ? { cellStyle: { textAlign: align } } : {},
+    // common-core 3.x 的 AG 适配层只调用函数型 cellStyle/cellClass；函数形态同时
+    // 也是 AG Grid 原生合法配置，避免对象型样式被兼容层静默丢弃。
+    ...needsCellStyle ? {
+      cellStyle: (params) => mergeCellStyle(column.cellStyle, align, params)
+    } : {},
+    ...needsCellClass ? {
+      cellClass: (params) => mergeCellClass(
+        column.cellClass,
+        CELL_ALIGNMENT_CLASS[align],
+        params
+      )
+    } : {},
     ...needsHeaderClass ? { headerClass: HEADER_ALIGNMENT_CLASS[headerAlign] } : {}
   };
 }