@xihan-ui/styles 3.1.0 → 4.0.0

package/dist/css/layout.css

@@ -0,0 +1,379 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 layout 样式。 */
+
+/* 独立皮肤传递引入折叠把手的动作控件配方，full bundle 递归去重。 */
+@import '../family/action-control.css';
+
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  .xh-scope-layout {
+    --xh-layout-skin: 1;
+  }
+
+  /* 页面骨架排成三行两列：头与脚各横贯一整行，侧栏与内容并排占中间那一行。
+     缺哪一段，对应的行/列就没有条目，宽高自动收成 0，不必为"少写一段"另立规则。
+
+     侧栏两档宽度与头的高度声明在根上：各段自己读这些槽，换档只改这里。
+     宽度槽用 -w 缩写，与同处的 --xh-layout-header-h 一致；两档宽度的缺省取侧栏令牌 --xh-sider-w / --xh-sider-collapsed-w。
+     头的高度之所以也归到根上：头吸顶时头这一行的轨道要按同一个值定高，两处必须同源。 */
+  .xh-scope-layout[data-part='root'] {
+    display: grid;
+    grid-template-areas:
+      'header header'
+      'sider content'
+      'footer footer';
+    grid-template-columns: auto minmax(0, 1fr);
+    grid-template-rows: auto minmax(0, 1fr) auto;
+    background: var(--xh-layout-bg, var(--xh-bg-page));
+    color: var(--xh-layout-fg, var(--xh-fg-default));
+    --xh-_layout-sider-expanded-w: var(--xh-layout-sider-w, var(--xh-sider-w));
+    --xh-_layout-sider-w: var(--xh-_layout-sider-expanded-w);
+    --xh-_layout-sider-collapsed-w: var(--xh-layout-sider-collapsed-w, var(--xh-sider-collapsed-w));
+    --xh-_layout-header-h: var(--xh-layout-header-h, var(--xh-app-header-h));
+    /* 侧栏吸附时钉在哪条线上：缺省贴滚动容器上沿，头也吸顶时改成让开头的高度 */
+    --xh-_layout-sider-offset: 0px;
+  }
+
+  /* —— 侧栏断点 —— */
+  /* 写了断点档就先按窄屏排（折叠宽），视口宽到那一档再还原成展开宽。
+     移动优先、四档只用 min-width：媒体查询不改选择器权重，同时命中好几档时由源码序决定谁生效。
+     宽度写字面量：自定义属性在 @media 条件里不参与求值，令牌变量写在这里等于没写条件。
+     换的只是宽度，折叠态不动——那条通道归 siderCollapsed。 */
+  .xh-scope-layout[data-part='root'][data-sider-breakpoint] {
+    --xh-_layout-sider-w: var(--xh-_layout-sider-collapsed-w);
+  }
+
+  @media (min-width: 640px) {
+    .xh-scope-layout[data-part='root'][data-sider-breakpoint='sm'] {
+      --xh-_layout-sider-w: var(--xh-_layout-sider-expanded-w);
+    }
+  }
+
+  @media (min-width: 768px) {
+    .xh-scope-layout[data-part='root'][data-sider-breakpoint='md'] {
+      --xh-_layout-sider-w: var(--xh-_layout-sider-expanded-w);
+    }
+  }
+
+  @media (min-width: 1024px) {
+    .xh-scope-layout[data-part='root'][data-sider-breakpoint='lg'] {
+      --xh-_layout-sider-w: var(--xh-_layout-sider-expanded-w);
+    }
+  }
+
+  @media (min-width: 1280px) {
+    .xh-scope-layout[data-part='root'][data-sider-breakpoint='xl'] {
+      --xh-_layout-sider-w: var(--xh-_layout-sider-expanded-w);
+    }
+  }
+
+  /* 侧栏挂到行尾：两列对调，内容在前 */
+  .xh-scope-layout[data-part='root'][data-sider-placement='end'] {
+    grid-template-areas:
+      'header header'
+      'content sider'
+      'footer footer';
+    grid-template-columns: minmax(0, 1fr) auto;
+  }
+
+  /* —— 各段 —— */
+  .xh-scope-layout[data-part='header'] {
+    display: flex;
+    grid-area: header;
+    align-items: center;
+    gap: var(--xh-layout-header-gap, var(--xh-space-3));
+    block-size: var(--xh-_layout-header-h);
+    padding-inline: var(--xh-layout-header-px, var(--xh-space-4));
+    background: var(--xh-layout-header-bg, var(--xh-bg-surface));
+  }
+
+  /* 宽度过渡在这里声明一次，展开与折叠两档、以及 props 直接写进内联的宽度，走的都是这一条。
+     侧栏与头同是白底承载面，坐在灰的页面底上：把手摆进来走白底阶梯 hover 100 → pressed 200 */
+  .xh-scope-layout[data-part='sider'] {
+    /* 内衬缺省一档，装了 SideNav 的侧栏在下面归零；覆盖档与安全区取大时读的也是这一支 */
+    --xh-_layout-sider-padding: var(--xh-space-3);
+
+    grid-area: sider;
+    inline-size: var(--xh-_layout-sider-w);
+    overflow: hidden;
+    padding: var(--xh-layout-sider-padding, var(--xh-_layout-sider-padding));
+    background: var(--xh-layout-sider-bg, var(--xh-bg-surface));
+    transition: inline-size var(--xh-motion-duration-move) var(--xh-motion-ease-continuous);
+  }
+
+  /* 折起来时不换行：窄到放不下的那几个字直接被 overflow 裁掉，不会挤成一列竖排 */
+  .xh-scope-layout[data-part='sider'][data-collapsed] {
+    inline-size: var(--xh-_layout-sider-collapsed-w);
+    white-space: nowrap;
+  }
+
+  /* 侧栏里装着 SideNav 时内衬缺省归零：SideNav 自带一圈内衬，宽度又与侧栏同取侧栏令牌，
+     再叠一圈侧栏内衬，导航就比侧栏的内容盒宽出两侧内衬、右缘被裁掉。
+     认后代而不是子代：Web Components 在侧栏与导航根之间隔着 <xh-side-nav> 宿主。
+     不认 :has() 的引擎（Firefox 121 以前）照旧留内衬，导航右缘被裁，与改动前一致 */
+  .xh-scope-layout[data-part='sider']:has(.xh-scope-side-nav[data-part='root']) {
+    --xh-_layout-sider-padding: 0;
+  }
+
+  /* 侧栏里的 SideNav 跟着侧栏收放：侧栏这一次开合直接落位（首帧、跨过断点）时，导航的宽度同样直接落位 */
+  .xh-scope-layout[data-part='sider'][data-instant] .xh-scope-side-nav[data-part='root'] {
+    transition: none;
+  }
+
+  .xh-scope-layout[data-part='content'] {
+    grid-area: content;
+    /* 内容列已是 minmax(0, 1fr)，这里再声明一次，宽表格与长串文本才撑不破列 */
+    min-inline-size: 0;
+    padding: var(--xh-layout-content-padding, var(--xh-space-4));
+  }
+
+  .xh-scope-layout[data-part='footer'] {
+    grid-area: footer;
+    padding: var(--xh-layout-footer-padding, var(--xh-space-3) var(--xh-space-4));
+    background: var(--xh-layout-footer-bg, var(--xh-bg-surface));
+    color: var(--xh-fg-muted);
+    font-size: var(--xh-text-secondary-size);
+  }
+
+  /* —— 折叠把手 —— */
+  /* 一枚小档文字按钮：盒型、悬停 / 按下面与按压缩放由 Action Control 的 text 档给（ghost 形态，sm 档：
+     摆在顶栏等白底上按画布承载 hover 100 → pressed 200，摆进占位档侧栏时由侧栏下发 host 槽 200 → 300，
+     覆盖档侧栏是 elevated 白底、仍是 100 → 200）；
+     这里只把使用者槽映射到桥接槽（-gap / -px / -radius / -bg / -bg-hover / -bg-active / -fg 保留为第一参数） */
+  .xh-scope-layout[data-part='sider-trigger'] {
+    --xh-action-gap: var(--xh-layout-sider-trigger-gap, var(--xh-_action-profile-gap));
+    --xh-action-padding-inline: var(--xh-layout-sider-trigger-px, var(--xh-_action-profile-padding-inline));
+    --xh-action-radius: var(--xh-layout-sider-trigger-radius, var(--xh-_action-profile-radius));
+    --xh-action-bg-rest: var(--xh-layout-sider-trigger-bg, var(--xh-_action-variant-bg-rest));
+    --xh-action-bg-hover: var(--xh-layout-sider-trigger-bg-hover, var(--xh-_action-variant-bg-hover));
+    --xh-action-bg-pressed: var(--xh-layout-sider-trigger-bg-active, var(--xh-_action-variant-bg-pressed));
+    --xh-action-fg-rest: var(--xh-layout-sider-trigger-fg, var(--xh-_action-variant-fg-rest));
+    --xh-action-fg-hover: var(--xh-layout-sider-trigger-fg, var(--xh-_action-variant-fg-hover));
+    --xh-action-fg-pressed: var(--xh-layout-sider-trigger-fg, var(--xh-_action-variant-fg-pressed));
+  }
+
+  /* —— 分隔线 —— */
+  /* 头与侧栏都是白底：头的下沿与侧栏挨着内容的那一边缺省画一条内部分隔，两块白面才分得开；
+     作者开了 split 再换成 border-default，并把内容与尾也隔开 */
+  .xh-scope-layout[data-part='header'] {
+    border-block-end: var(--xh-stroke-thin) solid var(--xh-layout-border, var(--xh-border-subtle));
+  }
+
+  .xh-scope-layout[data-part='sider'][data-placement='start'] {
+    border-inline-end: var(--xh-stroke-thin) solid var(--xh-layout-border, var(--xh-border-subtle));
+  }
+
+  .xh-scope-layout[data-part='sider'][data-placement='end'] {
+    border-inline-start: var(--xh-stroke-thin) solid var(--xh-layout-border, var(--xh-border-subtle));
+  }
+
+  /* 后代选择器带上 data-scope：骨架里装着整页内容，光凭 data-part 会连里面别的组件同名段一起画上线 */
+  .xh-scope-layout[data-part='root'][data-split] .xh-scope-layout[data-part='header'] {
+    border-block-end: var(--xh-stroke-thin) solid var(--xh-layout-border, var(--xh-border-default));
+  }
+
+  .xh-scope-layout[data-part='root'][data-split] .xh-scope-layout[data-part='footer'] {
+    border-block-start: var(--xh-stroke-thin) solid var(--xh-layout-border, var(--xh-border-default));
+  }
+
+  /* 侧栏只在挨着内容的那一边画线，另一边贴着骨架外沿，画了就是一条多出来的边框 */
+  .xh-scope-layout[data-part='root'][data-split] .xh-scope-layout[data-part='sider'][data-placement='start'] {
+    border-inline-end: var(--xh-stroke-thin) solid var(--xh-layout-border, var(--xh-border-default));
+  }
+
+  .xh-scope-layout[data-part='root'][data-split] .xh-scope-layout[data-part='sider'][data-placement='end'] {
+    border-inline-start: var(--xh-stroke-thin) solid var(--xh-layout-border, var(--xh-border-default));
+  }
+
+  /* —— 固定定位 —— */
+  /* 滚动容器的分工：滚动发生在骨架外面——root 的高度跟着内容长，页面（或作者套在外层的
+     那个定高盒子）才是滚动容器；content 不改成滚动容器。
+     两条理由：一是 content 自己滚的话头与侧栏本来就不会动，两个开关也就没有区别了；
+     二是 sticky 的行程被自己的包含块框住，root 一旦定高，行里的轨道就不再跟着内容长，
+     钉住的那一段滚过一屏后会被包含块拽走。
+     由此还有一条：给 root 写 overflow（比如为了圆角裁剪）会让它自己变成一个永远滚不动的
+     滚动容器，里面的 sticky 随之成为空操作——要固定就把 overflow 挪到 root 外面那层。 */
+
+  /* 头这一行改成定高：下面那条让头跨满所有行，行 1 就没有条目撑着它了 */
+  .xh-scope-layout[data-part='root'][data-header-fixed] {
+    grid-template-rows: var(--xh-_layout-header-h) minmax(0, 1fr) auto;
+  }
+
+  /* 跨满所有行只为把包含块撑到整副骨架那么高：头若只占行 1，包含块与它自己一样高，
+     sticky 的行程就是 0，钉住与不钉住看不出区别。
+     起始缘对齐把它按回行 1 的位置，视觉上与不固定时一样；高度被作者改成 auto 时也不会被拉满整块区域。
+     头的背景（--xh-layout-header-bg）要留实色，否则滚过去的正文会从头底下透出来。 */
+  .xh-scope-layout[data-part='header'][data-fixed] {
+    position: sticky;
+    z-index: var(--xh-layout-header-layer, var(--xh-layer-sticky));
+    grid-row: 1 / -1;
+    align-self: start;
+    inset-block-start: 0;
+  }
+
+  /* liquid 档：吸顶的顶栏是内容从下面滚过的导航层，换成液态面。贴边铺满的栏不取圆角，
+     边界由下沿那条墨色细线承担。液态面是墨色域，前景在这里按域重取，子孙跟着继承。
+     滚过深浅分界时色调翻转：底色、字色、细线与投影一起淡变，不在同一帧跳 */
+  :where([data-material='liquid']) .xh-scope-layout[data-part='header'][data-fixed][data-xh-liquid] {
+    border-block-end: var(--xh-stroke-thin) solid var(--xh-layout-border, var(--xh-material-liquid-border));
+    background: var(--xh-layout-header-bg, var(--xh-_liquid-bg));
+    color: var(--xh-material-liquid-fg);
+    box-shadow: var(--xh-_liquid-shadow);
+    -webkit-backdrop-filter: var(--xh-material-liquid-backdrop);
+    backdrop-filter: var(--xh-material-liquid-backdrop);
+    transition:
+      background-color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
+      border-color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
+      color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
+      box-shadow var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  /* 头也吸顶时侧栏钉在头的下沿，两段不叠在一起 */
+  .xh-scope-layout[data-part='root'][data-header-fixed][data-sider-fixed] {
+    --xh-_layout-sider-offset: var(--xh-_layout-header-h);
+  }
+
+  /* 侧栏保持默认的拉伸对齐，只加一道高度上限：内容短时它照旧填满整列，内容长过一屏时它收成
+     可视区那么高，短出来的那一段就是 sticky 的行程。
+     上限量的是滚动容器可视区的高度，缺省按视口算；滚动容器不是视口时由作者把那个高度写进
+     --xh-layout-scrollport-h。视口取 dvh：移动端地址栏收放会改变可视高度，dvh 跟着变；
+     不认 dvh 的引擎由级联回落到前一条的 vh。
+     侧栏自己的条目多到装不下时在内部滚，横轴仍归上面那条 overflow: hidden 裁，
+     折叠态靠它把放不下的字裁掉；逻辑属性 overflow-block 尚无可用实现，写物理轴。 */
+  .xh-scope-layout[data-part='sider'][data-fixed] {
+    position: sticky;
+    inset-block-start: var(--xh-_layout-sider-offset);
+    max-block-size: calc(var(--xh-layout-scrollport-h, 100vh) - var(--xh-_layout-sider-offset));
+    max-block-size: calc(var(--xh-layout-scrollport-h, 100dvh) - var(--xh-_layout-sider-offset));
+    overflow-y: auto;
+  }
+
+  /* —— 侧栏覆盖档 —— */
+  /* 侧栏移出画外、盖在内容之上：面板脱离网格，侧栏那一列于是收成零宽，内容占满整行。
+     排在固定定位那一节之后：两处特指度相同，覆盖档要盖住 sticky 那一档。
+     参照的是视口，与上面 sticky 那条同一个注意事项：整副骨架装进带 transform / filter 的祖先里时，
+     固定定位的包含块会换成那个祖先，面板跟着一起滚。 */
+  .xh-scope-layout[data-part='sider'][data-presentation='sheet'] {
+    /* 位移方向的私有槽位：默认按行首 + LTR，行尾与 RTL 在下面翻符号。幅度取整幅位移令牌，
+       减弱动效下归零。写成槽位而不是写死物理方向：贴边用的是逻辑 inset，RTL 下行首落在物理右边，
+       位移若写死物理方向就会出现「贴在右边、却从左边滑进来」 */
+    --xh-_layout-sheet-shift: calc(-1 * var(--xh-motion-travel));
+
+    position: fixed;
+    z-index: var(--xh-layout-sider-layer, var(--xh-layer-drawer));
+    inset-block: 0;
+    inset-inline-start: 0;
+    inset-inline-end: auto;
+    inline-size: var(--xh-_layout-sider-expanded-w);
+    /* 面板贴死上下两条边，高度上限就是滚动容器可视区那么高——上面 sticky 那一档的
+       「减去顶栏偏移」在这一档不作数：覆盖档从视口顶铺到底。
+       不认 dvh 的引擎由级联回落到前一条的 vh */
+    max-block-size: var(--xh-layout-scrollport-h, 100vh);
+    max-block-size: var(--xh-layout-scrollport-h, 100dvh);
+    /* 贴死视口的那一档，内衬与安全区取大的一头：刘海、圆角与底部横条压住的那一段由系统给出。
+       桌面上 env() 恒为 0，取值与内衬槽完全一致。安全区只有物理方向的四个名字，
+       行内轴上两侧同取较宽的那一段，RTL 下不会翻错边 */
+    padding-block-start: max(var(--xh-layout-sider-padding, var(--xh-_layout-sider-padding)), env(safe-area-inset-top));
+    padding-block-end: max(var(--xh-layout-sider-padding, var(--xh-_layout-sider-padding)), env(safe-area-inset-bottom));
+    padding-inline: max(
+      var(--xh-layout-sider-padding, var(--xh-_layout-sider-padding)),
+      env(safe-area-inset-left),
+      env(safe-area-inset-right)
+    );
+    /* 盖在内容之上、带遮罩的一面走 sheet 三件套（--xh-material-elevated-bg / -border / -shadow），
+       贴着内容那一侧描一条边；占位档的侧栏不画投影 */
+    border-inline-end: var(--xh-stroke-thin) solid var(--xh-layout-border, var(--xh-material-elevated-border));
+    background: var(--xh-layout-sider-bg, var(--xh-material-elevated-bg));
+    box-shadow: var(--xh-layout-sider-shadow, var(--xh-material-elevated-shadow));
+    translate: 0 0;
+    visibility: visible;
+    /* 条目多到装不下时在面板内部滚：这一档的高度就是视口那么高。
+       overscroll 不在这里写 contain：这一面与占位档共用同一个部件，scroll-surface-registry 把侧栏整体登记为
+       页内结构容器（overscroll=false），门禁按整个部件核，不按档分 */
+    overflow-y: auto;
+    /* 推出来走 slide 档：视口尺度的位移。并列的不透明度取淡变档：
+       缺省两端都是不透明、看不出来，减弱动效下整幅位移归零、由它表达进出。
+       visibility 展开那一路立刻露出来 */
+    opacity: 1;
+    transition:
+      translate var(--xh-motion-duration-slide) var(--xh-motion-ease-slide),
+      opacity var(--xh-motion-duration-enter) var(--xh-motion-ease-enter),
+      visibility var(--xh-motion-duration-slide) var(--xh-motion-ease-slide);
+  }
+
+  /* 挂在行尾：贴另一条边，位移随之反向，描边也换到贴着内容的那一侧 */
+  .xh-scope-layout[data-part='sider'][data-presentation='sheet'][data-placement='end'] {
+    --xh-_layout-sheet-shift: var(--xh-motion-travel);
+
+    inset-inline-start: auto;
+    inset-inline-end: 0;
+    border-inline-end: 0;
+    border-inline-start: var(--xh-stroke-thin) solid var(--xh-layout-border, var(--xh-material-elevated-border));
+  }
+
+  .xh-scope-layout[data-part='sider'][data-presentation='sheet']:dir(rtl) {
+    --xh-_layout-sheet-shift: var(--xh-motion-travel);
+  }
+
+  .xh-scope-layout[data-part='sider'][data-presentation='sheet'][data-placement='end']:dir(rtl) {
+    --xh-_layout-sheet-shift: calc(-1 * var(--xh-motion-travel));
+  }
+
+  /* 收起：推出画外并让出无障碍树与 Tab 序列。位移量按面板自身宽度的百分比算，
+     宽度换成任何一档都正好推到画外。收进去是退场，位移与淡出同走退场档，
+     visibility 等这一段播完才真正藏起来；减弱动效下位移归零，只剩淡出 */
+  .xh-scope-layout[data-part='sider'][data-presentation='sheet'][data-collapsed] {
+    translate: var(--xh-_layout-sheet-shift) 0;
+    opacity: var(--xh-motion-travel-opacity);
+    visibility: hidden;
+    transition:
+      translate var(--xh-motion-duration-exit) var(--xh-motion-ease-exit),
+      opacity var(--xh-motion-duration-exit) var(--xh-motion-ease-exit),
+      visibility var(--xh-motion-duration-exit) var(--xh-motion-ease-exit);
+  }
+
+  /* 覆盖档的遮罩：与面板同一个层号，谁盖谁看文档序——遮罩写在侧栏之前。
+     占位档下连接层给它打 hidden，这里不必再管 */
+  .xh-scope-layout[data-part='sider-backdrop'] {
+    position: fixed;
+    z-index: var(--xh-layout-sider-backdrop-layer, var(--xh-layer-drawer));
+    inset: 0;
+    background: var(--xh-layout-sider-backdrop-bg, var(--xh-bg-overlay));
+    opacity: 1;
+    transition: opacity var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
+  }
+
+  /* 收起态：淡出并让开指针，底下的内容照常点得到；淡出走退场档 */
+  .xh-scope-layout[data-part='sider-backdrop'][data-collapsed] {
+    opacity: 0;
+    pointer-events: none;
+    transition: opacity var(--xh-motion-duration-exit) var(--xh-motion-ease-exit);
+  }
+
+  /* 侧栏与遮罩的过渡只给用户的开合：首帧与跨过断点这类环境引起的开合，连接层投影 data-instant，
+     直接落位。三条各压过同一部件上带过渡的那一档（占位 / 覆盖展开、覆盖收起、遮罩收起） */
+  .xh-scope-layout:is([data-part='sider'], [data-part='sider-backdrop'])[data-instant],
+  .xh-scope-layout[data-part='sider'][data-presentation='sheet'][data-collapsed][data-instant],
+  .xh-scope-layout[data-part='sider-backdrop'][data-collapsed][data-instant] {
+    transition: none;
+  }
+
+  /* 纸上没有覆盖这回事：遮罩印出来就是盖住正文的一片灰 */
+  @media print {
+    .xh-scope-layout[data-part='sider-backdrop'] {
+      display: none;
+    }
+  }
+
+  /* 声明过任何 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去。
+     写在文件末尾：兜底必须排在该部件所有 display 声明之后 */
+  .xh-scope-layout[data-part='root'][hidden],
+  .xh-scope-layout[data-part='header'][hidden],
+  .xh-scope-layout[data-part='sider-trigger'][hidden] {
+    display: none;
+  }
+}

package/dist/css/liquid.css

@@ -0,0 +1,106 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/*
+ * 液态材质层：与组件无关，全库共用一份。
+ *
+ * data-material="liquid" 下，连接层投影了 data-xh-liquid 的导航层部件（浮动钮、回到顶部等浮在内容之上的控制面）
+ * 换成液态面。这里只声明私有槽，各组件皮肤在自己的部件上把 Action Control 的桥接槽指过来；standard 档下
+ * 这些槽没人读，部件保持原材质。
+ *
+ * 静态形态（服务端、挂载前，或液态面还没判定下层）：色调随主题极性，不透明度取可读下限，这一档对任何
+ * 下层都保证标签 4.5:1。组件的状态机把部件挂进 core 的液态面，由它按下层在部件上写：
+ *   data-xh-ink              dark / light：部件成为黑墨或白墨域。墨色域本身是浅色 / 深色主题边界，
+ *                            按主题取值的液态通道随之落到那一种色调
+ *   data-xh-liquid-clarity   clear：下层均匀且色调已知，换通透档
+ *   --xh-_liquid-light-x / -y 光源方向的单位向量，决定 1px 亮边落在哪一侧
+ *   --xh-_liquid-deform      按住时的形变（transform 串），松手弹回后撤掉
+ *
+ * 同一宿主里的几块可以结成液态组（core 的 trackLiquidGoo）：宿主带 data-xh-liquid-goo，最前面多一层
+ * [data-xh-liquid-goo-layer] 色块层，沿整组的外形画底色、墨色细线、亮边与投影；组件皮肤在这一档把块自己的
+ * 面、细线、亮边与投影撤掉，只留磨砂。
+ */
+@layer xihan.components {
+  :where([data-material='liquid']) [data-xh-liquid] {
+    /* 光源缺省在左上方 */
+    --xh-_liquid-light-x: -0.71;
+    --xh-_liquid-light-y: -0.71;
+    --xh-_liquid-bg: var(--xh-material-liquid-bg);
+    /* 1px 亮边是两层零模糊内阴影：阴影形状朝背光方向偏移，露出的一弯落在朝光源的一侧，
+       另一层反过来偏移，在背光一侧留一道弱亮边。面内不加高光 */
+    --xh-_liquid-rim:
+      inset calc(var(--xh-_liquid-light-x) * var(--xh-stroke-thin) * -1) calc(var(--xh-_liquid-light-y) * var(--xh-stroke-thin) * -1) 0 0 var(--xh-material-liquid-highlight),
+      inset calc(var(--xh-_liquid-light-x) * var(--xh-stroke-thin)) calc(var(--xh-_liquid-light-y) * var(--xh-stroke-thin)) 0 0 var(--xh-material-liquid-rim-far);
+    --xh-_liquid-shadow: var(--xh-_liquid-rim), var(--xh-material-liquid-shadow);
+    /* 交互阶梯往部件自己的前景色兑：浅色调变深、深色调变浅 */
+    --xh-_liquid-bg-hover: color-mix(in oklab, var(--xh-_liquid-bg), var(--xh-material-liquid-fg) 8%);
+    --xh-_liquid-bg-pressed: color-mix(in oklab, var(--xh-_liquid-bg), var(--xh-material-liquid-fg) 14%);
+    /* 按住时的黏滞形变：液态面在手指按住期间逐帧写进来（朝手指鼓出、沿指向拉长、另一个方向压扁），
+       松手由弹簧带回后撤掉；组件皮肤拿它当 transform。没按住时为 none */
+    --xh-_liquid-deform: none;
+  }
+
+  /* 通透档：下层均匀且色调已知时由液态面写上，着色按主题取值，已随墨色域落到对应色调 */
+  :where([data-material='liquid']) [data-xh-liquid][data-xh-liquid-clarity='clear'] {
+    --xh-_liquid-bg: color-mix(in oklab, var(--xh-material-liquid-tint) calc(var(--xh-material-liquid-alpha-clear) * 100%), transparent);
+  }
+
+  /* 液态组的色块层：core 在宿主最前面生成（aria-hidden、不接指针），压在各块之下，每块一个色块，
+     跟着块的盒子、圆角与变换走。色块层套 core 放在它旁边的粘连滤镜（行内 filter），滤镜只取色块的轮廓，
+     把靠得够近的连成一片，再沿整体外形画液态面：投影、底色、墨色细线、朝光亮边与背光弱亮边，颜色都在下面
+     按段取液态令牌，投影由色块自己带着、滤镜只留外形之外的那部分。色调（墨色域）与通透档由 core 按源块的
+     读数同步到色块层与装滤镜的 <svg> 上。
+     色块层不设层号，靠排在宿主最前压在各块之下：宿主须是定位元素，组里的块须是定位元素（或装在定位容器里）。
+     层往外多铺一圈，给模糊与投影留出余地。组件可以在自己的宿主上改写投影槽，把使用者的投影槽接进来 */
+  [data-xh-liquid-goo-layer] {
+    --xh-_liquid-goo-shadow: var(--xh-material-liquid-shadow);
+
+    position: absolute;
+    inset: calc(-1 * var(--xh-space-8));
+    pointer-events: none;
+  }
+
+  /* 色块提供轮廓与投影，底色由滤镜铺 */
+  [data-xh-liquid-goo-layer] > span {
+    position: absolute;
+    box-sizing: border-box;
+    background-color: var(--xh-material-liquid-tint);
+    box-shadow: var(--xh-_liquid-goo-shadow);
+  }
+
+  [data-xh-liquid-goo-filter] [data-xh-goo-paint='fill'] {
+    flood-color: var(--xh-material-liquid-tint);
+    flood-opacity: var(--xh-material-liquid-alpha-floor);
+  }
+
+  [data-xh-liquid-goo-filter][data-xh-liquid-clarity='clear'] [data-xh-goo-paint='fill'] {
+    flood-opacity: var(--xh-material-liquid-alpha-clear);
+  }
+
+  [data-xh-liquid-goo-filter] [data-xh-goo-paint='edge'] {
+    flood-color: var(--xh-material-liquid-border);
+  }
+
+  [data-xh-liquid-goo-filter] [data-xh-goo-paint='near'] {
+    flood-color: var(--xh-material-liquid-highlight);
+  }
+
+  [data-xh-liquid-goo-filter] [data-xh-goo-paint='far'] {
+    flood-color: var(--xh-material-liquid-rim-far);
+  }
+
+  /* 强制色：系统配色下只留块自己的边，装饰色块撤掉 */
+  @media (forced-colors: active) {
+    [data-xh-liquid-goo-layer] {
+      display: none;
+    }
+  }
+
+  /* 从右往左排版时光源缺省在右上方 */
+  :where([dir='rtl']) :where([data-material='liquid']) [data-xh-liquid],
+  :where([data-material='liquid']) :where([dir='rtl']) [data-xh-liquid] {
+    --xh-_liquid-light-x: 0.71;
+  }
+}

package/dist/css/list.css

@@ -0,0 +1,156 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 list 样式。 */
+
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  .xh-scope-list {
+    --xh-list-skin: 1;
+  }
+
+  .xh-scope-list[data-part='root'] {
+    /* 一个尺寸档只换这几个私有槽，条目与两行文字都从根上继承它们，
+       换档不必给每个部件各写一条选择器 */
+    --xh-_list-item-py: var(--xh-list-item-py-md);
+    --xh-_list-item-px: var(--xh-list-item-px-md);
+    --xh-_list-item-gap: var(--xh-space-4);
+    --xh-_list-title-size: var(--xh-control-font-md);
+    --xh-_list-description-size: var(--xh-control-font-md);
+    /* 条目悬停换到的面：坐在白底上是 100，淡底档的根把它抬到 200（按承载面的阶梯） */
+    --xh-_list-item-bg-hover: var(--xh-bg-subtle);
+
+    display: flex;
+    flex-direction: column;
+    /* 根可能写成 ul/ol，UA 的项目符号与左缩进在这里清掉：换哪个标签都排成同一个样子 */
+    margin: 0;
+    padding: 0;
+    list-style: none;
+    color: var(--xh-list-fg, var(--xh-fg-default));
+    font-size: var(--xh-text-body-size);
+    line-height: var(--xh-text-body-leading);
+  }
+
+  /* 上面声明了 display，会盖掉 UA 的 [hidden] 规则，收起态要在这里接回来 */
+  .xh-scope-list[data-part='root'][hidden] {
+    display: none;
+  }
+
+  /* —— 尺寸 —— */
+  .xh-scope-list[data-part='root'][data-size='sm'] {
+    --xh-_list-item-py: var(--xh-list-item-py-sm);
+    --xh-_list-item-px: var(--xh-list-item-px-sm);
+    --xh-_list-item-gap: var(--xh-space-3);
+    --xh-_list-title-size: var(--xh-control-font-sm);
+    --xh-_list-description-size: var(--xh-control-font-sm);
+  }
+
+  .xh-scope-list[data-part='root'][data-size='lg'] {
+    --xh-_list-item-py: var(--xh-list-item-py-lg);
+    --xh-_list-item-px: var(--xh-list-item-px-lg);
+    --xh-_list-item-gap: var(--xh-space-5);
+    --xh-_list-title-size: var(--xh-control-font-lg);
+    --xh-_list-description-size: var(--xh-control-font-lg);
+  }
+
+  /* —— 形态：ghost 即基础规则，不画壳 —— */
+  .xh-scope-list[data-part='root'][data-variant='outline'] {
+    border: var(--xh-stroke-thin) solid var(--xh-list-border, var(--xh-border-default));
+    border-radius: var(--xh-list-radius, var(--xh-shape-surface));
+    background: var(--xh-list-bg, var(--xh-bg-surface));
+    /* 首尾条目的悬停底色要被圆角裁住 */
+    overflow: hidden;
+  }
+
+  /* 淡底档：底换成 subtle，描边留一圈透明边位，与 outline 同一几何；
+     条目坐在淡底上，悬停面抬一档 */
+  .xh-scope-list[data-part='root'][data-variant='subtle'] {
+    --xh-_list-item-bg-hover: var(--xh-bg-subtle-hover);
+
+    border: var(--xh-stroke-thin) solid transparent;
+    border-radius: var(--xh-list-radius, var(--xh-shape-surface));
+    background: var(--xh-list-bg, var(--xh-bg-subtle));
+    overflow: hidden;
+  }
+
+  /* —— 条目 —— */
+  .xh-scope-list[data-part='item'] {
+    display: flex;
+    align-items: center;
+    gap: var(--xh-list-item-gap, var(--xh-_list-item-gap));
+    padding-block: var(--xh-list-item-py, var(--xh-_list-item-py));
+    padding-inline: var(--xh-list-item-px, var(--xh-_list-item-px));
+  }
+
+  /* 分隔线画在后一条的上边，条与条之间才只有一条；第一条没有上邻居。
+     只认自己的直接子条目，套在条目里的另一份列表由它自己的根管 */
+  .xh-scope-list[data-part='root'][data-split]
+    > .xh-scope-list[data-part='item']
+    + .xh-scope-list[data-part='item'] {
+    border-block-start: var(--xh-stroke-thin) solid var(--xh-list-divider, var(--xh-border-default));
+  }
+
+  .xh-scope-list[data-part='root'][data-hoverable] > .xh-scope-list[data-part='item'] {
+    transition: background-color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  /* 悬停换底色：只在能用指针的设备上生效，触摸端不留一个按不掉的悬停态 */
+  @media (hover: hover) {
+    .xh-scope-list[data-part='root'][data-hoverable] > .xh-scope-list[data-part='item']:hover {
+      background: var(--xh-list-item-bg-hover, var(--xh-_list-item-bg-hover));
+    }
+  }
+
+  /* —— 条目内的四个位 —— */
+  /* 媒体位不参与伸缩，宽度收到内容 */
+  .xh-scope-list[data-part='item-media'] {
+    display: flex;
+    flex: none;
+    align-items: center;
+    justify-content: center;
+  }
+
+  .xh-scope-list[data-part='item-content'] {
+    display: flex;
+    flex: 1 1 auto;
+    flex-direction: column;
+    gap: var(--xh-list-content-gap, var(--xh-space-0_5));
+    /* 标题与说明两行再上下各让出 4px，两行条目与单行条目的高度差拉开，扫读时一条一块 */
+    padding-block: var(--xh-list-item-content-py, var(--xh-space-1));
+    /* flex 项默认不肯收到内容以下，这行让长文本能被压窄 */
+    min-inline-size: 0;
+  }
+
+  .xh-scope-list[data-part='item-title'] {
+    color: var(--xh-list-title-fg, var(--xh-fg-default));
+    font-size: var(--xh-list-title-font-size, var(--xh-_list-title-size));
+    font-weight: var(--xh-list-title-font-weight, var(--xh-font-weight-medium));
+    line-height: var(--xh-leading-normal);
+  }
+
+  .xh-scope-list[data-part='item-description'] {
+    color: var(--xh-list-description-fg, var(--xh-fg-muted));
+    font-size: var(--xh-list-description-font-size, var(--xh-_list-description-size));
+    line-height: var(--xh-leading-normal);
+  }
+
+  /* 操作位推到条目末尾，宽度收到内容 */
+  .xh-scope-list[data-part='item-action'] {
+    display: flex;
+    flex: none;
+    align-items: center;
+    gap: var(--xh-list-action-gap, var(--xh-space-2));
+    margin-inline-start: auto;
+  }
+
+  /* 声明过任何 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去。
+     写在文件末尾：兜底必须排在该部件所有 display 声明之后 */
+  .xh-scope-list[data-part='item'][hidden],
+  .xh-scope-list[data-part='item-media'][hidden],
+  .xh-scope-list[data-part='item-content'][hidden],
+  .xh-scope-list[data-part='item-action'][hidden] {
+    display: none;
+  }
+}