@xihan-ui/styles 3.1.0 → 4.0.0

package/dist/css/heatmap.css

@@ -0,0 +1,552 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 heatmap 样式。 */
+
+/* 详情条与对照条走 Chart 家族配方：与其余图表的提示框、图例同一副外观。本皮肤 @import 它，单独引入仍成立。 */
+@import '../family/chart.css';
+
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  .xh-scope-heatmap {
+    --xh-heatmap-skin: 1;
+  }
+
+  /* 缺省的 calendar 形态：上下两条横排，月份行在网格之外（它只是一条对齐用的坐标轴），
+     网格里是七行星期。格子一律是固定尺寸的方块，列与列之间靠尺寸对齐，不必另立网格轨道。
+     另外两种形态只在下面的 [data-variant] 段里改摆法，这里的取值一概不动。 */
+  .xh-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: var(--xh-space-1);
+    --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-opaque));
+    --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));
+    /* 一整年五十几列，一屏放不下就自己横着滚。上下各留一道与格间距同宽的空当，
+       最上一行与最下一行不贴着滚动容器的边 */
+    padding-block: var(--xh-heatmap-py, var(--xh-_heatmap-gap));
+    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] 限定：不限定的话，放在语气容器里的热力图会跟着改色 */
+  .xh-scope-heatmap[data-part='root'][data-tone] {
+    --xh-_heatmap-ink: var(--xh-heatmap-ink, var(--xh-_tone, var(--xh-bg-brand)));
+  }
+
+  /* —— 色板 —— */
+  /* 直接按颜色点名，定的是满档那一端的实心底：取基础色板里同名色相的 600 档；0 档的空格底与中间各档的兑法一概不动。
+     基础色板同一档跨色相同一明度，十二个色相摊出来的五档深浅一致，换色板不换可读性。
+     这几条规则与上面那条语气规则同特指度，排在它之后：两个都写时色板赢——
+     色板指名了一个具体颜色，语气只是推得出一个颜色，指名的那个更具体。
+     取值一律逐值写死原语、不经 --xh-_tone：那一族槽位是语气层的派生结果，
+     色板借道它就会连带把语气的悬停 / 淡底 / 前景一起绑进来，也会被祖先的 data-tone 染色。
+     色板拼错取值时一条都不命中，落回上面两条，与没写一样 */
+  .xh-scope-heatmap[data-part='root'][data-palette='red'] {
+    --xh-_heatmap-ink: var(--xh-heatmap-ink, var(--xh-color-red-600));
+  }
+
+  .xh-scope-heatmap[data-part='root'][data-palette='orange'] {
+    --xh-_heatmap-ink: var(--xh-heatmap-ink, var(--xh-color-orange-600));
+  }
+
+  .xh-scope-heatmap[data-part='root'][data-palette='amber'] {
+    --xh-_heatmap-ink: var(--xh-heatmap-ink, var(--xh-color-amber-600));
+  }
+
+  .xh-scope-heatmap[data-part='root'][data-palette='yellow'] {
+    --xh-_heatmap-ink: var(--xh-heatmap-ink, var(--xh-color-yellow-600));
+  }
+
+  .xh-scope-heatmap[data-part='root'][data-palette='lime'] {
+    --xh-_heatmap-ink: var(--xh-heatmap-ink, var(--xh-color-lime-600));
+  }
+
+  .xh-scope-heatmap[data-part='root'][data-palette='green'] {
+    --xh-_heatmap-ink: var(--xh-heatmap-ink, var(--xh-color-green-600));
+  }
+
+  .xh-scope-heatmap[data-part='root'][data-palette='teal'] {
+    --xh-_heatmap-ink: var(--xh-heatmap-ink, var(--xh-color-teal-600));
+  }
+
+  .xh-scope-heatmap[data-part='root'][data-palette='cyan'] {
+    --xh-_heatmap-ink: var(--xh-heatmap-ink, var(--xh-color-cyan-600));
+  }
+
+  .xh-scope-heatmap[data-part='root'][data-palette='blue'] {
+    --xh-_heatmap-ink: var(--xh-heatmap-ink, var(--xh-color-blue-600));
+  }
+
+  .xh-scope-heatmap[data-part='root'][data-palette='indigo'] {
+    --xh-_heatmap-ink: var(--xh-heatmap-ink, var(--xh-color-indigo-600));
+  }
+
+  .xh-scope-heatmap[data-part='root'][data-palette='purple'] {
+    --xh-_heatmap-ink: var(--xh-heatmap-ink, var(--xh-color-purple-600));
+  }
+
+  .xh-scope-heatmap[data-part='root'][data-palette='pink'] {
+    --xh-_heatmap-ink: var(--xh-heatmap-ink, var(--xh-color-pink-600));
+  }
+
+  /* 灰是唯一按主题换档的一族：十二个色相的 600 档明度都是 0.546，
+     深色态的空格底（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 写在自己身上还是写在祖先上都算，两种用法都成立 */
+  .xh-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']).xh-scope-heatmap[data-part='root'][data-palette='gray'] {
+    --xh-_heatmap-ink: var(--xh-heatmap-ink, var(--xh-color-neutral-450));
+  }
+
+  /* —— 发散色阶 ——
+     以中点为界两侧各自加深：中点那一格是数据色的中性中点，低于中点兑向负向色、高于中点兑向正向色。
+     三色都取数据色的发散三色，语气与色板在这一档不生效。中点是没有色相的中性色，兑色走 oklab
+     （格子的基础规则已是 in oklab），oklch 会绕着色相环走出一段杂色 */
+  .xh-scope-heatmap[data-part='root'][data-scale='diverging'] {
+    --xh-_heatmap-empty: var(--xh-heatmap-diverging-center, var(--xh-chart-diverging-center));
+  }
+
+  /* 两侧的墨色写在格子上而不是根上：根上的语气与色板规则（含暗色的中性色板）不论权重多高都盖不到这里 */
+  .xh-scope-heatmap[data-part='root'][data-scale='diverging'] :is(.xh-scope-heatmap[data-part='cell'], .xh-scope-heatmap[data-part='legend-item'])[data-polarity='negative'] {
+    --xh-_heatmap-ink: var(--xh-heatmap-diverging-negative, var(--xh-chart-diverging-negative));
+  }
+
+  .xh-scope-heatmap[data-part='root'][data-scale='diverging'] :is(.xh-scope-heatmap[data-part='cell'], .xh-scope-heatmap[data-part='legend-item'])[data-polarity='positive'] {
+    --xh-_heatmap-ink: var(--xh-heatmap-diverging-positive, var(--xh-chart-diverging-positive));
+  }
+
+  /* —— 尺寸 —— */
+  /* 缺省的 md 档写在上面的基础规则里 */
+  .xh-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));
+  }
+
+  .xh-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));
+  }
+
+  .xh-scope-heatmap[data-part='grid'] {
+    display: flex;
+    flex-direction: column;
+    gap: var(--xh-heatmap-grid-gap, var(--xh-_heatmap-gap));
+  }
+
+  .xh-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）高，让它撑开行
+     会在纵向多挤出两像素，同一张图的横向格距与纵向格距就不一样宽。
+     钉死成格高之后星期名的字仍照常画，只是溢出到行外——那几行隔行留白，撞不到东西 */
+  .xh-scope-heatmap[data-part='row'][data-week-day],
+  .xh-scope-heatmap[data-part='row'][data-week] {
+    block-size: var(--xh-_heatmap-cell-size);
+  }
+
+  /* 行首的星期名。月份行行首那个占位也是它，宽度一样，月份才对得上列。
+     一整年放不下时网格横着滚，这一列钉在滚动容器的起始缘：跟着滚走的话，
+     滚过头一屏就再也认不出哪一行是星期几。底色必须实色，格子从它下面滚过去不能透出来 */
+  .xh-scope-heatmap[data-part='week-day'] {
+    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 × 格高 + 格距）可用。哪一行是星期几由行自己的可及名字念出来，
+     可见文字与可及名字是两件事，读屏这边一行都没少 */
+  .xh-scope-heatmap[data-part='week-day'][data-week-day='0'],
+  .xh-scope-heatmap[data-part='week-day'][data-week-day='2'],
+  .xh-scope-heatmap[data-part='week-day'][data-week-day='4'],
+  .xh-scope-heatmap[data-part='week-day'][data-week-day='6'] {
+    color: var(--xh-_heatmap-week-day-skip);
+  }
+
+  /* 月份名横跨这个月占的那几列：列宽加列间距，末尾少算一个间距（它由行的 gap 补上） */
+  .xh-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;
+  }
+
+  /* 一天一格。档位是连着的百分比，档数随便改都不必再写一条选择器 */
+  .xh-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: box-shadow var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  /* 详情条正在说的那一格（指针停着或焦点落着）描一圈正文色的粗线：扫过一片格子时看得出条说的是哪一格 */
+  .xh-scope-heatmap[data-part='cell'][data-highlighted] {
+    box-shadow: inset 0 0 0 var(--xh-stroke-thick) var(--xh-heatmap-cell-border-highlighted, var(--xh-fg-default));
+  }
+
+  /* 首次出现：有颜色的格子从空格底色填到自己的档位色，按日期（矩阵按列）的先后扫过去。
+     连接层写入这一格在扫描里的位置，乘上扫描时长就是它开始填色的延迟；
+     减弱动效下扫描时长归零，各格一起淡变填色 */
+  .xh-scope-heatmap[data-part='cell'][data-drawing] {
+    animation: xh-heatmap-fill var(--xh-motion-duration-enter) var(--xh-motion-ease-enter) both;
+    animation-delay: calc(var(--xh-motion-duration-reveal) * var(--xh-_chart-reveal-at));
+  }
+
+  /* 数据变化后的换色：各格从旧档的颜色过渡到新档。只在连接层标出的这一段过渡，
+     主题与语气的换色照常一步到位，不被数据的时长拖慢 */
+  .xh-scope-heatmap[data-part='root'][data-animating] .xh-scope-heatmap[data-part='cell'] {
+    transition:
+      background-color var(--xh-motion-duration-morph) var(--xh-motion-ease-continuous),
+      box-shadow var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  /* 错列打在本行第一个格子上：打在行上会连行首的星期名一起往后推，
+     左侧那一列星期名就变成锯齿。两条选择器合起来正好是「本行第一个格子」，
+     行里写不写星期名都成立 */
+  .xh-scope-heatmap[data-part='row'] > .xh-scope-heatmap[data-part='cell']:first-child,
+  .xh-scope-heatmap[data-part='week-day'] + .xh-scope-heatmap[data-part='cell'] {
+    margin-inline-start: calc(
+      var(--xh-_heatmap-row-offset) * (var(--xh-_heatmap-cell-size) + var(--xh-_heatmap-gap))
+    );
+  }
+
+  /* —— 月历形态：一个自然月一块，块内一行是一周、一列是一个星期几 —— */
+  .xh-scope-heatmap[data-part='root'][data-variant='month'] .xh-scope-heatmap[data-part='grid'] {
+    flex-flow: row wrap;
+    gap: var(--xh-heatmap-block-gap, var(--xh-_heatmap-gutter));
+  }
+
+  .xh-scope-heatmap[data-part='month-block'] {
+    display: flex;
+    flex-direction: column;
+    gap: var(--xh-heatmap-block-inner-gap, var(--xh-_heatmap-gap));
+  }
+
+  /* 月历形态的月块是换行排开的，没有钉住的那一列，滚动落点也不必让开 */
+  .xh-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;
+  }
+
+  /* 块里的星期名是一排列头，宽度改成格宽才对得上下面的格子，也不再钉住。
+     字比一格宽，不裁：裁掉就是七个缺角的字，让它往两边的列间距里溢出去，
+     相邻两个各溢出一点也还差着一段空白 */
+  .xh-scope-heatmap[data-part='root'][data-variant='month'] .xh-scope-heatmap[data-part='week-day'] {
+    position: static;
+    inline-size: var(--xh-_heatmap-cell-size);
+    overflow: visible;
+    background: none;
+    text-align: center;
+  }
+
+  /* 块的标题占整块宽，不再横跨若干列 */
+  .xh-scope-heatmap[data-part='root'][data-variant='month'] .xh-scope-heatmap[data-part='month-label'] {
+    inline-size: auto;
+    color: var(--xh-heatmap-title-fg, var(--xh-fg-default));
+  }
+
+  /* —— 矩阵形态：行列都由作者给，行名与列名是两条真表头 —— */
+  /* 行名与日历的星期名同一个位置、同一件事：列多到放不下时钉在起始缘 */
+  .xh-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;
+  }
+
+  /* 列名与它下面那一列的格子同宽：标签长就把列宽整体调大，别只调标签。
+     两处的兜底都是行高，不写列宽时矩阵格子就是正方块 */
+  .xh-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;
+  }
+
+  /* 矩阵的格子两向都不走日方块那把尺：宽跟列走，高跟行走 */
+  .xh-scope-heatmap[data-part='root'][data-variant='matrix'] .xh-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 的滚动裁掉 */
+  .xh-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));
+    /* 配方按物理左缘与平移落位，详情条自己按格子的逻辑缘落位：把配方那两处让开 */
+    translate: none;
+    /* 材质、圆角、内边距与影走配方：frosted、overlay 圆角、正文排版，不反白 */
+    --xh-_chart-tip-x: auto;
+    --xh-_chart-tooltip-gap: var(--xh-space-1);
+    --xh-_chart-tooltip-py: var(--xh-heatmap-tooltip-py, var(--xh-surface-pad-sm));
+    --xh-_chart-tooltip-px: var(--xh-heatmap-tooltip-px, var(--xh-surface-pad-sm));
+    --xh-_chart-tooltip-radius: var(--xh-heatmap-tooltip-radius, var(--xh-shape-overlay));
+    --xh-_chart-tooltip-shadow: var(--xh-heatmap-tooltip-shadow, var(--xh-material-frosted-shadow));
+    /* 作者覆盖的底、字与描边压在配方的材质上：只换颜色那一层，顶部的边界光与模糊照旧 */
+    border-color: var(--xh-heatmap-tooltip-border, var(--xh-material-frosted-border));
+    background-color: var(--xh-heatmap-tooltip-bg, var(--xh-material-frosted-bg));
+    color: var(--xh-heatmap-tooltip-fg, var(--xh-material-frosted-fg));
+    font-size: var(--xh-heatmap-tooltip-font-size, var(--xh-text-body-size));
+    line-height: var(--xh-leading-normal);
+  }
+
+  /* 从格子的末缘往回长：条比一格宽得多，格子后面的地方比前面少时往后长会伸出滚动容器被裁掉，
+     还会把横向滚动条撑长。按末缘定位，条自己多宽都贴着格子的末沿。
+     百分比是内边距盒的宽，在这条 calc 里前后抵消，横向滚到哪里都成立 */
+  .xh-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));
+  }
+
+  /* 摆在格子下边：从格子的下沿再让开一个格间距 */
+  .xh-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)
+    );
+  }
+
+  /* 摆在格子上边：按末缘定位，条自己多高都贴着格子的上沿。
+     两头都写就是过约束，起始缘要先让开 */
+  .xh-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));
+  }
+
+  /* 对照条的排布走配方，间距由配方的私有槽给出；色阶是一条连续的尺，不折行：
+     「少」、一排色块、「多」断开就读不出哪端表示多 */
+  .xh-scope-heatmap[data-part='legend'] {
+    --xh-_chart-legend-gap: var(--xh-heatmap-legend-gap, var(--xh-_heatmap-gap));
+
+    flex-wrap: nowrap;
+    align-items: center;
+    color: var(--xh-heatmap-label-fg, var(--xh-fg-subtle));
+  }
+
+  /* 对照条两端的那两个字。与色块同一行、同一档颜色，不换行：
+     「少」「多」断成两行就跟色块对不上了 */
+  .xh-scope-heatmap[data-part='legend-label'] {
+    flex: 0 0 auto;
+    white-space: nowrap;
+  }
+
+  /* 对照条里的一格与网格里同档的格子同色，两处共用同一条色阶 */
+  .xh-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 那条兜得住，不必列在这里 */
+  .xh-scope-heatmap[data-part='root'][hidden],
+  .xh-scope-heatmap[data-part='grid'][hidden],
+  .xh-scope-heatmap[data-part='month-block'][hidden],
+  .xh-scope-heatmap[data-part='row'][hidden],
+  .xh-scope-heatmap[data-part='week-day'][hidden],
+  .xh-scope-heatmap[data-part='month-label'][hidden],
+  .xh-scope-heatmap[data-part='row-label'][hidden],
+  .xh-scope-heatmap[data-part='column-label'][hidden],
+  .xh-scope-heatmap[data-part='tooltip'][hidden],
+  .xh-scope-heatmap[data-part='legend'][hidden],
+  .xh-scope-heatmap[data-part='legend-item'][hidden] {
+    display: none;
+  }
+
+  /*
+   * 打印：格子的深浅只写在底色上，纸上多数丢背景，整张图印成一片空白。
+   * 这一档把档位改画成边框的粗细——0 档只有一圈发丝线，档位越高边越厚，
+   * 顶到一半格宽时整格填满。边算在尺寸里（reset 兜了 border-box），格子大小一点不变。
+   *
+   * 比例取 0.2 / 0.3 / 0.4 / 0.5：缺省格宽 10px 下正好落在 2 / 3 / 4 / 5 像素，
+   * 与 0 档那一像素合成五档整数宽——边宽在屏幕与纸上都取整，分数宽会有两档并到一起。
+   *
+   * 第一条给的是高档那一身，下面四条按档位逐个改薄：档数由作者定，
+   * 超出缺省五档的那些落在第一条上，一律按最高档画。
+   * 图例里那几个方块与格子同源，跟着走同一套。
+   */
+  @media print {
+    .xh-scope-heatmap[data-part='cell'],
+    .xh-scope-heatmap[data-part='legend-item'] {
+      --xh-_heatmap-ink-ring: calc(var(--xh-_heatmap-cell-size) * 0.5);
+
+      border: var(--xh-_heatmap-ink-ring) solid currentColor;
+    }
+
+    .xh-scope-heatmap[data-part='cell'][data-level='0'],
+    .xh-scope-heatmap[data-part='legend-item'][data-level='0'] {
+      --xh-_heatmap-ink-ring: var(--xh-stroke-thin);
+    }
+
+    .xh-scope-heatmap[data-part='cell'][data-level='1'],
+    .xh-scope-heatmap[data-part='legend-item'][data-level='1'] {
+      --xh-_heatmap-ink-ring: calc(var(--xh-_heatmap-cell-size) * 0.2);
+    }
+
+    .xh-scope-heatmap[data-part='cell'][data-level='2'],
+    .xh-scope-heatmap[data-part='legend-item'][data-level='2'] {
+      --xh-_heatmap-ink-ring: calc(var(--xh-_heatmap-cell-size) * 0.3);
+    }
+
+    .xh-scope-heatmap[data-part='cell'][data-level='3'],
+    .xh-scope-heatmap[data-part='legend-item'][data-level='3'] {
+      --xh-_heatmap-ink-ring: calc(var(--xh-_heatmap-cell-size) * 0.4);
+    }
+
+    /* 发散色阶两侧同档的环一样粗，纸上分不出正负：负向一侧改用点线，点线在任何粗细下都认得出 */
+    .xh-scope-heatmap[data-part='cell'][data-polarity='negative'],
+    .xh-scope-heatmap[data-part='legend-item'][data-polarity='negative'] {
+      border-style: dotted;
+    }
+  }
+
+  /*
+   * 高对比档：格子画的就是色阶本身，被系统换成同一个底色之后整张图没有任何深浅。
+   * 这几处退出强制着色，自己保住色阶；退出之后不再跟系统底色走，
+   * 各补一圈系统描边把方格从背景里框出来（原来那圈发丝线写在 inset 阴影上，这一档里被丢弃）。
+   */
+  @media (forced-colors: active) {
+    .xh-scope-heatmap[data-part='cell'],
+    .xh-scope-heatmap[data-part='legend-item'] {
+      forced-color-adjust: none;
+      outline: var(--xh-stroke-thin) solid CanvasText;
+      outline-offset: calc(-1 * var(--xh-stroke-thin));
+    }
+  }
+}
+
+@layer xihan.motion {
+  /* 只写起点：终点是格子自己的档位色，作者改写 --xh-heatmap-cell-bg 时同样成立 */
+  @keyframes xh-heatmap-fill {
+    from {
+      background-color: var(--xh-_heatmap-empty);
+    }
+  }
+}