@xihan-ui/styles 2.1.0 → 3.1.0

package/css/cascader.css

@@ -7,9 +7,12 @@
 @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 探一次，取不到就说明这份皮肤没被引入。 */
@@ -208,6 +211,18 @@
     color: var(--xh-fg-disabled);
   }
 
+  /* 标签行：触发器里收着可见标签与 +N 那一枚的一行，行里每一枚都是 tag（data-scope="tag"），样子归 tag.css；
+     行怎么排、标签怎么进出归标签行家族配方（family/tag-list.css），这里只把使用者的间距槽接进去 */
+  [data-scope='cascader'][data-part='tag-list'] {
+    --xh-tag-list-gap: var(--xh-cascader-tag-list-gap, var(--xh-space-1));
+  }
+
+  /* 标签行露面时 value-text 让位：两者是触发器里的同一格，占位文字与标签不同屏。
+     value-text 留在 DOM 里，trigger 的可及名仍从它取到完整的选中路径文本 */
+  [data-scope='cascader'][data-part='trigger']:has([data-part='tag-list']:not([hidden])) [data-part='value-text'] {
+    display: none;
+  }
+
   /* 有值时清空钮顶上来，箭头让位：两个图标并排堆着，用户分不清点哪个。
      判据查的是盒里此刻真有一颗没收起的清空钮，不是「有没有值」——
      作者没摆清空钮时箭头照常留着，不然让了位没人接，指示符整个消失 */
@@ -221,7 +236,7 @@
     align-items: center;
     justify-content: center;
     color: var(--xh-cascader-indicator-fg, var(--xh-fg-muted));
-    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='cascader'][data-part='indicator'][hidden] {
@@ -279,22 +294,24 @@
   }
 
   /* 级联的骨架就在这一条上：列沿书写方向并排，一层一列。
-     横向随列数增减，因此不设固定宽度，只给每列自己的宽度 */
+     面板型浮层：每一列按条目的自然宽度，不随字段盒拉伸，面板随列数伸展。
+     面板含多列，材质取 floating：实体底 + border-default 描边 + 浮起投影，不透景 */
   [data-scope='cascader'][data-part='content'] {
     position: relative;
     display: flex;
     flex-direction: row;
     align-items: stretch;
-    /* 静态档与落位后的可用宽度取小：列多起来时外框自己就宽过了可用区，
-       盒内不产生溢出，下面那条 overflow-x 便一直没事可做，最右那一列落在屏外点不到 */
-    max-inline-size: min(var(--xh-cascader-content-max-w, var(--xh-overlay-max-w-xl)), var(--xh-_cascader-available-w));
-    border: var(--xh-stroke-thin) solid var(--xh-cascader-content-border, var(--xh-material-frosted-border));
+    /* 面板的下界：搜索视图与两个占位没有列托底，靠这一条不缩成一小块；可用区比它还窄时让位。
+       可用宽写在定位层上、沿继承流下来 */
+    min-inline-size: min(var(--xh-cascader-content-min-w, var(--xh-overlay-menu-min-w)), var(--xh-_cascader-available-w));
+    /* 列多起来时外框宽过可用区就收成可用宽度，溢出的列交给下面那条 overflow-x；
+       缺省不封顶，作者要封顶写 --xh-cascader-content-max-w */
+    max-inline-size: min(var(--xh-cascader-content-max-w, var(--xh-_cascader-available-w)), var(--xh-_cascader-available-w));
+    border: var(--xh-stroke-thin) solid var(--xh-cascader-content-border, var(--xh-border-default));
     border-radius: var(--xh-cascader-content-radius, var(--xh-shape-overlay));
-    background: var(--xh-cascader-content-bg, var(--xh-material-frosted-bg));
-    color: var(--xh-cascader-content-fg, var(--xh-material-frosted-fg));
-    box-shadow: var(--xh-cascader-content-shadow, var(--xh-material-frosted-shadow));
-    -webkit-backdrop-filter: var(--xh-cascader-content-backdrop, var(--xh-material-frosted-backdrop));
-    backdrop-filter: var(--xh-cascader-content-backdrop, var(--xh-material-frosted-backdrop));
+    background: var(--xh-cascader-content-bg, var(--xh-bg-surface));
+    color: var(--xh-cascader-content-fg, var(--xh-fg-default));
+    box-shadow: var(--xh-cascader-content-shadow, var(--xh-elevation-floating));
     /* 列多到放不下时整体横向滚动；纵向溢出归每一列自己 */
     overflow-x: auto;
     /* 浮层滚动面：滚到头不把页面一起带走 */
@@ -305,18 +322,6 @@
     --xh-scrollbar-track-bg: transparent;
   }
 
-  /* 唯一外壳的内侧顶光；列和状态部件不另画材质面。 */
-  [data-scope='cascader'][data-part='content']::before {
-    content: '';
-    position: absolute;
-    inset-block-start: 0;
-    inset-inline: 0;
-    block-size: var(--xh-stroke-thin);
-    border-radius: inherit;
-    background: var(--xh-cascader-content-highlight, var(--xh-material-frosted-highlight));
-    pointer-events: none;
-  }
-
   /* 这里刻意没有 [data-part='content'][hidden] { display: none }，与 dialog 一致：
      收起态连接层会给 content 打 hidden，而上面那条 display 正是要盖掉 UA 的
      [hidden]{display:none}——退场动画得先能播。presence 读的是 content 的 animationName，
@@ -328,7 +333,8 @@
     outline: none;
   }
 
-  [data-scope='cascader'][data-part='content'][data-state='open'] {
+  /* 挂载时就开着的那一段（data-instant）属于首帧，直接呈现 */
+  [data-scope='cascader'][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);
   }
 
@@ -345,13 +351,21 @@
     flex: none;
     flex-direction: column;
     gap: var(--xh-cascader-column-gap, var(--xh-list-option-gap));
-    min-inline-size: var(--xh-cascader-column-min-w, 7rem);
+    /* 每一列按条目的自然宽度，受菜单的下界托底；长选项撑到条目的上限为止，余下的在条目里截断 */
+    min-inline-size: var(--xh-cascader-column-min-w, var(--xh-overlay-menu-min-w));
     block-size: var(--xh-cascader-column-h, var(--xh-viewport-h-sm));
     padding-block: var(--xh-cascader-column-py, var(--xh-space-1));
     padding-inline: var(--xh-cascader-column-px, var(--xh-space-1));
     overflow-y: auto;
     /* 浮层滚动面：滚到头不把页面一起带走 */
     overscroll-behavior: contain;
+    transition: opacity var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  /* 刷新：已有候选时后台在取，保留上一帧，列与候选列表按 micro 淡下，数据到了再淡回；在途占位此时让位。
+     淡的是列不是面：content 是整块浮起面，整块淡下去面就透了 */
+  [data-scope='cascader'][data-part='content'][aria-busy='true'] > [data-scope='cascader']:is([data-part='column'], [data-part='search-list']) {
+    opacity: var(--xh-state-disabled-opacity);
   }
 
   /* 展开路径砍短了这一列就收起来。display 盖掉了 UA 的 [hidden]{display:none}，
@@ -364,7 +378,7 @@
      用逻辑属性，rtl 下自动跑到另一侧。每列后面紧跟着它自己的竖条节点，相邻选择器接不到下一列，
      按「前面有过列」取后续的列 */
   [data-scope='cascader'][data-part='column'] ~ [data-scope='cascader'][data-part='column'] {
-    border-inline-start: var(--xh-stroke-thin) solid var(--xh-cascader-column-divider, var(--xh-material-frosted-separator));
+    border-inline-start: var(--xh-stroke-thin) solid var(--xh-cascader-column-divider, var(--xh-material-solid-separator));
   }
 
   [data-scope='cascader'][data-part='column']:not([tabindex='0']):focus-visible {
@@ -393,7 +407,7 @@
     display: block;
     padding-block: var(--xh-cascader-group-label-py, var(--xh-space-1));
     padding-inline: var(--xh-cascader-group-label-px, var(--xh-_cascader-row-px));
-    color: var(--xh-cascader-group-label-fg, var(--xh-material-frosted-fg-muted));
+    color: var(--xh-cascader-group-label-fg, var(--xh-fg-muted));
     font-size: var(--xh-cascader-group-label-font-size, var(--xh-text-caption-size));
     font-weight: var(--xh-cascader-group-label-font-weight, var(--xh-font-weight-medium));
     line-height: var(--xh-leading-none);
@@ -417,7 +431,7 @@
     --xh-collection-inline-padding: var(--xh-cascader-item-px, var(--xh-_cascader-row-px));
     --xh-collection-gap: var(--xh-cascader-item-gap, var(--xh-_cascader-gap));
     --xh-collection-font-size: var(--xh-cascader-item-font-size, var(--xh-_cascader-font-size));
-    --xh-collection-radius: var(--xh-cascader-item-radius, var(--xh-shape-control));
+    --xh-collection-radius: var(--xh-cascader-item-radius, var(--xh-shape-inset));
     --xh-collection-glyph-size: var(--xh-cascader-icon-size, var(--xh-_collection-glyph-size));
     --xh-collection-fg-rest: var(--xh-cascader-item-fg, var(--xh-material-frosted-fg));
     --xh-collection-fg-hover: var(--xh-cascader-item-fg, var(--xh-material-frosted-fg));
@@ -463,9 +477,33 @@
     display: none;
   }
 
-  /* 一列开幕：条目自上而下逐条淡入。列从 hidden 转回来、或换了展开路径把另一批条目放出来时，
-     这段动画重新起跑。backwards 让每条在自己那份延迟里保持起始帧 */
-  [data-scope='cascader'][data-part='column'] [data-part='item'] {
+  /* 懒分支取数失败不预设错误面：失败由那一列里的提示与重试钮说明，父条目仍是一条可激活的普通条目，
+     与树选择同一口径。家族按 data-error 给的告警面（危险色字压在危险色淡底上，对比不到 4.5:1）在这里映射回常态 */
+  [data-scope='cascader'][data-part='item'][data-error] {
+    --xh-collection-bg-error: transparent;
+    --xh-collection-fg-error: var(--xh-cascader-item-fg, var(--xh-material-frosted-fg));
+    --xh-collection-description-fg-error: var(--xh-material-frosted-fg-muted);
+    --xh-collection-indicator-fg-error: var(--xh-_cascader-accent);
+    --xh-collection-outline-error: transparent;
+  }
+
+  /* 取数失败的条目仍可激活（点行或 Enter 重试），而家族的悬停、高亮、展开路径与按下几段都排除了 [data-error]：
+     在家族解算点上把同一阶梯接回——悬停、键盘高亮与展开路径 100 档，按下 200 档并走按下时长 */
+  [data-scope='cascader'][data-part='item'][data-error]:not([data-disabled]):is(:hover, [data-highlighted], [data-in-path]) {
+    --xh-_collection-bg: var(--xh-cascader-item-bg-hover, var(--xh-bg-subtle));
+  }
+
+  [data-scope='cascader'][data-part='item'][data-error]:not([data-disabled]):is(:active, [data-pressed]) {
+    --xh-_collection-bg: var(--xh-cascader-item-bg-pressed, var(--xh-bg-subtle-hover));
+
+    transition-duration: var(--xh-motion-duration-press);
+    transition-timing-function: var(--xh-motion-ease-press);
+  }
+
+  /* 一列开幕：条目自上而下逐条淡入。只在列头一次出现时播（浮层展开、此前收着的子列铺出来）；
+     列此前就在、展开路径换到同列另一个父项时（悬停扫过），连接层给露面的条目标 data-instant，
+     换内容不重播。backwards 让每条在自己那份延迟里保持起始帧 */
+  [data-scope='cascader'][data-part='column'] [data-part='item']:not([data-instant]) {
     animation: xh-fade-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter) backwards;
   }
 
@@ -553,7 +591,9 @@
   }
 
   /* 没写内容就由皮肤画勾；作者往部件里塞了自己的图形，这条规则即不命中。
-     尺寸读标记盒自己改接过的 --xh-icon-size：与盒同边长，随指示符档换档（见上面标记盒那块） */
+     尺寸读标记盒自己改接过的 --xh-icon-size：与盒同边长，随指示符档换档（见上面标记盒那块）。
+     勾与半选杠叠成两层遮罩，按状态只换两层的尺寸：离开半选淡出的那一段里横杠留着，
+     淡出播完才换回勾——不在淡出途中闪出一枚勾 */
   [data-scope='cascader'][data-part='item-indicator']:empty::before {
     content: '';
     display: inline-block;
@@ -561,25 +601,27 @@
     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;
+    -webkit-mask: var(--xh-glyph-mark-check) center / 100% 100% no-repeat, var(--xh-glyph-mark-minus) center / 0 0 no-repeat;
+    mask: var(--xh-glyph-mark-check) center / 100% 100% no-repeat, var(--xh-glyph-mark-minus) center / 0 0 no-repeat;
+    transition:
+      -webkit-mask-size 0s var(--xh-motion-duration-micro),
+      mask-size 0s var(--xh-motion-duration-micro);
+  }
+
+  [data-scope='cascader'][data-part='item-indicator'][data-state='checked']:empty::before {
+    transition-delay: 0s;
   }
 
   /* 级联勾选的半选态只在皮肤自绘（:empty）时露面画横杠：
      作者塞了自己的选中图形时，半选放出来会顶着一个语义相反的勾，表达交还作者 */
   [data-scope='cascader'][data-part='item-indicator'][data-state='indeterminate']:empty {
-    visibility: visible;
+    opacity: 1;
   }
 
   [data-scope='cascader'][data-part='item-indicator'][data-state='indeterminate']: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-minus) center / contain no-repeat;
-    mask: var(--xh-glyph-mark-minus) center / contain no-repeat;
+    -webkit-mask-size: 0 0, 100% 100%;
+    mask-size: 0 0, 100% 100%;
+    transition-delay: 0s;
   }
 
   /* 家族按行的禁用降级标记色；半选横线也一并跟着 */
@@ -592,13 +634,24 @@
     flex-wrap: wrap;
   }
 
+  /* 面板内嵌的搜索框：通栏一行，控件高与字号随尺寸档，只画一道面内分隔的下划线（取面材质的分隔令牌）；
+     重置与占位前景由字段家族按 data-xh-field-input 给，占位与值文本的占位同一支组件槽 */
   [data-scope='cascader'][data-part='input'] {
-    flex-basis: 100%;
-    min-inline-size: 0;
-    padding-block: var(--xh-cascader-input-py, var(--xh-space-2));
-    padding-inline: var(--xh-cascader-input-px, var(--xh-control-px-md));
+    --xh-field-placeholder-fg: var(--xh-cascader-placeholder-fg, var(--xh-fg-subtle));
+
+    /* 搜索框不参与定宽，面板宽度只由列（搜索视图里是候选列表）撑出：换行的 flex 容器按内容定宽时
+       把各项的固有宽度相加，原生输入框自带约 20 个字符的固有宽，内衬也算在里面。
+       内容宽取 0，落位后由 min-inline-size 铺满整行；内衬由等量的负外边距在宽度贡献里抵掉，
+       盒子本身仍铺满整行，下一项照样折到下一行 */
+    flex: none;
+    inline-size: 0;
+    min-inline-size: 100%;
+    margin-inline-end: calc(-2 * var(--xh-cascader-input-px, var(--xh-_cascader-px)));
+    block-size: var(--xh-cascader-input-h, var(--xh-_cascader-h));
+    padding-block: 0;
+    padding-inline: var(--xh-cascader-input-px, var(--xh-_cascader-px));
     border: none;
-    border-block-end: var(--xh-stroke-thin) solid var(--xh-cascader-search-divider, var(--xh-material-frosted-separator));
+    border-block-end: var(--xh-stroke-thin) solid var(--xh-cascader-search-divider, var(--xh-material-solid-separator));
     border-start-start-radius: inherit;
     border-start-end-radius: inherit;
     background: none;
@@ -608,6 +661,11 @@
     line-height: var(--xh-leading-normal);
   }
 
+  /* 聚焦不画环：插入符就是焦点指示。框没有外壳，全局那圈键盘焦点环只会压在通栏一行上 */
+  [data-scope='cascader'][data-part='input']:focus-visible {
+    outline: none;
+  }
+
   [data-scope='cascader'][data-part='input'][hidden] {
     display: none;
   }
@@ -639,6 +697,7 @@
     overflow-y: auto;
     /* 浮层滚动面：滚到头不把页面一起带走 */
     overscroll-behavior: contain;
+    transition: opacity var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
   }
 
   [data-scope='cascader'][data-part='search-list'][hidden] {
@@ -663,7 +722,7 @@
     --xh-collection-inline-padding: var(--xh-cascader-item-px, var(--xh-_cascader-row-px));
     --xh-collection-gap: var(--xh-cascader-item-gap, var(--xh-_cascader-gap));
     --xh-collection-font-size: var(--xh-cascader-item-font-size, var(--xh-_cascader-font-size));
-    --xh-collection-radius: var(--xh-cascader-item-radius, var(--xh-shape-control));
+    --xh-collection-radius: var(--xh-cascader-item-radius, var(--xh-shape-inset));
     --xh-collection-fg-rest: var(--xh-cascader-item-fg, var(--xh-material-frosted-fg));
     --xh-collection-fg-hover: var(--xh-cascader-item-fg, var(--xh-material-frosted-fg));
     --xh-collection-fg-keyboard-highlight: var(--xh-cascader-item-fg, var(--xh-material-frosted-fg));
@@ -718,19 +777,26 @@
     block-size: var(--xh-cascader-item-indicator-size, var(--xh-control-indicator-size));
     translate: 0 -50%;
     background-color: var(--xh-cascader-item-indicator-fg, var(--xh-_cascader-accent));
-    visibility: hidden;
-    -webkit-mask: var(--xh-glyph-mark-check) center / contain no-repeat;
-    mask: var(--xh-glyph-mark-check) center / contain no-repeat;
+    opacity: 0;
+    -webkit-mask: var(--xh-glyph-mark-check) center / 100% 100% no-repeat, var(--xh-glyph-mark-minus) center / 0 0 no-repeat;
+    mask: var(--xh-glyph-mark-check) center / 100% 100% no-repeat, var(--xh-glyph-mark-minus) center / 0 0 no-repeat;
+    /* 与列里的对号同一条淡变；离开半选时横杠留到淡出播完再换回勾 */
+    transition:
+      opacity var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
+      -webkit-mask-size 0s var(--xh-motion-duration-micro),
+      mask-size 0s var(--xh-motion-duration-micro);
   }
 
   [data-scope='cascader'][data-part='search-item'][data-state='checked']::after {
-    visibility: visible;
+    opacity: 1;
+    transition-delay: 0s;
   }
 
   [data-scope='cascader'][data-part='search-item'][data-state='indeterminate']::after {
-    visibility: visible;
-    -webkit-mask-image: var(--xh-glyph-mark-minus);
-    mask-image: var(--xh-glyph-mark-minus);
+    opacity: 1;
+    -webkit-mask-size: 0 0, 100% 100%;
+    mask-size: 0 0, 100% 100%;
+    transition-delay: 0s;
   }
 
   [data-scope='cascader'][data-part='search-item'][data-disabled]::after {
@@ -752,10 +818,8 @@
     flex: 1 1 100%;
     align-items: center;
     justify-content: center;
-    min-inline-size: var(--xh-cascader-column-min-w, 7rem);
-    min-block-size: var(--xh-cascader-empty-min-h, 5rem);
     padding: var(--xh-cascader-empty-p, var(--xh-space-3));
-    color: var(--xh-cascader-empty-fg, var(--xh-material-frosted-fg-muted));
+    color: var(--xh-cascader-empty-fg, var(--xh-fg-muted));
     font-size: var(--xh-cascader-item-font-size, var(--xh-_cascader-font-size));
   }
 
@@ -769,10 +833,9 @@
     flex: 0 0 100%;
     align-items: center;
     justify-content: center;
-    min-inline-size: var(--xh-cascader-loading-min-w, var(--xh-cascader-column-min-w, 7rem));
-    min-block-size: var(--xh-cascader-loading-min-h, 5rem);
+    gap: var(--xh-_cascader-gap);
     padding: var(--xh-cascader-loading-p, var(--xh-space-3));
-    color: var(--xh-cascader-loading-fg, var(--xh-material-frosted-fg-muted));
+    color: var(--xh-cascader-loading-fg, var(--xh-fg-muted));
     font-size: var(--xh-cascader-loading-font-size, var(--xh-_cascader-font-size));
   }
 
@@ -780,6 +843,41 @@
     display: none;
   }
 
+  /* 懒分支那一列：条目还没取回时列里只有一句次要文字（在途或失败），失败时下面跟一颗重试钮；
+     三块同一时刻至多露一种，露哪一块归连接层。文字的观感与整浮层的在途占位同一档 */
+  [data-scope='cascader'][data-part='branch-loading'],
+  [data-scope='cascader'][data-part='branch-error'] {
+    display: flex;
+    flex: none;
+    align-items: center;
+    justify-content: center;
+    padding-block: var(--xh-cascader-branch-status-py, var(--xh-space-3));
+    padding-inline: var(--xh-cascader-branch-status-px, var(--xh-_cascader-row-px));
+    color: var(--xh-cascader-branch-status-fg, var(--xh-material-frosted-fg-muted));
+    font-size: var(--xh-cascader-branch-status-font-size, var(--xh-_cascader-font-size));
+    text-align: center;
+  }
+
+  /* 重试钮是 Action Control 家族的 text ghost 档，盒与按压都归家族；这里只让它在列里居中 */
+  [data-scope='cascader'][data-part='branch-retry-trigger'] {
+    align-self: center;
+  }
+
+  [data-scope='cascader'][data-part='branch-loading'][hidden],
+  [data-scope='cascader'][data-part='branch-error'][hidden],
+  [data-scope='cascader'][data-part='branch-retry-trigger'][hidden] {
+    display: none;
+  }
+
+  /* 首次加载：文案前一枚加载环，由加载环配方画（连接层投影 data-xh-loading-ring 与 data-loading），
+     直径取所在尺寸档的图标档 */
+  [data-scope='cascader'][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));
+  }
+
   /* 底栏在场时浮层壳允许换行：列照旧并排在第一行，底栏占满一整行落在列下面。
      没写底栏的浮层不命中这条，列多到放不下时仍是整体横向滚动 */
   [data-scope='cascader'][data-part='content']:has(> [data-part='footer']) {
@@ -818,17 +916,35 @@
   }
 
   @media (forced-colors: active) {
-    /* 蒙版底色会被系统改成 Canvas 而消失；明确用系统前景保住箭头、对号与半选横线。 */
+    /* 蒙版底色会被系统改成 Canvas 而消失；明确用系统前景保住箭头、对号与半选横线。
+       按下与没被高亮时的悬停，家族把条目涂成 Highlight，字形跟着换 HighlightText。
+       触发器里的下拉箭头落在字段面上取 CanvasText，字段禁用时取 GrayText；
+       清除钮是按钮面，取 ButtonText，悬停与按下换 HighlightText，禁用取 GrayText */
     [data-scope='cascader'][data-part='item'][data-branch]::after,
     [data-scope='cascader'][data-part='item-indicator']:empty::before,
-    [data-scope='cascader'][data-part='search-item']::after {
+    [data-scope='cascader'][data-part='search-item']::after,
+    [data-scope='cascader'][data-part='indicator']:empty::before {
       forced-color-adjust: none;
       background-color: CanvasText;
     }
 
+    [data-scope='cascader'][data-part='clear-trigger']:empty::before {
+      forced-color-adjust: none;
+      background-color: ButtonText;
+    }
+
+    [data-scope='cascader'][data-part='item'][data-branch]:not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error]):is(:active, [data-pressed], :hover:not(:focus-visible, [data-highlighted]))::after,
+    [data-scope='cascader'][data-part='item']:not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error]):is(:active, [data-pressed], :hover:not(:focus-visible, [data-highlighted])) [data-scope='cascader'][data-part='item-indicator']:empty::before,
+    [data-scope='cascader'][data-part='search-item']:not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error]):is(:active, [data-pressed], :hover:not(:focus-visible, [data-highlighted]))::after,
+    [data-scope='cascader'][data-part='clear-trigger']:not([data-disabled]):not([data-loading]):is(:hover, :active, [data-pressed]):empty::before {
+      background-color: HighlightText;
+    }
+
     [data-scope='cascader'][data-part='item'][data-branch][data-disabled]::after,
     [data-scope='cascader'][data-part='item-indicator'][data-disabled]:empty::before,
-    [data-scope='cascader'][data-part='search-item'][data-disabled]::after {
+    [data-scope='cascader'][data-part='search-item'][data-disabled]::after,
+    [data-scope='cascader'][data-part='control'][data-disabled] [data-scope='cascader'][data-part='indicator']:empty::before,
+    [data-scope='cascader'][data-part='clear-trigger'][data-disabled]:empty::before {
       background-color: GrayText;
     }
   }

package/css/checkbox-group.css

@@ -6,6 +6,8 @@
 /* 定义 checkbox group 样式。 */
 
 @import '../family/action-control.css';
+@import '../family/check-mark.css';
+@import '../family/choice-card.css';
 
 @layer xihan.components {
   /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
@@ -26,8 +28,9 @@
     /* 作者塞进指示符槽的图标和皮肤画的兜底字形共用盒比例（与 checkbox 同一把尺）；显式 icon-size 仍可覆盖 */
     --xh-icon-size: var(--xh-checkbox-group-icon-size, var(--xh-_checkbox-group-glyph));
 
-    /* 勾中的填色随语气走；没写 data-tone 时退回品牌色 */
-    --xh-_checkbox-group-accent: var(--xh-_tone, var(--xh-bg-brand));
+    /* 勾中的填色随语气走，与独立 Checkbox 同一支：选中态是小面积控件边界，取保证 3:1 的语气 control 色；
+       没写 data-tone 时退回品牌色 */
+    --xh-_checkbox-group-accent: var(--xh-_tone-border-control, var(--xh-bg-brand));
     --xh-_checkbox-group-on-accent: var(--xh-_tone-on, var(--xh-fg-on-brand));
     /* 方框是字段家族的控制盒（字段静息形态）：透明底 + --xh-border-control 描边 + 无影，不消费海拔与顶光 */
     --xh-_checkbox-group-bg: var(--xh-checkbox-group-indicator-bg, transparent);
@@ -71,6 +74,17 @@
     align-items: center;
   }
 
+  /* card 形态：卡片撑满竖排的一列；横排时各卡等分一行、按内容等高，窄到放不下两张就折到下一行 */
+  [data-scope='checkbox-group'][data-part='root'][data-variant='card'] {
+    align-items: stretch;
+  }
+
+  [data-scope='checkbox-group'][data-part='root'][data-variant='card'][data-orientation='horizontal']
+    > [data-scope='checkbox-group'][data-part='item'] {
+    flex: 1 1 0;
+    min-inline-size: min(var(--xh-control-min-w), 100%);
+  }
+
   /* 集合标题：14 / 500 / fg-muted，字号不随 size 档 */
   [data-scope='checkbox-group'][data-part='label'] {
     color: var(--xh-checkbox-group-label-fg, var(--xh-fg-muted));
@@ -122,7 +136,7 @@
      家族的 :hover / 按压块不排 readonly，只能从槽上收回；排掉禁用项是因为这条选择器权重高过家族的禁用块，
      不排就会把 not-allowed 覆盖回 default */
   [data-scope='checkbox-group'][data-part='root'][data-readonly]
-    [data-scope='checkbox-group'][data-part='item']:not([data-disabled]) {
+    [data-scope='checkbox-group'][data-part='item']:not([data-disabled]):not([data-xh-choice-card]) {
     --xh-action-bg-hover: transparent;
     --xh-action-bg-pressed: transparent;
     --xh-action-cursor-rest: default;
@@ -203,67 +217,9 @@
     --xh-_checkbox-group-bg: var(--xh-checkbox-group-indicator-bg-checked-pressed, var(--xh-_tone-active, var(--xh-bg-brand-active)));
   }
 
-  /* 勾号由皮肤补，作者不必自己往 indicator 里塞字符 */
-  [data-scope='checkbox-group'][data-part='indicator'][data-state='checked']: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;
-  }
-
-  /* 全选格的三态：checked 打勾、indeterminate 打横杠、unchecked 留空。
-     indeterminate 就是读屏听到的 aria-checked=mixed，两者同源，样式只认 data-state。
-
-     字形走 ::after 而不是画方框的那颗 ::before：mask 会把所在元素的描边与底色一并裁成
-     字形的轮廓，写在 ::before 上就等于把方框本身裁没了，只剩一枚白勾。条目那一侧是
-     真实节点当方框、它的 ::before 当字形的两层结构，这里 anatomy 到 trigger 为止、
-     没有第二个节点，只能用第二个伪元素补上那一层。
-     方框是行首那颗 ::before、宽度即指示符尺寸，所以字形按「盒与字形的宽度差之半」
-     内推即落在圆心；纵向靠 inset-block: 0 + margin-block: auto 居中。
-     font-size 与 ::before 同值，--xh-icon-size 的 1em 兜底才和条目那侧量得一样大 */
-  [data-scope='checkbox-group'][data-part='select-all-trigger'][data-state='checked']::after {
-    content: '';
-    position: absolute;
-    inset-block: 0;
-    inset-inline-start: 0;
-    margin-block: auto;
-    margin-inline-start: calc(
-      (
-        var(--xh-checkbox-group-indicator-size, var(--xh-_checkbox-group-box)) -
-          var(--xh-icon-size, var(--xh-glyph-size-text))
-      ) / 2
-    );
-    inline-size: var(--xh-icon-size, var(--xh-glyph-size-text));
-    block-size: var(--xh-icon-size, var(--xh-glyph-size-text));
-    background-color: var(--xh-checkbox-group-indicator-fg, var(--xh-_checkbox-group-on-accent));
-    font-size: var(--xh-checkbox-group-indicator-font-size, var(--xh-_checkbox-group-glyph));
-    -webkit-mask: var(--xh-glyph-mark-check) center / contain no-repeat;
-    mask: var(--xh-glyph-mark-check) center / contain no-repeat;
-  }
-
-  [data-scope='checkbox-group'][data-part='select-all-trigger'][data-state='indeterminate']::after {
-    content: '';
-    position: absolute;
-    inset-block: 0;
-    inset-inline-start: 0;
-    margin-block: auto;
-    margin-inline-start: calc(
-      (
-        var(--xh-checkbox-group-indicator-size, var(--xh-_checkbox-group-box)) -
-          var(--xh-icon-size, var(--xh-glyph-size-text))
-      ) / 2
-    );
-    inline-size: var(--xh-icon-size, var(--xh-glyph-size-text));
-    block-size: var(--xh-icon-size, var(--xh-glyph-size-text));
-    background-color: var(--xh-checkbox-group-indicator-fg, var(--xh-_checkbox-group-on-accent));
-    font-size: var(--xh-checkbox-group-indicator-font-size, var(--xh-_checkbox-group-glyph));
-    -webkit-mask: var(--xh-glyph-mark-minus) center / contain no-repeat;
-    mask: var(--xh-glyph-mark-minus) center / contain no-repeat;
-  }
+  /* 方框里的勾与全选格的三态标记（checked 打勾、indeterminate 打横杠、unchecked 留空）由勾选标记配方画：
+     常驻、按状态淡变并轻缩放。条目的方框是真实节点，标记是它的 ::before；全选格的 anatomy 到 trigger
+     为止，方框只能是行首那颗 ::before，标记是 ::after、叠在方框正中——两支桥接槽写在 trigger 上 */
 
   /* 校验失败标在每个方框上：root 上的 data-invalid 是唯一出处，条目自己不带这个属性 */
   [data-scope='checkbox-group'][data-part='root'][data-invalid]
@@ -283,11 +239,43 @@
     color: var(--xh-checkbox-group-indicator-fg-disabled, var(--xh-fg-disabled));
   }
 
+  /* 全选格的标记画在 ::after 上，禁用色经桥接槽给，与条目方框里置灰的勾同色 */
+  [data-scope='checkbox-group'][data-part='select-all-trigger'][data-disabled] {
+    --xh-check-mark-fg: var(--xh-checkbox-group-indicator-fg-disabled, var(--xh-fg-disabled));
+  }
+
   [data-scope='checkbox-group'][data-part='item-text'] {
     color: inherit;
     user-select: none;
   }
 
+  /* 卡片的文案是卡的标题：取标签字重，与说明拉开层级 */
+  [data-scope='checkbox-group'][data-part='item'][data-xh-choice-card] > [data-scope='checkbox-group'][data-part='item-text'] {
+    font-weight: var(--xh-checkbox-group-card-title-font-weight, var(--xh-text-label-weight));
+  }
+
+  /* 说明是次级文字：13 / fg-muted / 正文行高，不随选中与语气换色；落在文案下方同一列。
+     列表形态的条目带了说明时同样排成两行，行首的方框对齐第一行 */
+  [data-scope='checkbox-group'][data-part='item-description'] {
+    grid-column: 2;
+    color: var(--xh-checkbox-group-item-description-fg, var(--xh-fg-muted));
+    font-size: var(--xh-checkbox-group-item-description-font-size, var(--xh-text-secondary-size));
+    font-weight: var(--xh-font-weight-regular);
+    line-height: var(--xh-leading-normal);
+    user-select: none;
+  }
+
+  [data-scope='checkbox-group'][data-part='item']:not([data-xh-choice-card]):has(> [data-scope='checkbox-group'][data-part='item-description']) {
+    display: grid;
+    grid-template-columns: auto minmax(0, 1fr);
+    align-items: center;
+    row-gap: var(--xh-checkbox-group-item-row-gap, var(--xh-space-1));
+  }
+
+  [data-scope='checkbox-group'][data-part='item'][data-disabled] > [data-scope='checkbox-group'][data-part='item-description'] {
+    color: var(--xh-checkbox-group-item-description-fg-disabled, var(--xh-fg-disabled));
+  }
+
   /* 全选格与条目同形（接 Action Control row 档 ghost、xs 命中地板、按下只换面不缩放，方框读宿主 host 槽），
      但字重加一档，读起来才不像又一个普通选项。它是普通元素而非原生控件（三态只有非原生控件表达得出），
      家族的禁用块同样只读 data-disabled。position 是给叠在方框上的那颗字形 ::after 当定位基准 */
@@ -308,6 +296,9 @@
     /* 行自己的面已由上面两支钉住，host 槽只对方框（::before）生效：200 → 300 */
     --xh-action-host-bg-hover: var(--xh-_checkbox-group-host-bg-hover);
     --xh-action-host-bg-pressed: var(--xh-_checkbox-group-host-bg-pressed);
+    /* 勾选标记叠在行首方框正中：方框边长与标记色交给配方 */
+    --xh-check-mark-box-size: var(--xh-checkbox-group-indicator-size, var(--xh-_checkbox-group-box));
+    --xh-check-mark-fg: var(--xh-checkbox-group-indicator-fg, var(--xh-_checkbox-group-on-accent));
 
     position: relative;
     inline-size: auto;
@@ -327,18 +318,12 @@
   }
 
   /* 家族 row 档在粗指针下用 ::after 把热区扩到 44px 高：条目按 24px 行 + 8px 间距密排，热区会压进相邻条目 2px、
-     指针落错行，A 档 24px 由 xs 地板保住（两者都不在 coarse-target 的 B 档名单）；勾中 / 半选时全选格的 ::after
-     是叠在方框上的字形，家族的热区 translate 会把它拖走，钉回原位（同 transfer select-all-trigger） */
+     指针落错行，A 档 24px 由 xs 地板保住（两者都不在 coarse-target 的 B 档名单）；全选格的 ::after 是叠在方框上的
+     勾选标记，热区由勾选标记配方逐项钉回 */
   @media (pointer: coarse) {
-    [data-scope='checkbox-group'][data-part='item']::after,
-    [data-scope='checkbox-group'][data-part='select-all-trigger']::after {
+    [data-scope='checkbox-group'][data-part='item']::after {
       min-block-size: 0;
     }
-
-    [data-scope='checkbox-group'][data-part='select-all-trigger']:is([data-state='checked'], [data-state='indeterminate'])::after {
-      min-block-size: 0;
-      translate: none;
-    }
   }
 
   /* 表单出口：连接层已经把整套视觉隐藏写进内联 style（absolute + 1px + clip-path），
@@ -357,22 +342,7 @@
     display: none;
   }
 
-  @media (forced-colors: active) {
-    /* 真实描边保留方框，系统前景重绘状态字形。 */
-    [data-scope='checkbox-group'][data-part='indicator'][data-state='checked']:empty::before,
-    [data-scope='checkbox-group'][data-part='select-all-trigger']:is([data-state='checked'], [data-state='indeterminate'])::after {
-      background-color: CanvasText;
-    }
-
-    [data-scope='checkbox-group'][data-part='item'][data-disabled]
-      [data-scope='checkbox-group'][data-part='indicator'][data-state='checked']:empty::before,
-    [data-scope='checkbox-group'][data-part='select-all-trigger'][data-disabled]:is(
-      [data-state='checked'],
-      [data-state='indeterminate']
-    )::after {
-      background-color: GrayText;
-    }
-  }
+  /* 强制色：真实描边保留方框，状态字形的系统前景由勾选标记配方给 */
 
   @media print {
     [data-scope='checkbox-group'][data-part='indicator'][data-state='checked'],