@xihan-ui/styles 3.0.0 → 3.2.0

package/dist/css/scroll-area.css

@@ -0,0 +1,240 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 scroll area 样式。 */
+
+/* 边缘渐隐的四条带宽登记成长度：滚到头时带子收起、离开端点时铺开，才能沿过渡淡变。
+   不认 @property 的引擎把它们当普通自定义属性，带子照旧按端点收放，只是没有过渡 */
+@property --xh-_scroll-area-fade-block-start {
+  syntax: '<length>';
+  inherits: false;
+  initial-value: 0px;
+}
+
+@property --xh-_scroll-area-fade-block-end {
+  syntax: '<length>';
+  inherits: false;
+  initial-value: 0px;
+}
+
+@property --xh-_scroll-area-fade-inline-start {
+  syntax: '<length>';
+  inherits: false;
+  initial-value: 0px;
+}
+
+@property --xh-_scroll-area-fade-inline-end {
+  syntax: '<length>';
+  inherits: false;
+  initial-value: 0px;
+}
+
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  .xh-scope-scroll-area {
+    --xh-scroll-area-skin: 1;
+  }
+
+  /* 滚动区是视口加两条 scrollbar 的组装：轨道、滑块与交叉口戴 data-scope="scrollbar"，
+     它们的皮归 scrollbar.css；这里只管视口、内容层，以及充当 scrollbar 根节点的那个挂载点。 */
+
+  /* 滚动条是绝对定位的，以它为参照，因此它必须自己建定位上下文。
+     overflow:hidden 管的是溢出边界：作者给 root 定了尺寸后，内容与滚动条都不该漫出这个框。 */
+  .xh-scope-scroll-area[data-part='root'] {
+    /* 厚度只算一次：尺寸档换的就是它，视口让道、交叉口让位与补丁都按同一个数 */
+    --xh-_scrollbar-thickness: var(--xh-scrollbar-thickness-md);
+
+    position: relative;
+    overflow: hidden;
+  }
+
+  .xh-scope-scroll-area[data-part='root'][data-size='sm'] {
+    --xh-_scrollbar-thickness: var(--xh-scrollbar-thickness-sm);
+  }
+
+  .xh-scope-scroll-area[data-part='root'][data-size='lg'] {
+    --xh-_scrollbar-thickness: var(--xh-scrollbar-thickness-lg);
+  }
+
+  /* 真正滚动的那层。原生滚动条藏起来，滚动能力一点不减——
+     键盘（PageUp/PageDown、方向键、Home/End）与滚轮走的都还是浏览器原生通路。 */
+  .xh-scope-scroll-area[data-part='viewport'] {
+    inline-size: 100%;
+    block-size: 100%;
+    /* 逻辑等价物 overflow-inline / overflow-block 至今只有个别引擎实现，
+       这两条是本文件里仅有的物理属性，换成逻辑写法会在多数浏览器上直接失效 */
+    overflow-x: auto;
+    overflow-y: auto;
+  }
+
+  /* 藏原生滚动条的标准写法；下面那条 ::-webkit-scrollbar 兜住还没实现它的引擎。
+     只藏外观，滚动能力一点不动：这里刻意不写 overscroll-behavior，
+     滚到尽头要不要把滚动传给外层，仍然按浏览器的默认来。
+     触屏上自绘滚动条交给了原生（data-native），原生滚动条就留着 */
+  .xh-scope-scroll-area[data-part='viewport']:not([data-native]) {
+    scrollbar-width: none;
+  }
+
+  .xh-scope-scroll-area[data-part='viewport']:not([data-native])::-webkit-scrollbar {
+    /* 这里不是角色节点而是伪元素，不涉及 [hidden] 那条规矩 */
+    display: none;
+  }
+
+  /* orientation 关掉的那条轴不该滚：滚动条已经不显形了，再能滚就成了滚不回来的暗格 */
+  .xh-scope-scroll-area[data-part='viewport'][data-orientation='vertical'] {
+    overflow-x: hidden;
+  }
+
+  .xh-scope-scroll-area[data-part='viewport'][data-orientation='horizontal'] {
+    overflow-y: hidden;
+  }
+
+  /* 有滚动条要占道时，视口在那条轴上收窄一条道的宽度，末端内容不再被压在滚动条底下。
+     缩视口而不是给视口加内边距：滚动容器末端缘的 padding 计不计进 scrollWidth，各引擎不一致。 */
+  .xh-scope-scroll-area[data-part='viewport'][data-lane-vertical] {
+    inline-size: calc(100% - var(--xh-_scrollbar-thickness));
+  }
+
+  .xh-scope-scroll-area[data-part='viewport'][data-lane-horizontal] {
+    block-size: calc(100% - var(--xh-_scrollbar-thickness));
+  }
+
+  /* —— 边缘渐隐 —— */
+  /* 两条轴各铺一层遮罩，取交集：还滚得动的那一侧把内容淡出，滚到头即收成 0。
+     渐变没有逻辑方向，只能沿物理方向铺，横轴那一层的两端在 rtl 下对调（见下）。
+     遮罩里的黑白画的是 alpha 的两端，不是设计色。
+     -webkit-* 那两条排在前面兜住只认前缀写法的引擎。
+     画在视口上而不是根上：自绘滚动条是视口的兄弟节点，不会跟着一起淡掉 */
+  .xh-scope-scroll-area[data-part='viewport'][data-variant='fade'] {
+    /* 渐隐带宽跟着尺寸档走，与滚动条厚度同一个 data-size */
+    --xh-_scroll-area-fade-size: var(--xh-scroll-area-fade-size, var(--xh-space-6));
+    /* 四条边各自的带宽：到头那一侧收成 0，没到头才铺开 */
+    --xh-_scroll-area-fade-block-start: 0px;
+    --xh-_scroll-area-fade-block-end: 0px;
+    --xh-_scroll-area-fade-inline-start: 0px;
+    --xh-_scroll-area-fade-inline-end: 0px;
+    --xh-_scroll-area-fade-left: var(--xh-_scroll-area-fade-inline-start);
+    --xh-_scroll-area-fade-right: var(--xh-_scroll-area-fade-inline-end);
+
+    -webkit-mask-image:
+      linear-gradient(to bottom, transparent 0, black var(--xh-_scroll-area-fade-block-start), black calc(100% - var(--xh-_scroll-area-fade-block-end)), transparent 100%),
+      linear-gradient(to right, transparent 0, black var(--xh-_scroll-area-fade-left), black calc(100% - var(--xh-_scroll-area-fade-right)), transparent 100%);
+    mask-image:
+      linear-gradient(to bottom, transparent 0, black var(--xh-_scroll-area-fade-block-start), black calc(100% - var(--xh-_scroll-area-fade-block-end)), transparent 100%),
+      linear-gradient(to right, transparent 0, black var(--xh-_scroll-area-fade-left), black calc(100% - var(--xh-_scroll-area-fade-right)), transparent 100%);
+    -webkit-mask-composite: source-in;
+    mask-composite: intersect;
+    /* 滚到头时那一侧的带子淡去、离开端点时淡回，不在到端那一帧瞬间消失 */
+    transition:
+      --xh-_scroll-area-fade-block-start var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
+      --xh-_scroll-area-fade-block-end var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
+      --xh-_scroll-area-fade-inline-start var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
+      --xh-_scroll-area-fade-inline-end var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  .xh-scope-scroll-area[data-part='viewport'][data-variant='fade'][data-size='sm'] {
+    --xh-_scroll-area-fade-size: var(--xh-scroll-area-fade-size, var(--xh-space-4));
+  }
+
+  .xh-scope-scroll-area[data-part='viewport'][data-variant='fade'][data-size='lg'] {
+    --xh-_scroll-area-fade-size: var(--xh-scroll-area-fade-size, var(--xh-space-8));
+  }
+
+  /* 还回得去、还去得了的那一侧才铺带：贴着那一端时属性在场，规则不命中 */
+  .xh-scope-scroll-area[data-part='viewport'][data-variant='fade']:not([data-at-min-vertical]) {
+    --xh-_scroll-area-fade-block-start: var(--xh-_scroll-area-fade-size);
+  }
+
+  .xh-scope-scroll-area[data-part='viewport'][data-variant='fade']:not([data-at-max-vertical]) {
+    --xh-_scroll-area-fade-block-end: var(--xh-_scroll-area-fade-size);
+  }
+
+  .xh-scope-scroll-area[data-part='viewport'][data-variant='fade']:not([data-at-min-horizontal]) {
+    --xh-_scroll-area-fade-inline-start: var(--xh-_scroll-area-fade-size);
+  }
+
+  .xh-scope-scroll-area[data-part='viewport'][data-variant='fade']:not([data-at-max-horizontal]) {
+    --xh-_scroll-area-fade-inline-end: var(--xh-_scroll-area-fade-size);
+  }
+
+  /* 从右往左排版时横轴的起始端在右：两端对调，逻辑那两支槽的取值不动 */
+  [dir='rtl'] .xh-scope-scroll-area[data-part='viewport'][data-variant='fade'] {
+    --xh-_scroll-area-fade-left: var(--xh-_scroll-area-fade-inline-end);
+    --xh-_scroll-area-fade-right: var(--xh-_scroll-area-fade-inline-start);
+  }
+
+  /* 横向溢出全靠它撑：内容若跟着视口一起收成 100% 宽，横轴永远量不出溢出，
+     横向滚动条也就永远不显形。 */
+  .xh-scope-scroll-area[data-part='content'] {
+    min-inline-size: fit-content;
+  }
+
+  /* 滚动条挂载点同时充当那条 scrollbar 的根节点：scrollbar 那份皮肤的根规则落在
+     .xh-scope-scrollbar[data-part='root'] 上，而这里没有那个节点，根该有的排布得在这儿补齐
+     （轨道与滑块的皮仍归 scrollbar 那一份）。滑块主轴的起点与长度由连接层写进内联样式，这里不碰。 */
+  .xh-scope-scroll-area[data-part='scrollbar'] {
+    position: absolute;
+    /* 浮层的 positioner 一律 pointer-events: none，条子作为它的子节点会继承到，拖不动也点不着；
+       收起态那条规则优先级更高，仍旧穿透 */
+    pointer-events: auto;
+    /* touch-action 关掉浏览器自己的手势：不关的话手指一按滑块页面就跟着滚，
+       指针随即被系统收走（pointercancel），拖到一半的滑块停在原地。
+       user-select 同理——拖动时选中页面文字会让滑块"粘"住。 */
+    touch-action: none;
+    user-select: none;
+    /* 露出与收起都淡变；收起态连 visibility 一起收，退场播完才真正摸不到 */
+    transition:
+      opacity var(--xh-motion-duration-enter) var(--xh-motion-ease-enter),
+      visibility 0s linear 0s;
+  }
+
+  .xh-scope-scroll-area[data-part='scrollbar'][data-orientation='vertical'] {
+    inset-block: 0;
+    inset-inline-end: 0;
+    inline-size: var(--xh-_scrollbar-thickness);
+  }
+
+  .xh-scope-scroll-area[data-part='scrollbar'][data-orientation='horizontal'] {
+    inset-inline: 0;
+    inset-block-end: 0;
+    block-size: var(--xh-_scrollbar-thickness);
+  }
+
+  /* 两条都在场：各自在末端让出交叉口那一格，交叉口由竖条里的 corner 补 */
+  .xh-scope-scroll-area[data-part='scrollbar'][data-orientation='vertical'][data-gutter] {
+    inset-block-end: var(--xh-_scrollbar-thickness);
+  }
+
+  .xh-scope-scroll-area[data-part='scrollbar'][data-orientation='horizontal'][data-gutter] {
+    inset-inline-end: var(--xh-_scrollbar-thickness);
+  }
+
+  .xh-scope-scroll-area[data-part='scrollbar'][data-state='hidden'] {
+    visibility: hidden;
+    opacity: 0;
+    pointer-events: none;
+    transition:
+      opacity var(--xh-motion-duration-exit) var(--xh-motion-ease-exit),
+      visibility 0s linear var(--xh-motion-duration-exit);
+  }
+
+  /* 触屏上交给原生滚动：整条不占位也不画 */
+  .xh-scope-scroll-area[data-part='scrollbar'][data-native] {
+    display: none;
+  }
+
+  /* 除视口外全是纯容器：既不进 Tab 序列也不承载焦点，作者若给它们加了 tabindex，
+     该显形的也该是视口那圈环，不是这里再多画一圈 */
+  .xh-scope-scroll-area[data-part='root']:focus-visible,
+  .xh-scope-scroll-area[data-part='content']:focus-visible,
+  .xh-scope-scroll-area[data-part='scrollbar']:focus-visible {
+    outline: none;
+  }
+
+  /* display 会盖掉 UA 的 [hidden]{display:none}，凡是被赋了 display 的角色节点都要显式让位 */
+  .xh-scope-scroll-area[data-part='scrollbar'][hidden] {
+    display: none;
+  }
+}

package/dist/css/scrollbar.css

@@ -0,0 +1,204 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 scrollbar 样式。 */
+
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  .xh-scope-scrollbar {
+    --xh-scrollbar-skin: 1;
+  }
+
+  /* 库内原生滚动面的细条规则住在 reset 层（reset.css），本文件只管自绘条本身。
+     挂了自绘滚动条的容器：原生滚动条只藏外观，滚动能力一点不动。
+     标记由机器挂监听时打上，最后一条滚动条拆走才撤。这条是 (0,1,0)，压得过 reset 层的 thin；
+     下面那条 ::-webkit-scrollbar 兜住还没实现 scrollbar-width 的引擎 */
+  [data-xh-scrollbar] {
+    scrollbar-width: none;
+  }
+
+  [data-xh-scrollbar]::-webkit-scrollbar {
+    display: none;
+  }
+
+  /* 定位分工：滑块在**主轴**上的起点与长度由连接层每帧写进内联样式——
+     竖向是 inset-block-start / block-size，横向是 inset-inline-start / inline-size。
+     这份皮肤一个都不碰：内联优先级高于样式表，写了不但是死声明，
+     换轴的那一帧还会跟连接层清空另一轴的动作抢位置，把滑块钉在两轴都被约束的地方。
+     皮肤只管另一条轴（交叉轴）的尺寸、颜色、圆角与状态表现。
+
+     根用绝对定位、贴容器的对应边：滚动容器归作者，本组件只要求它自己的定位祖先建了上下文。
+     作者要把它放在别处（比如浮在内容之上、或摆到框外），改这一条即可。 */
+  .xh-scope-scrollbar[data-part='root'] {
+    /* 厚度只算一次：尺寸档换的就是它，交叉口的让位与补丁都按同一个数 */
+    --xh-_scrollbar-thickness: var(--xh-scrollbar-thickness-md);
+
+    position: absolute;
+    /* 浮层的 positioner 一律 pointer-events: none，条子作为它的子节点会继承到，拖不动也点不着；
+       收起态那条规则优先级更高，仍旧穿透 */
+    pointer-events: auto;
+    /* touch-action 关掉浏览器自己的手势：不关的话手指一按滑块页面就跟着滚，
+       指针随即被系统收走（pointercancel），拖到一半的滑块停在原地。
+       user-select 同理——拖动时选中页面文字会让滑块"粘"住。 */
+    touch-action: none;
+    user-select: none;
+    /* 露出与收起都淡变；收起态连 visibility 一起收，退场播完才真正摸不到、也进不了 Tab 序 */
+    transition:
+      opacity var(--xh-motion-duration-enter) var(--xh-motion-ease-enter),
+      visibility 0s linear 0s;
+  }
+
+  .xh-scope-scrollbar[data-part='root'][data-size='sm'] {
+    --xh-_scrollbar-thickness: var(--xh-scrollbar-thickness-sm);
+  }
+
+  .xh-scope-scrollbar[data-part='root'][data-size='lg'] {
+    --xh-_scrollbar-thickness: var(--xh-scrollbar-thickness-lg);
+  }
+
+  .xh-scope-scrollbar[data-part='root'][data-orientation='vertical'] {
+    inset-block: 0;
+    inset-inline-end: 0;
+    inline-size: var(--xh-_scrollbar-thickness);
+  }
+
+  .xh-scope-scrollbar[data-part='root'][data-orientation='horizontal'] {
+    inset-inline: 0;
+    inset-block-end: 0;
+    block-size: var(--xh-_scrollbar-thickness);
+  }
+
+  /* 横竖两条同时摆着：各自在末端让出交叉口那一格，交叉口由 corner 补 */
+  .xh-scope-scrollbar[data-part='root'][data-orientation='vertical'][data-gutter] {
+    inset-block-end: var(--xh-_scrollbar-thickness);
+  }
+
+  .xh-scope-scrollbar[data-part='root'][data-orientation='horizontal'][data-gutter] {
+    inset-inline-end: var(--xh-_scrollbar-thickness);
+  }
+
+  /* 贴在滚动层上的根：位置由连接层按层在壳内的偏移盒写成内联几何（含让位），
+     壳边的 inset 全部放开，交叉轴的厚度仍由上面的方向规则给 */
+  .xh-scope-scrollbar[data-part='root'][data-anchor='layer'] {
+    inset: auto;
+  }
+
+  .xh-scope-scrollbar[data-part='root'][data-state='hidden'] {
+    visibility: hidden;
+    opacity: 0;
+    pointer-events: none;
+    transition:
+      opacity var(--xh-motion-duration-exit) var(--xh-motion-ease-exit),
+      visibility 0s linear var(--xh-motion-duration-exit);
+  }
+
+  /* 触屏上交给原生滚动：整条不占位也不画 */
+  .xh-scope-scrollbar[data-part='root'][data-native] {
+    display: none;
+  }
+
+  /* 轨道铺满根，滑块的行程按它量。内边距把滑块从两侧收进来一点，
+     与 scroll-area 那份共用同一个间隙令牌 */
+  .xh-scope-scrollbar[data-part='track'] {
+    position: relative;
+    inline-size: 100%;
+    block-size: 100%;
+    padding: var(--xh-scrollbar-gutter);
+    background: var(--xh-scrollbar-track-bg, var(--xh-bg-scrollbar-track));
+  }
+
+  /* 滑块。主轴（起点 + 长度）来自内联样式，这里只给定位模式、交叉轴与配色。
+     绝不给 inset / size 加过渡：滚动时这两个值每帧都在变，一加过渡滑块就永远追在内容后面。
+     也刻意不写 min-block-size / min-inline-size：滑块的最短长度由几何层折进内联尺寸里，
+     样式表再给一个下限就成了两个事实源，两者一旦不一致，滑块的实际长度与它能走的距离就对不上。 */
+  .xh-scope-scrollbar[data-part='thumb'] {
+    position: absolute;
+    border-radius: var(--xh-scrollbar-thumb-radius, var(--xh-shape-pill));
+    background: var(
+      --xh-scrollbar-thumb-bg,
+      var(--xh-fg-scrollbar-thumb)
+    );
+    /* 滑块里没有字，这支墨色只给聚焦环用。 */
+    color: var(--xh-fg-default);
+    cursor: default;
+    transition:
+      background-color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
+      color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  /* 交叉轴在轨道内两侧各收进一个间隙，与轨道那条 padding 共用同一个旋钮。
+     这一侧的 inset 连接层每帧写成空串（即不设），样式表接手才有确定值；
+     不写的话绝对定位会退回"静态位置"。
+     主轴那一侧一律不写：几何层量的轨道是 padding box，滑块长度也解析在同一个盒子上。 */
+  .xh-scope-scrollbar[data-part='thumb'][data-orientation='vertical'] {
+    inset-inline: var(--xh-scrollbar-gutter);
+  }
+
+  .xh-scope-scrollbar[data-part='thumb'][data-orientation='horizontal'] {
+    inset-block: var(--xh-scrollbar-gutter);
+  }
+
+  /* 这两档的面往另一头走（浅色主题更深、深色主题更亮），配对的墨色跟着翻到反色那一支 */
+  .xh-scope-scrollbar[data-part='thumb']:hover {
+    background: var(
+      --xh-scrollbar-thumb-bg-hover,
+      var(--xh-fg-scrollbar-thumb-hover)
+    );
+  }
+
+  .xh-scope-scrollbar[data-part='thumb'][data-dragging] {
+    background: var(
+      --xh-scrollbar-thumb-bg-active,
+      var(--xh-fg-scrollbar-thumb-active)
+    );
+  }
+
+  /* 面是实心的中性色，环色与面同族，画在面里就看不出来；环改取这一档配对的墨色 */
+  .xh-scope-scrollbar[data-part='thumb']:not([data-disabled]):focus-visible {
+    --xh-_ring-color: currentColor;
+  }
+
+  /* 根与轨道都是纯容器，不承载焦点；作者若给它们加了 tabindex，也不该在这儿多画一圈 */
+  .xh-scope-scrollbar[data-part='root']:focus-visible,
+  .xh-scope-scrollbar[data-part='track']:focus-visible {
+    outline: none;
+  }
+
+  /* 禁用：整条不显形，这里只兜住作者硬把它显出来的那一路 */
+  .xh-scope-scrollbar[data-part='thumb'][data-disabled] {
+    background: var(--xh-scrollbar-thumb-bg-disabled, var(--xh-border-subtle));
+  }
+
+  /* 交叉口补丁：贴在本条末端之外的那一格，与轨道同色，跟着本条淡入淡出 */
+  .xh-scope-scrollbar[data-part='corner'] {
+    position: absolute;
+    inline-size: var(--xh-_scrollbar-thickness);
+    block-size: var(--xh-_scrollbar-thickness);
+    background: var(--xh-scrollbar-corner-bg, var(--xh-scrollbar-track-bg, transparent));
+  }
+
+  .xh-scope-scrollbar[data-part='corner'][data-orientation='vertical'] {
+    inset-inline-start: 0;
+    inset-block-end: calc(-1 * var(--xh-_scrollbar-thickness));
+  }
+
+  .xh-scope-scrollbar[data-part='corner'][data-orientation='horizontal'] {
+    inset-block-start: 0;
+    inset-inline-end: calc(-1 * var(--xh-_scrollbar-thickness));
+  }
+
+  .xh-scope-scrollbar[data-part='root'][hidden],
+  .xh-scope-scrollbar[data-part='corner'][hidden] {
+    display: none;
+  }
+
+  @media print {
+    /* 打印：滚动条画的是「还能往下看多少」，纸上没有这回事，它只会在版心边上留一条灰带。 */
+    .xh-scope-scrollbar[data-part='root'],
+    .xh-scope-scrollbar[data-part='corner'] {
+      display: none;
+    }
+  }
+}