@xihan-ui/styles 1.0.0-alpha.2 → 1.0.0

package/css/masonry.css

@@ -0,0 +1,63 @@
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='masonry'] {
+    --xh-masonry-skin: 1;
+  }
+
+  [data-scope='masonry'][data-part='root'] {
+    display: flex;
+    /* 各列按自己的内容收高，不被最高的那列拉平——列不等高正是瀑布流的样子 */
+    align-items: flex-start;
+    gap: var(--xh-_masonry-gap);
+
+    /* 列间距与列内的项间距共用这一份取值，声明在根上、由列继承下去；
+       不写 gap 档位就不留间距。使用者槽位排在档位之前，写死一个值即盖过所有档 */
+    --xh-_masonry-gap: var(--xh-masonry-gap, var(--xh-space-0));
+  }
+
+  /* 声明了 display 就盖掉了 UA 的 [hidden] 规则，这里还回去 */
+  [data-scope='masonry'][data-part='root'][hidden] {
+    display: none;
+  }
+
+  [data-scope='masonry'][data-part='column'] {
+    display: flex;
+    flex-direction: column;
+    /* 各列等宽；下限写 0 而不是 auto，一段长内容才不会把自己那列撑宽 */
+    flex: 1 1 0;
+    min-inline-size: 0;
+    gap: var(--xh-_masonry-gap);
+  }
+
+  /* 当前档位用不上的那几列由适配器收起；这条兜住作者自己写 hidden 的情形 */
+  [data-scope='masonry'][data-part='column'][hidden] {
+    display: none;
+  }
+
+  /* 项不发话，高度由内容定；只兜住一件事——不被列的弹性压缩，压缩了量到的高度就不是它真实的高度 */
+  [data-scope='masonry'][data-part='item'] {
+    flex: none;
+  }
+
+  /* —— 间距档位 —— */
+  /* 每一档指向一个间距令牌，列之间与列内项之间吃同一份间距 */
+  [data-scope='masonry'][data-part='root'][data-gap='xs'] {
+    --xh-_masonry-gap: var(--xh-masonry-gap, var(--xh-layout-gap-xs));
+  }
+
+  [data-scope='masonry'][data-part='root'][data-gap='sm'] {
+    --xh-_masonry-gap: var(--xh-masonry-gap, var(--xh-layout-gap-sm));
+  }
+
+  [data-scope='masonry'][data-part='root'][data-gap='md'] {
+    --xh-_masonry-gap: var(--xh-masonry-gap, var(--xh-layout-gap-md));
+  }
+
+  [data-scope='masonry'][data-part='root'][data-gap='lg'] {
+    --xh-_masonry-gap: var(--xh-masonry-gap, var(--xh-layout-gap-lg));
+  }
+
+  [data-scope='masonry'][data-part='root'][data-gap='xl'] {
+    --xh-_masonry-gap: var(--xh-masonry-gap, var(--xh-layout-gap-xl));
+  }
+}

package/css/mention.css

@@ -1,13 +1,26 @@
 @layer xihan.motion {
   /* 动画名的查找只认「文档里有没有这个名字」：引用别处文件里的名字，那份文件不一定在场，
      动画会静默地整个不跑。每份皮肤都能单独引入，所以它用到的关键帧都写在自己身上。 */
-  @keyframes xh-fade-in {
+  @keyframes xh-pop-in {
     from {
       opacity: 0;
+      scale: var(--xh-motion-scale-enter);
     }
 
     to {
       opacity: 1;
+      scale: 1;
+    }
+  }
+  @keyframes xh-pop-out {
+    from {
+      opacity: 1;
+      scale: 1;
+    }
+
+    to {
+      opacity: 0;
+      scale: var(--xh-motion-scale-enter);
     }
   }
 }
@@ -18,13 +31,36 @@
     --xh-mention-skin: 1;
   }
 
-  [data-scope='mention'][data-part='root'] {
-    /* 尺寸档只换这四个私有槽，输入框与候选都从 root 继承它们，换档不必给每个部件各写一条选择器。
-       浮层在 positioner 里、也是 root 的后代，一并继承 */
+  /* 坐标由定位引擎写进 style（inset-inline-start / inset-block-start），这里只定位模式与层级 */
+  [data-scope='mention'][data-part='positioner'] {
+    /* 落定那一侧的可用高度，由定位引擎经内联自定义属性写进来，内容层继承它限高；
+       引擎没算（尚未落位 / 无引擎）时不额外限高 */
+    --xh-_mention-available-h: 100vh;
+
+    /* 候选列表的自绘条浮在内容之上：轨道不上底色，实色轨道会在列表右缘糊一条竖灰带 */
+    --xh-scrollbar-track-bg: transparent;
+
+    position: fixed;
+    z-index: var(--xh-mention-layer, var(--xh-layer-popover));
+    /* 空壳不吃指针，交互只发生在 content 上 */
+    pointer-events: none;
+  }
+
+  /* 输入框被滚出可视区：整个浮层随之收起 */
+  [data-scope='mention'][data-part='positioner'][data-hidden] {
+    visibility: hidden;
+  }
+
+  /* 私有槽同时声明在根与 positioner 上：浮层被搬到 portal 落点，不是根的后代，继承不过去 */
+  [data-scope='mention']:is([data-part='root'], [data-part='positioner']) {
+    /* 尺寸档只换这五个私有槽，输入框与候选都从这两处继承它们，换档不必给每个部件各写一条选择器 */
+    --xh-_mention-h: var(--xh-control-h-md);
     --xh-_mention-px: var(--xh-control-px-md);
+    --xh-_mention-item-py: var(--xh-list-option-py-md);
+    --xh-_mention-item-px: var(--xh-control-px-md);
     --xh-_mention-py: var(--xh-field-py);
     --xh-_mention-gap: var(--xh-control-gap-md);
-    --xh-_mention-font-size: var(--xh-text-body-size);
+    --xh-_mention-font-size: var(--xh-control-font-md);
 
     /* 形态档只换这三个槽：缺省即 outline（描边 + 画布底） */
     --xh-_mention-input-bg: var(--xh-bg-canvas);
@@ -33,7 +69,9 @@
 
     /* 聚焦环恒用固定环色，不随语气走 */
     --xh-_mention-ring: var(--xh-ring-focus);
+  }
 
+  [data-scope='mention'][data-part='root'] {
     display: block;
   }
 
@@ -44,37 +82,43 @@
 
   /* —— 尺寸 —— */
   /* 缺省档写在上面的基础规则里 */
-  [data-scope='mention'][data-part='root'][data-size='sm'] {
+  [data-scope='mention']:is([data-part='root'], [data-part='positioner'])[data-size='sm'] {
+    --xh-_mention-h: var(--xh-control-h-sm);
     --xh-_mention-px: var(--xh-control-px-sm);
+    --xh-_mention-item-py: var(--xh-list-option-py-sm);
+    --xh-_mention-item-px: var(--xh-control-px-sm);
     --xh-_mention-py: var(--xh-space-1);
     --xh-_mention-gap: var(--xh-control-gap-sm);
-    --xh-_mention-font-size: var(--xh-font-size-sm);
+    --xh-_mention-font-size: var(--xh-control-font-sm);
   }
 
-  [data-scope='mention'][data-part='root'][data-size='lg'] {
+  [data-scope='mention']:is([data-part='root'], [data-part='positioner'])[data-size='lg'] {
+    --xh-_mention-h: var(--xh-control-h-lg);
     --xh-_mention-px: var(--xh-control-px-lg);
+    --xh-_mention-item-py: var(--xh-list-option-py-lg);
+    --xh-_mention-item-px: var(--xh-control-px-lg);
     --xh-_mention-py: var(--xh-space-3);
     --xh-_mention-gap: var(--xh-control-gap-lg);
-    --xh-_mention-font-size: var(--xh-font-size-lg);
+    --xh-_mention-font-size: var(--xh-control-font-lg);
   }
 
   /* —— 形态 —— */
   /* 输入类不做 solid：实心底压着可编辑的正文，读起来像块不可点的色板。
      形态只决定描边与底色怎么用，用哪族颜色由 data-tone 决定 */
-  [data-scope='mention'][data-part='root'][data-variant='outline'] {
+  [data-scope='mention']:is([data-part='root'], [data-part='positioner'])[data-variant='outline'] {
     --xh-_mention-input-bg: var(--xh-bg-canvas);
     --xh-_mention-input-border: var(--xh-border-control);
     --xh-_mention-input-border-hover: var(--xh-border-control-hover);
   }
 
   /* 填充式：底色顶替描边，悬停时才浮出一道淡边 */
-  [data-scope='mention'][data-part='root'][data-variant='subtle'] {
+  [data-scope='mention']:is([data-part='root'], [data-part='positioner'])[data-variant='subtle'] {
     --xh-_mention-input-bg: var(--xh-_tone-subtle, var(--xh-bg-subtle));
     --xh-_mention-input-border: transparent;
     --xh-_mention-input-border-hover: var(--xh-_tone-border, var(--xh-border-control-hover));
   }
 
-  [data-scope='mention'][data-part='root'][data-variant='ghost'] {
+  [data-scope='mention']:is([data-part='root'], [data-part='positioner'])[data-variant='ghost'] {
     --xh-_mention-input-bg: transparent;
     --xh-_mention-input-border: transparent;
     --xh-_mention-input-border-hover: var(--xh-_tone-border, var(--xh-border-control-hover));
@@ -85,6 +129,9 @@
   [data-scope='mention'][data-part='input'] {
     display: block;
     inline-size: 100%;
+    min-inline-size: var(--xh-mention-input-min-w, var(--xh-control-min-w));
+    /* 缺省宿主是 textarea：高度按行数撑，控件档只兜住底线 */
+    min-block-size: var(--xh-mention-input-h, var(--xh-_mention-h));
     padding-block: var(--xh-mention-input-py, var(--xh-_mention-py));
     padding-inline: var(--xh-mention-input-px, var(--xh-_mention-px));
     border: var(--xh-stroke-thin) solid var(--xh-mention-input-border, var(--xh-_mention-input-border));
@@ -100,6 +147,13 @@
     transition: border-color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
   }
 
+  /* 单行宿主定高到控件档，纵向内距归零，与并排的其他控件等高。
+     单行与多行在 DOM 上只差一个标签名，没有别的标记可选，所以按标签名分支 */
+  input[data-scope='mention'][data-part='input'] {
+    block-size: var(--xh-mention-input-h, var(--xh-_mention-h));
+    padding-block: 0;
+  }
+
   [data-scope='mention'][data-part='input'][hidden] {
     display: none;
   }
@@ -108,16 +162,28 @@
     color: var(--xh-mention-placeholder-fg, var(--xh-fg-subtle));
   }
 
-  [data-scope='mention'][data-part='input']:hover:not(:disabled) {
+  [data-scope='mention'][data-part='input']:hover:not(:disabled, [data-invalid]) {
     border-color: var(--xh-mention-input-border-hover, var(--xh-_mention-input-border-hover));
   }
 
   [data-scope='mention'][data-part='input']:focus-visible {
-    border-color: var(--xh-mention-input-border-focus, var(--xh-_mention-ring));
+    border-color: var(--xh-mention-input-border-focus, var(--xh-_tone, var(--xh-border-control-focus)));
     outline: var(--xh-ring-width) solid var(--xh-_mention-ring);
     outline-offset: var(--xh-ring-offset);
   }
 
+  [data-scope='mention'][data-part='input'][data-invalid] {
+    border-color: var(--xh-mention-input-border-invalid, var(--xh-border-invalid));
+
+    /* 校验失败时环也跟着变红：两圈等宽相邻却一红一蓝，读的人不知道哪个才是当前状态 */
+    --xh-_mention-ring: var(--xh-ring-invalid);
+  }
+
+  /* 只读仍可聚焦、可复制，所以不置灰，只把底色压下去表示"改不动" */
+  [data-scope='mention'][data-part='input'][readonly] {
+    background: var(--xh-mention-input-bg-readonly, var(--xh-bg-subtle));
+  }
+
   /* 输入框是单体表单控件，禁用走原生 disabled（候选那边一律 aria-disabled） */
   [data-scope='mention'][data-part='input']:disabled {
     background: var(--xh-mention-input-bg-disabled, var(--xh-bg-subtle));
@@ -127,40 +193,29 @@
     cursor: not-allowed;
   }
 
-  /* 坐标由定位引擎写进 style（inset-inline-start / inset-block-start），这里只定位模式与层级 */
-  [data-scope='mention'][data-part='positioner'] {
-    position: fixed;
-    z-index: var(--xh-layer-popover);
-    /* 空壳不吃指针，交互只发生在 content 上 */
-    pointer-events: none;
-  }
-
-  /* 输入框被滚出可视区：整个浮层随之收起 */
-  [data-scope='mention'][data-part='positioner'][data-hidden] {
-    visibility: hidden;
-  }
-
   [data-scope='mention'][data-part='content'] {
     display: flex;
     flex-direction: column;
+    gap: var(--xh-mention-content-gap, var(--xh-list-option-gap));
     min-inline-size: var(--xh-mention-content-min-w, var(--xh-overlay-min-w));
     max-inline-size: var(--xh-mention-content-max-w, var(--xh-overlay-max-w));
-    max-block-size: var(--xh-mention-content-max-h, var(--xh-overlay-max-h));
+    max-block-size: min(var(--xh-mention-content-max-h, var(--xh-overlay-max-h)), var(--xh-_mention-available-h));
     padding-block: var(--xh-mention-content-py, var(--xh-space-1));
     padding-inline: var(--xh-mention-content-px, var(--xh-space-1));
     border: var(--xh-stroke-thin) solid var(--xh-mention-content-border, var(--xh-border-default));
     border-radius: var(--xh-mention-content-radius, var(--xh-shape-surface));
     background: var(--xh-mention-content-bg, var(--xh-bg-surface));
     color: var(--xh-mention-content-fg, var(--xh-fg-default));
-    box-shadow: var(--xh-mention-content-shadow, var(--xh-elevation-2));
+    box-shadow: var(--xh-mention-content-shadow, var(--xh-elevation-floating));
     overflow-y: auto;
     pointer-events: auto;
   }
 
-  /* display 会盖掉 hidden 属性的 UA 规则，收起态显式让位 */
-  [data-scope='mention'][data-part='content'][hidden] {
-    display: none;
-  }
+  /* 这里刻意没有 [data-part='content'][hidden] { display: none }，与 dialog 一致：
+     收起态连接层会给 content 打 hidden，而上面那条 display 正是要盖掉 UA 的
+     [hidden]{display:none}——退场动画得先能播。presence 读的是 content 的 animationName，
+     真正的收起由宿主在退场结束后落成内联 display:none（Vue 那边直接不渲染）。
+     其余声明了 display 的角色节点仍补 [hidden]，那几处没有退场动画。 */
 
   /* 宿主把候选全筛没了：浮层还开着，但这一副框壳没有内容可框，整个让位。
      组件不替宿主判空——「没有匹配项」要不要说话、说什么，是宿主的事 */
@@ -175,15 +230,21 @@
   }
 
   [data-scope='mention'][data-part='content'][data-state='open'] {
-    animation: xh-fade-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
+    animation: xh-pop-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
+  }
+
+  /* 退场：收起那一帧 hidden 由退场闸门押后，这里才播得出来。forwards 把末态钉住，
+     免得动画结束到真收起之间闪一下原样 */
+  [data-scope='mention'][data-part='content'][data-state='closed'] {
+    animation: xh-pop-out var(--xh-motion-duration-exit) var(--xh-motion-ease-exit) forwards;
   }
 
   [data-scope='mention'][data-part='item'] {
     display: flex;
     align-items: center;
     gap: var(--xh-mention-item-gap, var(--xh-_mention-gap));
-    padding-block: var(--xh-mention-item-py, var(--xh-space-1_5));
-    padding-inline: var(--xh-mention-item-px, var(--xh-control-px-md));
+    padding-block: var(--xh-mention-item-py, var(--xh-_mention-item-py));
+    padding-inline: var(--xh-mention-item-px, var(--xh-_mention-item-px));
     border-radius: var(--xh-mention-item-radius, var(--xh-shape-control));
     color: var(--xh-mention-item-fg, var(--xh-fg-default));
     font-size: var(--xh-mention-item-font-size, var(--xh-_mention-font-size));
@@ -205,6 +266,9 @@
      两套底色各画各的会出现"鼠标停在 A 上、回车却插进了 B" */
   [data-scope='mention'][data-part='item'][data-highlighted]:not([data-disabled]) {
     background: var(--xh-mention-item-bg-hover, var(--xh-bg-subtle));
+    /* 焦点恒在输入框，高亮条目自带内收环；列表是滚动容器，环画在外沿会被裁掉 */
+    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
+    outline-offset: calc(-1 * var(--xh-ring-width));
   }
 
   /* 禁用走 aria-disabled 而非原生 disabled（原生 disabled 不派 click，禁用守卫就走不到），

package/css/menu.css

@@ -1,13 +1,26 @@
 @layer xihan.motion {
   /* 动画名的查找只认「文档里有没有这个名字」：引用别处文件里的名字，那份文件不一定在场，
      动画会静默地整个不跑。每份皮肤都能单独引入，所以它用到的关键帧都写在自己身上。 */
-  @keyframes xh-fade-in {
+  @keyframes xh-pop-in {
     from {
       opacity: 0;
+      scale: var(--xh-motion-scale-enter);
     }
 
     to {
       opacity: 1;
+      scale: 1;
+    }
+  }
+  @keyframes xh-pop-out {
+    from {
+      opacity: 1;
+      scale: 1;
+    }
+
+    to {
+      opacity: 0;
+      scale: var(--xh-motion-scale-enter);
     }
   }
 }
@@ -20,8 +33,15 @@
 
   /* 坐标由定位引擎写进 style（inset-inline-start / inset-block-start），这里只定位模式与层级 */
   [data-scope='menu'][data-part='positioner'] {
+    /* 落定那一侧的可用高度，由定位引擎经内联自定义属性写进来，content 继承它限高；
+       引擎没算（尚未落位 / 无引擎）时不额外限高 */
+    --xh-_menu-available-h: 100vh;
+
+    /* 条目列表的自绘条浮在内容之上：轨道不上底色，实色轨道会在菜单右缘糊一条竖灰带 */
+    --xh-scrollbar-track-bg: transparent;
+
     position: fixed;
-    z-index: var(--xh-layer-popover);
+    z-index: var(--xh-menu-layer, var(--xh-layer-popover));
     /* 空壳不吃指针，交互只发生在 content 上 */
     pointer-events: none;
   }
@@ -31,13 +51,29 @@
     visibility: hidden;
   }
 
+  /* 触发器的长相归作者，皮肤只表达展开态。私有槽声明在它自己身上：
+     菜单没有 root 部件，触发器上头没有别的 menu 节点可以挂 */
+  [data-scope='menu'][data-part='trigger'] {
+    /* 展开着的那张菜单的触发器走品牌淡底强档，随语气换色相；没写 data-tone 时退回品牌淡底 */
+    --xh-_menu-active-bg: var(--xh-_tone-subtle, var(--xh-bg-brand-subtle));
+  }
+
+  /* 展开着的那一张是打开路径，走品牌淡底强档：哪一张开着必须一眼看得出来。
+     不加粗：加粗会推挤相邻内容 */
+  [data-scope='menu'][data-part='trigger']:not([data-disabled])[data-state='open'] {
+    background: var(--xh-menu-trigger-bg-active, var(--xh-_menu-active-bg));
+  }
+
   [data-scope='menu'][data-part='content'] {
+    /* 作者塞进条目里的图标跟着字号走，与皮肤画的兜底字形同一把尺 */
+    --xh-icon-size: var(--xh-menu-icon-size, var(--xh-glyph-size-text));
+
     /* 尺寸档只换这四个私有槽，条目从 content 继承它们，换档不必给每个部件各写一条选择器。
        菜单没有 root 部件（浮层树的最外层就是 content），三轴属性都落在这里 */
-    --xh-_menu-item-py: var(--xh-space-1_5);
+    --xh-_menu-item-py: var(--xh-list-option-py-md);
     --xh-_menu-item-px: var(--xh-control-px-md);
     --xh-_menu-item-gap: var(--xh-control-gap-md);
-    --xh-_menu-font-size: var(--xh-text-body-size);
+    --xh-_menu-font-size: var(--xh-control-font-md);
 
     /* 打开子菜单的触发条目走品牌淡底强档，随语气换色相；没写 data-tone 时退回品牌淡底。
        悬停与键盘焦点恒中性灰轻档、不接语气槽——两档同色相的话打开路径就认不出来了 */
@@ -45,22 +81,29 @@
 
     display: flex;
     flex-direction: column;
+    gap: var(--xh-menu-content-gap, var(--xh-list-option-gap));
     min-inline-size: var(--xh-menu-min-w, var(--xh-overlay-menu-min-w));
     max-inline-size: var(--xh-menu-max-w, var(--xh-overlay-max-w));
+    /* 两道上限取更小的那道：自己的高度上限，以及落定那一侧真正剩下的空间。
+       列表族的 16rem 对命令菜单偏矮，这里另给一档 */
+    max-block-size: min(var(--xh-menu-max-h, var(--xh-overlay-menu-max-h)), var(--xh-_menu-available-h));
     padding-block: var(--xh-menu-py, var(--xh-space-1));
     padding-inline: var(--xh-menu-px, var(--xh-space-1));
     border: var(--xh-stroke-thin) solid var(--xh-menu-border, var(--xh-border-default));
     border-radius: var(--xh-menu-radius, var(--xh-shape-surface));
     background: var(--xh-menu-bg, var(--xh-bg-surface));
     color: var(--xh-menu-fg, var(--xh-fg-default));
-    box-shadow: var(--xh-menu-shadow, var(--xh-elevation-2));
+    box-shadow: var(--xh-menu-shadow, var(--xh-elevation-floating));
+    /* 条目超过上限就在菜单内部滚。条目的焦点环是内收的，滚动容器裁在内边距缘上，环切不着 */
+    overflow-y: auto;
     pointer-events: auto;
   }
 
-  /* display 会盖掉 hidden 属性的 UA 规则，收起态显式让位 */
-  [data-scope='menu'][data-part='content'][hidden] {
-    display: none;
-  }
+  /* 这里刻意没有 [data-part='content'][hidden] { display: none }，与 dialog 一致：
+     收起态连接层会给 content 打 hidden，而上面那条 display 正是要盖掉 UA 的
+     [hidden]{display:none}——退场动画得先能播。presence 读的是 content 的 animationName，
+     真正的收起由宿主在退场结束后落成内联 display:none（Vue 那边直接不渲染）。
+     其余声明了 display 的角色节点仍补 [hidden]，那几处没有退场动画。 */
 
   /* 容器只是焦点域兜底落点，落焦不画环：高亮永远长在条目上 */
   [data-scope='menu'][data-part='content']:focus-visible {
@@ -68,24 +111,30 @@
   }
 
   [data-scope='menu'][data-part='content'][data-state='open'] {
-    animation: xh-fade-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
+    animation: xh-pop-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
+  }
+
+  /* 退场：收起那一帧 hidden 由退场闸门押后，这里才播得出来。forwards 把末态钉住，
+     免得动画结束到真收起之间闪一下原样 */
+  [data-scope='menu'][data-part='content'][data-state='closed'] {
+    animation: xh-pop-out var(--xh-motion-duration-exit) var(--xh-motion-ease-exit) forwards;
   }
 
   /* —— 尺寸 —— */
   /* 缺省档写在 content 的基础规则里。条目高度由 padding 撑出来：
      纵向走 space 档、行内内缩走 control-px 档（随密度轴），换档各挪一级 */
   [data-scope='menu'][data-part='content'][data-size='sm'] {
-    --xh-_menu-item-py: var(--xh-space-1);
+    --xh-_menu-item-py: var(--xh-list-option-py-sm);
     --xh-_menu-item-px: var(--xh-control-px-sm);
     --xh-_menu-item-gap: var(--xh-control-gap-sm);
-    --xh-_menu-font-size: var(--xh-font-size-sm);
+    --xh-_menu-font-size: var(--xh-control-font-sm);
   }
 
   [data-scope='menu'][data-part='content'][data-size='lg'] {
-    --xh-_menu-item-py: var(--xh-space-2);
+    --xh-_menu-item-py: var(--xh-list-option-py-lg);
     --xh-_menu-item-px: var(--xh-control-px-lg);
     --xh-_menu-item-gap: var(--xh-control-gap-lg);
-    --xh-_menu-font-size: var(--xh-font-size-lg);
+    --xh-_menu-font-size: var(--xh-control-font-lg);
   }
 
   [data-scope='menu'][data-part='item'] {
@@ -106,8 +155,8 @@
       color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
   }
 
-  /* 悬停与键盘焦点共用中性灰轻档：条目本身承载焦点，不另画描边 */
-  [data-scope='menu'][data-part='item']:not([data-disabled]):is(:hover, :focus) {
+  /* 悬停与键盘锚点共用中性灰轻档：锚点只认连接层打的 data-highlighted，不读 :focus */
+  [data-scope='menu'][data-part='item']:not([data-disabled]):is(:hover, [data-highlighted]) {
     background: var(--xh-menu-item-bg-hover, var(--xh-bg-subtle));
   }
 
@@ -118,7 +167,13 @@
     font-weight: var(--xh-menu-item-active-font-weight, var(--xh-font-weight-semibold));
   }
 
-  [data-scope='menu'][data-part='item']:focus {
+  /* 键盘落焦的条目画内收环；指针触发的聚焦不画 */
+  [data-scope='menu'][data-part='item']:focus-visible {
+    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
+    outline-offset: calc(-1 * var(--xh-ring-width));
+  }
+
+  [data-scope='menu'][data-part='item']:focus:not(:focus-visible) {
     outline: none;
   }
 
@@ -127,52 +182,74 @@
     cursor: not-allowed;
   }
 
+  /* 带子菜单的条目行尾画右向小箭头：不点开也看得出还有下一级。
+     位置靠 margin 顶到行尾，图形取兜底字形令牌 */
+  [data-scope='menu'][data-part='item'][aria-haspopup='menu']::after {
+    content: '';
+    flex: none;
+    margin-inline-start: auto;
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    background-color: currentColor;
+    -webkit-mask: var(--xh-glyph-mark-chevron-right) center / contain no-repeat;
+    mask: var(--xh-glyph-mark-chevron-right) center / contain no-repeat;
+  }
+
+  /* rtl 下子菜单开在左侧，箭头跟着指向行进方向 */
+  [dir='rtl'] [data-scope='menu'][data-part='item'][aria-haspopup='menu']::after {
+    -webkit-mask-image: var(--xh-glyph-mark-chevron-left);
+    mask-image: var(--xh-glyph-mark-chevron-left);
+  }
+
+  [data-scope='menu'][data-part='group'] {
+    display: flex;
+    flex-direction: column;
+    gap: var(--xh-menu-group-gap, var(--xh-list-option-gap));
+  }
+
+  [data-scope='menu'][data-part='group'][hidden] {
+    display: none;
+  }
+
+  /* 分组标题不是条目、进不了导航，画成小号次要文字，
+     内缩与条目对齐（同一个 padding-inline），标题与条目文字才在一条竖线上 */
+  [data-scope='menu'][data-part='group-label'] {
+    display: block;
+    padding-block: var(--xh-menu-group-label-py, var(--xh-space-1));
+    padding-inline: var(--xh-menu-group-label-px, var(--xh-_menu-item-px));
+    color: var(--xh-menu-group-label-fg, var(--xh-fg-subtle));
+    font-size: var(--xh-menu-group-label-font-size, var(--xh-text-caption-size));
+    font-weight: var(--xh-menu-group-label-font-weight, var(--xh-font-weight-medium));
+    line-height: var(--xh-leading-none);
+    user-select: none;
+  }
+
+  [data-scope='menu'][data-part='group-label'][hidden] {
+    display: none;
+  }
+
   [data-scope='menu'][data-part='separator'] {
     block-size: var(--xh-menu-separator-thickness, var(--xh-stroke-thin));
-    margin-block: var(--xh-menu-separator-my, var(--xh-space-1));
+    margin-block: var(--xh-menu-separator-my, var(--xh-space-0_5));
     background: var(--xh-menu-separator-color, var(--xh-border-default));
   }
 
-  /* 箭头是旋转 45° 的方块，只保留朝向锚点那两条边的描边；
+  /* 箭头的底色与描边色，几何在 overlay-arrow.css。
      交叉轴落点由定位引擎经内联自定义属性写进来，没给时退回居中 */
   [data-scope='menu'][data-part='arrow'] {
-    --xh-_menu-arrow-size: var(--xh-menu-arrow-size, var(--xh-overlay-arrow-size));
     --xh-_menu-arrow-x: 50%;
     --xh-_menu-arrow-y: 50%;
+    --xh-_overlay-arrow-size: var(--xh-menu-arrow-size, var(--xh-overlay-arrow-size));
+    --xh-_overlay-arrow-x: var(--xh-_menu-arrow-x);
+    --xh-_overlay-arrow-y: var(--xh-_menu-arrow-y);
 
-    position: absolute;
-    inline-size: var(--xh-_menu-arrow-size);
-    block-size: var(--xh-_menu-arrow-size);
     background: var(--xh-menu-bg, var(--xh-bg-surface));
     border: var(--xh-stroke-thin) solid var(--xh-menu-border, var(--xh-border-default));
-    rotate: 45deg;
-  }
-
-  [data-scope='menu'][data-part='arrow'][data-placement^='bottom'] {
-    inset-block-start: calc(var(--xh-_menu-arrow-size) / -2);
-    inset-inline-start: calc(var(--xh-_menu-arrow-x) - var(--xh-_menu-arrow-size) / 2);
-    border-block-end: 0;
-    border-inline-end: 0;
   }
 
-  [data-scope='menu'][data-part='arrow'][data-placement^='top'] {
-    inset-block-end: calc(var(--xh-_menu-arrow-size) / -2);
-    inset-inline-start: calc(var(--xh-_menu-arrow-x) - var(--xh-_menu-arrow-size) / 2);
-    border-block-start: 0;
-    border-inline-start: 0;
-  }
-
-  [data-scope='menu'][data-part='arrow'][data-placement^='right'] {
-    inset-inline-start: calc(var(--xh-_menu-arrow-size) / -2);
-    inset-block-start: calc(var(--xh-_menu-arrow-y) - var(--xh-_menu-arrow-size) / 2);
-    border-block-start: 0;
-    border-inline-end: 0;
-  }
-
-  [data-scope='menu'][data-part='arrow'][data-placement^='left'] {
-    inset-inline-end: calc(var(--xh-_menu-arrow-size) / -2);
-    inset-block-start: calc(var(--xh-_menu-arrow-y) - var(--xh-_menu-arrow-size) / 2);
-    border-block-end: 0;
-    border-inline-start: 0;
+  /* 声明过任何 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去。
+     写在文件末尾：兜底必须排在该部件所有 display 声明之后 */
+  [data-scope='menu'][data-part='item'][hidden] {
+    display: none;
   }
 }