@xihan-ui/styles 1.0.0 → 2.0.0

package/css/listbox.css

@@ -1,3 +1,13 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 listbox 样式。 */
+
+@import '../family/action-control.css';
+@import '../family/collection-item.css';
+
 @layer xihan.components {
   /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
   [data-scope='listbox'] {
@@ -5,9 +15,24 @@
   }
 
   [data-scope='listbox'][data-part='root'] {
-    /* 作者塞进指示符槽的图标跟着字号走，与皮肤画的兜底字形同一把尺 */
-    --xh-icon-size: var(--xh-listbox-icon-size, var(--xh-glyph-size-text));
+    /* 条目外的字形（空态 / 在途占位里作者塞的图标）按档取尺，缺省 md；条目内的字形由家族随
+       data-xh-collection-size 下发（§6.5）。列表框自绘的状态字形（前导对号所在的标记盒与盒里的勾）不读这支：
+       它们是指示符，走 --xh-control-indicator-* 一族——标记盒在自己身上把 --xh-icon-size 改接到盒的尺 */
+    --xh-icon-size: var(--xh-listbox-icon-size, var(--xh-glyph-size-md));
+    /* 定高小列表的自绘条挂在根上（§6.6）：根是条子的定位盒，轨道底色关掉才不会在列表右缘糊出一条灰带 */
+    --xh-scrollbar-track-bg: transparent;
+
+    /* 尺寸档只换这四个私有槽，条目、分组标题与空态占位都从 root 继承它们，
+       换档不必给每个部件各写一条选择器 */
+    --xh-_listbox-item-py: var(--xh-list-option-py-md);
+    --xh-_listbox-item-px: var(--xh-control-px-md);
+    --xh-_listbox-gap: var(--xh-control-gap-md);
+    --xh-_listbox-font-size: var(--xh-control-font-md);
 
+    /* 强调色随语气走，只落在勾选标记上；没写 data-tone 时退回品牌色 */
+    --xh-_listbox-accent: var(--xh-_tone, var(--xh-fg-brand));
+
+    position: relative;
     display: flex;
     flex-direction: column;
     gap: var(--xh-listbox-gap, var(--xh-space-2));
@@ -17,6 +42,43 @@
     display: none;
   }
 
+  /* —— 尺寸 —— */
+  /* 缺省档写在上面的基础规则里 */
+  [data-scope='listbox'][data-part='root'][data-size='sm'] {
+    --xh-icon-size: var(--xh-listbox-icon-size, var(--xh-glyph-size-sm));
+    --xh-_listbox-item-py: var(--xh-list-option-py-sm);
+    --xh-_listbox-item-px: var(--xh-control-px-sm);
+    --xh-_listbox-gap: var(--xh-control-gap-sm);
+    --xh-_listbox-font-size: var(--xh-control-font-sm);
+  }
+
+  [data-scope='listbox'][data-part='root'][data-size='lg'] {
+    --xh-icon-size: var(--xh-listbox-icon-size, var(--xh-glyph-size-lg));
+    --xh-_listbox-item-py: var(--xh-list-option-py-lg);
+    --xh-_listbox-item-px: var(--xh-control-px-lg);
+    --xh-_listbox-gap: var(--xh-control-gap-lg);
+    --xh-_listbox-font-size: var(--xh-control-font-lg);
+  }
+
+  /* 校验失败：整块列表框换成错误描边，与其余表单控件同一套表达 */
+  [data-scope='listbox'][data-part='content'][data-invalid] {
+    border-color: var(--xh-listbox-content-border-invalid, var(--xh-border-invalid));
+  }
+
+  /* 只读改不动选中值，但不是禁用：颜色照常，只把"可点"这个暗示收回来。
+     光标由家族按态解算，这里在各态的槽上统一收回；禁用项的 not-allowed 由家族按 aria-disabled 给，不在此列 */
+  [data-scope='listbox'][data-part='root'][data-readonly]
+    [data-scope='listbox'][data-part='item']:not([data-disabled]) {
+    --xh-collection-cursor-rest: default;
+    --xh-collection-cursor-hover: default;
+    --xh-collection-cursor-keyboard-highlight: default;
+    --xh-collection-cursor-pressed: default;
+    --xh-collection-cursor-selected: default;
+    --xh-collection-cursor-selected-hover: default;
+    --xh-collection-cursor-selected-highlight: default;
+    --xh-collection-cursor-selected-pressed: default;
+  }
+
   [data-scope='listbox'][data-part='label'] {
     color: var(--xh-listbox-label-fg, var(--xh-fg-muted));
     font-size: var(--xh-listbox-label-font-size, var(--xh-text-label-size));
@@ -24,7 +86,7 @@
     line-height: var(--xh-leading-none);
   }
 
-  /* 整组禁用会把 data-disabled 一路打到 label / content / item-group 上，各处观感保持一致 */
+  /* 整组禁用会把 data-disabled 一路打到 label / content / group 上，各处观感保持一致 */
   [data-scope='listbox'][data-part='label'][data-disabled] {
     color: var(--xh-fg-subtle);
   }
@@ -52,6 +114,18 @@
     display: none;
   }
 
+  /* 手写结构按真正的条目判断，空白文本与分组标题都不算候选。
+     只排除 content 内部的 hidden 祖先；外层浮层退场时不改变本列表的几何。
+     禁用条目仍是有效内容，不参与此处排除。 */
+  [data-scope='listbox'][data-part='content']:not(:has(
+    [data-scope='listbox'][data-part='item']:not([hidden]):not([data-scope='listbox'][data-part='content'] [hidden] *)
+  )),
+  [data-scope='listbox'][data-part='group']:not(:has(
+    [data-scope='listbox'][data-part='item']:not([hidden]):not([data-scope='listbox'][data-part='content'] [hidden] *)
+  )) {
+    display: none;
+  }
+
   /* 横向列表沿主轴排，此时高度由内容决定，再压最大高度只会白留一条滚动条 */
   [data-scope='listbox'][data-part='content'][data-orientation='horizontal'] {
     flex-direction: row;
@@ -64,27 +138,32 @@
     outline: none;
   }
 
-  [data-scope='listbox'][data-part='item-group'] {
+  [data-scope='listbox'][data-part='group'] {
     display: flex;
     flex-direction: column;
-    gap: var(--xh-listbox-item-group-gap, var(--xh-list-option-gap));
+    gap: var(--xh-listbox-group-gap, var(--xh-list-option-gap));
   }
 
-  [data-scope='listbox'][data-part='item-group'][hidden] {
+  [data-scope='listbox'][data-part='group'][hidden] {
     display: none;
   }
 
-  /* 组间留白只加在后继分组上：首组顶上已经有 content 的内边距，再加一层会显得头重 */
-  [data-scope='listbox'][data-part='item-group'] + [data-scope='listbox'][data-part='item-group'] {
-    margin-block-start: var(--xh-listbox-group-gap, var(--xh-space-1_5));
+  /* 只在两个有可见条目的分组之间留白；已收起的空组不能把首组额外向下推。 */
+  [data-scope='listbox'][data-part='group']:has(
+    [data-scope='listbox'][data-part='item']:not([hidden]):not([data-scope='listbox'][data-part='content'] [hidden] *)
+  )
+    ~ [data-scope='listbox'][data-part='group']:has(
+      [data-scope='listbox'][data-part='item']:not([hidden]):not([data-scope='listbox'][data-part='content'] [hidden] *)
+    ) {
+    margin-block-start: var(--xh-listbox-group-spacing, var(--xh-space-1_5));
   }
 
   /* 分组标题不是选项、进不了导航，画成小号次要文字，
      内缩与条目对齐（同一个 padding-inline），标题与条目文字才在一条竖线上 */
-  [data-scope='listbox'][data-part='item-group-label'] {
+  [data-scope='listbox'][data-part='group-label'] {
     display: block;
     padding-block: var(--xh-listbox-group-label-py, var(--xh-space-1));
-    padding-inline: var(--xh-listbox-group-label-px, var(--xh-control-px-md));
+    padding-inline: var(--xh-listbox-group-label-px, var(--xh-_listbox-item-px));
     color: var(--xh-listbox-group-label-fg, var(--xh-fg-subtle));
     font-size: var(--xh-listbox-group-label-font-size, var(--xh-text-caption-size));
     font-weight: var(--xh-listbox-group-label-font-weight, var(--xh-font-weight-medium));
@@ -92,93 +171,163 @@
     user-select: none;
   }
 
-  [data-scope='listbox'][data-part='item-group-label'][hidden] {
+  [data-scope='listbox'][data-part='group-label'][hidden] {
     display: none;
   }
 
-  [data-scope='listbox'][data-part='item-group-label'][data-disabled] {
+  [data-scope='listbox'][data-part='group-label'][data-disabled] {
     color: var(--xh-fg-disabled);
   }
 
-  [data-scope='listbox'][data-part='item'] {
-    display: flex;
-    align-items: center;
-    gap: var(--xh-listbox-item-gap, var(--xh-control-gap-md));
-    padding-block: var(--xh-listbox-item-py, var(--xh-space-1_5));
-    padding-inline: var(--xh-listbox-item-px, var(--xh-control-px-md));
-    border-radius: var(--xh-listbox-item-radius, var(--xh-shape-control));
-    color: var(--xh-listbox-item-fg, var(--xh-fg-default));
-    font-size: var(--xh-listbox-item-font-size, var(--xh-text-body-size));
-    /* 行高留出文字的上下伸展空间，行内那层 overflow:hidden 才不会把字削掉 */
-    line-height: var(--xh-listbox-item-leading, var(--xh-leading-normal));
-    white-space: nowrap;
-    cursor: pointer;
-    user-select: none;
-    transition:
-      background var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
-      color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  /* 空态占位：待在 root 里、content 的兄弟（列表框只许拥有 option 与 group）。
+     它只画作者提供的居中文字；零候选的 content 自身收起，不再留下空描边或留白。 */
+  [data-scope='listbox'][data-part='empty'] {
+    display: block;
+    padding-block: var(--xh-listbox-empty-py, var(--xh-space-3));
+    padding-inline: var(--xh-listbox-empty-px, var(--xh-_listbox-item-px));
+    color: var(--xh-listbox-empty-fg, var(--xh-fg-subtle));
+    font-size: var(--xh-listbox-empty-font-size, var(--xh-_listbox-font-size));
+    line-height: var(--xh-leading-none);
+    text-align: center;
   }
 
-  /* 条目可以按需收起（过滤掉的选项），有 display 就得补这条 */
-  [data-scope='listbox'][data-part='item'][hidden] {
+  /* 上面给了 display，UA 的 [hidden]{display:none} 已被盖掉，这里补回来 */
+  [data-scope='listbox'][data-part='empty'][hidden] {
+    display: none;
+  }
+
+  [data-scope='listbox'][data-part='empty'][data-disabled] {
+    color: var(--xh-fg-disabled);
+  }
+
+  /* 在途占位：与空态占位同一个位置、同一副观感，两者不同屏 */
+  [data-scope='listbox'][data-part='loading'] {
+    display: block;
+    padding-block: var(--xh-listbox-loading-py, var(--xh-space-3));
+    padding-inline: var(--xh-listbox-loading-px, var(--xh-_listbox-item-px));
+    color: var(--xh-listbox-loading-fg, var(--xh-fg-subtle));
+    font-size: var(--xh-listbox-loading-font-size, var(--xh-_listbox-font-size));
+    line-height: var(--xh-leading-none);
+    text-align: center;
+  }
+
+  [data-scope='listbox'][data-part='loading'][hidden] {
     display: none;
   }
 
-  /* 悬停与键盘锚点共用中性灰轻档：data-highlighted 跟的是连接层记的焦点条目，
-     与选中互相独立 */
-  [data-scope='listbox'][data-part='item']:not([data-disabled]):is(:hover, [data-highlighted]) {
-    background: var(--xh-listbox-item-bg-hover, var(--xh-bg-subtle));
+  /* 取下一页的按钮：铺满一行摆在列表尾——铺满一行的独立动作条目，接 Action Control 的 row 档、
+     ghost 形态（§9.2）：宽度由容器给、高度随内容、按下只换面不缩放；盒几何、悬停 / 按下 / 禁用面、
+     焦点环与粗指针热区全由家族给，白底承载 hover 100 → pressed 200。
+     这里只把使用者槽映射到桥接槽并把文案居中：它是一行里唯一的东西，靠起始缘会像一条没对齐的条目 */
+  [data-scope='listbox'][data-part='load-more-trigger'] {
+    --xh-action-gap: var(--xh-listbox-load-more-trigger-gap, var(--xh-_listbox-gap));
+    --xh-action-padding-block: var(--xh-listbox-load-more-trigger-py, var(--xh-_listbox-item-py));
+    --xh-action-padding-inline: var(--xh-listbox-load-more-trigger-px, var(--xh-_listbox-item-px));
+    --xh-action-radius: var(--xh-listbox-load-more-trigger-radius, var(--xh-shape-control));
+    --xh-action-bg-hover: var(--xh-listbox-load-more-trigger-bg-hover, var(--xh-_action-variant-bg-hover));
+    --xh-action-fg-rest: var(--xh-listbox-load-more-trigger-fg, var(--xh-_tone-fg, var(--xh-fg-brand-strong)));
+    --xh-action-fg-hover: var(--xh-listbox-load-more-trigger-fg, var(--xh-_tone-fg, var(--xh-fg-brand-strong)));
+    --xh-action-fg-pressed: var(--xh-listbox-load-more-trigger-fg, var(--xh-_tone-fg, var(--xh-fg-brand-strong)));
+    --xh-action-font-size: var(--xh-listbox-load-more-trigger-font-size, var(--xh-_listbox-font-size));
+
+    justify-content: center;
+    text-align: center;
+    /* row 档允许换行、高度随内容，折行的文案走正文行高（§6.4） */
+    line-height: var(--xh-leading-normal);
   }
 
-  /* 选中只换文字色与字重，配合行尾的 ✓ 标记；底色整条通道留给高亮，
-     两者因此能同时看见 */
-  [data-scope='listbox'][data-part='item'][data-state='checked'] {
-    color: var(--xh-listbox-item-fg-selected, var(--xh-fg-brand-strong));
-    font-weight: var(--xh-listbox-item-font-weight-selected, var(--xh-font-weight-medium));
+  [data-scope='listbox'][data-part='load-more-trigger'][hidden] {
+    display: none;
   }
 
-  /* 键盘落焦的条目画内收环；指针触发的聚焦不画 */
-  [data-scope='listbox'][data-part='item']:focus-visible {
-    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
-    outline-offset: calc(-1 * var(--xh-ring-width));
+  /* 条目走 Collection Item 的 page 语境（页内持久集合，§7.3）：网格、尺寸档、悬停 / 高亮 / 按下面
+     （白底承载 hover 100 → pressed 200）与选中面（品牌淡底 + 淡底前景 + 前导对号，selected+hover 20% /
+     +pressed 28%）都由家族按 aria-selected / aria-disabled 给出；禁用面（字色降级、not-allowed、不换面）
+     也归家族。这里只把公开槽映射到桥接槽，不复制任何状态选择器。
+     page 集合坐在 surface 白底上，前景走 fg-default 而不是浮层的 frosted 前景 */
+  [data-scope='listbox'][data-part='item'] {
+    --xh-collection-block-padding: var(--xh-listbox-item-py, var(--xh-_listbox-item-py));
+    --xh-collection-inline-padding: var(--xh-listbox-item-px, var(--xh-_listbox-item-px));
+    --xh-collection-gap: var(--xh-listbox-item-gap, var(--xh-_listbox-gap));
+    --xh-collection-font-size: var(--xh-listbox-item-font-size, var(--xh-_listbox-font-size));
+    --xh-collection-radius: var(--xh-listbox-item-radius, var(--xh-shape-control));
+    /* 作者的图标尺槽经桥接槽下发到条目，家族缺省按 data-xh-collection-size 取档 */
+    --xh-collection-glyph-size: var(--xh-listbox-icon-size, var(--xh-_collection-glyph-size));
+    --xh-collection-fg-rest: var(--xh-listbox-item-fg, var(--xh-fg-default));
+    --xh-collection-fg-hover: var(--xh-listbox-item-fg, var(--xh-fg-default));
+    --xh-collection-fg-keyboard-highlight: var(--xh-listbox-item-fg, var(--xh-fg-default));
+    --xh-collection-fg-pressed: var(--xh-listbox-item-fg, var(--xh-fg-default));
+    --xh-collection-fg-selected: var(--xh-listbox-item-fg-selected, var(--xh-fg-on-brand-subtle));
+    --xh-collection-fg-selected-hover: var(--xh-listbox-item-fg-selected, var(--xh-fg-on-brand-subtle));
+    --xh-collection-fg-selected-highlight: var(--xh-listbox-item-fg-selected, var(--xh-fg-on-brand-subtle));
+    --xh-collection-fg-selected-pressed: var(--xh-listbox-item-fg-selected, var(--xh-fg-on-brand-subtle));
+    --xh-collection-font-weight-selected: var(--xh-listbox-item-font-weight-selected, var(--xh-font-weight-regular));
+    --xh-collection-font-weight-selected-hover: var(--xh-listbox-item-font-weight-selected, var(--xh-font-weight-regular));
+    --xh-collection-font-weight-selected-highlight: var(--xh-listbox-item-font-weight-selected, var(--xh-font-weight-regular));
+    --xh-collection-font-weight-selected-pressed: var(--xh-listbox-item-font-weight-selected, var(--xh-font-weight-regular));
+    --xh-collection-bg-hover: var(--xh-listbox-item-bg-hover, var(--xh-bg-subtle));
+    --xh-collection-bg-keyboard-highlight: var(--xh-listbox-item-bg-hover, var(--xh-bg-subtle));
+    --xh-collection-bg-pressed: var(--xh-listbox-item-bg-pressed, var(--xh-bg-subtle-hover));
+    --xh-collection-bg-selected: var(--xh-listbox-item-bg-selected, var(--xh-bg-brand-subtle));
+    /* data-highlighted 跟的是连接层记的焦点条目（指针点选也会落焦）：只换面，焦点环在 :focus-visible 下再接回 */
+    --xh-collection-outline-keyboard-highlight: transparent;
+    --xh-collection-outline-selected-highlight: transparent;
+    /* 对号随语气走：没写 data-tone 时退回品牌色；槽按本部件取名（item-check-fg），标记部件的旧槽留在兜底位 */
+    --xh-collection-indicator-fg-rest: var(--xh-listbox-item-check-fg, var(--xh-listbox-item-indicator-fg, var(--xh-_listbox-accent)));
+    --xh-collection-indicator-fg-checked: var(--xh-listbox-item-check-fg, var(--xh-listbox-item-indicator-fg, var(--xh-_listbox-accent)));
+    --xh-collection-indicator-fg-selected: var(--xh-listbox-item-check-fg, var(--xh-listbox-item-indicator-fg, var(--xh-_listbox-accent)));
+    --xh-collection-indicator-fg-selected-hover: var(--xh-listbox-item-check-fg, var(--xh-listbox-item-indicator-fg, var(--xh-_listbox-accent)));
+    --xh-collection-indicator-fg-selected-highlight: var(--xh-listbox-item-check-fg, var(--xh-listbox-item-indicator-fg, var(--xh-_listbox-accent)));
+    --xh-collection-indicator-fg-selected-pressed: var(--xh-listbox-item-check-fg, var(--xh-listbox-item-indicator-fg, var(--xh-_listbox-accent)));
+
+    /* 行高留出文字的上下伸展空间，行内那层 overflow:hidden 才不会把字削掉 */
+    line-height: var(--xh-listbox-item-leading, var(--xh-leading-normal));
+    white-space: nowrap;
+    user-select: none;
   }
 
-  [data-scope='listbox'][data-part='item']:focus:not(:focus-visible) {
-    outline: none;
+  /* 家族给了 display，UA 的 [hidden]{display:none} 已被盖掉：条目可以按需收起（过滤掉的选项） */
+  [data-scope='listbox'][data-part='item'][hidden] {
+    display: none;
   }
 
-  /* 禁用走 aria-disabled 而非原生 disabled：条目仍要可聚焦（它还得当方向键的起点），
-     所以只能靠 data-disabled 表达，写 :disabled 永远不命中 */
-  [data-scope='listbox'][data-part='item'][data-disabled] {
-    color: var(--xh-fg-disabled);
-    cursor: not-allowed;
+  /* 键盘焦点出现时环才接回并立即到位，不压在背景过渡的中间帧上 */
+  [data-scope='listbox'][data-part='item']:focus-visible:not(:hover) {
+    --xh-collection-outline-keyboard-highlight: var(--xh-ring-focus);
+    --xh-collection-outline-selected-highlight: var(--xh-ring-focus);
+
+    transition: none;
   }
 
   [data-scope='listbox'][data-part='item-text'] {
-    flex: 1;
-    /* 弹性子项默认最小尺寸是内容尺寸，不归零则长文本把行撑破、省略号轮不上 */
+    /* 网格子项默认最小尺寸是内容尺寸，不归零则长文本把行撑破、省略号轮不上 */
     min-inline-size: 0;
     overflow: hidden;
     white-space: nowrap;
     text-overflow: ellipsis;
   }
 
-  /* 勾选标记只在选中项上出现；未选中时占位不塌，切换选中不引起行宽抖动 */
+  /* 勾选标记落在家族网格的 indicator 列（page 语境下前置为前导对号）；显隐与颜色由家族按选中态给，
+     未选中时占位不塌，切换选中不引起行宽抖动。
+     盒与盒里的勾是指示符（§6.5）：盒按指示符档取尺，并在自己身上把 --xh-icon-size 改接到盒的尺，皮肤画的
+     兜底勾与作者塞进盒里的 XhIcon 读同一把尺、与盒同边长（前导对号不是勾选格，不取 × 0.75，与 Menu 族同口径）；
+     不读家族按档下发到行的 --xh-icon-size——那支只管作者放进条目里的图标，按图标档取的 20px 比 16 / 14 的指示符档大一圈 */
   [data-scope='listbox'][data-part='item-indicator'] {
+    --xh-icon-size: var(--xh-listbox-item-indicator-size, var(--xh-control-indicator-size));
+
     display: inline-flex;
-    flex: none;
     align-items: center;
     justify-content: center;
     inline-size: var(--xh-listbox-item-indicator-size, var(--xh-control-indicator-size));
-    color: var(--xh-listbox-item-indicator-fg, var(--xh-fg-brand));
-    visibility: hidden;
+    block-size: var(--xh-listbox-item-indicator-size, var(--xh-control-indicator-size));
   }
 
   [data-scope='listbox'][data-part='item-indicator'][hidden] {
     display: none;
   }
 
-  /* 没写内容就由皮肤画勾；作者往部件里塞了自己的图形，这条规则即不命中 */
+  /* 没写内容就由皮肤画勾；作者往部件里塞了自己的图形，这条规则即不命中。
+     尺寸读标记盒自己改接过的 --xh-icon-size：与盒同边长，随指示符档换档（见上面标记盒那块） */
   [data-scope='listbox'][data-part='item-indicator']:empty::before {
     content: '';
     display: inline-block;
@@ -189,12 +338,4 @@
     -webkit-mask: var(--xh-glyph-mark-check) center / contain no-repeat;
     mask: var(--xh-glyph-mark-check) center / contain no-repeat;
   }
-
-  [data-scope='listbox'][data-part='item-indicator'][data-state='checked'] {
-    visibility: visible;
-  }
-
-  [data-scope='listbox'][data-part='item-indicator'][data-disabled] {
-    color: var(--xh-fg-disabled);
-  }
 }

package/css/loading-bar.css

@@ -1,3 +1,10 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 loading bar 样式。 */
+
 @layer xihan.components {
   /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
   [data-scope='loading-bar'] {
@@ -14,7 +21,9 @@
    */
   [data-scope='loading-bar'][data-part='root'] {
     position: fixed;
-    inset-block-start: 0;
+    /* 顶到视口上沿的那一条：刘海或状态栏压住的那一段由系统给出，不让位就整条藏在下面。
+       桌面上 env() 恒为 0，条子照旧贴着上沿。 */
+    inset-block-start: env(safe-area-inset-top);
     inset-inline: 0;
     z-index: var(--xh-loading-bar-layer, var(--xh-layer-sticky));
 
@@ -49,7 +58,7 @@
 
   /*
    * 进度段。宽度那条轴（inline-size）由连接层写进内联样式，这里绝不重复写。
-   * 背景色同理：给了 color 就走内联，盖过下面这条。
+   * 背景色不走内联：要别的颜色改 --xh-loading-bar-range 这个槽，或者换语气。
    *
    * 语气取装饰档 --xh-_tone-soft：那一档压在画布上够 3:1，细带才看得出来。
    * 槽位由 root 上的 data-tone 声明，继承下来。
@@ -58,7 +67,40 @@
   [data-scope='loading-bar'][data-part='range'] {
     block-size: 100%;
     background: var(--xh-loading-bar-range, var(--xh-_tone-soft, var(--xh-bg-brand)));
-    transition: inline-size var(--xh-loading-bar-speed, var(--xh-motion-duration-enter)) var(--xh-motion-ease-enter);
+    transition: inline-size var(--xh-loading-bar-speed, var(--xh-motion-duration-enter)) var(--xh-motion-ease-continuous);
+  }
+
+  /* 渲染了亮边才把进度段变成定位面：亮边贴在它的末端 */
+  [data-scope='loading-bar'][data-part='range']:has([data-part='peg']) {
+    position: relative;
+  }
+
+  /*
+   * 进度段末端那道亮边。它把「条子在往前走」这件事画出来：只有一条渐宽的色带时，
+   * 200ms 一跳的推进读起来像卡顿。
+   * 颜色接进度段自己的那一支，宽度与厚度各留一个槽。
+   */
+  [data-scope='loading-bar'][data-part='peg'] {
+    position: absolute;
+    inset-block: 0;
+    inset-inline-end: 0;
+    inline-size: var(--xh-loading-bar-peg-w, var(--xh-space-8));
+    /* 两端渐隐、中间最亮：亮斑对称，文字方向翻过来也不必再配一次 */
+    background: linear-gradient(
+      90deg,
+      transparent,
+      var(--xh-loading-bar-peg-fg, var(--xh-loading-bar-range, var(--xh-_tone-soft, var(--xh-bg-brand)))),
+      transparent
+    );
+  }
+
+  /* 条子还没起步时亮边一起收着：0% 宽的进度段末端不该先亮出一道边 */
+  [data-scope='loading-bar'][data-part='peg'][data-state='idle'] {
+    opacity: 0;
+  }
+
+  [data-scope='loading-bar'][data-part='peg'][hidden] {
+    display: none;
   }
 
   /* 减少动效：宽度与淡出都立刻到位。进度本身照常推进，只是不再有过渡的过程——
@@ -75,4 +117,11 @@
   :where([data-motion='reduce']) [data-scope='loading-bar'][data-part='range'] {
     transition: none;
   }
+
+  @media print {
+    /* 打印：加载进度条画的是「正在等」，落到纸上是一条没有含义的色带。 */
+    [data-scope='loading-bar'][data-part='root'] {
+      display: none;
+    }
+  }
 }

package/css/log.css

@@ -1,3 +1,30 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 log 样式。 */
+
+/* 独立皮肤同时传递引入回底钮的动作控件配方；full bundle 递归去重。 */
+@import '../family/action-control.css';
+
+@layer xihan.motion {
+  /* 关键帧写在本文件里：动画名的查找只认「文档里有没有这个名字」，
+     引用别处文件里的名字时那份文件不一定在场，动画会静默地整个不跑。
+     幅度与缩放走令牌，减弱动效时由令牌层归零 */
+  @keyframes xh-log-button-in {
+    from {
+      opacity: 0;
+      scale: var(--xh-motion-scale-enter);
+    }
+
+    to {
+      opacity: 1;
+      scale: 1;
+    }
+  }
+}
+
 @layer xihan.components {
   /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
   [data-scope='log'] {
@@ -9,13 +36,22 @@
   [data-scope='log'][data-part='root'] {
     --xh-_log-line-h: var(--xh-log-line-height, 1.25rem);
 
+    /* 尺寸缺省档：不写 data-size 时的取值。三档只改这两个私有槽，
+       公开槽留在读处当首选，作者在祖先上设的覆盖才赢得过档位声明。
+       行高不在档内：视口按 rows 定高读的是同一个基准，三档同值才对得上整数行 */
+    --xh-_log-font-size: var(--xh-text-secondary-size);
+    --xh-_log-content-px: var(--xh-space-3);
+
+    /* 一张静态内容面：--xh-border-default 描边 + surface 底 + 无影（§5.3 描边与淡底互斥），
+       与 code-view / diff-view / json-viewer 同走 solid */
     position: relative;
     display: flex;
     flex-direction: column;
     overflow: hidden;
     border: var(--xh-stroke-thin) solid var(--xh-log-border, var(--xh-border-default));
     border-radius: var(--xh-log-radius, var(--xh-shape-surface));
-    background: var(--xh-log-bg, var(--xh-bg-subtle));
+    background: var(--xh-log-bg, var(--xh-bg-surface));
+    box-shadow: var(--xh-log-shadow, none);
     color: var(--xh-log-fg, var(--xh-fg-default));
   }
 
@@ -43,12 +79,6 @@
     scrollbar-gutter: stable;
   }
 
-  /* 视口带 tabindex=0，需要焦点环；偏移取负画在内侧，避免被 root 裁掉 */
-  [data-scope='log'][data-part='viewport']:focus-visible {
-    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
-    outline-offset: calc(-1 * var(--xh-ring-width));
-  }
-
   /* 取行期间指针给出忙的反馈 */
   [data-scope='log'][data-part='root'][data-loading] [data-scope='log'][data-part='viewport'] {
     cursor: progress;
@@ -57,9 +87,9 @@
   /* 等宽排版落在包裹层上，各行继承；行与行之间不留空隙，视口高度才等于整数行 */
   [data-scope='log'][data-part='content'] {
     display: block;
-    padding-inline: var(--xh-log-content-px, var(--xh-space-3));
+    padding-inline: var(--xh-log-content-px, var(--xh-_log-content-px));
     font-family: var(--xh-log-font, var(--xh-font-family-mono));
-    font-size: var(--xh-log-font-size, var(--xh-text-secondary-size));
+    font-size: var(--xh-log-font-size, var(--xh-_log-font-size));
   }
 
   [data-scope='log'][data-part='content'][hidden] {
@@ -72,4 +102,109 @@
     white-space: pre;
     tab-size: var(--xh-log-tab-size, 4);
   }
+
+  /* 级别只染行文颜色，不动排版：一行的高度是定高基准，四档必须等高。
+     没写级别的行走内容层的前景色 */
+  [data-scope='log'][data-part='line'][data-level='debug'] {
+    color: var(--xh-log-level-debug-fg, var(--xh-fg-subtle));
+  }
+
+  [data-scope='log'][data-part='line'][data-level='info'] {
+    color: var(--xh-log-level-info-fg, var(--xh-fg-default));
+  }
+
+  [data-scope='log'][data-part='line'][data-level='warn'] {
+    color: var(--xh-log-level-warn-fg, var(--xh-fg-warning));
+  }
+
+  [data-scope='log'][data-part='line'][data-level='error'] {
+    color: var(--xh-log-level-error-fg, var(--xh-fg-danger));
+  }
+
+  /* 回到底部：浮在视口右下角，收起时不卸载只隐藏。盒型、悬停 / 按下面与缩放由 Action Control 的
+     floating 档给（circle 正方盒、ghost 形态：白底承载 hover 100 → pressed 200）；材质随角落浮钮族走
+     frosted 四件套（底 + 边 + 影 + 磨砂，§8），这里只把使用者槽映射到桥接槽：
+     字形按 xs 档取 --xh-_action-profile-glyph-size（16px），与 back-top 同一把尺 */
+  [data-scope='log'][data-part='scroll-to-end-trigger'] {
+    --xh-_log-scroll-to-end-trigger-shadow: var(--xh-log-scroll-to-end-trigger-shadow, var(--xh-material-frosted-shadow));
+    --xh-action-visual-size: var(--xh-log-scroll-to-end-trigger-size, var(--xh-_action-profile-visual-size));
+    --xh-action-radius: var(--xh-log-scroll-to-end-trigger-radius, var(--xh-shape-circle));
+    --xh-action-bg-rest: var(--xh-log-scroll-to-end-trigger-bg, var(--xh-material-frosted-bg));
+    --xh-action-bg-hover: var(--xh-log-scroll-to-end-trigger-bg-hover, var(--xh-_action-variant-bg-hover));
+    --xh-action-border-rest: var(--xh-log-scroll-to-end-trigger-border, var(--xh-material-frosted-border));
+    --xh-action-border-hover: var(--xh-log-scroll-to-end-trigger-border, var(--xh-material-frosted-border));
+    --xh-action-border-pressed: var(--xh-log-scroll-to-end-trigger-border, var(--xh-material-frosted-border));
+    --xh-action-border-focus-visible: var(--xh-log-scroll-to-end-trigger-border, var(--xh-material-frosted-border));
+    --xh-action-shadow-rest: var(--xh-_log-scroll-to-end-trigger-shadow);
+    --xh-action-shadow-hover: var(--xh-_log-scroll-to-end-trigger-shadow);
+    --xh-action-shadow-pressed: var(--xh-_log-scroll-to-end-trigger-shadow);
+    --xh-action-fg-rest: var(--xh-log-scroll-to-end-trigger-fg, var(--xh-material-frosted-fg));
+    --xh-icon-size: var(--xh-log-icon-size, var(--xh-_action-profile-glyph-size));
+
+    position: absolute;
+    inset-block-end: var(--xh-log-scroll-to-end-trigger-inset, var(--xh-space-3));
+    inset-inline-end: var(--xh-log-scroll-to-end-trigger-inset, var(--xh-space-3));
+    -webkit-backdrop-filter: var(--xh-material-frosted-backdrop);
+    backdrop-filter: var(--xh-material-frosted-backdrop);
+  }
+
+  /* 连接层收起按钮时写 hidden 属性，上面的 display 会盖掉 UA 规则，这里补回 */
+  [data-scope='log'][data-part='scroll-to-end-trigger'][hidden] {
+    display: none;
+  }
+
+  /* 收起不卸载，冒出来时靠这条进场动画；不写 display，可见性归上面那条 [hidden] 管 */
+  [data-scope='log'][data-part='scroll-to-end-trigger'][data-state='visible'] {
+    animation: xh-log-button-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter-strong);
+  }
+
+  /* 没写内容就由皮肤画一枚向下的字形；作者往按钮里塞了自己的图形，这条规则即不命中。
+     不画的话这颗按钮就是一枚空盒，看不出它是干什么的——名字只在 aria-label 上 */
+  [data-scope='log'][data-part='scroll-to-end-trigger']:empty::before {
+    content: '';
+    display: inline-block;
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-sm));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-sm));
+    vertical-align: var(--xh-glyph-baseline-shift);
+    background-color: currentColor;
+    -webkit-mask: var(--xh-glyph-mark-chevron-down) center / contain no-repeat;
+    mask: var(--xh-glyph-mark-chevron-down) center / contain no-repeat;
+  }
+
+  /* 尺寸档只改行文字号与内衬 */
+  [data-scope='log'][data-part='root'][data-size='sm'] {
+    --xh-_log-font-size: var(--xh-text-caption-size);
+    --xh-_log-content-px: var(--xh-space-2);
+  }
+
+  [data-scope='log'][data-part='root'][data-size='md'] {
+    --xh-_log-font-size: var(--xh-text-secondary-size);
+    --xh-_log-content-px: var(--xh-space-3);
+  }
+
+  [data-scope='log'][data-part='root'][data-size='lg'] {
+    --xh-_log-font-size: var(--xh-text-body-size);
+    --xh-_log-content-px: var(--xh-space-4);
+  }
+
+  /* 视觉隐藏但仍参与播报：用 clip-path 裁到不可见，不能用 display:none 或 visibility:hidden；
+     white-space: nowrap 防止 1px 宽把文本挤成竖排。 */
+  [data-scope='log'][data-part='live-region'] {
+    position: absolute;
+    inline-size: 1px;
+    block-size: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+    border: 0;
+  }
+
+  @media print {
+    /* 打印：回到底部这颗钮只有在能滚的地方才成立，落到纸上是一颗按不动的按钮。 */
+    [data-scope='log'][data-part='scroll-to-end-trigger'] {
+      display: none;
+    }
+  }
 }