@xihan-ui/styles 2.0.0 → 3.0.0

package/css/message-feed.css

@@ -5,37 +5,11 @@
 
 /* 定义 message feed 样式。 */
 
+/* 共享关键帧由 family/motion.css 提供，本皮肤 @import 它，单独引入仍成立。 */
+@import '../family/motion.css';
 /* 独立皮肤同时传递引入回底钮的动作控件配方，full bundle 递归去重。 */
 @import '../family/action-control.css';
-
-@layer xihan.motion {
-  /* 关键帧写在本文件里：动画名的查找只认「文档里有没有这个名字」，
-     引用别处文件里的名字时那份文件不一定在场，动画会静默地整个不跑。
-     幅度与缩放走令牌，减弱动效时由令牌层归零 */
-  @keyframes xh-message-feed-item-in {
-    from {
-      opacity: 0;
-      translate: 0 var(--xh-motion-distance-md);
-    }
-
-    to {
-      opacity: 1;
-      translate: 0 0;
-    }
-  }
-
-  @keyframes xh-message-feed-button-in {
-    from {
-      opacity: 0;
-      scale: var(--xh-motion-scale-enter);
-    }
-
-    to {
-      opacity: 1;
-      scale: 1;
-    }
-  }
-}
+@import '../family/material.css';
 
 @layer xihan.components {
   /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
@@ -68,7 +42,7 @@
     overscroll-behavior: contain;
   }
 
-  /* 流式视口的内容高度一直在变，还在用原生滚动条的视口留一条空道，滚动条出现与消失时不推动文字（§6.6）。
+  /* 流式视口的内容高度一直在变，还在用原生滚动条的视口留一条空道，滚动条出现与消失时不推动文字。
      带 data-xh-scrollbar 的容器已经把原生条藏成零宽，这条空道对它没有布局作用，排除掉 */
   [data-scope='message-feed'][data-part='viewport']:not([data-xh-scrollbar]) {
     scrollbar-gutter: stable;
@@ -85,14 +59,62 @@
     display: none;
   }
 
-  /* 一条消息。默认整行铺开，左右分侧由使用者按 data-role 自己写。
-     进场只动 opacity 与 translate：改高度会扰动粘底补偿量到的 scrollHeight */
+  /* 已发送、等首个片段：列表之后一颗呼吸的圆点，行首与消息内容对齐。
+     呼吸只表达「正在进行、给不出进度」：明暗与缩放的起伏持续到首个片段到来，外扩光环同周期播 3 轮后停下。
+     连接层只在 submitted 时撤掉 hidden */
+  [data-scope='message-feed'][data-part='pending-indicator'] {
+    position: relative;
+    display: block;
+    inline-size: var(--xh-message-feed-pending-indicator-size, var(--xh-space-2));
+    block-size: var(--xh-message-feed-pending-indicator-size, var(--xh-space-2));
+    margin-block-end: var(--xh-message-feed-p, var(--xh-_message-feed-p));
+    margin-inline-start: var(--xh-message-feed-p, var(--xh-_message-feed-p));
+    border-radius: var(--xh-message-feed-pending-indicator-radius, var(--xh-shape-circle));
+    background: var(--xh-message-feed-pending-indicator-color, var(--xh-fg-muted));
+    animation: xh-breathe var(--xh-motion-loop-breathe) var(--xh-motion-ease-breathe) infinite;
+  }
+
+  [data-scope='message-feed'][data-part='pending-indicator']::after {
+    content: '';
+    position: absolute;
+    inset: 0;
+    border-radius: inherit;
+    background: inherit;
+    opacity: 0;
+    pointer-events: none;
+    animation: xh-breathe-halo var(--xh-motion-loop-breathe) var(--xh-motion-ease-breathe) 3;
+  }
+
+  /* 减弱动效：两者都停，圆点停在满不透明度，光环不出现 */
+  @media (prefers-reduced-motion: reduce) {
+    [data-scope='message-feed'][data-part='pending-indicator'],
+    [data-scope='message-feed'][data-part='pending-indicator']::after {
+      animation: none;
+    }
+  }
+
+  :where([data-motion='reduce']) [data-scope='message-feed'][data-part='pending-indicator'],
+  :where([data-motion='reduce']) [data-scope='message-feed'][data-part='pending-indicator']::after {
+    animation: none;
+  }
+
+  [data-scope='message-feed'][data-part='pending-indicator'][hidden] {
+    display: none;
+  }
+
+  /* 一条消息。默认整行铺开，左右分侧由使用者按 data-role 自己写 */
   [data-scope='message-feed'][data-part='item'] {
     display: flex;
     flex-direction: column;
     gap: var(--xh-message-feed-item-gap, var(--xh-space-1));
     border-radius: var(--xh-message-feed-item-radius, var(--xh-shape-surface));
-    animation: xh-message-feed-item-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter-strong);
+  }
+
+  /* 新到的消息进场，同一批按到达顺序错开；首帧就在的历史消息直接呈现（自己或 list 带 data-instant）。
+     进场只动 opacity 与 translate：改高度会扰动粘底补偿量到的 scrollHeight */
+  [data-scope='message-feed'][data-part='item']:not([data-instant], [data-instant] > *) {
+    animation: xh-item-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter-strong) backwards;
+    animation-delay: calc(var(--xh-_stagger-index, 0) * var(--xh-motion-stagger-step));
   }
 
   [data-scope='message-feed'][data-part='item'][hidden] {
@@ -112,29 +134,42 @@
 
   /* 回到底部：浮在滚动区右下角，收起时不卸载只隐藏。盒型、悬停 / 按下面与缩放由 Action Control 的
      floating 档给（circle 正方盒、ghost 形态：白底承载 hover 100 → pressed 200）；材质随角落浮钮族走
-     frosted 四件套（底 + 边 + 影 + 磨砂，§8），这里只把使用者槽映射到桥接槽：
+     frosted 四件套（底 + 边 + 影 + 磨砂），这里只把使用者槽映射到桥接槽：
      字形按 xs 档取 --xh-_action-profile-glyph-size（16px），与 log / back-top 同一把尺 */
   [data-scope='message-feed'][data-part='scroll-to-end-trigger'] {
-    --xh-_message-feed-scroll-to-end-trigger-shadow: var(--xh-message-feed-scroll-to-end-trigger-shadow, var(--xh-material-frosted-shadow));
+    /* 面走材质家族配方（family/material.css）：frosted 档的底、交互阶梯、描边、投影、1px 顶光与背景滤镜，
+       liquid 档由配方换成液态面；这里把使用者槽接到 Action Control 的桥接槽 */
+    --xh-action-bg-rest: var(--xh-message-feed-scroll-to-end-trigger-bg, var(--xh-_material-bg));
+    --xh-action-bg-hover: var(--xh-message-feed-scroll-to-end-trigger-bg-hover, var(--xh-_material-bg-hover));
+    --xh-action-bg-pressed: var(--xh-_material-bg-pressed);
+    --xh-action-bg-focus-visible: var(--xh-message-feed-scroll-to-end-trigger-bg, var(--xh-_material-bg-focus));
+    --xh-action-bg-disabled: var(--xh-message-feed-scroll-to-end-trigger-bg, var(--xh-_material-bg));
+    --xh-action-fg-rest: var(--xh-message-feed-scroll-to-end-trigger-fg, var(--xh-_material-fg));
+    --xh-action-fg-hover: var(--xh-message-feed-scroll-to-end-trigger-fg, var(--xh-_material-fg));
+    --xh-action-fg-pressed: var(--xh-message-feed-scroll-to-end-trigger-fg, var(--xh-_material-fg));
+    --xh-action-fg-focus-visible: var(--xh-message-feed-scroll-to-end-trigger-fg, var(--xh-_material-fg));
+    --xh-action-border-rest: var(--xh-message-feed-scroll-to-end-trigger-border, var(--xh-_material-border));
+    --xh-action-border-hover: var(--xh-message-feed-scroll-to-end-trigger-border, var(--xh-_material-border));
+    --xh-action-border-pressed: var(--xh-message-feed-scroll-to-end-trigger-border, var(--xh-_material-border));
+    --xh-action-border-focus-visible: var(--xh-message-feed-scroll-to-end-trigger-border, var(--xh-_material-border));
+    --xh-action-border-disabled: var(--xh-message-feed-scroll-to-end-trigger-border, var(--xh-_material-border));
+    --xh-action-shadow-rest: var(--xh-message-feed-scroll-to-end-trigger-shadow, var(--xh-_material-shadow));
+    --xh-action-shadow-hover: var(--xh-message-feed-scroll-to-end-trigger-shadow, var(--xh-_material-shadow));
+    --xh-action-shadow-pressed: var(--xh-message-feed-scroll-to-end-trigger-shadow, var(--xh-_material-shadow));
+    --xh-action-shadow-focus-visible: var(--xh-message-feed-scroll-to-end-trigger-shadow, var(--xh-_material-shadow));
+    --xh-action-shadow-disabled: var(--xh-message-feed-scroll-to-end-trigger-shadow, var(--xh-_material-shadow));
+    --xh-action-highlight-rest: var(--xh-_material-highlight);
+    --xh-action-highlight-hover: var(--xh-_material-highlight);
+    --xh-action-highlight-pressed: var(--xh-_material-highlight);
+    --xh-action-highlight-focus-visible: var(--xh-_material-highlight);
+    --xh-action-highlight-disabled: var(--xh-_material-highlight);
     --xh-action-visual-size: var(--xh-message-feed-scroll-to-end-trigger-size, var(--xh-_action-profile-visual-size));
     --xh-action-radius: var(--xh-message-feed-scroll-to-end-trigger-radius, var(--xh-shape-circle));
-    --xh-action-bg-rest: var(--xh-message-feed-scroll-to-end-trigger-bg, var(--xh-material-frosted-bg));
-    --xh-action-bg-hover: var(--xh-message-feed-scroll-to-end-trigger-bg-hover, var(--xh-_action-variant-bg-hover));
-    --xh-action-border-rest: var(--xh-message-feed-scroll-to-end-trigger-border, var(--xh-material-frosted-border));
-    --xh-action-border-hover: var(--xh-message-feed-scroll-to-end-trigger-border, var(--xh-material-frosted-border));
-    --xh-action-border-pressed: var(--xh-message-feed-scroll-to-end-trigger-border, var(--xh-material-frosted-border));
-    --xh-action-border-focus-visible: var(--xh-message-feed-scroll-to-end-trigger-border, var(--xh-material-frosted-border));
-    --xh-action-shadow-rest: var(--xh-_message-feed-scroll-to-end-trigger-shadow);
-    --xh-action-shadow-hover: var(--xh-_message-feed-scroll-to-end-trigger-shadow);
-    --xh-action-shadow-pressed: var(--xh-_message-feed-scroll-to-end-trigger-shadow);
-    --xh-action-fg-rest: var(--xh-message-feed-scroll-to-end-trigger-fg, var(--xh-material-frosted-fg));
     --xh-icon-size: var(--xh-message-feed-icon-size, var(--xh-_action-profile-glyph-size));
 
     position: absolute;
     inset-block-end: var(--xh-message-feed-scroll-to-end-trigger-inset, var(--xh-space-4));
     inset-inline-end: var(--xh-message-feed-scroll-to-end-trigger-inset, var(--xh-space-4));
-    -webkit-backdrop-filter: var(--xh-material-frosted-backdrop);
-    backdrop-filter: var(--xh-material-frosted-backdrop);
   }
 
   /* 连接层收起按钮时写 hidden 属性，家族那条 display 会盖掉 UA 规则，这里补回 */
@@ -142,13 +177,20 @@
     display: none;
   }
 
-  /* 收起不卸载，冒出来时靠这条进场动画；不写 display，可见性归上面那条 [hidden] 管 */
+  /* 收起不卸载：离底时冒出来播进场，回底时先播完退场、连接层才写 hidden 藏起。
+     不写 display，可见性归上面那条 [hidden] 管；退场途中不再接指针 */
   [data-scope='message-feed'][data-part='scroll-to-end-trigger'][data-state='visible'] {
-    animation: xh-message-feed-button-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter-strong);
+    animation: xh-pop-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter-strong);
+  }
+
+  [data-scope='message-feed'][data-part='scroll-to-end-trigger'][data-state='hidden']:not([hidden]) {
+    pointer-events: none;
+    animation: xh-pop-out var(--xh-motion-duration-exit) var(--xh-motion-ease-exit) forwards;
   }
 
-  /* 没写内容就由皮肤画一枚向下的字形；作者往按钮里塞了自己的图形，这条规则即不命中 */
-  [data-scope='message-feed'][data-part='scroll-to-end-trigger']:empty::before {
+  /* 没写内容（或只放了未读数角标）就由皮肤画一枚向下的字形；作者往按钮里塞了自己的图形，这条规则即不命中 */
+  [data-scope='message-feed'][data-part='scroll-to-end-trigger']:empty::before,
+  [data-scope='message-feed'][data-part='scroll-to-end-trigger']:has(> [data-part='unread-count']:only-child)::before {
     content: '';
     display: inline-block;
     inline-size: var(--xh-icon-size, var(--xh-glyph-size-sm));
@@ -188,10 +230,89 @@
     white-space: nowrap;
   }
 
+  /* 消息之间的分隔（按日期分组）：一行次级标注居中，两侧各一道内部分隔线 */
+  [data-scope='message-feed'][data-part='separator'] {
+    display: flex;
+    align-items: center;
+    gap: var(--xh-message-feed-separator-gap, var(--xh-space-3));
+    color: var(--xh-message-feed-separator-fg, var(--xh-fg-subtle));
+    font-size: var(--xh-message-feed-separator-font-size, var(--xh-text-caption-size));
+  }
+
+  [data-scope='message-feed'][data-part='separator']::before,
+  [data-scope='message-feed'][data-part='separator']::after {
+    flex: 1;
+    border-block-start: var(--xh-stroke-thin) solid var(--xh-message-feed-separator-line, var(--xh-border-subtle));
+    content: '';
+  }
+
+  [data-scope='message-feed'][data-part='separator'][hidden] {
+    display: none;
+  }
+
+  /* 回到底部上的未读数：状态 chip，钉在按钮行尾上角外侧，不改按钮盒 */
+  [data-scope='message-feed'][data-part='unread-count'] {
+    position: absolute;
+    inset-block-start: calc(-1 * var(--xh-space-1));
+    inset-inline-end: calc(-1 * var(--xh-space-1));
+    box-sizing: border-box;
+    min-inline-size: var(--xh-message-feed-unread-count-size, var(--xh-space-4));
+    block-size: var(--xh-message-feed-unread-count-size, var(--xh-space-4));
+    padding-inline: var(--xh-message-feed-unread-count-px, var(--xh-space-1));
+    border-radius: var(--xh-message-feed-unread-count-radius, var(--xh-shape-pill));
+    background: var(--xh-message-feed-unread-count-bg, var(--xh-bg-brand));
+    color: var(--xh-message-feed-unread-count-fg, var(--xh-fg-on-brand));
+    font-size: var(--xh-message-feed-unread-count-font-size, var(--xh-text-caption-size));
+    font-variant-numeric: tabular-nums;
+    line-height: var(--xh-message-feed-unread-count-size, var(--xh-space-4));
+    text-align: center;
+    pointer-events: none;
+  }
+
+  [data-scope='message-feed'][data-part='unread-count'][hidden] {
+    display: none;
+  }
+
   @media print {
-    /* 打印：回到底部这颗钮只有在能滚的地方才成立，落到纸上是一颗按不动的按钮。 */
-    [data-scope='message-feed'][data-part='scroll-to-end-trigger'] {
+    /* 打印：回到底部这颗钮只有在能滚的地方才成立，落到纸上是一颗按不动的按钮；
+       等首个片段的呼吸点是一瞬间的状态，纸上没有「正在进行」。 */
+    [data-scope='message-feed'][data-part='scroll-to-end-trigger'],
+    [data-scope='message-feed'][data-part='pending-indicator'] {
       display: none;
     }
   }
+
+  /* 强制色：底色会被系统背景吃掉，圆点改用系统前景色 */
+  @media (forced-colors: active) {
+    [data-scope='message-feed'][data-part='pending-indicator'] {
+      background: CanvasText;
+    }
+
+    [data-scope='message-feed'][data-part='unread-count'] {
+      background: Highlight;
+      color: HighlightText;
+    }
+  }
+
+  @media (forced-colors: active) {
+    /* 兜底字形是 mask 挖出来的一块底色，这一档里底色被系统换成 Canvas，字形跟着消失。
+       字形退出强制换色、直接写系统色（不能取 currentColor：退出强制换色的伪元素读到的是被系统换掉之前的作者色）：
+       按钮面上取 ButtonText，悬停与按下时家族把按钮涂成 Highlight、字形换 HighlightText；
+       禁用取 GrayText */
+    [data-scope='message-feed'][data-part='scroll-to-end-trigger']:empty::before,
+    [data-scope='message-feed'][data-part='scroll-to-end-trigger']:has(> [data-part='unread-count']:only-child)::before {
+      forced-color-adjust: none;
+      background-color: ButtonText;
+    }
+
+    [data-scope='message-feed'][data-part='scroll-to-end-trigger']:not([data-disabled]):not([data-loading]):is(:hover, :active, [data-pressed]):empty::before,
+    [data-scope='message-feed'][data-part='scroll-to-end-trigger']:not([data-disabled]):not([data-loading]):is(:hover, :active, [data-pressed]):has(> [data-part='unread-count']:only-child)::before {
+      background-color: HighlightText;
+    }
+
+    [data-scope='message-feed'][data-part='scroll-to-end-trigger'][data-disabled]:empty::before,
+    [data-scope='message-feed'][data-part='scroll-to-end-trigger'][data-disabled]:has(> [data-part='unread-count']:only-child)::before {
+      background-color: GrayText;
+    }
+  }
 }

package/css/navigation-menu.css

@@ -23,7 +23,7 @@
        换档不必给每个部件各写一条选择器。面板与共享外壳都是 root 的后代，一并继承。
        trigger 的字号经家族桥接槽接回 root 这一档，不另立私有槽 */
     /* 入口里的方向标记按档取尺，缺省 md，随 data-size 换档；面板里链接内的字形由家族随
-       data-xh-collection-size 下发（§6.5） */
+       data-xh-collection-size 下发 */
     --xh-icon-size: var(--xh-navigation-menu-icon-size, var(--xh-glyph-size-md));
 
     --xh-_navigation-menu-font-size: var(--xh-control-font-md);
@@ -34,7 +34,7 @@
     --xh-_navigation-menu-link-px: var(--xh-control-px-md);
     --xh-_navigation-menu-link-font-size: var(--xh-control-font-md);
 
-    /* 悬停、键盘锚点与展开着的入口同走中性灰轻档、不接语气槽：打开中不是选中，不用品牌色（§7.3） */
+    /* 悬停、键盘锚点与展开着的入口同走中性灰轻档、不接语气槽：打开中不是选中，不用品牌色 */
     --xh-_navigation-menu-highlight-bg: var(--xh-bg-subtle);
 
     /* 语气只落在指示条上；没写 data-tone 时 --xh-_tone 没被声明，退回品牌色。
@@ -111,7 +111,7 @@
   /* 入口归 Collection Item 展开路径 / 打开中（nav 语境）：几何、字号、面与字重全经家族桥接槽。静息 muted /
      regular，悬停走白底承载 hover 100 + default 字；展开着的那一张由连接层投影 data-in-path，家族给与悬停同档的
      中性面——打开中不是选中，不用品牌色、不加粗（横排的栏加粗会推挤相邻触发器），哪一张开着由指示条与转向的
-     箭头说明；按下 pressed 200 只换面不缩放（§9.2）；禁用走 aria-disabled，家族给禁用字色与 not-allowed。
+     箭头说明；按下 pressed 200 只换面不缩放；禁用走 aria-disabled，家族给禁用字色与 not-allowed。
      高度由 block-size 定，块向内边距归零。本条 (0,2,0) 压过家族基础块 (0,1,0)，不能再写 background / color /
      font-weight / cursor；也不写 font: inherit（reset.css 已抹平按钮 UA 字体，再写会把家族给的字号字重一并盖掉） */
   [data-scope='navigation-menu'][data-part='trigger'] {
@@ -144,7 +144,9 @@
     flex: 1;
   }
 
-  /* 面板贴着自己那一项落位：横排从 trigger 底下长出来 */
+  /* 面板贴着自己那一项落位：横排从 trigger 底下长出来。面板型浮层按内容的自然宽度排开：
+     它绝对定位在入口那一项（一个窄 li）里，收缩适配的可用宽就是那一项的宽，不给宽度只剩最小宽、
+     一行放得下的文字也折行；超过浮层最大宽才折 */
   [data-scope='navigation-menu'][data-part='content'] {
     position: absolute;
     z-index: var(--xh-navigation-menu-layer, var(--xh-_layer, var(--xh-layer-popover)));
@@ -153,7 +155,9 @@
     display: flex;
     flex-direction: column;
     gap: var(--xh-navigation-menu-content-gap, var(--xh-space-1));
+    inline-size: max-content;
     min-inline-size: var(--xh-navigation-menu-content-min-w, var(--xh-overlay-menu-min-w));
+    max-inline-size: var(--xh-navigation-menu-content-max-w, var(--xh-overlay-max-w-xl));
     padding: var(--xh-navigation-menu-content-p, var(--xh-surface-pad-xs));
     border: var(--xh-stroke-thin) solid var(--xh-navigation-menu-content-border, var(--xh-border-default));
     border-radius: var(--xh-navigation-menu-content-radius, var(--xh-shape-overlay));
@@ -172,14 +176,14 @@
     inset-inline-start: calc(100% + var(--xh-navigation-menu-content-offset, var(--xh-space-1)));
   }
 
-  /* 在场那一档才提前备好合成层：属性随 data-state 一起消失，收起后不长期占着 */
-  [data-scope='navigation-menu'][data-part='content'][data-state='open'] {
-    will-change: opacity, scale;
+  /* 首开弹出、末收收回；在两张之间换张时两侧都带 data-instant，瞬时换张——与菜单栏同一条成规，
+     交叉的进退场读起来就是闪烁。挂载时就展开着的那一项同样带它，直接呈现 */
+  [data-scope='navigation-menu'][data-part='content'][data-state='open']:not([data-instant]) {
     animation: xh-pop-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter-strong);
   }
 
   /* 退场：收起那一帧 hidden 由退场闸门押后，这里才播得出来 */
-  [data-scope='navigation-menu'][data-part='content'][data-state='closed'] {
+  [data-scope='navigation-menu'][data-part='content'][data-state='closed']:not([data-instant]) {
     animation: xh-pop-out var(--xh-motion-duration-exit) var(--xh-motion-ease-exit) forwards;
   }
 
@@ -193,9 +197,19 @@
     box-shadow: none;
   }
 
+  /* 外壳里的面板不自己弹出：弹出与收回归外壳，面板只随之淡入淡出，时长与外壳同档——
+     末收时面板的淡出与外壳的收回同时播完，外壳等它播完才藏起 */
+  [data-scope='navigation-menu'][data-part='viewport'] [data-scope='navigation-menu'][data-part='content'][data-state='open']:not([data-instant]) {
+    animation: xh-fade-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
+  }
+
+  [data-scope='navigation-menu'][data-part='viewport'] [data-scope='navigation-menu'][data-part='content'][data-state='closed']:not([data-instant]) {
+    animation: xh-fade-out var(--xh-motion-duration-exit) var(--xh-motion-ease-exit) forwards;
+  }
+
   /* 面板里的链接归 Collection Item 导航当前（nav 语境）：悬停 / 键盘高亮（白底承载 100）与按下（200）面由家族
      按 :hover / :focus-visible / :active 给出，指向当前页面的那一条（data-current）取 strong 档品牌字色 +
-     medium 字重（§7.3），字色不随语气、不加下划线（下划线是"可点"的信号，它已经在这儿了）；这里只把公开槽
+     medium 字重，字色不随语气、不加下划线（下划线是"可点"的信号，它已经在这儿了）；这里只把公开槽
      映射到桥接槽。面板是实色 floating 面，常态字色取 --xh-fg-default 而非 nav 缺省的 muted。
      布局保持 flex：链接是一行文字，不用家族网格。position: relative 是当前链接静态线的定位参照 */
   [data-scope='navigation-menu'][data-part='link'] {
@@ -223,6 +237,68 @@
     display: none;
   }
 
+  /* 面板里一枝子级的开关与链接同一种行，读链接那一组槽，两种行才等高、左缘才齐。
+     展开不换面、不算打开中：由转向的箭头与露出的子级说明；按下只换面不缩放 */
+  [data-scope='navigation-menu'][data-part='branch-trigger'] {
+    --xh-collection-block-padding: var(--xh-navigation-menu-link-py, var(--xh-_navigation-menu-link-py));
+    --xh-collection-inline-padding: var(--xh-navigation-menu-link-px, var(--xh-_navigation-menu-link-px));
+    --xh-collection-radius: var(--xh-navigation-menu-link-radius, var(--xh-shape-control));
+    --xh-collection-font-size: var(--xh-navigation-menu-link-font-size, var(--xh-_navigation-menu-link-font-size));
+    --xh-collection-fg-rest: var(--xh-navigation-menu-link-fg, var(--xh-fg-default));
+    --xh-collection-fg-hover: var(--xh-navigation-menu-link-fg, var(--xh-fg-default));
+    --xh-collection-fg-keyboard-highlight: var(--xh-navigation-menu-link-fg, var(--xh-fg-default));
+    --xh-collection-fg-pressed: var(--xh-navigation-menu-link-fg, var(--xh-fg-default));
+    --xh-collection-bg-hover: var(--xh-navigation-menu-link-bg-hover, var(--xh-_navigation-menu-highlight-bg));
+    --xh-collection-bg-keyboard-highlight: var(--xh-navigation-menu-link-bg-hover, var(--xh-_navigation-menu-highlight-bg));
+    --xh-collection-bg-pressed: var(--xh-navigation-menu-link-bg-pressed, var(--xh-bg-subtle-hover));
+
+    display: flex;
+    align-items: center;
+    gap: var(--xh-navigation-menu-branch-trigger-gap, var(--xh-_navigation-menu-trigger-gap));
+    border: 0;
+    text-align: start;
+  }
+
+  /* 行尾的展开方向标记，与 SideNav / Tree 的分支箭头同一种：盒按指示符档定尺，兜底字形与作者的图标读盒的尺。
+     收着时指向行尾（旋转角乘书写方向的符号，rtl 转半圈），展开时转向下方 */
+  [data-scope='navigation-menu'][data-part='branch-indicator'] {
+    --xh-icon-size: var(--xh-navigation-menu-branch-indicator-size, var(--xh-control-indicator-size));
+
+    margin-inline-start: auto;
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    justify-content: center;
+    inline-size: var(--xh-navigation-menu-branch-indicator-size, var(--xh-control-indicator-size));
+    block-size: var(--xh-navigation-menu-branch-indicator-size, var(--xh-control-indicator-size));
+    rotate: calc(90deg - 90deg * var(--xh-direction-sign));
+    transition: rotate var(--xh-motion-duration-nudge) var(--xh-motion-ease-enter-strong);
+  }
+
+  [data-scope='navigation-menu'][data-part='branch-indicator'][data-state='open'] {
+    rotate: 90deg;
+  }
+
+  /* 没写内容就由皮肤画兜底字形；作者往部件里塞了自己的图形，这条规则即不命中 */
+  [data-scope='navigation-menu'][data-part='branch-indicator']:empty::before {
+    content: '';
+    display: inline-block;
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    vertical-align: var(--xh-glyph-baseline-shift);
+    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;
+  }
+
+  /* 子级紧跟在开关之后，靠缩进表出层级、行距同面板；密集披露，不动高度、刻意瞬时 */
+  [data-scope='navigation-menu'][data-part='branch-content'] {
+    display: flex;
+    flex-direction: column;
+    gap: var(--xh-navigation-menu-content-gap, var(--xh-space-1));
+    padding-inline-start: var(--xh-navigation-menu-branch-content-indent, var(--xh-space-4));
+  }
+
   /* 入口里表示"底下还有一张面板"的标记，排在入口文字之后，展开时转向 */
   [data-scope='navigation-menu'][data-part='trigger-indicator'] {
     display: inline-flex;
@@ -230,7 +306,7 @@
     align-items: center;
     justify-content: center;
     line-height: var(--xh-leading-none);
-    transition: rotate var(--xh-motion-duration-micro) var(--xh-motion-ease-enter-strong);
+    transition: rotate var(--xh-motion-duration-nudge) var(--xh-motion-ease-enter-strong);
   }
 
   [data-scope='navigation-menu'][data-part='trigger-indicator'][hidden] {
@@ -257,7 +333,7 @@
     color: var(--xh-fg-disabled);
   }
 
-  /* 指向当前页面的链接自画一条静态指示线（§7.3 导航当前页）：与 Tabs line / Anchor 同一取法，作者不必为了
+  /* 指向当前页面的链接自画一条静态指示线（导航当前页）：与 Tabs line / Anchor 同一取法，作者不必为了
      这条线多放一个部件。下面的 indicator 部件表达的是「哪张面板开着」而不是当前页，所以这条线不随部件收起，
      两者各说各的：部件亮着时开着的入口下有一条、当前页链接上另有一条。
      线画在当前链接的 ::after 上，以链接盒为定位参照（上面已给 position: relative），
@@ -285,21 +361,37 @@
     block-size: var(--xh-navigation-menu-indicator-thickness, var(--xh-stroke-thick));
   }
 
-  /* 主轴上的位置与长度由连接层写成内联样式（它量得到，样式表量不到）；
-     这里只管交叉轴的贴边与粗细，以及长什么样。它指的是开着的面板：无面板开着时隐藏，
+  /* 展开入口的四个几何量由机器量好、连接层写成私有槽 --xh-_navigation-menu-indicator-x / -y / -w / -h
+     （它量得到，样式表量不到）；这里按排布取主轴那两支，落点交给 translate（只走合成），
+     另管交叉轴的贴边与粗细，以及长什么样。它指的是开着的面板：无面板开着时隐藏，
      当前页由上面链接自画的静态线表达 */
   [data-scope='navigation-menu'][data-part='indicator'] {
+    /* 还没量到时的落点，量到即被机器写的私有槽盖过 */
+    --xh-_navigation-menu-indicator-x: 0;
+    --xh-_navigation-menu-indicator-y: 0;
+    --xh-_navigation-menu-indicator-w: 0;
+    --xh-_navigation-menu-indicator-h: 0;
+    --xh-_navigation-menu-indicator-stretch: 0;
+
     position: absolute;
     display: block;
     /* 指示条也是列表项，宿主给 li 的外边距会把绝对定位的它推离入口 */
     margin: 0;
+    inset-inline-start: 0;
     inset-block-end: calc(var(--xh-navigation-menu-indicator-thickness, var(--xh-stroke-thick)) * -1);
+    inline-size: var(--xh-_navigation-menu-indicator-w);
     block-size: var(--xh-navigation-menu-indicator-thickness, var(--xh-stroke-thick));
     border-radius: var(--xh-navigation-menu-indicator-radius, var(--xh-shape-pill));
     background: var(--xh-navigation-menu-indicator-color, var(--xh-_navigation-menu-accent));
+    translate: var(--xh-_navigation-menu-indicator-x) 0;
     transition:
-      inset-inline-start var(--xh-motion-duration-enter) var(--xh-motion-ease-continuous),
-      inline-size var(--xh-motion-duration-enter) var(--xh-motion-ease-continuous);
+      translate var(--xh-motion-duration-move) var(--xh-motion-ease-continuous),
+      inline-size var(--xh-motion-duration-move) var(--xh-motion-ease-continuous);
+  }
+
+  /* translate 只认物理方向：RTL 下行首在右边，起始缘量出的距离往左推 */
+  [data-scope='navigation-menu'][data-part='indicator']:dir(rtl) {
+    translate: calc(-1 * var(--xh-_navigation-menu-indicator-x)) 0;
   }
 
   [data-scope='navigation-menu'][data-part='indicator'][hidden] {
@@ -308,13 +400,35 @@
 
   /* 竖排：指示条改贴在起始缘，交叉轴换成内联轴 */
   [data-scope='navigation-menu'][data-part='indicator'][data-orientation='vertical'] {
+    inset-block-start: 0;
     inset-block-end: auto;
     inset-inline-start: 0;
     inline-size: var(--xh-navigation-menu-indicator-thickness, var(--xh-stroke-thick));
-    block-size: auto;
+    block-size: var(--xh-_navigation-menu-indicator-h);
+    translate: 0 var(--xh-_navigation-menu-indicator-y);
     transition:
-      inset-block-start var(--xh-motion-duration-enter) var(--xh-motion-ease-continuous),
-      block-size var(--xh-motion-duration-enter) var(--xh-motion-ease-continuous);
+      translate var(--xh-motion-duration-move) var(--xh-motion-ease-continuous),
+      block-size var(--xh-motion-duration-move) var(--xh-motion-ease-continuous);
+  }
+
+  /* 首次落位与同一项的重量（窗口缩放、换上正式字体）直接到位，只有换项才滑：连接层在这一落点投影
+     data-instant。写在排布那几条之后，同一特异性按先后压过它们单写的过渡 */
+  [data-scope='navigation-menu'][data-part='indicator'][data-instant] {
+    transition: none;
+  }
+
+  /* 液态档：两沿由弹簧逐帧推着走（连接层每一帧写好盒子），几何量不再补过渡；
+     被拉长时在另一个方向上压扁（横排缺省压块向，竖排压行向），表达体积守恒，拉长到目标的两倍时压到 --xh-motion-scale-squash */
+  :where([data-material='liquid']) [data-scope='navigation-menu'][data-part='indicator'] {
+    --xh-_navigation-menu-indicator-squash: max(var(--xh-motion-scale-squash), calc(1 - var(--xh-_navigation-menu-indicator-stretch) * (1 - var(--xh-motion-scale-squash))));
+
+    scale: 1 var(--xh-_navigation-menu-indicator-squash);
+    transition: none;
+  }
+
+  :where([data-material='liquid']) [data-scope='navigation-menu'][data-part='indicator'][data-orientation='vertical'] {
+    scale: var(--xh-_navigation-menu-indicator-squash) 1;
+    transition: none;
   }
 
   /* 共享面板外壳：只管落位与统一的面板外观，里面装哪一份内容归 content。
@@ -326,6 +440,9 @@
     inset-block-start: calc(100% + var(--xh-navigation-menu-content-offset, var(--xh-space-1)));
     inset-inline-start: 0;
     display: block;
+    /* 外壳同样按装进来的那一张的自然宽度排开，道理同 content */
+    inline-size: max-content;
+    max-inline-size: var(--xh-navigation-menu-content-max-w, var(--xh-overlay-max-w-xl));
     padding: var(--xh-navigation-menu-viewport-p, var(--xh-space-2));
     border: var(--xh-stroke-thin) solid var(--xh-navigation-menu-content-border, var(--xh-border-default));
     border-radius: var(--xh-navigation-menu-content-radius, var(--xh-shape-overlay));
@@ -337,12 +454,29 @@
     display: none;
   }
 
+  /* 共享外壳是面板那一面：首开弹出、末收收回，换张时外壳留在原处、高度即刻换成新的一张。
+     挂载时就展开着的那一段（data-instant）属于首帧，直接呈现 */
+  [data-scope='navigation-menu'][data-part='viewport'][data-state='open']:not([data-instant]) {
+    animation: xh-pop-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter-strong);
+  }
+
+  [data-scope='navigation-menu'][data-part='viewport'][data-state='closed'] {
+    animation: xh-pop-out var(--xh-motion-duration-exit) var(--xh-motion-ease-exit) forwards;
+  }
+
   /* 竖排导航：共享外壳跟着面板改从侧边长出来 */
   [data-scope='navigation-menu'][data-part='viewport'][data-orientation='vertical'] {
     inset-block-start: 0;
     inset-inline-start: calc(100% + var(--xh-navigation-menu-content-offset, var(--xh-space-1)));
   }
 
+  /* 声明过 display 就盖掉了 UA 的 [hidden]{display:none}，兜底排在这几个部件所有 display 声明之后 */
+  [data-scope='navigation-menu'][data-part='branch-trigger'][hidden],
+  [data-scope='navigation-menu'][data-part='branch-indicator'][hidden],
+  [data-scope='navigation-menu'][data-part='branch-content'][hidden] {
+    display: none;
+  }
+
   @media (forced-colors: active) {
     /* 两条指示线画的都是一块纯底色，这一档里底色被统一换成 Canvas，线整根消失：
        开着的入口只剩转向的箭头、当前页只剩字重。换成系统高亮色画回来 */
@@ -350,5 +484,30 @@
     [data-scope='navigation-menu'][data-part='link'][data-current]::after {
       background: Highlight;
     }
+
+    /* 顶层入口与子级开关的箭头都是 mask 挖出来的一块底色，这一档里底色换成 Canvas、箭头跟着消失，
+       开合只剩读屏听得到。直接写系统前景（不能取 currentColor：退出强制色的伪元素读到的是被系统换掉之前的作者色）：
+       子级开关取按钮前景 ButtonText，顶层入口落在条目面上取 CanvasText；
+       两者都是集合条目，按下与没被高亮时的悬停，家族把条目涂成 Highlight，箭头跟着换 HighlightText；
+       禁用的取 GrayText，与公共补救层给禁用行的字色一致 */
+    [data-scope='navigation-menu'][data-part='branch-indicator']:empty::before {
+      background-color: ButtonText;
+      forced-color-adjust: none;
+    }
+
+    [data-scope='navigation-menu'][data-part='trigger-indicator']:empty::before {
+      background-color: CanvasText;
+      forced-color-adjust: none;
+    }
+
+    [data-scope='navigation-menu'][data-part='branch-trigger']:not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error]):is(:active, [data-pressed], :hover:not(:focus-visible, [data-highlighted])) [data-scope='navigation-menu'][data-part='branch-indicator']:empty::before,
+    [data-scope='navigation-menu'][data-part='trigger']:not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error]):is(:active, [data-pressed], :hover:not(:focus-visible, [data-highlighted])) [data-scope='navigation-menu'][data-part='trigger-indicator']:empty::before {
+      background-color: HighlightText;
+    }
+
+    [data-scope='navigation-menu'][data-part='branch-trigger'][data-disabled] [data-scope='navigation-menu'][data-part='branch-indicator']:empty::before,
+    [data-scope='navigation-menu'][data-part='trigger']:is([aria-disabled='true'], [data-disabled]) [data-scope='navigation-menu'][data-part='trigger-indicator']:empty::before {
+      background-color: GrayText;
+    }
   }
 }