@xihan-ui/styles 1.0.0 → 2.0.0

package/css/command.css

@@ -0,0 +1,399 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 command 样式。 */
+
+/* 共享关键帧由 family/motion.css 提供，命令走 Collection Item 家族；本皮肤 @import 它们，单独引入仍成立。 */
+@import '../family/collection-item.css';
+@import '../family/motion.css';
+
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='command'] {
+    --xh-command-skin: 1;
+  }
+
+  /* 私有槽同时声明在定位层与面板上：面板被搬到 portal 落点，两处各自带一份 data-size，
+     谁先命中谁给出这一档的取值；条目、检索框与提示条都从面板继承下去 */
+  [data-scope='command']:is([data-part='positioner'], [data-part='content']) {
+    /* 条目外的字形（分组标题、底部提示条）按档取尺，缺省 md，随 data-size 换档；命令里的图标由家族随
+       data-xh-collection-size 下发（§6.5） */
+    --xh-icon-size: var(--xh-command-icon-size, var(--xh-glyph-size-md));
+
+    /* 尺寸档只换这六个私有槽，换档不必给每个部件各写一条选择器 */
+    --xh-_command-max-w: var(--xh-overlay-sheet-w-md);
+    --xh-_command-input-h: var(--xh-control-h-md);
+    --xh-_command-px: var(--xh-control-px-md);
+    --xh-_command-item-py: var(--xh-list-option-py-md);
+    --xh-_command-gap: var(--xh-control-gap-md);
+    --xh-_command-font-size: var(--xh-control-font-md);
+  }
+
+  /* 面板从上方落下来一小段：方向槽写在定位层上，面板继承过去喂给进场那支动画 */
+  [data-scope='command'][data-part='positioner'] {
+    --xh-_overlay-enter-down: 1;
+  }
+
+  /* —— 尺寸 —— */
+  /* 缺省档写在上面的基础规则里 */
+  [data-scope='command']:is([data-part='positioner'], [data-part='content'])[data-size='sm'] {
+    --xh-icon-size: var(--xh-command-icon-size, var(--xh-glyph-size-sm));
+    --xh-_command-max-w: var(--xh-overlay-sheet-w-sm);
+    --xh-_command-input-h: var(--xh-control-h-sm);
+    --xh-_command-px: var(--xh-control-px-sm);
+    --xh-_command-item-py: var(--xh-list-option-py-sm);
+    --xh-_command-gap: var(--xh-control-gap-sm);
+    --xh-_command-font-size: var(--xh-control-font-sm);
+  }
+
+  [data-scope='command']:is([data-part='positioner'], [data-part='content'])[data-size='lg'] {
+    --xh-icon-size: var(--xh-command-icon-size, var(--xh-glyph-size-lg));
+    --xh-_command-max-w: var(--xh-overlay-sheet-w-lg);
+    --xh-_command-input-h: var(--xh-control-h-lg);
+    --xh-_command-px: var(--xh-control-px-lg);
+    --xh-_command-item-py: var(--xh-list-option-py-lg);
+    --xh-_command-gap: var(--xh-control-gap-lg);
+    --xh-_command-font-size: var(--xh-control-font-lg);
+  }
+
+  /* —— 遮罩 —— */
+  [data-scope='command'][data-part='backdrop'] {
+    position: fixed;
+    inset: 0;
+    z-index: var(--xh-command-backdrop-layer, var(--xh-_layer, var(--xh-layer-modal)));
+    background: var(--xh-command-backdrop-bg, var(--xh-bg-overlay));
+  }
+
+  /* 同一层底色之上再糊背后的页面 */
+  [data-scope='command'][data-part='backdrop'][data-variant='blur'] {
+    backdrop-filter: blur(var(--xh-command-backdrop-blur, var(--xh-overlay-backdrop-blur)));
+  }
+
+  /* 去掉底色，只留下这一层吃指针：交互外关闭与滚动锁定照旧 */
+  [data-scope='command'][data-part='backdrop'][data-variant='transparent'] {
+    background: transparent;
+  }
+
+  [data-scope='command'][data-part='backdrop'][data-state='open'] {
+    animation: xh-fade-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
+  }
+
+  /* 退场补 forwards：动画播完到宿主真正卸载之间还有一帧，不定住终态遮罩会闪回全黑 */
+  [data-scope='command'][data-part='backdrop'][data-state='closed'] {
+    animation: xh-fade-out var(--xh-motion-duration-exit) var(--xh-motion-ease-exit) forwards;
+  }
+
+  /* —— 定位层 —— */
+  /* 面板不居中，贴着上沿放：下方留出来的空间全归结果列表，条目多的时候面板往下长，
+     不像居中那样两头一起挪、每敲一个字整块面板都在动 */
+  [data-scope='command'][data-part='positioner'] {
+    position: fixed;
+    inset: 0;
+    z-index: var(--xh-command-layer, var(--xh-_layer, var(--xh-layer-modal)));
+    display: flex;
+    align-items: flex-start;
+    justify-content: center;
+    /* 全屏定位层只负责排版，不截获页面指针；模态拦截由 backdrop 承担。 */
+    pointer-events: none;
+    padding-block-start: max(var(--xh-command-inset-block-start, var(--xh-space-8)), env(safe-area-inset-top));
+    padding-block-end: max(var(--xh-command-positioner-pb, var(--xh-space-4)), env(safe-area-inset-bottom));
+    padding-inline: max(
+      var(--xh-command-positioner-px, var(--xh-space-4)),
+      env(safe-area-inset-left),
+      env(safe-area-inset-right)
+    );
+  }
+
+  /* —— 面板 —— */
+  [data-scope='command'][data-part='content'] {
+    /* 结果列表的自绘条浮在内容之上：轨道不上底色，实色轨道会在面板右缘糊一条竖灰带 */
+    --xh-scrollbar-track-bg: transparent;
+
+    position: relative;
+    display: flex;
+    flex-direction: column;
+    inline-size: 100%;
+    max-inline-size: var(--xh-command-max-w, var(--xh-_command-max-w));
+    /* 封顶才有可滚的余量：不封顶结果列表会一路撑到视口外，滚动条永远出不来 */
+    max-block-size: var(--xh-command-max-h, var(--xh-overlay-max-h));
+    /* 模态命令面板与 Dialog 同档：overlay 圆角 + sheet 三件套（material-elevated 的边 / 底 / 影，§8.4），
+       边界由描边承担，不再只靠落影 */
+    border: var(--xh-stroke-thin) solid var(--xh-command-border, var(--xh-material-elevated-border));
+    border-radius: var(--xh-command-radius, var(--xh-shape-overlay));
+    background: var(--xh-command-bg, var(--xh-material-elevated-bg));
+    color: var(--xh-command-fg, var(--xh-material-elevated-fg));
+    box-shadow: var(--xh-command-shadow, var(--xh-material-elevated-shadow));
+    /* 条目的高亮底色是方角，滚到两端时会探出面板的圆角 */
+    overflow: hidden;
+    /* positioner 不吃指针，面板自身恢复交互。 */
+    pointer-events: auto;
+    /* 进退场的缩放锚在面板顶缘：它是从上方落下来的 */
+    transform-origin: var(--xh-_overlay-origin-x, 50%) var(--xh-_overlay-origin-y, 0);
+  }
+
+  /* 这里刻意没有 [data-part='content'][hidden] { display: none }，与 dialog 一致：
+     收起态连接层会给 content 打 hidden，而上面那条 display: flex 正是要盖掉 UA 的
+     [hidden]{display:none}——退场动画得先能播。presence 读的是 content 的 animationName，
+     读到才申领租约、等 animationend 才卸载；一旦 display: none，元素不生成盒子、
+     动画根本不启动，探测器直接放弃租约，退场动画一帧都播不出来。
+     真正的收起由适配器兜住：Vue 卸载整棵，WC 写内联 style.display。
+     其余声明了 display 的角色节点仍补 [hidden]，那几处没有退场动画。 */
+
+  /* 面板本身只承接程序化聚焦（开场那一刻还没轮到检索框），不画环 */
+  [data-scope='command'][data-part='content']:focus-visible {
+    outline: none;
+  }
+
+  [data-scope='command'][data-part='content'][data-state='open'] {
+    animation: xh-overlay-pop-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter-strong);
+    /* 只在开着的这一档挂：合成层随 data-state 一起收走，收起后不再占着 */
+    will-change: opacity, scale, translate;
+  }
+
+  /* 退场：收起那一帧 hidden 由退场闸门押后，这里才播得出来。forwards 把末态钉住，
+     免得动画结束到真收起之间闪一下原样 */
+  [data-scope='command'][data-part='content'][data-state='closed'] {
+    animation: xh-pop-out var(--xh-motion-duration-exit) var(--xh-motion-ease-exit) forwards;
+  }
+
+  /* —— 检索框 —— */
+  /* 通栏一行，底下一道线把它与结果分开；框自己不画边不画底，边界归面板 */
+  [data-scope='command'][data-part='input'] {
+    flex: none;
+    inline-size: 100%;
+    block-size: var(--xh-command-input-h, var(--xh-_command-input-h));
+    padding-block: 0;
+    padding-inline: var(--xh-command-input-px, var(--xh-_command-px));
+    border: 0;
+    border-block-end: var(--xh-stroke-thin) solid var(--xh-command-input-border, var(--xh-border-subtle));
+    border-radius: 0;
+    background: transparent;
+    color: var(--xh-command-input-fg, var(--xh-fg-default));
+    font-family: inherit;
+    font-size: var(--xh-command-input-font-size, var(--xh-text-body-size));
+  }
+
+  [data-scope='command'][data-part='input']::placeholder {
+    color: var(--xh-command-placeholder-fg, var(--xh-fg-subtle));
+  }
+
+  /* 自动填充态：浏览器给填过的框强加一套系统色（多数引擎是黄底黑字），
+     优先级高到 background / color 改不动，也不跟主题走。
+     底用 box-shadow 的 inset 扩散铺满内容盒，字用 -webkit-text-fill-color 接回令牌。
+     两个选择器名分写两条：一条选择器列表里只要有一个名字不被认识，整条规则就被丢弃。
+     底取不透明的面令牌而不是 transparent：检索框自己不画底，铺透明等于没铺 */
+  [data-scope='command'][data-part='input']:autofill {
+    box-shadow: inset 0 0 0 100vmax var(--xh-command-input-autofill-bg, var(--xh-bg-surface));
+    -webkit-text-fill-color: var(--xh-command-input-autofill-fg, var(--xh-fg-default));
+  }
+
+  [data-scope='command'][data-part='input']:-webkit-autofill {
+    box-shadow: inset 0 0 0 100vmax var(--xh-command-input-autofill-bg, var(--xh-bg-surface));
+    -webkit-text-fill-color: var(--xh-command-input-autofill-fg, var(--xh-fg-default));
+  }
+
+  /* —— 结果列表 —— */
+  /* 只管滚动，留白归条目。min-block-size: 0 是弹性子项能真正滚动的前提——
+     不给的话它按内容撑高，面板的 max-block-size 就只会把溢出的部分裁掉而不是交给它滚 */
+  [data-scope='command'][data-part='list'] {
+    display: flex;
+    flex: 1 1 auto;
+    flex-direction: column;
+    gap: var(--xh-command-list-gap, var(--xh-list-option-gap));
+    min-block-size: 0;
+    padding-block: var(--xh-command-list-py, var(--xh-space-2));
+    padding-inline: var(--xh-command-list-px, var(--xh-space-2));
+    /* 模态面板里的滚动面：到底后不把滚动链穿透给页面（§6.6） */
+    overflow-y: auto;
+    overscroll-behavior: contain;
+  }
+
+  /* 没有可见命令时不保留列表的上下内距；只排除列表内部 hidden 祖先，退场中的外壳不影响判断。 */
+  [data-scope='command'][data-part='list']:not(:has(
+    [data-scope='command'][data-part='item']:not([hidden]):not(
+      [data-scope='command'][data-part='list'] [hidden] *
+    )
+  )) {
+    display: none;
+  }
+
+  /* 列表从不承载焦点（焦点恒在检索框，锚点走 aria-activedescendant），
+     可滚动容器在某些浏览器里会被自动塞进 Tab 序列，落焦时不画环 */
+  [data-scope='command'][data-part='list']:focus-visible {
+    outline: none;
+  }
+
+  /* —— 分组 —— */
+  [data-scope='command'][data-part='group'] {
+    display: flex;
+    flex-direction: column;
+    gap: var(--xh-command-group-gap, var(--xh-list-option-gap));
+  }
+
+  /* 组间留白只加在后继分组上：首组顶上已经有列表的内边距，再加一层会显得头重 */
+  [data-scope='command'][data-part='group'] + [data-scope='command'][data-part='group'] {
+    margin-block-start: var(--xh-command-group-spacing, var(--xh-space-1_5));
+  }
+
+  /* 分组标题不是命令、进不了导航，画成小号次要文字，内缩与条目对齐 */
+  [data-scope='command'][data-part='group-label'] {
+    display: block;
+    padding-block: var(--xh-command-group-label-py, var(--xh-space-1));
+    padding-inline: var(--xh-command-group-label-px, var(--xh-_command-px));
+    color: var(--xh-command-group-label-fg, var(--xh-fg-subtle));
+    font-size: var(--xh-command-group-label-font-size, var(--xh-text-caption-size));
+    font-weight: var(--xh-command-group-label-font-weight, var(--xh-font-weight-medium));
+    line-height: var(--xh-leading-none);
+    user-select: none;
+  }
+
+  /* —— 命令 —— */
+  /* 命令走 Collection Item 的 overlay 语境：悬停 / 键盘锚点（data-highlighted，白底承载 100）、按下（200）与禁用面
+     （aria-disabled）都由家族给，这里只把公开槽映射到桥接槽。aria-selected 跟着活动候选走（selection-follows-focus），
+     家族的浮层选中面缺省透明：这里把选中各态映射到与悬停 / 按下同一档，活动候选与指针悬停看上去是同一副面，
+     命令面板里没有第二档，选中即执行、不留状态。命令从不承载焦点（焦点恒在检索框），高亮不画环。
+     布局保持 flex：图标、正文、快捷键按作者顺序排成一行，不用家族网格；间距由行的 gap 给 */
+  [data-scope='command'][data-part='item'] {
+    --xh-collection-block-padding: var(--xh-command-item-py, var(--xh-_command-item-py));
+    --xh-collection-inline-padding: var(--xh-command-item-px, var(--xh-_command-px));
+    --xh-collection-gap: 0;
+    --xh-collection-font-size: var(--xh-command-item-font-size, var(--xh-_command-font-size));
+    --xh-collection-radius: var(--xh-command-item-radius, var(--xh-shape-control));
+    --xh-collection-fg-rest: var(--xh-command-item-fg, var(--xh-fg-default));
+    --xh-collection-fg-hover: var(--xh-command-item-fg, var(--xh-fg-default));
+    --xh-collection-fg-keyboard-highlight: var(--xh-command-item-fg, var(--xh-fg-default));
+    --xh-collection-fg-pressed: var(--xh-command-item-fg, var(--xh-fg-default));
+    --xh-collection-fg-selected: var(--xh-command-item-fg, var(--xh-fg-default));
+    --xh-collection-fg-selected-hover: var(--xh-command-item-fg, var(--xh-fg-default));
+    --xh-collection-fg-selected-highlight: var(--xh-command-item-fg, var(--xh-fg-default));
+    --xh-collection-fg-selected-pressed: var(--xh-command-item-fg, var(--xh-fg-default));
+    --xh-collection-bg-hover: var(--xh-command-item-bg-hover, var(--xh-bg-subtle));
+    --xh-collection-bg-keyboard-highlight: var(--xh-command-item-bg-hover, var(--xh-bg-subtle));
+    --xh-collection-bg-selected: var(--xh-command-item-bg-hover, var(--xh-bg-subtle));
+    --xh-collection-bg-selected-hover: var(--xh-command-item-bg-hover, var(--xh-bg-subtle));
+    --xh-collection-bg-selected-highlight: var(--xh-command-item-bg-hover, var(--xh-bg-subtle));
+    --xh-collection-bg-pressed: var(--xh-command-item-bg-pressed, var(--xh-bg-subtle-hover));
+    --xh-collection-bg-selected-pressed: var(--xh-command-item-bg-pressed, var(--xh-bg-subtle-hover));
+    --xh-collection-outline-keyboard-highlight: transparent;
+    --xh-collection-outline-selected-highlight: transparent;
+
+    display: flex;
+    align-items: center;
+    gap: var(--xh-command-item-gap, var(--xh-_command-gap));
+    /* 行高留出文字的上下伸展空间，行内那层 overflow:hidden 才不会把字削掉 */
+    line-height: var(--xh-command-item-leading, var(--xh-leading-normal));
+    user-select: none;
+  }
+
+  /* 开幕：结果自上而下逐条冒出来。筛掉的条目带 hidden 不生成盒子，重新露面时这段动画重新起跑，
+     所以每改一次检索串都会重播一遍。backwards 让每条在自己那份延迟里保持起始帧 */
+  [data-scope='command'][data-part='list'] [data-part='item'] {
+    animation: xh-rise-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter-strong) backwards;
+  }
+
+  /* 交错的间隔：第二条起逐级往后推，第六条起统一钉在第五级，命令再多也不会拖出一条越来越慢的尾巴。
+     列表里同时挂着被筛掉的条目（收起态），计数把它们排掉，序号才对得上看得见的那几条 */
+  [data-scope='command'][data-part='list'] [data-part='item']:nth-child(2 of :not([hidden])) {
+    animation-delay: var(--xh-motion-stagger-step);
+  }
+
+  [data-scope='command'][data-part='list'] [data-part='item']:nth-child(3 of :not([hidden])) {
+    animation-delay: calc(2 * var(--xh-motion-stagger-step));
+  }
+
+  [data-scope='command'][data-part='list'] [data-part='item']:nth-child(4 of :not([hidden])) {
+    animation-delay: calc(3 * var(--xh-motion-stagger-step));
+  }
+
+  [data-scope='command'][data-part='list'] [data-part='item']:nth-child(5 of :not([hidden])) {
+    animation-delay: calc(4 * var(--xh-motion-stagger-step));
+  }
+
+  [data-scope='command'][data-part='list'] [data-part='item']:nth-child(n + 6 of :not([hidden])) {
+    animation-delay: calc(5 * var(--xh-motion-stagger-step));
+  }
+
+  [data-scope='command'][data-part='item-text'] {
+    flex: 1;
+    /* 弹性子项默认最小尺寸是内容尺寸，不归零则长文本把行撑破、省略号轮不上 */
+    min-inline-size: 0;
+    overflow: hidden;
+    white-space: nowrap;
+    text-overflow: ellipsis;
+  }
+
+  /* —— 两个占位 —— */
+  /* 空态占位：待在面板里、列表的兄弟；盒与阴影归面板，这里只画一句居中的次要文字 */
+  [data-scope='command'][data-part='empty'] {
+    display: block;
+    flex: none;
+    padding-block: var(--xh-command-empty-py, var(--xh-space-6));
+    padding-inline: var(--xh-command-empty-px, var(--xh-_command-px));
+    color: var(--xh-command-empty-fg, var(--xh-fg-subtle));
+    font-size: var(--xh-command-empty-font-size, var(--xh-_command-font-size));
+    line-height: var(--xh-leading-none);
+    text-align: center;
+  }
+
+  /* 在途占位：与空态占位同一个位置、同一副观感，两者不同屏 */
+  [data-scope='command'][data-part='loading'] {
+    display: block;
+    flex: none;
+    padding-block: var(--xh-command-loading-py, var(--xh-space-6));
+    padding-inline: var(--xh-command-loading-px, var(--xh-_command-px));
+    color: var(--xh-command-loading-fg, var(--xh-fg-subtle));
+    font-size: var(--xh-command-loading-font-size, var(--xh-_command-font-size));
+    line-height: var(--xh-leading-none);
+    text-align: center;
+  }
+
+  /* 未提供状态内容时不渲染一块纯留白，提示文案仍由作者明确提供。 */
+  [data-scope='command'][data-part='empty']:empty,
+  [data-scope='command'][data-part='loading']:empty {
+    display: none;
+  }
+
+  /* 取数在途：列表压暗一档，与在途占位一起说明这块正在变 */
+  [data-scope='command'][data-part='list'][aria-busy='true'] {
+    opacity: var(--xh-command-list-busy-opacity, var(--xh-state-disabled-opacity));
+  }
+
+  /* —— 底部提示条 —— */
+  /* 贴在列表下沿，用一道分隔线与命令断开；作者往里放什么由作者定 */
+  [data-scope='command'][data-part='footer'] {
+    display: flex;
+    flex: none;
+    align-items: center;
+    gap: var(--xh-command-footer-gap, var(--xh-space-2));
+    padding-block: var(--xh-command-footer-py, var(--xh-space-2));
+    padding-inline: var(--xh-command-footer-px, var(--xh-_command-px));
+    border-block-start: var(--xh-stroke-thin) solid var(--xh-command-footer-border, var(--xh-border-subtle));
+    color: var(--xh-command-footer-fg, var(--xh-fg-muted));
+    font-size: var(--xh-command-footer-font-size, var(--xh-text-caption-size));
+  }
+
+  /* 声明过任何 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去。
+     写在文件末尾：兜底必须排在该部件所有 display 声明之后 */
+  [data-scope='command'][data-part='positioner'][hidden],
+  [data-scope='command'][data-part='list'][hidden],
+  [data-scope='command'][data-part='group'][hidden],
+  [data-scope='command'][data-part='group-label'][hidden],
+  [data-scope='command'][data-part='item'][hidden],
+  [data-scope='command'][data-part='item-text'][hidden],
+  [data-scope='command'][data-part='empty'][hidden],
+  [data-scope='command'][data-part='loading'][hidden],
+  [data-scope='command'][data-part='footer'][hidden] {
+    display: none;
+  }
+
+  @media print {
+    /* 打印：定位层与遮罩是交互期才存在的东西，落到纸上只会盖住底下的正文。
+       收起写在这份皮肤里而不是 reset：reset 层排在组件层之前，组件层里任何一条 display 都压得住它。 */
+    [data-scope='command'][data-part='backdrop'],
+    [data-scope='command'][data-part='positioner'] {
+      display: none;
+    }
+  }
+}