@xihan-ui/styles 1.0.0-alpha.2 → 1.0.0

package/css/heatmap.css

@@ -0,0 +1,411 @@
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='heatmap'] {
+    --xh-heatmap-skin: 1;
+  }
+
+  /* 缺省的 calendar 形态：上下两条横排，月份行在网格之外（它只是一条对齐用的坐标轴），
+     网格里是七行星期。格子一律是固定尺寸的方块，列与列之间靠尺寸对齐，不必另立网格轨道。
+     另外两种形态只在下面的 [data-variant] 段里改摆法，这里的取值一概不动。 */
+  [data-scope='heatmap'][data-part='root'] {
+    /* 尺寸档只换这里的私有槽，各部件从 root 继承它们，换档不必给每个部件各写一条选择器。
+       格宽在这一处就把使用者令牌解析掉：错列与月份名的宽度都按它算，
+       各处分头读会让作者改宽格子后错列与月份名对不上 */
+    --xh-_heatmap-cell-size: var(--xh-heatmap-cell-size, var(--xh-space-2_5));
+    /* 矩阵形态的行高。格宽那把尺是给「一天一个小方块」定的，矩阵一行左边还挂着行名，
+       格子照那把尺定高就矮过行名，行高由行名的字定、格子在行里摊成一条。
+       这里取格宽尺的两倍：三档一起走，且每一档都高过行名那行字。
+       不接控件高度那把尺——它是给可点可输的控件在一行里排齐用的，矩阵格子不可交互，
+       接上去密度档一换矩阵就跟着变形 */
+    --xh-_heatmap-row-h: var(--xh-heatmap-row-h, var(--xh-space-5));
+    /* 格间距等于聚焦环占的宽度（偏移 + 环宽）：环因此整圈落在格子之间的空当里，
+       不压到相邻的格子上（外缘与相邻格相接） */
+    --xh-_heatmap-gap: calc(var(--xh-ring-offset) + var(--xh-ring-width));
+    --xh-_heatmap-gutter: var(--xh-heatmap-gutter, var(--xh-space-8));
+    --xh-_heatmap-font-size: var(--xh-text-caption-size);
+    /* 星期名隔行画：第 0/2/4/6 行那个字的颜色。缺省透明——只是字不上色，
+       盒子、底色与命中区都还在，钉住那一列的实色底不缺一块，七行的悬停行为也一致。
+       改写这个槽为一个看得见的颜色（`var(--xh-heatmap-label-fg, var(--xh-fg-subtle))`）即七行全画。
+       周首日是星期一时留下的是二 / 四 / 六，是星期日时留下的是一 / 三 / 五 */
+    --xh-_heatmap-week-day-skip: var(--xh-heatmap-week-day-skip, transparent);
+    /* 色阶的两端：0 档的空格底与满档的实心底。没写 data-tone 也没写 data-palette 时就是这里的取值 */
+    --xh-_heatmap-empty: var(--xh-heatmap-empty, var(--xh-bg-subtle));
+    --xh-_heatmap-ink: var(--xh-heatmap-ink, var(--xh-bg-brand));
+    /* 钉住的行首那一列自带的底色：格子从它下面滚过去时不能透出来。
+       整块摆在别的底色上（卡片、分区）时改写 --xh-heatmap-bg，否则那一列会是一块补丁 */
+    --xh-_heatmap-surface: var(--xh-heatmap-bg, var(--xh-bg-surface));
+
+    /* 详情条按内边距盒绝对定位，参照系就是它 */
+    position: relative;
+    /* 自建层叠上下文：钉住那一列与详情条的层号只跟组件里的兄弟比，
+       不写这条它们是拿去跟页面同层的元素比，热力图会压住页面上后来的定位元素 */
+    isolation: isolate;
+    display: flex;
+    flex-direction: column;
+    gap: var(--xh-heatmap-gap, var(--xh-space-2));
+    /* 一整年五十几列，一屏放不下就自己横着滚。横向滚动会把纵向也变成 auto，
+       上下留出一圈聚焦环的余量，最上一行与最下一行的环才不会被裁掉 */
+    padding-block: var(--xh-heatmap-py, calc(var(--xh-ring-offset) + var(--xh-ring-width)));
+    overflow-x: auto;
+    /* 键盘走到视口外的格子时 scrollIntoView 会把它滚进来，落点要让开钉住的那一列，
+       否则往回走的那一格正好停在行首星期名底下 */
+    scroll-padding-inline-start: calc(var(--xh-_heatmap-gutter) + var(--xh-_heatmap-gap));
+    color: var(--xh-heatmap-fg, var(--xh-fg-muted));
+    font-size: var(--xh-heatmap-font-size, var(--xh-_heatmap-font-size));
+    line-height: var(--xh-leading-none);
+  }
+
+  /* —— 语气 —— */
+  /* 选择器带 [data-tone] 限定：不限定的话，放在语气容器里的热力图会跟着改色 */
+  [data-scope='heatmap'][data-part='root'][data-tone] {
+    --xh-_heatmap-ink: var(--xh-heatmap-ink, var(--xh-_tone, var(--xh-bg-brand)));
+  }
+
+  /* —— 色板 —— */
+  /* 直接按颜色点名，定的是满档那一端的实心底；0 档的空格底与中间各档的兑法一概不动。
+     六条规则与上面那条语气规则同特指度，排在它之后：两个都写时色板赢——
+     色板指名了一个具体颜色，语气只是推得出一个颜色，指名的那个更具体。
+     取值一律逐值写死原语、不经 --xh-_tone：那一族槽位是语气层的派生结果，
+     色板借道它就会连带把语气的悬停 / 淡底 / 前景一起绑进来，也会被祖先的 data-tone 染色。
+     色板拼错取值时六条都不命中，落回上面两条，与没写一样 */
+  [data-scope='heatmap'][data-part='root'][data-palette='green'] {
+    --xh-_heatmap-ink: var(--xh-heatmap-ink, var(--xh-color-success-600));
+  }
+
+  [data-scope='heatmap'][data-part='root'][data-palette='blue'] {
+    --xh-_heatmap-ink: var(--xh-heatmap-ink, var(--xh-color-info-600));
+  }
+
+  [data-scope='heatmap'][data-part='root'][data-palette='orange'] {
+    --xh-_heatmap-ink: var(--xh-heatmap-ink, var(--xh-color-warning-600));
+  }
+
+  [data-scope='heatmap'][data-part='root'][data-palette='purple'] {
+    --xh-_heatmap-ink: var(--xh-heatmap-ink, var(--xh-color-purple-600));
+  }
+
+  [data-scope='heatmap'][data-part='root'][data-palette='red'] {
+    --xh-_heatmap-ink: var(--xh-heatmap-ink, var(--xh-color-danger-600));
+  }
+
+  /* 灰是唯一按主题换档的一族：五个彩色族的 600 档明度在 0.577–0.705，
+     深色态的空格底（neutral-800，明度 0.269）离得够远；中性 600 档只有 0.439，
+     五档摊下来每档只差 0.0425、相邻两档对比度 1.16–1.20，等于看不出分档。
+     深色态改取 neutral-450（明度 0.65），步长回到 0.095、相邻两档 1.42–1.50，与彩色族齐平。
+     不取更亮的 neutral-400：高对比档的 border-default 正是那一档，满档格子的描边会与底色同色。
+     data-theme 写在自己身上还是写在祖先上都算，两种用法都成立 */
+  [data-scope='heatmap'][data-part='root'][data-palette='gray'] {
+    --xh-_heatmap-ink: var(--xh-heatmap-ink, var(--xh-color-neutral-600));
+  }
+
+  :is([data-theme='dark'] *, [data-theme='dark'])[data-scope='heatmap'][data-part='root'][data-palette='gray'] {
+    --xh-_heatmap-ink: var(--xh-heatmap-ink, var(--xh-color-neutral-450));
+  }
+
+  /* —— 尺寸 —— */
+  /* 缺省的 md 档写在上面的基础规则里 */
+  [data-scope='heatmap'][data-part='root'][data-size='sm'] {
+    --xh-_heatmap-cell-size: var(--xh-heatmap-cell-size, var(--xh-space-2));
+    --xh-_heatmap-row-h: var(--xh-heatmap-row-h, var(--xh-space-4));
+    --xh-_heatmap-gutter: var(--xh-heatmap-gutter, var(--xh-space-6));
+  }
+
+  [data-scope='heatmap'][data-part='root'][data-size='lg'] {
+    --xh-_heatmap-cell-size: var(--xh-heatmap-cell-size, var(--xh-space-3));
+    --xh-_heatmap-row-h: var(--xh-heatmap-row-h, var(--xh-space-6));
+  }
+
+  [data-scope='heatmap'][data-part='grid'] {
+    display: flex;
+    flex-direction: column;
+    gap: var(--xh-heatmap-grid-gap, var(--xh-_heatmap-gap));
+  }
+
+  /* 网格自己只在没有格子可落焦点时才占 Tab 位，那几帧里也该看得出焦点在哪。
+     环往内收：网格铺满 root，root 那层 overflow-x: auto 会把画在外沿的环裁掉 */
+  [data-scope='heatmap'][data-part='grid']:focus-visible {
+    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
+    outline-offset: calc(-1 * var(--xh-ring-width));
+  }
+
+  [data-scope='heatmap'][data-part='row'] {
+    /* 行首空出的列数由连接层写进这个槽：日历形态是区间起点不在周首日时的错列，
+       月历形态是这一周里 1 号之前的那几个星期几 */
+    --xh-_heatmap-row-offset: 0;
+
+    display: flex;
+    /* 行至少要有内容那么宽。行是列方向 flex 的子项，缺省会被拉成容器的宽（一屏那么宽），
+       行首钉住的那一列只能在自己这一行的盒子里钉——盒子只有一屏宽，滚过一屏它就跟着走了 */
+    min-inline-size: max-content;
+    align-items: center;
+    gap: var(--xh-heatmap-row-gap, var(--xh-_heatmap-gap));
+  }
+
+  /* 数据行的高度只由格子定。行首那一列星期名的字（12px）比格子（10px）高，让它撑开行
+     会在纵向多挤出两像素，同一张图的横向格距与纵向格距就不一样宽。
+     钉死成格高之后星期名的字仍照常画，只是溢出到行外——那几行隔行留白，撞不到东西 */
+  [data-scope='heatmap'][data-part='row'][data-week-day],
+  [data-scope='heatmap'][data-part='row'][data-week] {
+    block-size: var(--xh-_heatmap-cell-size);
+  }
+
+  /* 行首的星期名。月份行行首那个占位也是它，宽度一样，月份才对得上列。
+     一整年放不下时网格横着滚，这一列钉在滚动容器的起始缘：跟着滚走的话，
+     滚过头一屏就再也认不出哪一行是星期几。底色必须实色，格子从它下面滚过去不能透出来 */
+  [data-scope='heatmap'][data-part='week-day-label'] {
+    position: sticky;
+    /* 层号收在 root 建的层叠上下文里，只跟组件内的兄弟比 */
+    z-index: var(--xh-heatmap-sticky-layer, 1);
+    inset-inline-start: 0;
+    display: block;
+    flex: 0 0 auto;
+    inline-size: var(--xh-_heatmap-gutter);
+    overflow: hidden;
+    background: var(--xh-_heatmap-surface);
+    color: var(--xh-heatmap-label-fg, var(--xh-fg-subtle));
+    white-space: nowrap;
+    text-align: end;
+  }
+
+  /* 隔行画：这几行只是字不上色，节点、文字、盒子与底色都还在。
+     不能用 visibility 关：那会连盒子一起不画，钉住那一列的实色底跟着缺四行，
+     格子从行首透出来，且这四行不再参与命中测试——鼠标划过行首会弹出看不见那一格的详情条。
+     一行只有 10px 高，七个 12px 的字挨着写会上下叠在一起；隔一行之后每个留下来的字
+     有两行的高度（2 × 格高 + 格距）可用。哪一行是星期几由行自己的可及名字念出来，
+     可见文字与可及名字是两件事，读屏这边一行都没少 */
+  [data-scope='heatmap'][data-part='week-day-label'][data-week-day='0'],
+  [data-scope='heatmap'][data-part='week-day-label'][data-week-day='2'],
+  [data-scope='heatmap'][data-part='week-day-label'][data-week-day='4'],
+  [data-scope='heatmap'][data-part='week-day-label'][data-week-day='6'] {
+    color: var(--xh-_heatmap-week-day-skip);
+  }
+
+  /* 月份名横跨这个月占的那几列：列宽加列间距，末尾少算一个间距（它由行的 gap 补上） */
+  [data-scope='heatmap'][data-part='month-label'] {
+    --xh-_heatmap-month-weeks: 1;
+
+    display: block;
+    flex: 0 0 auto;
+    inline-size: calc(
+      var(--xh-_heatmap-month-weeks) * (var(--xh-_heatmap-cell-size) + var(--xh-_heatmap-gap))
+      - var(--xh-_heatmap-gap)
+    );
+    overflow: hidden;
+    color: var(--xh-heatmap-label-fg, var(--xh-fg-subtle));
+    white-space: nowrap;
+  }
+
+  /* 一天一格。档位是连着的百分比，档数随便改都不必再写一条选择器 */
+  [data-scope='heatmap'][data-part='cell'] {
+    --xh-_heatmap-level: 0%;
+
+    flex: 0 0 auto;
+    inline-size: var(--xh-_heatmap-cell-size);
+    block-size: var(--xh-_heatmap-cell-size);
+    border-radius: var(--xh-heatmap-cell-radius, var(--xh-shape-inset));
+    background: var(
+      --xh-heatmap-cell-bg,
+      color-mix(in oklab, var(--xh-_heatmap-ink) var(--xh-_heatmap-level), var(--xh-_heatmap-empty))
+    );
+    /* 空格与浅档在浅色底上几乎没有边界，描一圈极淡的线把方格勾出来。
+       这一档不能取 border-subtle：它与空格底色 bg-subtle 是同一个原色，描了等于没描 */
+    box-shadow: inset 0 0 0 var(--xh-stroke-thin) var(--xh-heatmap-cell-border, var(--xh-border-default));
+    transition: background var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  /* 错列打在本行第一个格子上：打在行上会连行首的星期名一起往后推，
+     左侧那一列星期名就变成锯齿。两条选择器合起来正好是「本行第一个格子」，
+     行里写不写星期名都成立 */
+  [data-scope='heatmap'][data-part='row'] > [data-scope='heatmap'][data-part='cell']:first-child,
+  [data-scope='heatmap'][data-part='week-day-label'] + [data-scope='heatmap'][data-part='cell'] {
+    margin-inline-start: calc(
+      var(--xh-_heatmap-row-offset) * (var(--xh-_heatmap-cell-size) + var(--xh-_heatmap-gap))
+    );
+  }
+
+  [data-scope='heatmap'][data-part='cell']:focus-visible {
+    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
+    outline-offset: var(--xh-ring-offset);
+  }
+
+  /* —— 月历形态：一个自然月一块，块内一行是一周、一列是一个星期几 —— */
+  [data-scope='heatmap'][data-part='root'][data-variant='month'] [data-scope='heatmap'][data-part='grid'] {
+    flex-flow: row wrap;
+    gap: var(--xh-heatmap-block-gap, var(--xh-_heatmap-gutter));
+  }
+
+  [data-scope='heatmap'][data-part='month-block'] {
+    display: flex;
+    flex-direction: column;
+    gap: var(--xh-heatmap-block-inner-gap, var(--xh-_heatmap-gap));
+  }
+
+  /* 月历形态的月块是换行排开的，没有钉住的那一列，滚动落点也不必让开 */
+  [data-scope='heatmap'][data-part='root'][data-variant='month'] {
+    /* 这里的星期名是一排列头，七个一个都不能少：隔行不上色就有四列认不出是星期几 */
+    --xh-_heatmap-week-day-skip: var(--xh-heatmap-label-fg, var(--xh-fg-subtle));
+
+    /* 月块换行排开，宽度永不超过容器，这一档不当滚动容器：留着 overflow-x: auto 的话，
+       下面那排列头（12px 的字装在 10px 的列里）往外溢的那点行盒会算进可滚动宽度，
+       2px 的溢出就换来一条常驻的横向滚动条，白吃掉十几像素高。
+       clip 只裁不滚，再放出一个格距的余量让列头两端那点溢出照常画出来 */
+    overflow-x: clip;
+    overflow-clip-margin: var(--xh-_heatmap-gap);
+    scroll-padding-inline-start: 0;
+  }
+
+  /* 块里的星期名是一排列头，宽度改成格宽才对得上下面的格子，也不再钉住。
+     字比一格宽，不裁：裁掉就是七个缺角的字，让它往两边的列间距里溢出去，
+     相邻两个各溢出一点也还差着一段空白 */
+  [data-scope='heatmap'][data-part='root'][data-variant='month'] [data-scope='heatmap'][data-part='week-day-label'] {
+    position: static;
+    inline-size: var(--xh-_heatmap-cell-size);
+    overflow: visible;
+    background: none;
+    text-align: center;
+  }
+
+  /* 块的标题占整块宽，不再横跨若干列 */
+  [data-scope='heatmap'][data-part='root'][data-variant='month'] [data-scope='heatmap'][data-part='month-label'] {
+    inline-size: auto;
+    color: var(--xh-heatmap-title-fg, var(--xh-fg-default));
+  }
+
+  /* —— 矩阵形态：行列都由作者给，行名与列名是两条真表头 —— */
+  /* 行名与日历的星期名同一个位置、同一件事：列多到放不下时钉在起始缘 */
+  [data-scope='heatmap'][data-part='row-label'] {
+    position: sticky;
+    z-index: var(--xh-heatmap-sticky-layer, 1);
+    inset-inline-start: 0;
+    display: block;
+    flex: 0 0 auto;
+    inline-size: var(--xh-_heatmap-gutter);
+    overflow: hidden;
+    background: var(--xh-_heatmap-surface);
+    color: var(--xh-heatmap-label-fg, var(--xh-fg-subtle));
+    white-space: nowrap;
+    text-align: end;
+  }
+
+  /* 列名与它下面那一列的格子同宽：标签长就把列宽整体调大，别只调标签。
+     两处的兜底都是行高，不写列宽时矩阵格子就是正方块 */
+  [data-scope='heatmap'][data-part='column-label'] {
+    display: block;
+    flex: 0 0 auto;
+    inline-size: var(--xh-heatmap-column-w, var(--xh-_heatmap-row-h));
+    overflow: hidden;
+    color: var(--xh-heatmap-label-fg, var(--xh-fg-subtle));
+    white-space: nowrap;
+    text-align: center;
+  }
+
+  /* 矩阵的格子两向都不走日方块那把尺：宽跟列走，高跟行走 */
+  [data-scope='heatmap'][data-part='root'][data-variant='matrix'] [data-scope='heatmap'][data-part='cell'] {
+    inline-size: var(--xh-heatmap-column-w, var(--xh-_heatmap-row-h));
+    block-size: var(--xh-_heatmap-row-h);
+  }
+
+  /* —— 详情条 —— */
+  /* 位置由连接层在事件那一刻量好写成内联样式（它量得到，样式表量不到）；
+     这四个是还没量到时的落点，量到即被内联样式盖过。四个都带长度单位：
+     下面 block-start 那一档要把它们放进 calc(100% - …)，无单位的 0 会让整条声明作废。
+     不引浮层引擎：它按 root 的内边距盒绝对定位，跟着 root 一起横向滚动，
+     摆上边还是摆下边由连接层按行序给出，因此始终压在网格自己身上，不会被 root 的滚动裁掉 */
+  [data-scope='heatmap'][data-part='tooltip'] {
+    --xh-_heatmap-tip-x: 0px;
+    --xh-_heatmap-tip-y: 0px;
+    --xh-_heatmap-tip-w: 0px;
+    --xh-_heatmap-tip-h: 0px;
+
+    position: absolute;
+    /* 排在钉住的行首那一列之上：条从末缘往回长时会盖到那一列上，它不该把条切掉 */
+    z-index: var(--xh-heatmap-tooltip-layer, 2);
+    display: block;
+    inset-inline-start: var(--xh-_heatmap-tip-x);
+    inset-block-start: var(--xh-_heatmap-tip-y);
+    /* 至少与格子同宽，一两个字的详情也不会瘦成一条 */
+    min-inline-size: var(--xh-_heatmap-tip-w);
+    max-inline-size: var(--xh-heatmap-tooltip-max-w, var(--xh-overlay-max-w));
+    padding-block: var(--xh-heatmap-tooltip-py, var(--xh-space-1));
+    padding-inline: var(--xh-heatmap-tooltip-px, var(--xh-space-2));
+    border-radius: var(--xh-heatmap-tooltip-radius, var(--xh-shape-control));
+    background: var(--xh-heatmap-tooltip-bg, var(--xh-fg-default));
+    color: var(--xh-heatmap-tooltip-fg, var(--xh-bg-surface));
+    font-size: var(--xh-heatmap-tooltip-font-size, var(--xh-text-caption-size));
+    line-height: var(--xh-leading-normal);
+    white-space: nowrap;
+    box-shadow: var(--xh-heatmap-tooltip-shadow, var(--xh-elevation-floating));
+    /* 详情条不接指针：压在格子上时指针要能穿过去，否则一进条里就算离开了格子，
+       详情自己把自己收起来，来回闪 */
+    pointer-events: none;
+  }
+
+  /* 从格子的末缘往回长：条比一格宽得多，格子后面的地方比前面少时往后长会伸出滚动容器被裁掉，
+     还会把横向滚动条撑长。按末缘定位，条自己多宽都贴着格子的末沿。
+     百分比是内边距盒的宽，在这条 calc 里前后抵消，横向滚到哪里都成立 */
+  [data-scope='heatmap'][data-part='tooltip'][data-inline-anchor='end'] {
+    inset-inline-start: auto;
+    inset-inline-end: calc(100% - var(--xh-_heatmap-tip-x) - var(--xh-_heatmap-tip-w));
+  }
+
+  /* 摆在格子下边：从格子的下沿再让开一个格间距 */
+  [data-scope='heatmap'][data-part='tooltip'][data-placement='block-end'] {
+    inset-block-start: calc(
+      var(--xh-_heatmap-tip-y) + var(--xh-_heatmap-tip-h) + var(--xh-_heatmap-gap)
+    );
+  }
+
+  /* 摆在格子上边：按末缘定位，条自己多高都贴着格子的上沿。
+     两头都写就是过约束，起始缘要先让开 */
+  [data-scope='heatmap'][data-part='tooltip'][data-placement='block-start'] {
+    inset-block-start: auto;
+    inset-block-end: calc(100% - var(--xh-_heatmap-tip-y) + var(--xh-_heatmap-gap));
+  }
+
+  [data-scope='heatmap'][data-part='legend'] {
+    display: flex;
+    align-items: center;
+    gap: var(--xh-heatmap-legend-gap, var(--xh-_heatmap-gap));
+    color: var(--xh-heatmap-label-fg, var(--xh-fg-subtle));
+  }
+
+  /* 对照条两端的那两个字。与色块同一行、同一档颜色，不换行：
+     「少」「多」断成两行就跟色块对不上了 */
+  [data-scope='heatmap'][data-part='legend-label'] {
+    flex: 0 0 auto;
+    white-space: nowrap;
+  }
+
+  /* 对照条里的一格与网格里同档的格子同色，两处共用同一条色阶 */
+  [data-scope='heatmap'][data-part='legend-item'] {
+    --xh-_heatmap-level: 0%;
+
+    display: block;
+    flex: 0 0 auto;
+    inline-size: var(--xh-_heatmap-cell-size);
+    block-size: var(--xh-_heatmap-cell-size);
+    border-radius: var(--xh-heatmap-cell-radius, var(--xh-shape-inset));
+    background: var(
+      --xh-heatmap-cell-bg,
+      color-mix(in oklab, var(--xh-_heatmap-ink) var(--xh-_heatmap-level), var(--xh-_heatmap-empty))
+    );
+    box-shadow: inset 0 0 0 var(--xh-stroke-thin) var(--xh-heatmap-cell-border, var(--xh-border-default));
+  }
+
+  /* 给了 display 的角色节点必须补这条：display 声明会盖掉 UA 的 [hidden]{display:none}，
+     不补的话作者给节点加 hidden 后它照样显示。详情条收起靠的正是这一条。
+     格子没有声明 display，UA 那条兜得住，不必列在这里 */
+  [data-scope='heatmap'][data-part='root'][hidden],
+  [data-scope='heatmap'][data-part='grid'][hidden],
+  [data-scope='heatmap'][data-part='month-block'][hidden],
+  [data-scope='heatmap'][data-part='row'][hidden],
+  [data-scope='heatmap'][data-part='week-day-label'][hidden],
+  [data-scope='heatmap'][data-part='month-label'][hidden],
+  [data-scope='heatmap'][data-part='row-label'][hidden],
+  [data-scope='heatmap'][data-part='column-label'][hidden],
+  [data-scope='heatmap'][data-part='tooltip'][hidden],
+  [data-scope='heatmap'][data-part='legend'][hidden],
+  [data-scope='heatmap'][data-part='legend-item'][hidden] {
+    display: none;
+  }
+}

package/css/highlight.css

@@ -13,8 +13,8 @@
   /* 浏览器给 mark 的默认底色是一个固定的亮黄，暗色主题下压在深底上刺眼、
      配的黑字也不随主题走；这里整份换成随主题走的品牌淡底 */
   [data-scope='highlight'][data-part='mark'] {
-    padding-inline: var(--xh-space-0_5);
-    border-radius: var(--xh-highlight-radius, var(--xh-radius-sm));
+    padding-inline: var(--xh-highlight-mark-px, var(--xh-space-0_5));
+    border-radius: var(--xh-highlight-radius, var(--xh-shape-inset));
     background: var(--xh-highlight-bg, var(--xh-bg-brand-subtle));
     color: var(--xh-highlight-fg, var(--xh-fg-brand-strong));
     font-weight: var(--xh-font-weight-medium);

package/css/hotkeys.css

@@ -0,0 +1,90 @@
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  [data-scope='hotkeys'] {
+    --xh-hotkeys-skin: 1;
+  }
+
+  /* 一排键帽连着连接符。整块不换行：一组组合被折成两行就读不出是一组了 */
+  [data-scope='hotkeys'][data-part='root'] {
+    /* 尺寸档只换这两个私有槽，键帽从 root 继承它们，换档不必给每个部件各写一条选择器 */
+    --xh-_hotkeys-font-size: var(--xh-control-caption-md);
+    --xh-_hotkeys-key-px: var(--xh-space-1);
+
+    display: inline-flex;
+    align-items: center;
+    gap: var(--xh-hotkeys-gap, var(--xh-space-0_5));
+    color: var(--xh-hotkeys-fg, var(--xh-fg-muted));
+    font-size: var(--xh-hotkeys-font-size, var(--xh-_hotkeys-font-size));
+    line-height: var(--xh-leading-none);
+    white-space: nowrap;
+  }
+
+  /* 一枚键帽：等宽字，带描边与一层薄阴影凑出按键的样子。
+     min-inline-size 保证单个字母的键帽不至于窄成一条 */
+  [data-scope='hotkeys'][data-part='key'] {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    min-inline-size: var(--xh-hotkeys-key-min-w, var(--xh-control-indicator-size));
+    padding-block: var(--xh-hotkeys-key-py, var(--xh-space-0_5));
+    padding-inline: var(--xh-hotkeys-key-px, var(--xh-_hotkeys-key-px));
+    border: var(--xh-stroke-thin) solid var(--xh-hotkeys-key-border, var(--xh-border-subtle));
+    border-radius: var(--xh-hotkeys-key-radius, var(--xh-shape-inset));
+    background: var(--xh-hotkeys-key-bg, var(--xh-bg-surface));
+    box-shadow: var(--xh-hotkeys-key-shadow, var(--xh-elevation-raised));
+    color: var(--xh-hotkeys-key-fg, var(--xh-fg-default));
+    /* kbd 的 UA 字体是等宽，但字号会被压小；两者都显式接过来，档位才归尺寸轴管 */
+    font-family: var(--xh-hotkeys-key-font, var(--xh-font-family-mono));
+    font-size: inherit;
+    font-weight: var(--xh-hotkeys-key-font-weight, var(--xh-font-weight-medium));
+    line-height: var(--xh-leading-none);
+  }
+
+  /* 修饰键多是符号，与主键的字母混排时字宽差得远，单独留一档给使用者调 */
+  [data-scope='hotkeys'][data-part='key'][data-modifier] {
+    color: var(--xh-hotkeys-key-fg-modifier, var(--xh-fg-muted));
+  }
+
+  /* 连接符是排版符号，不参与键帽的盒子 */
+  [data-scope='hotkeys'][data-part='separator'] {
+    color: var(--xh-hotkeys-separator-fg, var(--xh-fg-subtle));
+    user-select: none;
+  }
+
+  /* 监听关掉时组合按不出来，整块转成不可用的样子：键帽换成暗底、去掉阴影，前景压到 fg-subtle。
+     这块是 role=img 的说明性文字而不是失效控件，读者仍要认出按的是哪几枚键，
+     所以前景不用 fg-disabled（那一档压在 muted 底上只有 2.36:1 / 1.94:1），也不叠 opacity */
+  [data-scope='hotkeys'][data-part='root'][data-disabled] {
+    color: var(--xh-fg-subtle);
+  }
+
+  [data-scope='hotkeys'][data-part='root'][data-disabled] [data-scope='hotkeys'][data-part='key'] {
+    background: var(--xh-hotkeys-key-bg-disabled, var(--xh-bg-muted));
+    box-shadow: none;
+    color: var(--xh-fg-subtle);
+  }
+
+  [data-scope='hotkeys'][data-part='root'][data-disabled] [data-scope='hotkeys'][data-part='separator'] {
+    color: var(--xh-fg-subtle);
+  }
+
+  /* —— 尺寸 —— */
+  /* 缺省的 md 档写在上面的基础规则里 */
+  [data-scope='hotkeys'][data-part='root'][data-size='sm'] {
+    --xh-_hotkeys-font-size: var(--xh-control-caption-sm);
+    --xh-_hotkeys-key-px: var(--xh-space-0_5);
+  }
+
+  [data-scope='hotkeys'][data-part='root'][data-size='lg'] {
+    --xh-_hotkeys-font-size: var(--xh-control-caption-lg);
+    --xh-_hotkeys-key-px: var(--xh-space-1_5);
+  }
+
+  /* 给了 display 的角色节点必须补这条：display 声明会盖掉 UA 的 [hidden]{display:none}，
+     不补的话作者给节点加 hidden 后它照样显示。Mac 写法下连接符恒带 hidden，靠这条收起 */
+  [data-scope='hotkeys'][data-part='root'][hidden],
+  [data-scope='hotkeys'][data-part='key'][hidden],
+  [data-scope='hotkeys'][data-part='separator'][hidden] {
+    display: none;
+  }
+}

package/css/hover-card.css

@@ -1,13 +1,26 @@
 @layer xihan.motion {
   /* 动画名的查找只认「文档里有没有这个名字」：引用别处文件里的名字，那份文件不一定在场，
      动画会静默地整个不跑。每份皮肤都能单独引入，所以它用到的关键帧都写在自己身上。 */
-  @keyframes xh-fade-in {
+  @keyframes xh-pop-in {
     from {
       opacity: 0;
+      scale: var(--xh-motion-scale-enter);
     }
 
     to {
       opacity: 1;
+      scale: 1;
+    }
+  }
+  @keyframes xh-pop-out {
+    from {
+      opacity: 1;
+      scale: 1;
+    }
+
+    to {
+      opacity: 0;
+      scale: var(--xh-motion-scale-enter);
     }
   }
 }
@@ -50,8 +63,15 @@
 
   /* 坐标由定位引擎写进 style（inset-inline-start / inset-block-start），这里只定位模式与层级 */
   [data-scope='hover-card'][data-part='positioner'] {
+    /* 落定那一侧的可用高度，由定位引擎经内联自定义属性写进来，内容层继承它限高；
+       引擎没算（尚未落位 / 无引擎 / 贴边归零）时不额外限高 */
+    --xh-_hover-card-available-h: 100vh;
+
+    /* 卡片内容的自绘条浮在内容之上：轨道不上底色，实色轨道会在卡片右缘糊一条竖灰带 */
+    --xh-scrollbar-track-bg: transparent;
+
     position: fixed;
-    z-index: var(--xh-layer-popover);
+    z-index: var(--xh-hover-card-layer, var(--xh-layer-popover));
     /* 空壳不吃指针：trigger 与 content 之间那段间隙要能点得穿，
        指针穿行的判定全靠 content 自己的进出事件 */
     pointer-events: none;
@@ -77,22 +97,24 @@
     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));
+    /* 内容由作者给，长度不可预知：不限高就整块伸出视口且滚不到 */
+    max-block-size: min(var(--xh-hover-card-max-h, var(--xh-overlay-max-h)), var(--xh-_hover-card-available-h));
+    overflow-y: auto;
     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));
+    box-shadow: var(--xh-hover-card-shadow, var(--xh-elevation-floating));
     pointer-events: auto;
   }
 
-  /* display 会盖掉 hidden 属性的 UA 规则，收起态显式让位 */
-  [data-scope='hover-card'][data-part='content'][hidden] {
-    display: none;
-  }
+  /* 这里刻意没有 [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='hover-card'][data-part='content']:focus-visible {
@@ -100,7 +122,13 @@
   }
 
   [data-scope='hover-card'][data-part='content'][data-state='open'] {
-    animation: xh-fade-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
+    animation: xh-pop-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
+  }
+
+  /* 退场：收起那一帧 hidden 由退场闸门押后，这里才播得出来。forwards 把末态钉住，
+     免得动画结束到真收起之间闪一下原样 */
+  [data-scope='hover-card'][data-part='content'][data-state='closed'] {
+    animation: xh-pop-out var(--xh-motion-duration-exit) var(--xh-motion-ease-exit) forwards;
   }
 
   /* —— 尺寸 —— */
@@ -118,46 +146,16 @@
     --xh-_hover-card-max-w: var(--xh-overlay-max-w-lg);
   }
 
-  /* 箭头是旋转 45° 的方块，只保留朝向锚点那两条边的描边；
+  /* 箭头的底色与描边色，几何在 overlay-arrow.css。
      交叉轴落点由定位引擎经内联自定义属性写进来，没给时退回居中 */
   [data-scope='hover-card'][data-part='arrow'] {
-    --xh-_hover-card-arrow-size: var(--xh-hover-card-arrow-size, var(--xh-overlay-arrow-size));
     --xh-_hover-card-arrow-x: 50%;
     --xh-_hover-card-arrow-y: 50%;
+    --xh-_overlay-arrow-size: var(--xh-hover-card-arrow-size, var(--xh-overlay-arrow-size));
+    --xh-_overlay-arrow-x: var(--xh-_hover-card-arrow-x);
+    --xh-_overlay-arrow-y: var(--xh-_hover-card-arrow-y);
 
-    position: absolute;
-    inline-size: var(--xh-_hover-card-arrow-size);
-    block-size: var(--xh-_hover-card-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) / -2);
-    inset-inline-start: calc(var(--xh-_hover-card-arrow-x) - var(--xh-_hover-card-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) / -2);
-    inset-inline-start: calc(var(--xh-_hover-card-arrow-x) - var(--xh-_hover-card-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) / -2);
-    inset-block-start: calc(var(--xh-_hover-card-arrow-y) - var(--xh-_hover-card-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) / -2);
-    inset-block-start: calc(var(--xh-_hover-card-arrow-y) - var(--xh-_hover-card-arrow-size) / 2);
-    border-block-end: 0;
-    border-inline-start: 0;
+    border: var(--xh-stroke-thin) solid var(--xh-hover-card-border, var(--xh-border-default));
   }
 }