@xihan-ui/styles 3.1.0 → 4.0.0

package/dist/css/combobox.css

@@ -0,0 +1,578 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* Combobox 独立皮肤同时传递引入字段视觉盒、字段内动作与浮层集合行；full bundle 递归去重。 */
+@import '../family/field-chrome.css';
+@import '../family/action-control.css';
+@import '../family/collection-item.css';
+@import '../family/loading-ring.css';
+
+/* 共享关键帧由 family/motion.css 提供，本皮肤 @import 它，单独引入仍成立。 */
+@import '../family/motion.css';
+@import '../family/material.css';
+@import '../family/tag-list.css';
+
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  .xh-scope-combobox {
+    --xh-combobox-skin: 1;
+  }
+
+  /* 坐标由定位引擎写进 style（inset-inline-start / inset-block-start），这里只定位模式与层级 */
+  .xh-scope-combobox[data-part='positioner'] {
+    /* 落定那一侧的可用高度，由定位引擎经内联自定义属性写进来，内容层继承它限高；
+       引擎没算（尚未落位 / 无引擎）时不额外限高 */
+    --xh-_combobox-available-h: 100vh;
+    /* 落定那一侧的可用宽度，同样由定位引擎经内联自定义属性写进来，行内轴据此夹取；
+       引擎没算（尚未落位 / 无引擎 / 贴边归零）时退到视口宽 */
+    --xh-_combobox-available-w: 100vw;
+    /* 字段盒实测宽度，由定位引擎经内联自定义属性写进来，内容层与它等宽；
+       引擎没算（尚未落位 / 无引擎）时为 0，面板取下界 */
+    --xh-_combobox-anchor-w: 0px;
+    /* 每层使用自身落位方向，不继承外层弹窗留下的方向。 */
+    --xh-_overlay-enter-up: 0;
+    --xh-_overlay-enter-down: 0;
+    --xh-_overlay-enter-left: 0;
+    --xh-_overlay-enter-right: 0;
+
+    /* 候选列表的自绘条浮在内容之上：轨道不上底色，实色轨道会在列表右缘糊一条竖灰带 */
+    --xh-scrollbar-track-bg: transparent;
+
+    position: fixed;
+    /* listbox 与同级 status 占同一个格：content 始终是唯一表面，状态文字叠在它上面。 */
+    display: grid;
+    z-index: var(--xh-combobox-layer, var(--xh-_layer, var(--xh-layer-popover)));
+    /* 空壳不吃指针，交互只发生在 content 与 empty 上 */
+    pointer-events: none;
+  }
+
+  /* 锚点被滚出可视区：整个浮层随之收起 */
+  .xh-scope-combobox[data-part='positioner'][data-hidden] {
+    visibility: hidden;
+  }
+
+  /* 作者显式收起整层时让位；连接层自己的退场只操作 content，不会命中这条。 */
+  .xh-scope-combobox[data-part='positioner'][hidden] {
+    display: none;
+  }
+
+  /* placement 与位移同为物理方向，不随书写方向翻转。 */
+  .xh-scope-combobox[data-part='positioner'][data-placement^='top'] {
+    --xh-_overlay-enter-down: 1;
+  }
+
+  .xh-scope-combobox[data-part='positioner'][data-placement^='bottom'] {
+    --xh-_overlay-enter-up: 1;
+  }
+
+  .xh-scope-combobox[data-part='positioner'][data-placement^='left'] {
+    --xh-_overlay-enter-right: 1;
+  }
+
+  .xh-scope-combobox[data-part='positioner'][data-placement^='right'] {
+    --xh-_overlay-enter-left: 1;
+  }
+
+  /* 私有槽同时声明在根与 positioner 上：浮层被搬到 portal 落点，不是根的后代，继承不过去 */
+  .xh-scope-combobox:is([data-part='root'], [data-part='positioner']) {
+    /* 尺寸档只换这几个私有槽，输入行与候选都从这两处继承它们，
+       换档不必给每个部件各写一条选择器；形态三档由家族按 control 上的 data-variant 生成，皮肤不再声明 */
+    --xh-_combobox-h: var(--xh-control-h-md);
+    --xh-_combobox-px: var(--xh-control-px-md);
+    --xh-_combobox-item-py: var(--xh-list-option-py-md);
+    --xh-_combobox-item-h: var(--xh-list-option-h-md);
+    --xh-_combobox-item-px: var(--xh-control-px-md);
+    --xh-_combobox-gap: var(--xh-control-gap-md);
+    --xh-_combobox-font-size: var(--xh-control-font-md);
+
+    /* 作者塞进指示符槽的图标跟着控件的尺寸档走；它自己写了 size 时仍以作者的为准。
+       浮层条目里自绘的状态字形（勾选标记所在的标记盒与盒里的勾）不读这支：它们是指示符，走
+       --xh-control-indicator-* 一族——标记盒在自己身上把 --xh-icon-size 改接到盒的尺 */
+    --xh-icon-size: var(--xh-combobox-icon-size, var(--xh-glyph-size-md));
+
+    /* 语气只落在勾选标记上，单选与多选正文使用同一颜色。 */
+    --xh-_combobox-accent: var(--xh-_tone, var(--xh-fg-brand));
+  }
+
+  .xh-scope-combobox[data-part='root'] {
+    display: inline-flex;
+    flex-direction: column;
+    gap: var(--xh-combobox-gap, var(--xh-space-1));
+
+    /* 不传尺寸时一律这么宽，宽度不随内容走；父容器给不出这么宽时整件跟着收，地板同步让步，不越出父容器。
+       地板不高过缺省宽：使用者把缺省宽钉到底线以下时不必再放开底线 */
+    inline-size: var(--xh-combobox-control-w, var(--xh-control-w));
+    min-inline-size: min(var(--xh-combobox-control-w, var(--xh-control-w)), var(--xh-combobox-control-min-w, var(--xh-control-min-w)), 100%);
+    max-inline-size: 100%;
+  }
+
+  /* 只要声明了 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去 */
+  .xh-scope-combobox[data-part='root'][hidden] {
+    display: none;
+  }
+
+  /* —— 尺寸 —— */
+  /* 缺省档写在上面的基础规则里 */
+  .xh-scope-combobox:is([data-part='root'], [data-part='positioner'])[data-size='sm'] {
+    --xh-_combobox-h: var(--xh-control-h-sm);
+    --xh-_combobox-px: var(--xh-control-px-sm);
+    --xh-_combobox-item-py: var(--xh-list-option-py-sm);
+    --xh-_combobox-item-h: var(--xh-list-option-h-sm);
+    --xh-_combobox-item-px: var(--xh-control-px-sm);
+    --xh-_combobox-gap: var(--xh-control-gap-sm);
+    --xh-_combobox-font-size: var(--xh-control-font-sm);
+
+    --xh-icon-size: var(--xh-combobox-icon-size, var(--xh-glyph-size-sm));
+  }
+
+  .xh-scope-combobox:is([data-part='root'], [data-part='positioner'])[data-size='lg'] {
+    --xh-_combobox-h: var(--xh-control-h-lg);
+    --xh-_combobox-px: var(--xh-control-px-lg);
+    --xh-_combobox-item-py: var(--xh-list-option-py-lg);
+    --xh-_combobox-item-h: var(--xh-list-option-h-lg);
+    --xh-_combobox-item-px: var(--xh-control-px-lg);
+    --xh-_combobox-gap: var(--xh-control-gap-lg);
+    --xh-_combobox-font-size: var(--xh-control-font-lg);
+
+    --xh-icon-size: var(--xh-combobox-icon-size, var(--xh-glyph-size-lg));
+  }
+
+  .xh-scope-combobox[data-part='label'] {
+    /* 竖排时标签与控件之间的距离：根的 gap 之上补一段差值，--xh-combobox-label-gap 给多少最终就是多少 */
+    margin-block-end: calc(var(--xh-combobox-label-gap, var(--xh-space-2)) - var(--xh-combobox-gap, var(--xh-space-1)));
+    color: var(--xh-combobox-label-fg, var(--xh-fg-muted));
+    font-size: var(--xh-combobox-label-font-size, var(--xh-text-label-size));
+    font-weight: var(--xh-combobox-label-font-weight, var(--xh-text-label-weight));
+    line-height: var(--xh-leading-none);
+  }
+
+  .xh-scope-combobox[data-part='label'][data-disabled] {
+    color: var(--xh-combobox-label-fg-disabled, var(--xh-fg-muted));
+  }
+
+  /* 画成一个框的是 control 而不是 input：输入框、展开按钮、清空按钮三者要看起来是一体的，
+     边框长在里面任何一个身上都会把另外两个割在框外。描边、底色、圆角、聚焦环、五态与悬停由
+     Field Chrome 家族画在 control 上，多行宿主的排版由家族按 input 上的布局值切换；
+     组件只映射既有公开槽（shadow 缺省 none：字段静息描边式、无影） */
+  .xh-scope-combobox[data-part='control'] {
+    --xh-field-control-height: var(--xh-combobox-control-h, var(--xh-_combobox-h));
+    --xh-field-control-padding-inline: var(--xh-combobox-control-px, var(--xh-_combobox-px));
+    --xh-field-control-gap: var(--xh-combobox-control-gap, var(--xh-_combobox-gap));
+    --xh-field-control-min-inline-size: var(--xh-combobox-control-min-w, var(--xh-control-min-w));
+    --xh-field-control-radius: var(--xh-combobox-control-radius, var(--xh-shape-control));
+    --xh-field-bg-rest: var(--xh-combobox-control-bg, var(--xh-_field-variant-bg-rest));
+    --xh-field-bg-hover: var(--xh-combobox-control-bg-hover, var(--xh-_field-variant-bg-hover));
+    --xh-field-bg-read-only: var(--xh-combobox-control-bg-readonly, var(--xh-_field-variant-bg-read-only));
+    --xh-field-bg-disabled: var(--xh-combobox-control-bg-disabled, var(--xh-_field-variant-bg-disabled));
+    --xh-field-fg-rest: var(--xh-combobox-control-fg, var(--xh-fg-default));
+    --xh-field-border-rest: var(--xh-combobox-control-border, var(--xh-_field-variant-border-rest));
+    --xh-field-border-hover: var(--xh-combobox-control-border-hover, var(--xh-_field-variant-border-hover));
+    --xh-field-border-focus: var(--xh-combobox-control-border-focus, var(--xh-_field-variant-border-focus));
+    --xh-field-border-invalid: var(--xh-combobox-control-border-invalid, var(--xh-_field-variant-border-invalid));
+    --xh-field-shadow-rest: var(--xh-combobox-control-shadow, none);
+    /* 家族 chrome 会重写 --xh-icon-size，使用者图标槽必须经桥接槽下发才能在盒内生效 */
+    --xh-field-glyph-size: var(--xh-combobox-icon-size, var(--xh-_field-size-glyph-size));
+  }
+
+  .xh-scope-combobox[data-part='control'][hidden] {
+    display: none;
+  }
+
+  /* input 是单体表单控件，禁用走原生 disabled（候选那边一律 aria-disabled）。
+     它自己不画框也不画环，两者都归 control；边框 / 底 / 内距的重置、占位色与自动填充回铺由家族按
+     data-xh-field-input 给（含撑满剩余宽度的 flex:1），多行宿主的 block-size:auto 与只许纵向拉伸同由家族的 textarea 布局给 */
+  .xh-scope-combobox[data-part='input'] {
+    --xh-field-input-fg: var(--xh-combobox-input-fg, var(--xh-combobox-control-fg, var(--xh-fg-default)));
+    --xh-field-input-font-size: var(--xh-combobox-input-font-size, var(--xh-_combobox-font-size));
+    --xh-field-placeholder-fg: var(--xh-combobox-placeholder-fg, var(--xh-fg-subtle));
+    --xh-field-autofill-bg: var(--xh-combobox-input-autofill-bg, var(--xh-bg-canvas));
+    --xh-field-autofill-fg: var(--xh-combobox-input-autofill-fg, var(--xh-fg-default));
+
+    /* 多选的标签排在它前面：标签再多也给打字留出这一截，挤不下时标签先截断、再折进 +N */
+    min-inline-size: var(--xh-combobox-input-min-w, var(--xh-control-input-min-w));
+  }
+
+  /* 标签行：盒里、输入框之前收着已选值标签与 +N 那一枚的一行，行里每一枚都是 tag（data-scope="tag"），
+     样子归 tag.css；行怎么排、标签怎么进出归标签行家族配方（family/tag-list.css），这里只把使用者的间距槽接进去 */
+  .xh-scope-combobox[data-part='tag-list'] {
+    --xh-tag-list-gap: var(--xh-combobox-tag-list-gap, var(--xh-space-1));
+  }
+
+  .xh-scope-combobox[data-part='input'][hidden] {
+    display: none;
+  }
+
+  /* 两个按钮同一副长相：贴在框内末端的小方钮，不占宽度也不撑高 control。正方视觉盒、inset 圆角、
+     悬停 100 / 按下 200 与 0.97 按压、粗指针热区、禁用面与 :focus-visible 关环（盒的 :focus-within
+     已画了一圈）全由 Action Control 的 field-inset ghost 档给，组件只映射既有覆盖槽 */
+  .xh-scope-combobox[data-part='trigger'],
+  .xh-scope-combobox[data-part='clear-trigger'] {
+    --xh-action-visual-size: var(--xh-combobox-action-size, var(--xh-_action-profile-visual-size));
+    --xh-action-min-inline-size: var(--xh-combobox-action-size, var(--xh-_action-profile-visual-size));
+    --xh-action-radius: var(--xh-combobox-action-radius, var(--xh-shape-inset));
+    /* 底色阶梯由 ghost 档给（透明 → 100 → 200），使用者槽只作覆盖入口 */
+    --xh-action-bg-rest: var(--xh-combobox-action-bg, var(--xh-_action-variant-bg-rest));
+    --xh-action-bg-hover: var(--xh-combobox-action-bg-hover, var(--xh-_action-variant-bg-hover));
+    --xh-action-bg-pressed: var(--xh-combobox-action-bg-active, var(--xh-_action-variant-bg-pressed));
+    --xh-action-fg-rest: var(--xh-combobox-action-fg, var(--xh-fg-muted));
+    --xh-action-fg-hover: var(--xh-combobox-action-fg-hover, var(--xh-fg-default));
+    --xh-action-border-rest: transparent;
+    --xh-action-highlight-rest: transparent;
+    --xh-action-shadow-rest: none;
+    --xh-action-shadow-hover: none;
+    --xh-action-shadow-pressed: none;
+    --xh-action-font-size: var(--xh-combobox-action-font-size, var(--xh-text-secondary-size));
+    /* 配方尚未把 profile 字形档灌进 --xh-icon-size，钮内字形先按 field-inset 档逐钮取值 */
+    --xh-icon-size: var(--xh-_action-profile-glyph-size);
+
+    border-width: 0;
+  }
+
+  /* 没值时连接层给的是 hidden 属性；家族那条 display 会把 UA 规则盖掉 */
+  .xh-scope-combobox[data-part='trigger'][hidden],
+  .xh-scope-combobox[data-part='clear-trigger'][hidden] {
+    display: none;
+  }
+
+  /* 有值时清空钮顶上来，展开钮让位：两颗并排堆着用户分不清点哪个，换来换去还会让盒的宽度跳一下。
+     判据是盒里此刻有一颗没收起的清空钮——没写清空钮的结构里展开钮照常留着；
+     输入框仍是展开的入口（打字、方向键、openOnClick） */
+  .xh-scope-combobox[data-part='control']:has([data-part='clear-trigger']:not([hidden])) [data-part='trigger']:where(.xh-scope-combobox) {
+    display: none;
+  }
+
+  /* 展开时箭头翻个面，指向与列表的去向一致。转的是字形或作者塞的图形，不转按钮本体：
+     按钮自带悬停底色，整个按钮转会带着底色一起转；家族按压缩放的是整钮，不影响这里的转向 */
+  .xh-scope-combobox[data-part='trigger']:empty::before {
+    transition: rotate var(--xh-motion-duration-nudge) var(--xh-motion-ease-enter-strong);
+  }
+
+  /* 作者的箭头是任意节点：转向写在 trigger 自己的私有槽上，箭头只读槽（规则主体无特征时不挂在 data-state 后面） */
+  .xh-scope-combobox[data-part='trigger'] > * {
+    rotate: var(--xh-_combobox-trigger-turn, none);
+    transition: rotate var(--xh-motion-duration-nudge) var(--xh-motion-ease-enter-strong);
+  }
+
+  /* 没写内容就由皮肤画箭头；作者往部件里塞了自己的图形，这条规则即不命中 */
+  .xh-scope-combobox[data-part='trigger']: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-down) center / contain no-repeat;
+    mask: var(--xh-glyph-mark-chevron-down) center / contain no-repeat;
+  }
+
+  /* 同上：没写内容就由皮肤画叉 */
+  .xh-scope-combobox[data-part='clear-trigger']: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-close) center / contain no-repeat;
+    mask: var(--xh-glyph-mark-close) center / contain no-repeat;
+  }
+
+  /* 打开中与悬停同档：展开钮不另上底，方向由箭头转向承担 */
+  .xh-scope-combobox[data-part='trigger'][data-state='open']:empty::before {
+    rotate: 180deg;
+  }
+
+  .xh-scope-combobox[data-part='trigger'][data-state='open'] {
+    --xh-_combobox-trigger-turn: 180deg;
+  }
+
+  .xh-scope-combobox[data-part='content'] {
+    /* 材质由家族配方画（family/material.css 的 frosted 面：描边、底、1px 顶光、前景、投影与背景滤镜），
+       这里只把使用者槽接进来 */
+    --xh-frosted-bg: var(--xh-combobox-content-bg, var(--xh-_material-bg));
+    --xh-frosted-border: var(--xh-combobox-content-border, var(--xh-_material-border));
+    --xh-frosted-fg: var(--xh-combobox-content-fg, var(--xh-_material-fg));
+    --xh-frosted-shadow: var(--xh-combobox-content-shadow, var(--xh-_material-shadow));
+    --xh-frosted-backdrop: var(--xh-combobox-content-backdrop, var(--xh-_material-backdrop));
+    --xh-frosted-highlight: var(--xh-combobox-content-highlight, var(--xh-_material-highlight));
+
+    position: relative;
+    display: flex;
+    flex-direction: column;
+    gap: var(--xh-combobox-content-gap, var(--xh-list-option-gap));
+    grid-area: 1 / 1;
+    /* 列表型浮层与字段盒等宽：长选项在条目里截断，面板不随最长的一条变宽。锚点比下界还窄时取下界，
+       比可用区还宽时收成可用宽度；要封顶由作者另写上界槽 */
+    inline-size: min(
+      max(var(--xh-combobox-content-min-w, var(--xh-overlay-menu-min-w)), var(--xh-_combobox-anchor-w)),
+      var(--xh-_combobox-available-w)
+    );
+    max-inline-size: var(--xh-combobox-content-max-w, none);
+    /* 空列表也保留完整状态面的高度；empty/loading 先隐藏时，Presence 退场不会塌成细边条。 */
+    min-block-size: var(--xh-combobox-content-min-h, var(--xh-_combobox-h));
+    max-block-size: min(var(--xh-combobox-content-max-h, var(--xh-overlay-menu-max-h)), var(--xh-_combobox-available-h));
+    padding-block: var(--xh-combobox-content-py, var(--xh-space-1));
+    padding-inline: var(--xh-combobox-content-px, 0);
+    border-radius: var(--xh-combobox-content-radius, var(--xh-shape-overlay));
+    overflow-y: auto;
+    /* 浮层滚动面：滚到头不把页面一起带走 */
+    overscroll-behavior: contain;
+    pointer-events: auto;
+  }
+
+  /* 这里刻意没有 [data-part='content'][hidden] { display: none }，与 dialog 一致：
+     收起态连接层会给 content 打 hidden，而上面那条 display 正是要盖掉 UA 的
+     [hidden]{display:none}——退场动画得先能播。presence 读的是 content 的 animationName，
+     真正的收起由宿主在退场结束后落成内联 display:none（Vue 那边直接不渲染）。
+     其余声明了 display 的角色节点仍补 [hidden]，那几处没有退场动画。 */
+
+  /* 列表从不承载焦点（焦点恒在输入框，高亮走 aria-activedescendant），
+     可滚动容器在某些浏览器里会被自动塞进 Tab 序列，落焦时不画环 */
+  .xh-scope-combobox[data-part='content']:focus-visible {
+    outline: none;
+  }
+
+  /* 挂载时就开着的那一段（data-instant）属于首帧，直接呈现 */
+  .xh-scope-combobox[data-part='content'][data-state='open']:not([data-instant]) {
+    animation: xh-overlay-slide-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter-strong);
+  }
+
+  /* 退场：收起那一帧 hidden 由退场闸门押后，这里才播得出来。forwards 把末态钉住，
+     免得动画结束到真收起之间闪一下原样 */
+  .xh-scope-combobox[data-part='content'][data-state='closed'] {
+    animation: xh-overlay-slide-out var(--xh-motion-duration-exit) var(--xh-motion-ease-exit) forwards;
+  }
+
+  .xh-scope-combobox[data-part='group'] {
+    display: flex;
+    flex-direction: column;
+    gap: var(--xh-combobox-group-gap, var(--xh-list-option-gap));
+  }
+
+  .xh-scope-combobox[data-part='group'][hidden] {
+    display: none;
+  }
+
+  /* 组间留白只加在后继分组上：首组顶上已经有 content 的内边距，再加一层会显得头重 */
+  .xh-scope-combobox[data-part='group'] + .xh-scope-combobox[data-part='group'] {
+    margin-block-start: var(--xh-combobox-group-spacing, var(--xh-space-1_5));
+  }
+
+  /* 分组标题不是候选、进不了导航，画成小号次要文字，内缩与候选对齐（同一个 padding-inline） */
+  .xh-scope-combobox[data-part='group-label'] {
+    display: block;
+    padding-block: var(--xh-combobox-group-label-py, var(--xh-space-1));
+    padding-inline: var(--xh-combobox-group-label-px, var(--xh-_combobox-item-px));
+    color: var(--xh-combobox-group-label-fg, var(--xh-material-frosted-fg-muted));
+    font-size: var(--xh-combobox-group-label-font-size, var(--xh-text-caption-size));
+    font-weight: var(--xh-combobox-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-combobox[data-part='content'][aria-busy='true'] .xh-scope-combobox:is([data-part='item'], [data-part='group-label']) {
+    opacity: var(--xh-state-disabled-opacity);
+  }
+
+  .xh-scope-combobox[data-part='group-label'][hidden] {
+    display: none;
+  }
+
+  /* 候选行：网格、尺寸档、悬停 / 高亮 100、按下 200、禁用面与选中标记由 Collection Item 家族按 overlay
+     语境给（选中 = 透明底 + 行尾对号，正文保持 rest 色与常规字重），公开 Combobox 槽只映射到家族合同 */
+  .xh-scope-combobox[data-part='item'] {
+    --xh-collection-block-padding: var(--xh-combobox-item-py, var(--xh-_combobox-item-py));
+    --xh-collection-row-h: var(--xh-combobox-item-h, var(--xh-_combobox-item-h));
+    --xh-collection-inline-padding: var(--xh-combobox-item-px, var(--xh-_combobox-item-px));
+    --xh-collection-gap: var(--xh-combobox-item-gap, var(--xh-_combobox-gap));
+    --xh-collection-font-size: var(--xh-combobox-item-font-size, var(--xh-_combobox-font-size));
+    --xh-collection-radius: var(--xh-combobox-item-radius, 0);
+    --xh-collection-fg-rest: var(--xh-combobox-item-fg, var(--xh-material-frosted-fg));
+    --xh-collection-fg-hover: var(--xh-combobox-item-fg, var(--xh-material-frosted-fg));
+    --xh-collection-fg-keyboard-highlight: var(--xh-combobox-item-fg, var(--xh-material-frosted-fg));
+    --xh-collection-fg-selected: var(--xh-combobox-item-fg-selected, var(--xh-combobox-item-fg, var(--xh-material-frosted-fg)));
+    --xh-collection-fg-selected-highlight: var(--xh-combobox-item-fg-selected, var(--xh-combobox-item-fg, var(--xh-material-frosted-fg)));
+    --xh-collection-fg-selected-hover: var(--xh-combobox-item-fg-selected, var(--xh-combobox-item-fg, var(--xh-material-frosted-fg)));
+    --xh-collection-fg-selected-pressed: var(--xh-combobox-item-fg-selected, var(--xh-combobox-item-fg, var(--xh-material-frosted-fg)));
+    --xh-collection-fg-pressed: var(--xh-combobox-item-fg, var(--xh-material-frosted-fg));
+    --xh-collection-font-weight-selected: var(--xh-combobox-item-font-weight-selected, var(--xh-font-weight-medium));
+    --xh-collection-font-weight-selected-highlight: var(--xh-combobox-item-font-weight-selected, var(--xh-font-weight-medium));
+    --xh-collection-font-weight-selected-hover: var(--xh-combobox-item-font-weight-selected, var(--xh-font-weight-medium));
+    --xh-collection-font-weight-selected-pressed: var(--xh-combobox-item-font-weight-selected, var(--xh-font-weight-medium));
+    --xh-collection-bg-hover: var(--xh-combobox-item-bg-hover, var(--xh-bg-subtle));
+    --xh-collection-bg-keyboard-highlight: var(--xh-combobox-item-bg-hover, var(--xh-bg-subtle));
+    --xh-collection-bg-selected-highlight: var(--xh-combobox-item-bg-hover, var(--xh-bg-subtle));
+    --xh-collection-bg-selected-hover: var(--xh-combobox-item-bg-hover, var(--xh-bg-subtle));
+    --xh-collection-bg-pressed: var(--xh-combobox-item-bg-pressed, var(--xh-bg-subtle-hover));
+    --xh-collection-bg-selected-pressed: var(--xh-combobox-item-bg-pressed, var(--xh-bg-subtle-hover));
+    /* data-highlighted 同时覆盖指针与键盘路径；焦点恒在输入框，候选不接环 */
+    --xh-collection-outline-keyboard-highlight: transparent;
+    --xh-collection-outline-selected-highlight: transparent;
+    --xh-collection-indicator-fg-rest: var(--xh-combobox-item-check-fg, var(--xh-combobox-item-indicator-fg, var(--xh-_combobox-accent)));
+    --xh-collection-indicator-fg-checked: var(--xh-combobox-item-check-fg, var(--xh-combobox-item-indicator-fg, var(--xh-_combobox-accent)));
+    --xh-collection-indicator-fg-selected: var(--xh-combobox-item-check-fg, var(--xh-combobox-item-indicator-fg, var(--xh-_combobox-accent)));
+    --xh-collection-indicator-fg-selected-hover: var(--xh-combobox-item-check-fg, var(--xh-combobox-item-indicator-fg, var(--xh-_combobox-accent)));
+    --xh-collection-indicator-fg-selected-highlight: var(--xh-combobox-item-check-fg, var(--xh-combobox-item-indicator-fg, var(--xh-_combobox-accent)));
+    --xh-collection-indicator-fg-selected-pressed: var(--xh-combobox-item-check-fg, var(--xh-combobox-item-indicator-fg, var(--xh-_combobox-accent)));
+
+    /* 行高留出文字的上下伸展空间，行内那层 overflow:hidden 才不会把字削掉 */
+    line-height: var(--xh-combobox-item-leading, var(--xh-leading-normal));
+    white-space: nowrap;
+    user-select: none;
+  }
+
+  /* 候选按需收起（作者自己藏掉某几条）时要让位，家族给了 display 就得补这条 */
+  .xh-scope-combobox[data-part='item'][hidden] {
+    display: none;
+  }
+
+  /* 正文落在家族网格的 text 列；网格项默认最小尺寸是内容尺寸，不归零则长文本把行撑破、省略号轮不上 */
+  .xh-scope-combobox[data-part='item-text'] {
+    min-inline-size: 0;
+    overflow: hidden;
+    white-space: nowrap;
+    text-overflow: ellipsis;
+  }
+
+  .xh-scope-combobox[data-part='item-text'][hidden] {
+    display: none;
+  }
+
+  /* 勾选标记落在家族网格的 indicator 列，只在选中项上显形（家族按 aria-selected / data-state=checked 给）；
+     未选中时占位不塌，切换选中不引起行宽抖动。
+     盒与盒里的勾是指示符：盒按指示符档取尺，并在自己身上把 --xh-icon-size 改接到盒的尺，皮肤画的
+     兜底勾与作者塞进盒里的 XhIcon 读同一把尺、与盒同边长（勾选标记不是勾选格，不取 × 0.75，与 Select /
+     Listbox / Menu 族同口径）；不读 root / positioner 按档下发的 --xh-icon-size——那支只管作者放进条目里的
+     图标，按图标档取的 20px 比 16 / 14 的指示符档大一圈 */
+  .xh-scope-combobox[data-part='item-indicator'] {
+    --xh-icon-size: var(--xh-combobox-item-indicator-size, var(--xh-control-indicator-size));
+
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    inline-size: var(--xh-combobox-item-indicator-size, var(--xh-control-indicator-size));
+    block-size: var(--xh-combobox-item-indicator-size, var(--xh-control-indicator-size));
+  }
+
+  .xh-scope-combobox[data-part='item-indicator'][hidden] {
+    display: none;
+  }
+
+  /* 同上：没写内容就由皮肤画勾。尺寸读标记盒自己改接过的 --xh-icon-size：与盒同边长，随指示符档换档 */
+  .xh-scope-combobox[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;
+  }
+
+  /* 空态提示保持为 listbox 的同级 role=status；它只承载文字，表面由同格 content 统一绘制。 */
+  .xh-scope-combobox[data-part='empty'] {
+    /* 与带滤镜的 content 同属定位绘制层，按 DOM 顺序将状态文字画在表面之上。 */
+    position: relative;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    grid-area: 1 / 1;
+    padding-block: var(--xh-combobox-empty-py, var(--xh-space-3));
+    padding-inline: var(--xh-combobox-empty-px, var(--xh-_combobox-item-px));
+    color: var(--xh-combobox-empty-fg, var(--xh-material-frosted-fg-muted));
+    font-size: var(--xh-combobox-empty-font-size, var(--xh-_combobox-font-size));
+    line-height: var(--xh-leading-none);
+    text-align: center;
+    pointer-events: none;
+  }
+
+  /* 漏了这条，候选一有结果空态提示就永远撤不下去（上面那条 display 盖掉了 UA 的 [hidden] 规则） */
+  .xh-scope-combobox[data-part='empty'][hidden] {
+    display: none;
+  }
+
+  /* 在途占位与空态占同一个表面、两者不同屏；同样只承载状态文字。 */
+  .xh-scope-combobox[data-part='loading'] {
+    position: relative;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: var(--xh-_combobox-gap);
+    grid-area: 1 / 1;
+    padding-block: var(--xh-combobox-loading-py, var(--xh-space-3));
+    padding-inline: var(--xh-combobox-loading-px, var(--xh-_combobox-item-px));
+    color: var(--xh-combobox-loading-fg, var(--xh-material-frosted-fg-muted));
+    font-size: var(--xh-combobox-loading-font-size, var(--xh-_combobox-font-size));
+    line-height: var(--xh-leading-none);
+    text-align: center;
+    pointer-events: none;
+  }
+
+  .xh-scope-combobox[data-part='loading'][hidden] {
+    display: none;
+  }
+
+  /* 首次加载：文案前一枚加载环，由加载环配方画（连接层投影 data-xh-loading-ring 与 data-loading），
+     直径取所在尺寸档的图标档 */
+  .xh-scope-combobox[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));
+  }
+
+  /* 自动结构没收到状态文案时，空 status 不生成盒；打开着的空 listbox 也不画无意义表面。
+     closed 不命中：有文案的空态刚关闭时，content 仍要作为 Presence 宿主完成退场。 */
+  .xh-scope-combobox[data-part='empty']:empty,
+  .xh-scope-combobox[data-part='loading']:empty {
+    display: none;
+  }
+
+  .xh-scope-combobox[data-part='positioner']:not(:has(
+    > .xh-scope-combobox[data-part='empty']:not([hidden]):not(:empty),
+    > .xh-scope-combobox[data-part='loading']:not([hidden]):not(:empty)
+  )) > .xh-scope-combobox[data-part='content'][data-state='open']:empty {
+    visibility: hidden;
+  }
+
+  @media print {
+    /* 打印：定位层与遮罩是交互期才存在的东西，落到纸上只会盖住底下的正文。
+       收起写在这份皮肤里而不是 reset：reset 层排在组件层之前，组件层里任何一条 display 都压得住它。 */
+    .xh-scope-combobox[data-part='positioner'] {
+      display: none;
+    }
+  }
+
+  @media (forced-colors: active) {
+    /* 兜底字形是 mask 挖出来的一块底色，这一档里底色被系统换成 Canvas，字形跟着消失。
+       字形退出强制换色、直接写系统色（不能取 currentColor：退出强制换色的伪元素读到的是被系统换掉之前的作者色）：
+       按钮面上取 ButtonText，悬停与按下时家族把按钮涂成 Highlight、字形换 HighlightText；
+       条目面上取 CanvasText；按下与没被高亮时的悬停，家族把条目涂成 Highlight，字形换 HighlightText；
+       禁用取 GrayText */
+    .xh-scope-combobox:is([data-part='trigger'], [data-part='clear-trigger']):empty::before {
+      forced-color-adjust: none;
+      background-color: ButtonText;
+    }
+
+    .xh-scope-combobox[data-part='item-indicator']:empty::before {
+      forced-color-adjust: none;
+      background-color: CanvasText;
+    }
+
+    .xh-scope-combobox:is([data-part='trigger'], [data-part='clear-trigger']):not([data-disabled]):not([data-loading]):is(:hover, :active, [data-pressed]):empty::before,
+    .xh-scope-combobox[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-combobox[data-part='item-indicator']:empty::before {
+      background-color: HighlightText;
+    }
+
+    .xh-scope-combobox:is([data-part='trigger'], [data-part='clear-trigger'])[data-disabled]:empty::before,
+    .xh-scope-combobox[data-part='item']:is([aria-disabled='true'], [data-disabled]) .xh-scope-combobox[data-part='item-indicator']:empty::before {
+      background-color: GrayText;
+    }
+  }
+}