@xihan-ui/styles 1.0.0 → 2.0.0

package/css/date-range-picker.css

@@ -0,0 +1,559 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* DateRangePicker 独立皮肤同时传递引入字段视觉盒、字段内动作与浮层集合行；full bundle 递归去重。 */
+@import '../family/field-chrome.css';
+@import '../family/action-control.css';
+@import '../family/collection-item.css';
+
+@import './scrollbar.css';
+
+/* 共享关键帧由 family/motion.css 提供，本皮肤 @import 它，单独引入仍成立。 */
+@import '../family/motion.css';
+
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='date-range-picker'] {
+    --xh-date-range-picker-skin: 1;
+  }
+
+  /* 坐标由定位引擎写进 style（inset-inline-start / inset-block-start），这里只定位模式与层级 */
+  [data-scope='date-range-picker'][data-part='positioner'] {
+    /* 落定那一侧的可用高度，由定位引擎经内联自定义属性写进来，内容层继承它限高；
+       引擎没算（尚未落位 / 无引擎 / 贴边归零）时不额外限高 */
+    --xh-_date-range-picker-available-h: 100vh;
+    /* 落定那一侧的可用宽度，同样由定位引擎经内联自定义属性写进来，内容层据此夹住行内轴；
+       引擎没算（尚未落位 / 无引擎 / 贴边归零）时退到视口宽 */
+    --xh-_date-range-picker-available-w: 100vw;
+
+    /* 每个浮层独立声明方向，避免继承祖先浮层的进场位移。 */
+    --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;
+    z-index: var(--xh-date-range-picker-layer, var(--xh-_layer, var(--xh-layer-popover)));
+    /* 空壳不吃指针，交互只发生在 content 里 */
+    pointer-events: none;
+  }
+
+  /* 锚点被滚出可视区：整个浮层随之收起 */
+  [data-scope='date-range-picker'][data-part='positioner'][data-hidden] {
+    visibility: hidden;
+  }
+
+  /* 短位移按实际落位的物理方向给，不随书写方向翻转。 */
+  [data-scope='date-range-picker'][data-part='positioner'][data-placement^='top'] {
+    --xh-_overlay-enter-down: 1;
+  }
+
+  [data-scope='date-range-picker'][data-part='positioner'][data-placement^='bottom'] {
+    --xh-_overlay-enter-up: 1;
+  }
+
+  [data-scope='date-range-picker'][data-part='positioner'][data-placement^='left'] {
+    --xh-_overlay-enter-right: 1;
+  }
+
+  [data-scope='date-range-picker'][data-part='positioner'][data-placement^='right'] {
+    --xh-_overlay-enter-left: 1;
+  }
+
+  /* 私有槽同时声明在根与 positioner 上：浮层被搬到 portal 落点，不是根的后代，继承不过去 */
+  [data-scope='date-range-picker']:is([data-part='root'], [data-part='positioner']) {
+    /* 尺寸档只换这几个私有槽，标题、输入行与浮层里的部件都从这两处继承它们，
+       换档不必给每个部件各写一条选择器；形态三档由家族按 control 上的 data-variant 生成，皮肤不再声明 */
+    --xh-_date-range-picker-control-h: var(--xh-control-h-md);
+    --xh-_date-range-picker-control-px: var(--xh-control-px-md);
+    --xh-_date-range-picker-gap: var(--xh-control-gap-md);
+    --xh-_date-range-picker-font-size: var(--xh-control-font-md);
+
+    /* 选中对号随语气走。没写 data-tone 时这几个 --xh-_tone* 没被声明，退回品牌色 */
+    /* 内嵌日期段沿用日期输入的轻强调焦点：当前段是「当前项」，淡底 + 淡底前景，不另画一套实心选择态。 */
+    --xh-_date-field-segment-bg: var(--xh-_tone-subtle, var(--xh-bg-brand-subtle));
+    --xh-_date-field-segment-fg: var(--xh-_tone-fg, var(--xh-fg-on-brand-subtle));
+    /* 对号画在普通面上，取语气前景角色，不拿实心强调底色充当前景。 */
+    --xh-_date-range-picker-check-fg: var(--xh-_tone, var(--xh-fg-brand));
+  }
+
+  /* 与文本框、分段日期同一套堆叠：标签一行、输入行一行 */
+  [data-scope='date-range-picker'][data-part='root'] {
+    /* 作者塞进指示符槽的图标跟着字号走，与皮肤画的兜底字形同一把尺 */
+    --xh-icon-size: var(--xh-date-range-picker-icon-size, var(--xh-glyph-size-md));
+
+    display: inline-flex;
+    flex-direction: column;
+    gap: var(--xh-date-range-picker-gap, var(--xh-space-1));
+
+    /* 起止两组段位、分隔符与日历钮排在一行，按日的内容本身就比字段缺省宽（--xh-control-w）宽，
+       钉成缺省宽会裁掉终点的段位：这一件缺省按内容撑开，使用者要钉宽仍走这条槽。
+       地板抬到一族的缺省宽：按年、按月的内容比缺省宽窄，不能比别的字段还窄，底线槽只在高过缺省宽时起作用。
+       父容器给不出这么宽时整件跟着收，地板同步让步，不越出父容器 */
+    inline-size: var(--xh-date-range-picker-control-w, max-content);
+    min-inline-size: min(max(var(--xh-control-w), var(--xh-date-range-picker-control-min-w, var(--xh-control-min-w))), 100%);
+    max-inline-size: 100%;
+  }
+
+  /* —— 尺寸 —— */
+  /* 缺省档写在上面的基础规则里 */
+  [data-scope='date-range-picker']:is([data-part='root'], [data-part='positioner'])[data-size='sm'] {
+    --xh-icon-size: var(--xh-date-range-picker-icon-size, var(--xh-glyph-size-sm));
+    --xh-_date-range-picker-control-h: var(--xh-control-h-sm);
+    --xh-_date-range-picker-control-px: var(--xh-control-px-sm);
+    --xh-_date-range-picker-gap: var(--xh-control-gap-sm);
+    --xh-_date-range-picker-font-size: var(--xh-control-font-sm);
+  }
+
+  [data-scope='date-range-picker']:is([data-part='root'], [data-part='positioner'])[data-size='lg'] {
+    --xh-icon-size: var(--xh-date-range-picker-icon-size, var(--xh-glyph-size-lg));
+    --xh-_date-range-picker-control-h: var(--xh-control-h-lg);
+    --xh-_date-range-picker-control-px: var(--xh-control-px-lg);
+    --xh-_date-range-picker-gap: var(--xh-control-gap-lg);
+    --xh-_date-range-picker-font-size: var(--xh-control-font-lg);
+  }
+
+  /* 只要声明了 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去 */
+  [data-scope='date-range-picker'][data-part='root'][hidden] {
+    display: none;
+  }
+
+  [data-scope='date-range-picker'][data-part='label'] {
+    color: var(--xh-date-range-picker-label-fg, var(--xh-fg-default));
+    font-size: var(--xh-date-range-picker-label-font-size, var(--xh-text-label-size));
+    font-weight: var(--xh-date-range-picker-label-font-weight, var(--xh-text-label-weight));
+    line-height: var(--xh-leading-none);
+  }
+
+  [data-scope='date-range-picker'][data-part='label'][hidden] {
+    display: none;
+  }
+
+  [data-scope='date-range-picker'][data-part='label'][data-disabled] {
+    color: var(--xh-date-range-picker-label-fg-disabled, var(--xh-fg-subtle));
+  }
+
+  /* 画成一个框的是 control 而不是 input：段位、清空按钮、日历按钮三者要看起来是一体的，
+     边框长在里面任何一个身上都会把另外两个割在框外。描边、底色、圆角、聚焦环、五态与悬停由
+     Field Chrome 家族画在 control 上（焦点落在段或按钮上，家族 :focus-within 让整框亮起来）；
+     组件只映射既有公开槽（shadow 缺省 none：字段静息描边式、无影）。打开中不另画环，由浮层本身承担 */
+  [data-scope='date-range-picker'][data-part='control'] {
+    --xh-field-control-height: var(--xh-date-range-picker-control-h, var(--xh-_date-range-picker-control-h));
+    --xh-field-control-padding-inline: var(--xh-date-range-picker-control-px, var(--xh-_date-range-picker-control-px));
+    --xh-field-control-gap: var(--xh-date-range-picker-control-gap, var(--xh-_date-range-picker-gap));
+    --xh-field-control-min-inline-size: var(--xh-date-range-picker-control-min-w, var(--xh-control-min-w));
+    --xh-field-control-radius: var(--xh-date-range-picker-control-radius, var(--xh-shape-control));
+    --xh-field-bg-rest: var(--xh-date-range-picker-control-bg, var(--xh-_field-variant-bg-rest));
+    --xh-field-bg-hover: var(--xh-date-range-picker-control-bg-hover, var(--xh-_field-variant-bg-hover));
+    --xh-field-bg-read-only: var(--xh-date-range-picker-control-bg-readonly, var(--xh-_field-variant-bg-read-only));
+    --xh-field-bg-disabled: var(--xh-date-range-picker-control-bg-disabled, var(--xh-_field-variant-bg-disabled));
+    --xh-field-fg-rest: var(--xh-date-range-picker-control-fg, var(--xh-fg-default));
+    --xh-field-border-rest: var(--xh-date-range-picker-control-border, var(--xh-_field-variant-border-rest));
+    --xh-field-border-hover: var(--xh-date-range-picker-control-border-hover, var(--xh-_field-variant-border-hover));
+    --xh-field-border-focus: var(--xh-date-range-picker-control-border-focus, var(--xh-_field-variant-border-focus));
+    --xh-field-border-invalid: var(--xh-date-range-picker-control-border-invalid, var(--xh-_field-variant-border-invalid));
+    --xh-field-ring-focus: var(--xh-ring-focus);
+    --xh-field-ring-invalid: var(--xh-ring-invalid);
+    --xh-field-shadow-rest: var(--xh-date-range-picker-control-shadow, none);
+    /* 段位靠键盘编辑，盒上不是文本光标 */
+    --xh-field-cursor-rest: default;
+    /* 家族 chrome 会重写 --xh-icon-size，使用者图标槽必须经桥接槽下发才能在盒内生效 */
+    --xh-field-glyph-size: var(--xh-date-range-picker-icon-size, var(--xh-_field-size-glyph-size));
+  }
+
+  [data-scope='date-range-picker'][data-part='control'][hidden] {
+    display: none;
+  }
+
+  /* 段位与作者写在段间的分隔符都在这一层里：段位自己那身皮由 date-field 那份样式负责
+     （它们戴的是那一份解剖的标记），这里只管把一排段位横过来、占满输入行剩下的宽度 */
+  [data-scope='date-range-picker'][data-part='segment-group'] {
+    display: inline-flex;
+    flex: 1 1 auto;
+    align-items: center;
+    min-inline-size: 0;
+    block-size: 100%;
+    color: inherit;
+    /* 表单控件不继承页面字体，只给字号会让段位用 UA 默认字族，与周围文本对不上 */
+    font-family: inherit;
+    font-size: var(--xh-date-range-picker-font-size, var(--xh-_date-range-picker-font-size));
+    line-height: var(--xh-leading-none);
+  }
+
+  [data-scope='date-range-picker'][data-part='segment-group'][hidden] {
+    display: none;
+  }
+
+  /* 起点那组只占自己的宽度，分隔符紧跟在起点后面；剩下的宽度全给终点那组 */
+  [data-scope='date-range-picker'][data-part='segment-group'][data-index='0']:has(+ [data-part='range-separator']) {
+    flex: 0 0 auto;
+  }
+
+  [data-scope='date-range-picker'][data-part='range-separator'] {
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    justify-content: center;
+    /* 两侧各留一个小间距：把输入行的常规间距收回来，再补上自己那一份 */
+    --xh-_date-range-picker-range-separator-mx: calc(var(--xh-date-range-picker-range-separator-px, var(--xh-space-1)) - var(--xh-date-range-picker-control-gap, var(--xh-_date-range-picker-gap)));
+
+    margin-inline: var(--xh-date-range-picker-range-separator-mx, var(--xh-_date-range-picker-range-separator-mx));
+    padding-inline: var(--xh-date-range-picker-range-separator-px, var(--xh-space-1));
+    color: var(--xh-date-range-picker-range-separator-fg, var(--xh-fg-subtle));
+    font: inherit;
+    line-height: var(--xh-leading-none);
+    pointer-events: none;
+    user-select: none;
+  }
+
+  /* 作者自己给分隔符加 hidden 时也真的收起：上面那条 display 会盖掉 UA 的兜底 */
+  [data-scope='date-range-picker'][data-part='range-separator'][hidden] {
+    display: none;
+  }
+
+  [data-scope='date-range-picker'][data-part='segment-group'] > :not([data-scope]) {
+    color: var(--xh-date-range-picker-literal-fg, var(--xh-fg-subtle));
+  }
+
+  /* 容器自己不占 Tab 位、也不承载焦点，环由 control 画，这里不再套一圈 */
+  [data-scope='date-range-picker'][data-part='segment-group']:focus-visible {
+    outline: none;
+  }
+
+  /* 两个按钮同一副长相：贴在框内末端的小方钮，不占宽度也不撑高 control。正方视觉盒、inset 圆角、
+     悬停 100 / 按下 200 与 0.97 按压、粗指针热区、禁用面与 :focus-visible 关环（盒的 :focus-within
+     已画了一圈）全由 Action Control 的 field-inset ghost 档给，组件只映射既有覆盖槽。
+     打开中与悬停同档：日历钮不另上底，方向由浮层本身承担 */
+  [data-scope='date-range-picker'][data-part='trigger'],
+  [data-scope='date-range-picker'][data-part='clear-trigger'] {
+    --xh-action-visual-size: var(--xh-date-range-picker-action-size, var(--xh-_action-profile-visual-size));
+    --xh-action-min-inline-size: var(--xh-date-range-picker-action-size, var(--xh-_action-profile-visual-size));
+    --xh-action-radius: var(--xh-date-range-picker-action-radius, var(--xh-shape-inset));
+    /* 底色阶梯由 ghost 档给（透明 → 100 → 200），使用者槽只作覆盖入口 */
+    --xh-action-bg-rest: var(--xh-date-range-picker-action-bg, var(--xh-_action-variant-bg-rest));
+    --xh-action-bg-hover: var(--xh-date-range-picker-action-bg-hover, var(--xh-_action-variant-bg-hover));
+    --xh-action-bg-pressed: var(--xh-date-range-picker-action-bg-active, var(--xh-_action-variant-bg-pressed));
+    --xh-action-fg-rest: var(--xh-date-range-picker-action-fg, var(--xh-fg-muted));
+    --xh-action-fg-hover: var(--xh-date-range-picker-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-date-range-picker-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 规则盖掉 */
+  [data-scope='date-range-picker'][data-part='trigger'][hidden],
+  [data-scope='date-range-picker'][data-part='clear-trigger'][hidden] {
+    display: none;
+  }
+
+  /* 打开中与悬停同档：日历钮的静息底换到悬停那一支中性面，不用品牌色、不另画环；方向由浮层本身承担 */
+  [data-scope='date-range-picker'][data-part='trigger'][data-state='open'] {
+    --xh-action-bg-rest: var(--xh-date-range-picker-action-bg-hover, var(--xh-_action-variant-bg-hover));
+    --xh-action-fg-rest: var(--xh-date-range-picker-action-fg-hover, var(--xh-fg-default));
+  }
+
+  /* 有值时清空钮顶上来，日历钮让位：两颗并排堆着用户分不清点哪个 */
+  [data-scope='date-range-picker'][data-part='control']:has(
+      > [data-scope='date-range-picker'][data-part='clear-trigger']:not([hidden])
+    )
+    > [data-scope='date-range-picker'][data-part='trigger'] {
+    display: none;
+  }
+
+  /* 浮层：含两张日历网格的锚定面板，走 floating 材质——实体底 + --xh-border-default 描边 +
+     --xh-elevation-floating 落影，不透景、不画顶光 */
+  [data-scope='date-range-picker'][data-part='content'] {
+    position: relative;
+    display: block;
+    /* 行内轴只有落位后的可用宽度这一个上限：不夹住，浮层就会被定位层的包含块压窄，
+       网格轨道跟着缩到比日期钮还窄，相邻两颗日期钮互相盖住 */
+    max-inline-size: var(--xh-_date-range-picker-available-w);
+    padding-block: var(--xh-date-range-picker-content-py, var(--xh-space-2));
+    padding-inline: var(--xh-date-range-picker-content-px, var(--xh-space-2));
+    border: var(--xh-stroke-thin) solid var(--xh-date-range-picker-content-border, var(--xh-border-default));
+    border-radius: var(--xh-date-range-picker-content-radius, var(--xh-shape-overlay));
+    background: var(--xh-date-range-picker-content-bg, var(--xh-bg-surface));
+    color: var(--xh-date-range-picker-content-fg, var(--xh-fg-default));
+    /* 日历是定高结构：六行日期加表头本来就有固定高度，上限走页内滚动面那一档；
+       可用高度是定位引擎算出的视口余量，视口真放不下时再收一截 */
+    max-block-size: min(var(--xh-date-range-picker-max-h, var(--xh-viewport-h-lg)), var(--xh-_date-range-picker-available-h));
+    /* 两轴都滚：块轴放不下时面板内自己竖滚，行内轴放不下时面板内自己横滚，
+       日历那几块保持各自的天然宽度，不被压 */
+    overflow: auto;
+    /* 浮层滚动面：滚到头不把页面一起带走 */
+    overscroll-behavior: contain;
+    box-shadow: var(--xh-date-range-picker-content-shadow, var(--xh-elevation-floating));
+    pointer-events: auto;
+    /* 快捷选项列的条子贴在它的盒子上、挂在这一层里（它已是定位盒）：轨道不画底 */
+    --xh-scrollbar-track-bg: transparent;
+  }
+
+  /* 这里刻意没有 [data-part='content'][hidden] { display: none }，与 dialog 一致：
+     收起态连接层会给 content 打 hidden，而上面那条 display 正是要盖掉 UA 的
+     [hidden]{display:none}——退场动画得先能播。presence 读的是 content 的 animationName，
+     真正的收起由宿主在退场结束后落成内联 display:none（Vue 那边直接不渲染）。
+     其余声明了 display 的角色节点仍补 [hidden]，那几处没有退场动画。 */
+
+  /* 浮层壳不承载焦点（焦点直接落到聚焦日那一格），但它写着 tabindex=-1，
+     程序化落焦时不该再画一圈环 */
+  [data-scope='date-range-picker'][data-part='content']:focus-visible {
+    outline: none;
+  }
+
+  [data-scope='date-range-picker'][data-part='content'][data-state='open'] {
+    /* 只在展开态挂着：随状态属性一起消失，不长期占着合成层 */
+    will-change: opacity, translate;
+    animation: xh-overlay-slide-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter-strong);
+  }
+
+  /* 退场：收起那一帧 hidden 由退场闸门押后，这里才播得出来。forwards 把末态钉住，
+     免得动画结束到真收起之间闪一下原样 */
+  [data-scope='date-range-picker'][data-part='content'][data-state='closed'] {
+    animation: xh-overlay-slide-out var(--xh-motion-duration-exit) var(--xh-motion-ease-exit) forwards;
+  }
+
+  /* 内嵌日历的挂载点同时充当日历的根节点：日历那份样式的 root 规则落在
+     [data-scope='calendar-range-picker'][data-part='root'] 上，而这里没有那个节点，
+     所以网格外层该有的排布得在这儿补齐（网格内部的皮仍归 calendar-range-picker 那一份） */
+  /* 真的摆了两张日历才横过来。写成 :has 而不是无条件 flex 行：
+     作者可能在 content 里再包一层自己的块，无条件横排会把它并到日历旁边去。
+     不加 :not([hidden])：content 收起态带 hidden 但仍在播退场动画，
+     排除掉会让它在那几帧退回 block、两张日历竖着堆一下。
+     并排放不下就折行，第二张月历落到第一张下面：视口窄与面板被夹窄都命中这一条 */
+  [data-scope='date-range-picker'][data-part='content']:has(> [data-part='calendar'] + [data-part='calendar']) {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: flex-start;
+  }
+
+  /* 快捷选项列摆在日历的行内起始一侧，同样只在它真在场时才横过来。
+     与上一条同理：不加 :not([hidden])，退场那几帧塌回 block 会让两块竖着堆一下。
+     一并折行：选项条在手机档占满一行，日历落到它下面 */
+  [data-scope='date-range-picker'][data-part='content']:has(> [data-part='preset-group']) {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: stretch;
+  }
+
+  /* 第二个起的面板画一道分隔线：两张网格挨着排时要有条界，
+     否则 8 月末与 9 月初那两列看着像同一张表。
+     手机档两张月历折行堆叠，线画在块起始边 */
+  [data-scope='date-range-picker'][data-part='calendar'] + [data-scope='date-range-picker'][data-part='calendar'] {
+    padding-block-start: var(--xh-date-range-picker-panel-gap, var(--xh-space-3));
+    border-block-start: var(--xh-stroke-thin) solid var(--xh-date-range-picker-panel-divider, var(--xh-material-frosted-separator));
+  }
+
+  /* 平板起两张月历并排放得下，线改画在行内起始边 */
+  @media (min-width: 768px) {
+    [data-scope='date-range-picker'][data-part='calendar'] + [data-scope='date-range-picker'][data-part='calendar'] {
+      padding-block-start: 0;
+      padding-inline-start: var(--xh-date-range-picker-panel-gap, var(--xh-space-3));
+      border-block-start: none;
+      border-inline-start: var(--xh-stroke-thin) solid var(--xh-date-range-picker-panel-divider, var(--xh-material-frosted-separator));
+    }
+  }
+
+  /* 快捷选项与它旁边那张日历之间留出同样的空当。
+     手机档选项条在上、日历在下，空当留在块轴。
+     选项列后面紧跟着它自己的两条条子节点，相邻选择器接不到日历，按「前面有过选项列」取日历 */
+  [data-scope='date-range-picker'][data-part='preset-group'] ~ [data-scope='date-range-picker'][data-part='calendar'] {
+    padding-block-start: var(--xh-date-range-picker-panel-gap, var(--xh-space-3));
+  }
+
+  /* 平板起选项列回到日历一侧，空当跟着回到行内轴，两道分隔线左右对称 */
+  @media (min-width: 768px) {
+    [data-scope='date-range-picker'][data-part='preset-group'] ~ [data-scope='date-range-picker'][data-part='calendar'] {
+      padding-block-start: 0;
+      padding-inline-start: var(--xh-date-range-picker-panel-gap, var(--xh-space-3));
+    }
+  }
+
+  [data-scope='date-range-picker'][data-part='calendar'] {
+    display: flex;
+    /* 面板被夹窄时不跟着缩：日期钮的宽度是定死的，网格轨道再窄下去就会与右邻的钮叠在一起。
+       撑出去的那截交给面板自己横滚 */
+    min-inline-size: max-content;
+    flex-direction: column;
+    gap: var(--xh-date-range-picker-calendar-gap, var(--xh-space-2));
+    /* 数字等宽：1 与 7 的字形宽度在比例字体里并不相同，不定住会让整张网格随月份抖动 */
+    font-variant-numeric: tabular-nums;
+  }
+
+  [data-scope='date-range-picker'][data-part='calendar'][hidden] {
+    display: none;
+  }
+
+  /* —— 快捷选项：一条按钮式条目 —— */
+  /* 手机档：整条压在面板顶部占满一行，条目横着排，放不下就这一条自己横滚 */
+  [data-scope='date-range-picker'][data-part='preset-group'] {
+    display: flex;
+    /* 独占面板的一整行，后面的日历折到它下面 */
+    flex: 0 0 100%;
+    /* 这一条的另一轴由并排的那块给：不写就按内容收，分隔线只画到最后一条选项 */
+    align-self: stretch;
+    flex-direction: row;
+    gap: var(--xh-date-range-picker-preset-group-gap, var(--xh-list-option-gap));
+    /* 选项多起来时这一条自己滚，不把整张面板撑大 */
+    max-block-size: var(--xh-date-range-picker-preset-group-h, var(--xh-viewport-h-lg));
+    padding: var(--xh-date-range-picker-preset-group-padding, var(--xh-space-1));
+    overflow-x: auto;
+    overflow-y: hidden;
+    /* 浮层滚动面：滚到头不把页面一起带走 */
+    overscroll-behavior: contain;
+    border-block-end: var(--xh-stroke-thin) solid var(--xh-date-range-picker-column-divider, var(--xh-material-frosted-separator));
+  }
+
+  /* 平板起：换成贴在日历行内起始一侧的竖列，滚动轴与分隔线一起转过来 */
+  @media (min-width: 768px) {
+    [data-scope='date-range-picker'][data-part='preset-group'] {
+      flex: none;
+      flex-direction: column;
+      overflow: auto;
+      border-block-end: none;
+      border-inline-end: var(--xh-stroke-thin) solid var(--xh-date-range-picker-column-divider, var(--xh-material-frosted-separator));
+    }
+  }
+
+  [data-scope='date-range-picker'][data-part='preset-group'][hidden] {
+    display: none;
+  }
+
+  /* 快捷选项：悬停 / 高亮 100、按下 200、禁用面由 Collection Item 家族按 overlay 语境给（选中 = 透明底 +
+     行尾对号，正文保持 rest 色与常规字重）。选项没有正文部件，匿名文本进不了家族网格的 text 列，
+     行保持块级排版，末端为对号预留固定轨 */
+  [data-scope='date-range-picker'][data-part='preset'] {
+    --xh-collection-block-padding: var(--xh-date-range-picker-preset-py, var(--xh-space-1));
+    --xh-collection-inline-padding: var(--xh-date-range-picker-preset-px, var(--xh-space-3));
+    --xh-collection-font-size: var(--xh-text-secondary-size);
+    --xh-collection-radius: var(--xh-date-range-picker-preset-radius, var(--xh-shape-control));
+    /* 面板是实体面（floating），正文取页面前景 */
+    --xh-collection-fg-rest: var(--xh-fg-default);
+    --xh-collection-fg-hover: var(--xh-fg-default);
+    --xh-collection-fg-keyboard-highlight: var(--xh-fg-default);
+    --xh-collection-fg-pressed: var(--xh-fg-default);
+    --xh-collection-fg-selected: var(--xh-date-range-picker-preset-fg-selected, var(--xh-fg-default));
+    --xh-collection-fg-selected-highlight: var(--xh-date-range-picker-preset-fg-selected, var(--xh-fg-default));
+    --xh-collection-fg-selected-hover: var(--xh-date-range-picker-preset-fg-selected, var(--xh-fg-default));
+    --xh-collection-fg-selected-pressed: var(--xh-date-range-picker-preset-fg-selected, var(--xh-fg-default));
+    --xh-collection-fg-disabled: var(--xh-date-range-picker-preset-fg-disabled, var(--xh-fg-disabled));
+    --xh-collection-bg-hover: var(--xh-date-range-picker-preset-bg-hover, var(--xh-bg-subtle));
+    --xh-collection-bg-keyboard-highlight: var(--xh-date-range-picker-preset-bg-hover, var(--xh-bg-subtle));
+    --xh-collection-bg-selected-highlight: var(--xh-date-range-picker-preset-bg-hover, var(--xh-bg-subtle));
+    --xh-collection-bg-selected-hover: var(--xh-date-range-picker-preset-bg-hover, var(--xh-bg-subtle));
+    --xh-collection-bg-pressed: var(--xh-date-range-picker-preset-bg-pressed, var(--xh-bg-subtle-hover));
+    --xh-collection-bg-selected-pressed: var(--xh-date-range-picker-preset-bg-pressed, var(--xh-bg-subtle-hover));
+    --xh-collection-outline-keyboard-highlight: transparent;
+    --xh-collection-outline-selected-highlight: transparent;
+
+    /* 横着排那一档不许被压扁：条目文本本来就不折行 */
+    position: relative;
+    display: block;
+    flex: none;
+    /* 对号的末端轨始终留着，切换选中时文字与整列宽度都不移动。 */
+    padding-inline-end: calc(
+      var(--xh-date-range-picker-preset-px, var(--xh-space-3)) +
+        var(--xh-date-range-picker-preset-check-size, var(--xh-glyph-size-sm)) +
+        var(--xh-space-1)
+    );
+    white-space: nowrap;
+    user-select: none;
+  }
+
+  /* 键盘焦点出现时环才接回并立即到位，不压在背景过渡的中间帧上 */
+  [data-scope='date-range-picker'][data-part='preset']:focus-visible:not(:hover) {
+    --xh-collection-outline-keyboard-highlight: var(--xh-ring-focus);
+    --xh-collection-outline-selected-highlight: var(--xh-ring-focus);
+
+    transition: none;
+  }
+
+  /* 上面给了 display，UA 的 [hidden]{display:none} 已被盖掉，这里补回来 */
+  [data-scope='date-range-picker'][data-part='preset'][hidden] {
+    display: none;
+  }
+
+  [data-scope='date-range-picker'][data-part='preset']::after {
+    content: '';
+    position: absolute;
+    inset-block-start: 50%;
+    inset-inline-end: var(--xh-date-range-picker-preset-px, var(--xh-space-3));
+    inline-size: var(--xh-date-range-picker-preset-check-size, var(--xh-glyph-size-sm));
+    block-size: var(--xh-date-range-picker-preset-check-size, var(--xh-glyph-size-sm));
+    translate: 0 -50%;
+    background-color: var(--xh-date-range-picker-preset-check-fg, var(--xh-_date-range-picker-check-fg));
+    opacity: 0;
+    pointer-events: none;
+    transition: opacity var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+    -webkit-mask: var(--xh-glyph-mark-check) center / contain no-repeat;
+    mask: var(--xh-glyph-mark-check) center / contain no-repeat;
+  }
+
+  [data-scope='date-range-picker'][data-part='preset'][data-state='checked']::after {
+    opacity: 1;
+  }
+
+  [data-scope='date-range-picker'][data-part='preset'][data-disabled]::after {
+    background-color: var(--xh-date-range-picker-preset-fg-disabled, var(--xh-fg-disabled));
+  }
+
+  /* 没写内容就由皮肤画兜底字形；作者往部件里塞了自己的图形，这几条即不命中 */
+  [data-scope='date-range-picker'][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;
+  }
+
+  [data-scope='date-range-picker'][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-calendar) center / contain no-repeat;
+    mask: var(--xh-glyph-mark-calendar) center / contain no-repeat;
+  }
+
+  @media (forced-colors: active) {
+    /* 系统接管底色后仍保住末端对号；禁用标记改用系统失效色。 */
+    [data-scope='date-range-picker'][data-part='preset']::after {
+      forced-color-adjust: none;
+      background-color: CanvasText;
+    }
+
+    [data-scope='date-range-picker'][data-part='preset'][data-disabled]::after {
+      background-color: GrayText;
+    }
+
+    [data-scope='date-range-picker'][data-part='preset'][data-disabled] {
+      color: GrayText;
+    }
+  }
+}
+
+@layer xihan.motion {
+  @media print {
+    /* 打印：定位层与遮罩是交互期才存在的东西，落到纸上只会盖住底下的正文。
+       收起写在这份皮肤里而不是 reset：reset 层排在组件层之前，组件层里任何一条 display 都压得住它。 */
+    [data-scope='date-range-picker'][data-part='positioner'] {
+      display: none;
+    }
+  }
+}

package/css/description.css

@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/*
+ * 字段族说明与错误文案的公共层，按 [data-part='description'] / [data-part='error-text']
+ * 匹配下面逐个列出的 scope。
+ *
+ * 收在这里的是逐值相同的角色规则：说明 = --xh-text-secondary-size / --xh-fg-muted /
+ * --xh-leading-normal；错误文案 = --xh-text-secondary-size / --xh-fg-danger / --xh-leading-normal；
+ * 两者外边距归零，与控件的距离由字段根的 gap 给。挂了 --xh-<组件>-description-* /
+ * --xh-<组件>-error-* 覆盖槽的组件在各自皮肤里只另写带槽的 color / font-size 压过这里，
+ * margin 与 line-height 不再重写。
+ *
+ * 说明与错误文案落在控件下方的同一处：无效时收起说明，那一行只剩错误。两段同时在场
+ * 会把辅助区撑成两行，整表的字段高度随之参差。
+ *
+ * 收起只收视觉。说明的 id 仍挂在控件的 aria-describedby 上，读屏两段都念得到——
+ * 直接被 aria-describedby 指到的节点，隐藏与否都计入可及描述。
+ *
+ * scope 逐个列出，不写成 [data-part='description']：这个部件名在提示、气泡、
+ * 空状态、说明列表上指的是另一段文字，通配规则会把它们在无效态下一并收起。
+ * 要接进来的组件把自己的几条加进列表。
+ *
+ * 收起限定到直接子节点：字段集无效时收起的是它自己那段说明，不是组内各字段的说明。
+ * 引入顺序排在全部组件皮肤之前，组件要另作安排照写同样的无效态限定即可压过。
+ */
+@layer xihan.components {
+  [data-scope='field'][data-part='description'],
+  [data-scope='fieldset'][data-part='description'] {
+    margin: 0;
+    font-size: var(--xh-text-secondary-size);
+    line-height: var(--xh-leading-normal);
+    color: var(--xh-fg-muted);
+  }
+
+  /* 不 invalid 时节点带 hidden：此处不声明 display，交给浏览器的 [hidden] 规则收起 */
+  [data-scope='field'][data-part='error-text'],
+  [data-scope='fieldset'][data-part='error-text'] {
+    margin: 0;
+    font-size: var(--xh-text-secondary-size);
+    line-height: var(--xh-leading-normal);
+    color: var(--xh-fg-danger);
+  }
+
+  [data-scope='field'][data-part='root'][data-invalid] > [data-scope='field'][data-part='description'],
+  [data-scope='fieldset'][data-part='root'][data-invalid] > [data-scope='fieldset'][data-part='description'] {
+    display: none;
+  }
+}