iter(g184): 层级字面值归零

packages/tools/cli/lib/visual-rules.mjs

@@ -56,6 +56,11 @@ export const KIND_META = [
     label: '行高字面值',
     hint: 'line-height 写死数值，应改用 --ua-leading-*（px 行高是图形对齐技巧，不入此口径）',
   },
+  {
+    key: 'z-literal',
+    label: '层级字面值',
+    hint: 'z-index 写死数字，应改用 --ua-z-* 五档（组件内 1/2 微排序豁免）',
+  },
 ];
 
 /*** 作用：需要扫描的 CSS 属性白名单（其余属性本轮不动；用白名单顺带避开伪类选择器误判） ***/
@@ -86,6 +91,7 @@ const SCAN_PROPS = new Set([
   'height',
   'font-weight',
   'line-height',
+  'z-index',
 ]);
 
 /*** 作用：内距类属性集合（迁移与统计共用同一判定） ***/
@@ -183,6 +189,9 @@ const LEADING_TOKENS = new Map([
   ['1.65', 'var(--ua-leading-normal)'],
 ]);
 
+/*** 作用：下拉类 z-index 字面值集合（历史上下拉/气泡弹层用的 20/30/40 档，统一归 --ua-z-dropdown） ***/
+const Z_DROPDOWN_LIKE = new Set(['20', '30', '40']);
+
 /*** 作用：压缩空白，便于用稳定字符串比对（不改语义） ***/
 export function squash(value) {
   return String(value).replace(/\s+/g, ' ').trim();
@@ -208,7 +217,7 @@ export function blankComments(src) {
 
 /*** 作用：逐条产出「属性 + 值」及其在原文中的偏移；只认白名单属性且必须以分号收尾（避开伪类选择器） ***/
 export function eachDeclaration(code) {
-  const re = /(padding-top|padding-right|padding-bottom|padding-left|padding|margin-top|margin-right|margin-bottom|margin-left|margin|row-gap|column-gap|gap|font-weight|line-height|min-height|max-height|height|transition-duration|animation-duration|transition|animation|font-size|box-shadow|border-radius|outline)\s*:\s*([^;{}]*);/gi;
+  const re = /(padding-top|padding-right|padding-bottom|padding-left|padding|margin-top|margin-right|margin-bottom|margin-left|margin|row-gap|column-gap|gap|font-weight|line-height|z-index|min-height|max-height|height|transition-duration|animation-duration|transition|animation|font-size|box-shadow|border-radius|outline)\s*:\s*([^;{}]*);/gi;
   const list = [];
   for (const m of code.matchAll(re)) {
     const prop = m[1].toLowerCase();
@@ -334,6 +343,13 @@ function migrateLeading(core) {
   return { kind: 'leading-literal', value: token };
 }
 
+/*** 作用：迁移单条层级：下拉类常见字面值（20/30/40）归 dropdown 档；其余取值层级语义需按选择器人工归档，留给门禁拦截 ***/
+function migrateZ(core) {
+  const token = Z_DROPDOWN_LIKE.has(squash(core)) ? 'var(--ua-z-dropdown)' : null;
+  if (!token) return null;
+  return { kind: 'z-literal', value: token };
+}
+
 /*** 作用：判定单条声明是否需要迁移，返回 { kind, value } 或 null（幂等：已是令牌就返回 null） ***/
 export function migrateDeclaration(prop, rawValue) {
   const { core, tail } = splitImportant(rawValue);
@@ -356,6 +372,8 @@ export function migrateDeclaration(prop, rawValue) {
     result = migrateWeight(core);
   } else if (prop === 'line-height') {
     result = migrateLeading(core);
+  } else if (prop === 'z-index') {
+    result = migrateZ(core);
   }
   if (!result) return null;
   return { kind: result.kind, value: result.value + tail };
@@ -417,6 +435,12 @@ function detect(prop, rawValue, key) {
     if (/px|em|rem|%|calc/.test(value)) return 0; // px 行高是图形对齐技巧（图标 / 角标），不入此口径
     return /^\d+(\.\d+)?$/.test(value) ? 1 : 0; // unitless 数值归三档令牌
   }
+  if (key === 'z-literal') {
+    if (prop !== 'z-index') return 0;
+    if (/^var\(/.test(value)) return 0;
+    if (value === '1' || value === '2') return 0; // 组件内微排序（表头压行、水印叠层、头像悬停），不是全局层级
+    return /^\d+$/.test(value) ? 1 : 0;
+  }
   return 0;
 }