@xihan-ui/styles 3.1.0 → 4.0.0

package/dist/css/listbox.css

@@ -0,0 +1,395 @@
+/*
+ * 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';
+@import '../family/loading-ring.css';
+@import '../family/motion.css';
+
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  .xh-scope-listbox {
+    --xh-listbox-skin: 1;
+  }
+
+  .xh-scope-listbox[data-part='root'] {
+    /* 条目外的字形（空态 / 在途占位里作者塞的图标）按档取尺，缺省 md；条目内的字形由家族随
+       data-xh-collection-size 下发。列表框自绘的状态字形（行尾对号所在的标记盒与盒里的勾）不读这支：
+       它们是指示符，走 --xh-control-indicator-* 一族——标记盒在自己身上把 --xh-icon-size 改接到盒的尺 */
+    --xh-icon-size: var(--xh-listbox-icon-size, var(--xh-glyph-size-md));
+    /* 定高小列表的自绘条挂在根上：根是条子的定位盒，轨道底色关掉才不会在列表右缘糊出一条灰带 */
+    --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));
+  }
+
+  .xh-scope-listbox[data-part='root'][hidden] {
+    display: none;
+  }
+
+  /* —— 尺寸 —— */
+  /* 缺省档写在上面的基础规则里 */
+  .xh-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);
+  }
+
+  .xh-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);
+  }
+
+  /* 校验失败：整块列表框换成错误描边，与其余表单控件同一套表达 */
+  .xh-scope-listbox[data-part='content'][data-invalid] {
+    border-color: var(--xh-listbox-content-border-invalid, var(--xh-border-invalid));
+  }
+
+  /* 只读改不动选中值，但不是禁用：颜色照常，只把"可点"这个暗示收回来。
+     光标由家族按态解算，这里在各态的槽上统一收回；禁用项的 not-allowed 由家族按 aria-disabled 给，不在此列 */
+  .xh-scope-listbox[data-part='root'][data-readonly]
+    .xh-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;
+  }
+
+  .xh-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));
+    font-weight: var(--xh-listbox-label-font-weight, var(--xh-text-label-weight));
+    line-height: var(--xh-leading-none);
+  }
+
+  /* 整组禁用会把 data-disabled 一路打到 label / content / group 上，各处观感保持一致 */
+  .xh-scope-listbox[data-part='label'][data-disabled] {
+    color: var(--xh-fg-subtle);
+  }
+
+  /* 常驻列表不是浮层：容器留边框与底色，但不投影、不脱离文档流，
+     因此这里既不写 position 也不写 z-index，滚动发生在容器自身 */
+  .xh-scope-listbox[data-part='content'] {
+    display: flex;
+    flex-direction: column;
+    gap: var(--xh-listbox-content-gap, var(--xh-list-option-gap));
+    max-block-size: var(--xh-listbox-content-max-h, var(--xh-viewport-h-md));
+    padding-block: var(--xh-listbox-content-py, var(--xh-space-1));
+    padding-inline: var(--xh-listbox-content-px, var(--xh-space-1));
+    border: var(--xh-stroke-thin) solid var(--xh-listbox-content-border, var(--xh-border-default));
+    border-radius: var(--xh-listbox-content-radius, var(--xh-shape-surface));
+    background: var(--xh-listbox-content-bg, var(--xh-bg-surface));
+    color: var(--xh-listbox-content-fg, var(--xh-fg-default));
+    /* 两轴一起给：条目文字用省略号收口，正常不会横向溢出，
+       但作者塞进宽内容时至少还够得着，而不是被裁掉 */
+    overflow: auto;
+  }
+
+  /* display 会盖掉 hidden 属性的 UA 规则，作者手动收起时要显式让位 */
+  .xh-scope-listbox[data-part='content'][hidden] {
+    display: none;
+  }
+
+  /* 手写结构按真正的条目判断，空白文本与分组标题都不算候选。
+     只排除 content 内部的 hidden 祖先；外层浮层退场时不改变本列表的几何。
+     禁用条目仍是有效内容，不参与此处排除。 */
+  .xh-scope-listbox[data-part='content']:not([data-xh-virtualized]):not(:has(
+    .xh-scope-listbox[data-part='item']:not([hidden]):not(.xh-scope-listbox[data-part='content'] [hidden] *)
+  )),
+  .xh-scope-listbox[data-part='group']:not(:has(
+    .xh-scope-listbox[data-part='item']:not([hidden]):not(.xh-scope-listbox[data-part='content'] [hidden] *)
+  )) {
+    display: none;
+  }
+
+  /* 横向列表沿主轴排，此时高度由内容决定，再压最大高度只会白留一条滚动条 */
+  .xh-scope-listbox[data-part='content'][data-orientation='horizontal'] {
+    flex-direction: row;
+    align-items: center;
+    max-block-size: none;
+  }
+
+  /* 焦点在列表外时容器自己进 Tab 序列兜底，落焦不画环：高亮永远长在条目上 */
+  .xh-scope-listbox[data-part='content']:focus-visible {
+    outline: none;
+  }
+
+  .xh-scope-listbox[data-part='group'] {
+    display: flex;
+    flex-direction: column;
+    gap: var(--xh-listbox-group-gap, var(--xh-list-option-gap));
+  }
+
+  .xh-scope-listbox[data-part='group'][hidden] {
+    display: none;
+  }
+
+  /* 只在两个有可见条目的分组之间留白；已收起的空组不能把首组额外向下推。 */
+  .xh-scope-listbox[data-part='group']:has(
+    .xh-scope-listbox[data-part='item']:not([hidden]):not(.xh-scope-listbox[data-part='content'] [hidden] *)
+  )
+    ~ .xh-scope-listbox[data-part='group']:has(
+      .xh-scope-listbox[data-part='item']:not([hidden]):not(.xh-scope-listbox[data-part='content'] [hidden] *)
+    ) {
+    margin-block-start: var(--xh-listbox-group-spacing, var(--xh-space-1_5));
+  }
+
+  /* 分组标题不是选项、进不了导航，画成小号次要文字，
+     内缩与条目对齐（同一个 padding-inline），标题与条目文字才在一条竖线上 */
+  .xh-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-_listbox-item-px));
+    color: var(--xh-listbox-group-label-fg, var(--xh-fg-muted));
+    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));
+    line-height: var(--xh-leading-none);
+    user-select: none;
+    transition: opacity var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  /* 刷新：已有选项时后台在取，保留上一帧，条目与分组标题按 micro 淡下，数据到了再淡回；在途占位此时让位。
+     淡的是内容不是面：content 自己是描边面，整块淡下去边也跟着淡 */
+  .xh-scope-listbox[data-part='content'][aria-busy='true'] .xh-scope-listbox:is([data-part='item'], [data-part='group-label']) {
+    opacity: var(--xh-state-disabled-opacity);
+  }
+
+  .xh-scope-listbox[data-part='group-label'][hidden] {
+    display: none;
+  }
+
+  .xh-scope-listbox[data-part='group-label'][data-disabled] {
+    color: var(--xh-fg-disabled);
+  }
+
+  /* 空态占位：待在 root 里、content 的兄弟（列表框只许拥有 option 与 group）。
+     它只画作者提供的居中文字；零候选的 content 自身收起，不再留下空描边或留白。 */
+  .xh-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-muted));
+    font-size: var(--xh-listbox-empty-font-size, var(--xh-_listbox-font-size));
+    line-height: var(--xh-leading-none);
+    text-align: center;
+  }
+
+  /* 上面给了 display，UA 的 [hidden]{display:none} 已被盖掉，这里补回来 */
+  .xh-scope-listbox[data-part='empty'][hidden] {
+    display: none;
+  }
+
+  .xh-scope-listbox[data-part='empty'][data-disabled] {
+    color: var(--xh-fg-disabled);
+  }
+
+  /* 在途占位：与空态占位同一个位置、同一副观感，两者不同屏 */
+  .xh-scope-listbox[data-part='loading'] {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: var(--xh-_listbox-gap);
+    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-muted));
+    font-size: var(--xh-listbox-loading-font-size, var(--xh-_listbox-font-size));
+    line-height: var(--xh-leading-none);
+    text-align: center;
+  }
+
+  .xh-scope-listbox[data-part='loading'][hidden] {
+    display: none;
+  }
+
+  /* 首次加载：文案前一枚加载环，由加载环配方画（连接层投影 data-xh-loading-ring 与 data-loading），
+     直径取所在尺寸档的图标档 */
+  .xh-scope-listbox[data-part='loading']::before {
+    content: '';
+    flex: none;
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-md));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-md));
+  }
+
+  /* 取下一页的按钮：铺满一行摆在列表尾——铺满一行的独立动作条目，接 Action Control 的 row 档、
+     ghost 形态：宽度由容器给、高度随内容、按下只换面不缩放；盒几何、悬停 / 按下 / 禁用面、
+     焦点环与粗指针热区全由家族给，白底承载 hover 100 → pressed 200。
+     这里只把使用者槽映射到桥接槽，文案居中写在下一条 */
+  .xh-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));
+
+    /* row 档允许换行、高度随内容，折行的文案走正文行高 */
+    line-height: var(--xh-leading-normal);
+  }
+
+  /* 文案居中（单行整段居中，折行逐行居中），盖掉 row 档的靠起始缘排布：它是一行里唯一的东西，
+     靠起始缘会像一条没对齐的条目。选择器点名 row 档，有层与无层两份产物里都压得住它 */
+  .xh-scope-listbox[data-part='load-more-trigger'][data-xh-action-profile='row'] {
+    justify-content: center;
+    text-align: center;
+  }
+
+  .xh-scope-listbox[data-part='load-more-trigger'][hidden] {
+    display: none;
+  }
+
+  /* 条目走 Collection Item 的 overlay 语境，与树选择同一种选中读法：网格、尺寸档、悬停 / 高亮 / 按下面
+     （白底承载 hover 100 → pressed 200）由家族给，选中不换面、不换字色，只在行尾亮对号，
+     选中叠悬停 / 按下沿用同一条阶梯；禁用面（字色降级、not-allowed、不换面）也归家族。
+     这里只把公开槽映射到桥接槽，不复制任何状态选择器。
+     列表框坐在 surface 白底上，前景走 fg-default 而不是浮层的 frosted 前景 */
+  .xh-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-inset));
+    /* 作者的图标尺槽经桥接槽下发到条目，家族缺省按 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-listbox-item-fg, var(--xh-fg-default)));
+    --xh-collection-fg-selected-hover: var(--xh-listbox-item-fg-selected, var(--xh-listbox-item-fg, var(--xh-fg-default)));
+    --xh-collection-fg-selected-highlight: var(--xh-listbox-item-fg-selected, var(--xh-listbox-item-fg, var(--xh-fg-default)));
+    --xh-collection-fg-selected-pressed: var(--xh-listbox-item-fg-selected, var(--xh-listbox-item-fg, var(--xh-fg-default)));
+    --xh-collection-font-weight-selected: var(--xh-listbox-item-font-weight-selected, var(--xh-font-weight-medium));
+    --xh-collection-font-weight-selected-hover: var(--xh-listbox-item-font-weight-selected, var(--xh-font-weight-medium));
+    --xh-collection-font-weight-selected-highlight: var(--xh-listbox-item-font-weight-selected, var(--xh-font-weight-medium));
+    --xh-collection-font-weight-selected-pressed: var(--xh-listbox-item-font-weight-selected, var(--xh-font-weight-medium));
+    --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-hover: var(--xh-listbox-item-bg-hover, var(--xh-bg-subtle));
+    --xh-collection-bg-selected-highlight: var(--xh-listbox-item-bg-hover, var(--xh-bg-subtle));
+    --xh-collection-bg-selected-pressed: var(--xh-listbox-item-bg-pressed, var(--xh-bg-subtle-hover));
+    /* 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;
+  }
+
+  /* 家族给了 display，UA 的 [hidden]{display:none} 已被盖掉：条目可以按需收起（过滤掉的选项） */
+  .xh-scope-listbox[data-part='item'][hidden] {
+    display: none;
+  }
+
+  /* 键盘焦点出现时环才接回并立即到位，不压在背景过渡的中间帧上 */
+  .xh-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;
+  }
+
+  .xh-scope-listbox[data-part='item-text'] {
+    /* 网格子项默认最小尺寸是内容尺寸，不归零则长文本把行撑破、省略号轮不上 */
+    min-inline-size: 0;
+    overflow: hidden;
+    white-space: nowrap;
+    text-overflow: ellipsis;
+  }
+
+  /* 勾选标记落在家族网格行尾的 indicator 列（page 与 overlay 同位）；显隐与颜色由家族按选中态给，
+     未选中时占位不塌，切换选中不引起行宽抖动。
+     盒与盒里的勾是指示符：盒按指示符档取尺，并在自己身上把 --xh-icon-size 改接到盒的尺，皮肤画的
+     兜底勾与作者塞进盒里的 XhIcon 读同一把尺、与盒同边长（对号不是勾选格，不取 × 0.75，与 Menu 族同口径）；
+     不读家族按档下发到行的 --xh-icon-size——那支只管作者放进条目里的图标，按图标档取的 20px 比 16 / 14 的指示符档大一圈 */
+  .xh-scope-listbox[data-part='item-indicator'] {
+    --xh-icon-size: var(--xh-listbox-item-indicator-size, var(--xh-control-indicator-size));
+
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    inline-size: var(--xh-listbox-item-indicator-size, var(--xh-control-indicator-size));
+    block-size: var(--xh-listbox-item-indicator-size, var(--xh-control-indicator-size));
+  }
+
+  .xh-scope-listbox[data-part='item-indicator'][hidden] {
+    display: none;
+  }
+
+  /* 没写内容就由皮肤画勾；作者往部件里塞了自己的图形，这条规则即不命中。
+     尺寸读标记盒自己改接过的 --xh-icon-size：与盒同边长，随指示符档换档（见上面标记盒那块） */
+  .xh-scope-listbox[data-part='item-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-check) center / contain no-repeat;
+    mask: var(--xh-glyph-mark-check) center / contain no-repeat;
+  }
+
+  @media print {
+    /* 打印默认丢底色，而对号是遮罩出来的一块底色：行本就不换面，丢了它选中在纸上就没了踪影 */
+    .xh-scope-listbox[data-part='item-indicator'] {
+      print-color-adjust: exact;
+    }
+  }
+
+  @media (forced-colors: active) {
+    /* 兜底字形是 mask 挖出来的一块底色，这一档里底色被系统换成 Canvas，字形跟着消失。
+       字形退出强制换色、直接写系统色（不能取 currentColor：退出强制换色的伪元素读到的是被系统换掉之前的作者色）：
+       条目面上取 CanvasText；按下与没被高亮时的悬停，家族把条目涂成 Highlight，字形换 HighlightText；
+       禁用取 GrayText */
+    .xh-scope-listbox[data-part='item-indicator']:empty::before {
+      forced-color-adjust: none;
+      background-color: CanvasText;
+    }
+
+    .xh-scope-listbox[data-part='item']:not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error]):is(:active, [data-pressed], :hover:not(:focus-visible, [data-highlighted])) .xh-scope-listbox[data-part='item-indicator']:empty::before {
+      background-color: HighlightText;
+    }
+
+    .xh-scope-listbox[data-part='item']:is([aria-disabled='true'], [data-disabled]) .xh-scope-listbox[data-part='item-indicator']:empty::before {
+      background-color: GrayText;
+    }
+  }
+}

package/dist/css/loading-bar.css

@@ -0,0 +1,144 @@
+/*
+ * 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 探一次，取不到就说明这份皮肤没被引入。 */
+  .xh-scope-loading-bar {
+    --xh-loading-bar-skin: 1;
+  }
+
+  /*
+   * 贴在视口顶边的一条细带。厚度那条轴（block-size）由连接层写进内联样式——
+   * height 这个 prop 的缺省值在 connect 里收口，这里再声明一次只会被内联盖掉，
+   * 还会让人误以为厚度归样式层管。
+   *
+   * fixed 认的是视口，祖先上一旦出现 transform / filter / backdrop-filter / contain
+   * 就会把包含块抢走，条子立刻贴错位置——覆盖钩子里别加这几个属性。
+   */
+  .xh-scope-loading-bar[data-part='root'] {
+    position: fixed;
+    /* 顶到视口上沿的那一条：刘海或状态栏压住的那一段由系统给出，不让位就整条藏在下面。
+       桌面上 env() 恒为 0，条子照旧贴着上沿。 */
+    inset-block-start: env(safe-area-inset-top);
+    inset-inline: 0;
+    z-index: var(--xh-loading-bar-layer, var(--xh-layer-sticky));
+
+    /* 它只报进度，不吃点击：盖在顶栏上的一条带子若拦住指针，页面顶部就点不动了 */
+    pointer-events: none;
+    opacity: 1;
+    transition: opacity var(--xh-loading-bar-fade, var(--xh-motion-duration-exit)) var(--xh-motion-ease-exit);
+  }
+
+  /* 只要声明过任何 display，就盖掉了 UA 的 [hidden]{display:none}；
+     这里虽然没声明，作者层随手给一条 display 也会盖掉，所以补齐这条兜住收起态。
+     连接层只会给 root 写 hidden，track / range 不需要同样的兜底 */
+  .xh-scope-loading-bar[data-part='root'][hidden] {
+    display: none;
+  }
+
+  /* 走满之后才淡出：complete 期间根节点保持不透明，进度段冲到头的平移播完，机器才进 finishing。
+     满格先停一拍（延迟一个 micro）再淡：用户要看清「走完了」，一到头就开始淡读起来像中途断掉。
+     机器等的是浏览器实际起播的这段过渡（含延迟），不按毫秒猜 */
+  .xh-scope-loading-bar[data-part='root'][data-state='finishing'] {
+    opacity: 0;
+    transition-delay: var(--xh-motion-duration-micro);
+  }
+
+  /* 背景槽。默认透明：顶部加载条通常直接压在页面顶边上，一条贯穿整屏的浅色底
+     在视觉上等于凭空多出一道分隔线 */
+  .xh-scope-loading-bar[data-part='track'] {
+    overflow: hidden;
+    inline-size: 100%;
+    block-size: 100%;
+    background: var(--xh-loading-bar-track, transparent);
+  }
+
+  /*
+   * 进度段。铺满轨道，按连接层交出的比例往行首平移、由轨道裁掉：推进只走合成，
+   * 不重排也不重绘；末端的亮边跟着它一起走。背景色不走内联：要别的颜色改 --xh-loading-bar-range 这个槽，或者换语气。
+   *
+   * 语气取装饰档 --xh-_tone-soft：那一档压在画布上够 3:1，细带才看得出来。
+   * 槽位由 root 上的 data-tone 声明，继承下来。
+   * 没写 data-tone 时该槽没被声明，退回原来的品牌色。
+   */
+  .xh-scope-loading-bar[data-part='range'] {
+    inline-size: 100%;
+    block-size: 100%;
+    /* 露出的前端（行尾）是一维对象的圆头；行首一端由轨道与视口边裁掉，保持方头贴边 */
+    border-start-end-radius: var(--xh-loading-bar-range-radius, var(--xh-shape-pill));
+    border-end-end-radius: var(--xh-loading-bar-range-radius, var(--xh-shape-pill));
+    background: var(--xh-loading-bar-range, var(--xh-_tone-soft, var(--xh-bg-brand)));
+    translate: calc((var(--xh-_loading-bar-value, 0) - 1) * 100%) 0;
+    transition: translate var(--xh-loading-bar-speed, var(--xh-motion-duration-move)) var(--xh-motion-ease-continuous);
+  }
+
+  /* translate 只认物理方向：RTL 下行首在右边，平移方向翻转 */
+  .xh-scope-loading-bar[data-part='range']:dir(rtl) {
+    translate: calc((1 - var(--xh-_loading-bar-value, 0)) * 100%) 0;
+  }
+
+  /* 渲染了亮边才把进度段变成定位面：亮边贴在它的末端 */
+  .xh-scope-loading-bar[data-part='range']:has([data-part='peg']) {
+    position: relative;
+  }
+
+  /*
+   * 进度段末端那道亮边。它把「条子在往前走」这件事画出来：只有一条渐宽的色带时，
+   * 200ms 一跳的推进读起来像卡顿。
+   * 颜色接进度段自己的那一支，宽度与厚度各留一个槽。
+   */
+  .xh-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 的末端不该先亮出一道边 */
+  .xh-scope-loading-bar[data-part='peg'][data-state='idle'] {
+    opacity: 0;
+  }
+
+  .xh-scope-loading-bar[data-part='peg'][hidden] {
+    display: none;
+  }
+
+  /* 减少动效：作者写进两个时长槽的值不作数，退回令牌——进度段的平移随几何时长立刻到位，
+     收尾的淡出保留减弱档的那一小段。一条按 200ms 一拍持续推进的带子正是最容易引发不适的那种动效。
+     两条规则是同一件事的两个触发条件：系统偏好与作者打的 data-motion */
+  @media (prefers-reduced-motion: reduce) {
+    .xh-scope-loading-bar[data-part='root'] {
+      transition-duration: var(--xh-motion-duration-exit);
+    }
+
+    .xh-scope-loading-bar[data-part='range'] {
+      transition-duration: var(--xh-motion-duration-move);
+    }
+  }
+
+  :where([data-motion='reduce']) .xh-scope-loading-bar[data-part='root'] {
+    transition-duration: var(--xh-motion-duration-exit);
+  }
+
+  :where([data-motion='reduce']) .xh-scope-loading-bar[data-part='range'] {
+    transition-duration: var(--xh-motion-duration-move);
+  }
+
+  @media print {
+    /* 打印：加载进度条画的是「正在等」，落到纸上是一条没有含义的色带。 */
+    .xh-scope-loading-bar[data-part='root'] {
+      display: none;
+    }
+  }
+}