@xihan-ui/styles 1.0.0-alpha.0

package/css/hover-card.css

@@ -0,0 +1,146 @@
+@layer xihan.components {
+  /* 根节点只把 trigger 与浮层收在一处，不参与定位（坐标系仍由祖先的定位上下文决定） */
+  [data-scope='hover-card'][data-part='root'] {
+    display: inline-block;
+  }
+
+  [data-scope='hover-card'][data-part='root'][hidden] {
+    display: none;
+  }
+
+  [data-scope='hover-card'][data-part='trigger'] {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: var(--xh-hover-card-trigger-gap, var(--xh-control-gap-sm));
+    border: 0;
+    background: transparent;
+    color: inherit;
+    font: inherit;
+    cursor: inherit;
+  }
+
+  [data-scope='hover-card'][data-part='trigger'][hidden] {
+    display: none;
+  }
+
+  [data-scope='hover-card'][data-part='trigger']:focus-visible {
+    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
+    outline-offset: var(--xh-ring-offset);
+  }
+
+  /* 坐标由定位引擎写进 style（inset-inline-start / inset-block-start），这里只定位模式与层级 */
+  [data-scope='hover-card'][data-part='positioner'] {
+    position: fixed;
+    z-index: var(--xh-layer-popover);
+    /* 空壳不吃指针：trigger 与 content 之间那段间隙要能点得穿，
+       指针穿行的判定全靠 content 自己的进出事件 */
+    pointer-events: none;
+  }
+
+  /* 锚点被滚出可视区：整个浮层随之收起 */
+  [data-scope='hover-card'][data-part='positioner'][data-hidden] {
+    visibility: hidden;
+  }
+
+  /* 与 tooltip 不同：卡片本体承载交互，必须吃指针——
+     指针停在卡片上就不该收起，里面的链接与按钮也要点得到 */
+  [data-scope='hover-card'][data-part='content'] {
+    /* 尺寸档只换这两个私有槽。size 落在 content 上而非 root：root 是可选部件，
+       面板几何也长在 content 上。语气不接：卡片是内容容器，语气该由里面的内容表达 */
+    --xh-_hover-card-py: var(--xh-space-3);
+    --xh-_hover-card-px: var(--xh-control-px-md);
+    --xh-_hover-card-max-w: var(--xh-overlay-max-w);
+
+    position: relative;
+    display: flex;
+    flex-direction: column;
+    gap: var(--xh-hover-card-gap, var(--xh-space-2));
+    inline-size: max-content;
+    max-inline-size: var(--xh-hover-card-max-w, var(--xh-_hover-card-max-w));
+    padding-block: var(--xh-hover-card-py, var(--xh-_hover-card-py));
+    padding-inline: var(--xh-hover-card-px, var(--xh-_hover-card-px));
+    border: var(--xh-stroke-thin) solid var(--xh-hover-card-border, var(--xh-border-default));
+    border-radius: var(--xh-hover-card-radius, var(--xh-shape-surface));
+    background: var(--xh-hover-card-bg, var(--xh-bg-surface));
+    color: var(--xh-hover-card-fg, var(--xh-fg-default));
+    font-size: var(--xh-hover-card-font-size, var(--xh-text-body-size));
+    line-height: var(--xh-leading-normal);
+    box-shadow: var(--xh-hover-card-shadow, var(--xh-elevation-2));
+    pointer-events: auto;
+  }
+
+  /* display 会盖掉 hidden 属性的 UA 规则，收起态显式让位 */
+  [data-scope='hover-card'][data-part='content'][hidden] {
+    display: none;
+  }
+
+  /* 卡片是可编程聚焦的容器（tabindex=-1），焦点环留给里面真正的可聚焦元素 */
+  [data-scope='hover-card'][data-part='content']:focus-visible {
+    outline: none;
+  }
+
+  [data-scope='hover-card'][data-part='content'][data-state='open'] {
+    animation: xh-fade-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
+  }
+
+  /* —— 尺寸 —— */
+  /* 缺省档写在 content 的基础规则里；行内内缩本就取 control-px 那把尺，上下各挪一档，
+     纵向内缩按 space 档同步 */
+  [data-scope='hover-card'][data-part='content'][data-size='sm'] {
+    --xh-_hover-card-py: var(--xh-space-2);
+    --xh-_hover-card-px: var(--xh-control-px-sm);
+    --xh-_hover-card-max-w: var(--xh-overlay-max-w-sm);
+  }
+
+  [data-scope='hover-card'][data-part='content'][data-size='lg'] {
+    --xh-_hover-card-py: var(--xh-space-4);
+    --xh-_hover-card-px: var(--xh-control-px-lg);
+    --xh-_hover-card-max-w: var(--xh-overlay-max-w-lg);
+  }
+
+  /* 箭头是旋转 45° 的方块，只保留朝向锚点那两条边的描边；
+     引擎不产出箭头偏移，因此沿交叉轴固定居中 */
+  [data-scope='hover-card'][data-part='arrow'] {
+    position: absolute;
+    inline-size: var(--xh-hover-card-arrow-size, var(--xh-overlay-arrow-size));
+    block-size: var(--xh-hover-card-arrow-size, var(--xh-overlay-arrow-size));
+    border: var(--xh-stroke-thin) solid var(--xh-hover-card-border, var(--xh-border-default));
+    background: var(--xh-hover-card-bg, var(--xh-bg-surface));
+    rotate: 45deg;
+  }
+
+  [data-scope='hover-card'][data-part='arrow'][data-placement^='bottom'] {
+    inset-block-start: calc(var(--xh-hover-card-arrow-size, var(--xh-overlay-arrow-size)) / -2);
+    inset-inline-start: calc(50% - var(--xh-hover-card-arrow-size, var(--xh-overlay-arrow-size)) / 2);
+    border-block-end: 0;
+    border-inline-end: 0;
+  }
+
+  [data-scope='hover-card'][data-part='arrow'][data-placement^='top'] {
+    inset-block-end: calc(var(--xh-hover-card-arrow-size, var(--xh-overlay-arrow-size)) / -2);
+    inset-inline-start: calc(50% - var(--xh-hover-card-arrow-size, var(--xh-overlay-arrow-size)) / 2);
+    border-block-start: 0;
+    border-inline-start: 0;
+  }
+
+  [data-scope='hover-card'][data-part='arrow'][data-placement^='right'] {
+    inset-inline-start: calc(var(--xh-hover-card-arrow-size, var(--xh-overlay-arrow-size)) / -2);
+    inset-block-start: calc(50% - var(--xh-hover-card-arrow-size, var(--xh-overlay-arrow-size)) / 2);
+    border-block-start: 0;
+    border-inline-end: 0;
+  }
+
+  [data-scope='hover-card'][data-part='arrow'][data-placement^='left'] {
+    inset-inline-end: calc(var(--xh-hover-card-arrow-size, var(--xh-overlay-arrow-size)) / -2);
+    inset-block-start: calc(50% - var(--xh-hover-card-arrow-size, var(--xh-overlay-arrow-size)) / 2);
+    border-block-end: 0;
+    border-inline-start: 0;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    [data-scope='hover-card'][data-part='content'] {
+      animation-duration: 0.01ms !important;
+    }
+  }
+}

package/css/icon-wrapper.css

@@ -0,0 +1,64 @@
+@layer xihan.components {
+  /* 定直径的图标底座：图元在正中，底色、描边与形状由三轴决定。
+     直径与图元直径分两个槽位，底座换档时里面的图元跟着一起换 */
+  [data-scope='icon-wrapper'][data-part='root'] {
+    /* 私有槽位：底座直径与图元直径，换档只改这两个 */
+    --xh-_icon-wrapper-size: var(--xh-icon-wrapper-size, var(--xh-control-h-md));
+
+    /* 流给里面的图元；图元自己写了档位时仍按自己的档走 */
+    --xh-icon-size: var(--xh-icon-wrapper-glyph-size, var(--xh-glyph-size-md));
+
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    justify-content: center;
+    inline-size: var(--xh-_icon-wrapper-size);
+    block-size: var(--xh-_icon-wrapper-size);
+    border: var(--xh-stroke-thin) solid transparent;
+    border-radius: var(--xh-icon-wrapper-radius, var(--xh-shape-pill));
+    background: var(--xh-icon-wrapper-bg, var(--xh-bg-subtle));
+    color: var(--xh-icon-wrapper-fg, var(--xh-fg-default));
+    line-height: var(--xh-leading-none);
+  }
+
+  /* 给了 display 的角色节点必须补这条：display 声明会盖掉 UA 的 [hidden]{display:none}，
+     不补的话作者给节点加 hidden 后它照样显示 */
+  [data-scope='icon-wrapper'][data-part='root'][hidden] {
+    display: none;
+  }
+
+  /* —— 形态 —— */
+  /* 形态只决定颜色怎么用；用哪族颜色由 data-tone 决定，没写 tone 就沿用原来的品牌/中性配色 */
+  [data-scope='icon-wrapper'][data-part='root'][data-variant='solid'] {
+    background: var(--xh-_tone, var(--xh-bg-brand));
+    color: var(--xh-_tone-on, var(--xh-fg-on-brand));
+  }
+
+  [data-scope='icon-wrapper'][data-part='root'][data-variant='subtle'] {
+    background: var(--xh-_tone-subtle, var(--xh-bg-subtle));
+    color: var(--xh-_tone-fg, var(--xh-fg-default));
+  }
+
+  [data-scope='icon-wrapper'][data-part='root'][data-variant='outline'] {
+    border-color: var(--xh-_tone-border, var(--xh-border-default));
+    background: transparent;
+    color: var(--xh-_tone-fg, var(--xh-fg-default));
+  }
+
+  [data-scope='icon-wrapper'][data-part='root'][data-variant='ghost'] {
+    background: transparent;
+    color: var(--xh-_tone-fg, var(--xh-fg-default));
+  }
+
+  /* —— 尺寸 —— */
+  /* 缺省档写在上面的基础规则里 */
+  [data-scope='icon-wrapper'][data-part='root'][data-size='sm'] {
+    --xh-_icon-wrapper-size: var(--xh-icon-wrapper-size, var(--xh-control-h-sm));
+    --xh-icon-size: var(--xh-icon-wrapper-glyph-size, var(--xh-glyph-size-sm));
+  }
+
+  [data-scope='icon-wrapper'][data-part='root'][data-size='lg'] {
+    --xh-_icon-wrapper-size: var(--xh-icon-wrapper-size, var(--xh-control-h-lg));
+    --xh-icon-size: var(--xh-icon-wrapper-glyph-size, var(--xh-glyph-size-lg));
+  }
+}

package/css/icon.css

@@ -0,0 +1,54 @@
+@layer xihan.components {
+  /*
+   * 根 <svg>。直径、描边粗细、行内位置都由这里给，记录只带几何。
+   * 不写 fill / stroke：记录里那两条呈现属性取 currentColor，改这里会把
+   * 描边图标与实心图标一起改掉；皮肤只给 color，配色随上下文流下来。
+   */
+  [data-scope='icon'][data-part='root'] {
+    display: inline-block;
+    flex: none;
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-md));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-md));
+
+    /* 替换元素的基线就是自身下边缘，落在文字基线上时整块图形都在基线以上、看着偏高。
+       往下挪一小段，单位是 em，跟着相邻文字的字号一起缩放 */
+    vertical-align: var(--xh-icon-shift, var(--xh-glyph-baseline-shift));
+    color: var(--xh-icon-fg, currentColor);
+
+    /* 记录把 stroke-width 写成根上的呈现属性，呈现属性的层叠优先级低于任何 CSS 规则，
+       这条与下面两档因此能接管粗细，再沿继承落到每个图元上 */
+    stroke-width: var(--xh-icon-stroke, var(--xh-glyph-stroke-regular));
+  }
+
+  /* 声明了 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去 */
+  [data-scope='icon'][data-part='root'][hidden] {
+    display: none;
+  }
+
+  /* 三档直径，缺省档写在上面的基础规则里 */
+  [data-scope='icon'][data-part='root'][data-size='sm'] {
+    inline-size: var(--xh-glyph-size-sm);
+    block-size: var(--xh-glyph-size-sm);
+  }
+
+  [data-scope='icon'][data-part='root'][data-size='lg'] {
+    inline-size: var(--xh-glyph-size-lg);
+    block-size: var(--xh-glyph-size-lg);
+  }
+
+  /* 三档描边，缺省档同样写在基础规则里 */
+  [data-scope='icon'][data-part='root'][data-weight='light'] {
+    stroke-width: var(--xh-glyph-stroke-light);
+  }
+
+  [data-scope='icon'][data-part='root'][data-weight='bold'] {
+    stroke-width: var(--xh-glyph-stroke-bold);
+  }
+
+  /* 语气：图标没有底色，语气只落在前景上，取普通背景上表达该语气的那档文字色。
+     选择器上带 [data-tone] 是必需的：语气槽会沿继承流下来，不限定在写了语气的
+     那个节点上，放在语气容器里的装饰图标会跟着一起改色 */
+  [data-scope='icon'][data-part='root'][data-tone] {
+    color: var(--xh-icon-fg, var(--xh-_tone-fg, currentColor));
+  }
+}

package/css/image.css

@@ -0,0 +1,45 @@
+@layer xihan.components {
+  /* 尺寸交给三个变量而不是写死：这个组件既要能当封面图，也要能当头图与缩略图。
+     给了 --xh-image-ratio 才有确定高度，回退内容与图片在同一个盒子里换人时不会跳。 */
+  [data-scope='image'][data-part='root'] {
+    position: relative;
+    display: block;
+    overflow: hidden;
+    inline-size: var(--xh-image-w, 100%);
+    block-size: var(--xh-image-h, auto);
+    aspect-ratio: var(--xh-image-ratio, auto);
+    border-radius: var(--xh-image-radius, var(--xh-radius-md));
+    background: var(--xh-image-bg, var(--xh-bg-subtle));
+  }
+
+  /* 声明了 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去 */
+  [data-scope='image'][data-part='root'][hidden] {
+    display: none;
+  }
+
+  /* 不声明 display：加载完成前的 hidden 直接交给浏览器的 [hidden] 规则收起 */
+  [data-scope='image'][data-part='image'] {
+    inline-size: 100%;
+    block-size: 100%;
+    object-fit: var(--xh-image-fit, cover);
+  }
+
+  [data-scope='image'][data-part='fallback'] {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    inline-size: 100%;
+    block-size: 100%;
+    /* 没给 ratio 时根盒子高度是 auto，回退内容自己撑出一个不塌的高度 */
+    min-block-size: var(--xh-image-fallback-min-h, var(--xh-control-h-lg));
+    color: var(--xh-image-fallback-fg, var(--xh-fg-muted));
+    font-size: var(--xh-image-fallback-font-size, var(--xh-font-size-sm));
+    line-height: var(--xh-leading-none);
+    user-select: none;
+  }
+
+  /* display 会盖掉 hidden 属性的 UA 规则：延迟窗口内与加载完成后都靠这条收起 */
+  [data-scope='image'][data-part='fallback'][hidden] {
+    display: none;
+  }
+}

package/css/infinite-scroll.css

@@ -0,0 +1,22 @@
+@layer xihan.components {
+  /*
+   * 列表外壳这一层刻意不给盒模型：滚的是页面还是作者自己的 overflow 容器、列表长什么样，
+   * 都归作者的布局管，组件只往它身上挂 data-state / data-loading / data-disabled 供作者取用。
+   * 一旦声明 display，UA 的 [hidden]{display:none} 就压不住了，故连 display 也不写。
+   *
+   * 哨兵是纯机制，不是可见元素：给它一条最细的高度让它有个能被观察到的盒子，
+   * 高度为 0 的元素在部分实现里交叠比恒为 0，永远等不到进入。
+   * 不吃指针：它紧贴在列表末尾，吃了指针就会挡住最后一条的点击。
+   */
+  [data-scope='infinite-scroll'][data-part='sentinel'] {
+    display: block;
+    inline-size: 100%;
+    block-size: var(--xh-infinite-scroll-sentinel-size, var(--xh-stroke-thin));
+    pointer-events: none;
+  }
+
+  /* 声明过 display 就盖掉了 UA 的 [hidden]{display:none}，作者要藏哨兵时得自己补回来 */
+  [data-scope='infinite-scroll'][data-part='sentinel'][hidden] {
+    display: none;
+  }
+}

package/css/layers.css

@@ -0,0 +1,2 @@
+/* 库层序单一真源：级联顺序由首次声明决定，与 @import 顺序解耦。 */
+@layer xihan.reset, xihan.tokens, xihan.motion, xihan.components, xihan.overrides;

package/css/layout.css

@@ -0,0 +1,169 @@
+@layer xihan.components {
+  /* 页面骨架排成三行两列：头与脚各横贯一整行，侧栏与内容并排占中间那一行。
+     缺哪一段，对应的行/列就没有条目，宽高自动收成 0，不必为"少写一段"另立规则。
+
+     侧栏两档宽度与头的高度声明在根上：各段自己读这些槽，换档只改这里。
+     头的高度之所以也归到根上：头吸顶时头这一行的轨道要按同一个值定高，两处必须同源。 */
+  [data-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-canvas));
+    color: var(--xh-layout-fg, var(--xh-fg-default));
+    --xh-_layout-sider-w: var(--xh-layout-sider-width, 15rem);
+    --xh-_layout-sider-collapsed-w: var(--xh-layout-sider-collapsed-width, 4rem);
+    --xh-_layout-header-h: var(--xh-layout-header-h, 3.5rem);
+    /* 侧栏吸附时钉在哪条线上：缺省贴滚动容器上沿，头也吸顶时改成让开头的高度 */
+    --xh-_layout-sider-offset: 0px;
+  }
+
+  /* 侧栏挂到行尾：两列对调，内容在前 */
+  [data-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;
+  }
+
+  /* —— 各段 —— */
+  [data-scope='layout'][data-part='header'] {
+    display: flex;
+    grid-area: header;
+    align-items: center;
+    gap: var(--xh-space-3);
+    block-size: var(--xh-_layout-header-h);
+    padding-inline: var(--xh-space-4);
+    background: var(--xh-layout-header-bg, var(--xh-bg-surface));
+  }
+
+  /* 宽度过渡在这里声明一次，展开与折叠两档、以及 props 直接写进内联的宽度，走的都是这一条 */
+  [data-scope='layout'][data-part='sider'] {
+    grid-area: sider;
+    inline-size: var(--xh-_layout-sider-w);
+    overflow: hidden;
+    padding: var(--xh-space-3);
+    background: var(--xh-layout-sider-bg, var(--xh-bg-subtle));
+    transition: inline-size var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
+  }
+
+  /* 折起来时不换行：窄到放不下的那几个字直接被 overflow 裁掉，不会挤成一列竖排 */
+  [data-scope='layout'][data-part='sider'][data-state='collapsed'] {
+    inline-size: var(--xh-_layout-sider-collapsed-w);
+    white-space: nowrap;
+  }
+
+  [data-scope='layout'][data-part='content'] {
+    grid-area: content;
+    /* 内容列已是 minmax(0, 1fr)，这里再声明一次，宽表格与长串文本才撑不破列 */
+    min-inline-size: 0;
+    padding: var(--xh-space-4);
+  }
+
+  [data-scope='layout'][data-part='footer'] {
+    grid-area: 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-font-size-sm);
+  }
+
+  /* —— 折叠把手 —— */
+  [data-scope='layout'][data-part='sider-trigger'] {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: var(--xh-control-gap-sm);
+    block-size: var(--xh-control-h-sm);
+    padding-inline: var(--xh-control-px-sm);
+    border: 0;
+    border-radius: var(--xh-layout-sider-trigger-radius, var(--xh-shape-control));
+    background: var(--xh-layout-sider-trigger-bg, transparent);
+    color: var(--xh-layout-sider-trigger-fg, var(--xh-fg-default));
+    font-size: var(--xh-font-size-sm);
+    line-height: var(--xh-leading-none);
+    cursor: pointer;
+  }
+
+  [data-scope='layout'][data-part='sider-trigger']:hover {
+    background: var(--xh-layout-sider-trigger-bg-hover, var(--xh-bg-subtle-hover));
+  }
+
+  [data-scope='layout'][data-part='sider-trigger']:focus-visible {
+    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
+    outline-offset: var(--xh-ring-offset);
+  }
+
+  /* —— 分隔线 —— */
+  /* 后代选择器带上 data-scope：骨架里装着整页内容，光凭 data-part 会连里面别的组件同名段一起画上线 */
+  [data-scope='layout'][data-part='root'][data-bordered] [data-scope='layout'][data-part='header'] {
+    border-block-end: var(--xh-stroke-thin) solid var(--xh-layout-border, var(--xh-border-default));
+  }
+
+  [data-scope='layout'][data-part='root'][data-bordered] [data-scope='layout'][data-part='footer'] {
+    border-block-start: var(--xh-stroke-thin) solid var(--xh-layout-border, var(--xh-border-default));
+  }
+
+  /* 侧栏只在挨着内容的那一边画线，另一边贴着骨架外沿，画了就是一条多出来的边框 */
+  [data-scope='layout'][data-part='root'][data-bordered] [data-scope='layout'][data-part='sider'][data-placement='start'] {
+    border-inline-end: var(--xh-stroke-thin) solid var(--xh-layout-border, var(--xh-border-default));
+  }
+
+  [data-scope='layout'][data-part='root'][data-bordered] [data-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 就没有条目撑着它了 */
+  [data-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）要留实色，否则滚过去的正文会从头底下透出来。 */
+  [data-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;
+  }
+
+  /* 头也吸顶时侧栏钉在头的下沿，两段不叠在一起 */
+  [data-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 跟着变。
+     侧栏自己的条目多到装不下时在内部滚，横轴仍归上面那条 overflow: hidden 裁，
+     折叠态靠它把放不下的字裁掉；逻辑属性 overflow-block 尚无可用实现，写物理轴。 */
+  [data-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, 100dvh) - var(--xh-_layout-sider-offset));
+    overflow-y: auto;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    [data-scope='layout'][data-part='sider'] {
+      transition: none;
+    }
+  }
+}

package/css/list.css

@@ -0,0 +1,117 @@
+@layer xihan.components {
+  [data-scope='list'][data-part='root'] {
+    /* 一个尺寸档只换这几个私有槽，条目与两行文字都从根上继承它们，
+       换档不必给每个部件各写一条选择器 */
+    --xh-_list-item-py: var(--xh-space-3);
+    --xh-_list-item-px: var(--xh-space-4);
+    --xh-_list-item-gap: var(--xh-space-3);
+    --xh-_list-title-size: var(--xh-font-size-md);
+    --xh-_list-description-size: var(--xh-font-size-sm);
+
+    display: flex;
+    flex-direction: column;
+    /* 根可能写成 ul/ol，UA 的项目符号与左缩进在这里清掉：换哪个标签都排成同一个样子 */
+    margin: 0;
+    padding: 0;
+    list-style: none;
+    color: var(--xh-list-fg, var(--xh-fg-default));
+  }
+
+  /* 上面声明了 display，会盖掉 UA 的 [hidden] 规则，收起态要在这里接回来 */
+  [data-scope='list'][data-part='root'][hidden] {
+    display: none;
+  }
+
+  /* —— 尺寸 —— */
+  [data-scope='list'][data-part='root'][data-size='sm'] {
+    --xh-_list-item-py: var(--xh-space-2);
+    --xh-_list-item-px: var(--xh-space-3);
+    --xh-_list-item-gap: var(--xh-space-2);
+    --xh-_list-title-size: var(--xh-font-size-sm);
+    --xh-_list-description-size: var(--xh-font-size-xs);
+  }
+
+  [data-scope='list'][data-part='root'][data-size='lg'] {
+    --xh-_list-item-py: var(--xh-space-4);
+    --xh-_list-item-px: var(--xh-space-5);
+    --xh-_list-item-gap: var(--xh-space-4);
+    --xh-_list-title-size: var(--xh-font-size-lg);
+  }
+
+  /* —— 外框 —— */
+  [data-scope='list'][data-part='root'][data-bordered] {
+    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;
+  }
+
+  /* —— 条目 —— */
+  [data-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));
+  }
+
+  /* 分隔线画在后一条的上边，条与条之间才只有一条；第一条没有上邻居。
+     只认自己的直接子条目，套在条目里的另一份列表由它自己的根管 */
+  [data-scope='list'][data-part='root'][data-split]
+    > [data-scope='list'][data-part='item']
+    + [data-scope='list'][data-part='item'] {
+    border-block-start: var(--xh-stroke-thin) solid var(--xh-list-border, var(--xh-border-subtle));
+  }
+
+  [data-scope='list'][data-part='root'][data-hoverable] > [data-scope='list'][data-part='item'] {
+    transition: background-color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  /* 悬停换底色：只在能用指针的设备上生效，触摸端不留一个按不掉的悬停态 */
+  @media (hover: hover) {
+    [data-scope='list'][data-part='root'][data-hoverable] > [data-scope='list'][data-part='item']:hover {
+      background: var(--xh-list-item-bg-hover, var(--xh-bg-subtle-hover));
+    }
+  }
+
+  /* —— 条目内的四个位 —— */
+  /* 媒体位不参与伸缩，宽度收到内容 */
+  [data-scope='list'][data-part='item-media'] {
+    display: flex;
+    flex: none;
+    align-items: center;
+    justify-content: center;
+  }
+
+  [data-scope='list'][data-part='item-content'] {
+    display: flex;
+    flex: 1 1 auto;
+    flex-direction: column;
+    gap: var(--xh-list-content-gap, var(--xh-space-1));
+    /* flex 项默认不肯收到内容以下，这行让长文本能被压窄 */
+    min-inline-size: 0;
+  }
+
+  [data-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-tight);
+  }
+
+  [data-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);
+  }
+
+  /* 操作位推到条目末尾，宽度收到内容 */
+  [data-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;
+  }
+}