@xihan-ui/styles 3.1.0 → 4.0.0

package/dist/css/timeline.css

@@ -0,0 +1,440 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 timeline 样式。 */
+
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  .xh-scope-timeline {
+    --xh-timeline-skin: 1;
+  }
+
+  .xh-scope-timeline[data-part='root'] {
+    /* 尺寸档只换这几个私有槽，条目、圆点与文字都从 root 继承它们，
+       换档不必给每个部件各写一条选择器 */
+    /* 圆点只标位置，6px 实心；圆点到内容 16px；条目之间 32px，事件一条条分得开 */
+    --xh-_timeline-dot-size: var(--xh-space-1_5);
+    --xh-_timeline-gutter: var(--xh-space-4);
+    --xh-_timeline-item-gap: var(--xh-space-8);
+    --xh-_timeline-title-font-size: var(--xh-control-font-md);
+    --xh-_timeline-caption-font-size: var(--xh-text-caption-size);
+    /* 标题首行占多高。圆点按它居中下移，圆心才落在标题这一行的中线上 */
+    --xh-_timeline-line-h: calc(
+      var(--xh-timeline-title-font-size, var(--xh-_timeline-title-font-size)) * var(--xh-leading-normal)
+    );
+
+    /* 条目之间不设 gap：留白由 content 自己的边距撑出来，连线才连得到下一条的圆点。
+       ol 的项目符号与内外边距是 UA 给的，库里没有全局 preflight，只能在这儿自己抹平 */
+    display: flex;
+    margin: 0;
+    padding: 0;
+    color: var(--xh-timeline-fg, var(--xh-fg-default));
+    list-style: none;
+  }
+
+  .xh-scope-timeline[data-part='root'][hidden] {
+    display: none;
+  }
+
+  .xh-scope-timeline[data-part='root'][data-orientation='vertical'] {
+    flex-direction: column;
+  }
+
+  /* 横排排成一行、允许折行：窄档里每条占满整行，于是一条一行地堆下来。
+     朝向两档都是 row，换档换的是下面每条的 flex 基准 */
+  .xh-scope-timeline[data-part='root'][data-orientation='horizontal'] {
+    flex-direction: row;
+    flex-wrap: wrap;
+  }
+
+  /* —— 尺寸 —— */
+  /* 缺省档写在上面的基础规则里。圆点直径不在控件高度那把尺上，三档走空间尺相邻的三格 */
+  .xh-scope-timeline[data-part='root'][data-size='sm'] {
+    --xh-_timeline-dot-size: var(--xh-space-1);
+    --xh-_timeline-gutter: var(--xh-space-3);
+    --xh-_timeline-item-gap: var(--xh-space-6);
+    --xh-_timeline-title-font-size: var(--xh-control-font-sm);
+    /* 字号档最小就是 xs，时刻文本不再往下走，故不重声明 caption */
+  }
+
+  .xh-scope-timeline[data-part='root'][data-size='lg'] {
+    --xh-_timeline-dot-size: var(--xh-space-2);
+    --xh-_timeline-gutter: var(--xh-space-5);
+    --xh-_timeline-item-gap: calc(var(--xh-space-8) + var(--xh-space-2));
+    --xh-_timeline-title-font-size: var(--xh-control-font-lg);
+    --xh-_timeline-caption-font-size: var(--xh-text-secondary-size);
+  }
+
+  /* —— 条目 —— */
+  /* 圆点与连线占一列，内容占另一列，用 grid 而不是再包一层节点：
+     解剖里没有那个包裹层，作者也不该被逼着多写一个 div。
+     这份两列的摆法是两个朝向共同的窄档，横排在下面的宽档里改写它 */
+  .xh-scope-timeline[data-part='item'] {
+    display: grid;
+    grid-template-columns: auto minmax(0, 1fr);
+    grid-template-rows: auto minmax(0, 1fr);
+    column-gap: var(--xh-timeline-gutter, var(--xh-_timeline-gutter));
+    /* 库里没有全局 preflight，列表项的外边距在这里自己抹平 */
+    margin: 0;
+    /* 允许被压缩，内容里的省略号才有生效的余地 */
+    min-inline-size: 0;
+  }
+
+  .xh-scope-timeline[data-part='item'][hidden] {
+    display: none;
+  }
+
+  /* 横排的窄档：每条占满整行，一条一行地堆下来 */
+  .xh-scope-timeline[data-part='item'][data-orientation='horizontal'] {
+    flex: 0 0 100%;
+  }
+
+  /* —— 圆点 —— */
+  .xh-scope-timeline[data-part='indicator'] {
+    display: flex;
+    flex: none;
+    align-items: center;
+    justify-content: center;
+    inline-size: var(--xh-timeline-indicator-size, var(--xh-_timeline-dot-size));
+    block-size: var(--xh-timeline-indicator-size, var(--xh-_timeline-dot-size));
+    border-radius: var(--xh-timeline-indicator-radius, var(--xh-shape-circle));
+    /* 使用者令牌排在语气之前；两者都没有时退回品牌色的实心点 */
+    background: var(--xh-timeline-indicator-bg, var(--xh-_tone-soft, var(--xh-fg-brand)));
+    color: var(--xh-timeline-indicator-fg, var(--xh-_tone-on, var(--xh-fg-on-brand)));
+    font-size: var(--xh-timeline-indicator-font-size, var(--xh-_timeline-caption-font-size));
+    line-height: var(--xh-leading-none);
+    /* 语气色由每条自己的数据给，同一条的语气改了（事情办成了、出错了）走一遍过渡，
+       整列圆点不在数据回来的那一帧集体跳色 */
+    transition:
+      background-color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
+      color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  .xh-scope-timeline[data-part='indicator'][hidden] {
+    display: none;
+  }
+
+  .xh-scope-timeline[data-part='item'] .xh-scope-timeline[data-part='indicator'] {
+    grid-column: 1;
+    grid-row: 1;
+    /* 行高减去直径的一半：calc 里的除法要写成乘 0.5，除号在这儿是无效语法 */
+    margin-block-start: calc(
+      (var(--xh-_timeline-line-h) - var(--xh-timeline-indicator-size, var(--xh-_timeline-dot-size))) * 0.5
+    );
+  }
+
+  /* —— 连线 —— */
+  .xh-scope-timeline[data-part='connector'] {
+    border-radius: var(--xh-timeline-connector-radius, var(--xh-shape-pill));
+    background: var(--xh-timeline-connector-bg, var(--xh-border-default));
+  }
+
+  .xh-scope-timeline[data-part='connector'][hidden] {
+    display: none;
+  }
+
+  /* 堆叠时：从圆点下沿一直伸到条目底边，接上下一条的圆点。
+     min-block-size 兜住内容极短的条目，那时也还看得见一截线 */
+  .xh-scope-timeline[data-part='item'] .xh-scope-timeline[data-part='connector'] {
+    grid-column: 1;
+    grid-row: 2;
+    justify-self: center;
+    inline-size: var(--xh-timeline-connector-thickness, var(--xh-stroke-thin));
+    min-block-size: var(--xh-timeline-connector-min-length, var(--xh-space-4));
+    margin-block-start: var(--xh-space-1);
+  }
+
+  /* 末条后面没有下一件事，那截线不该占地方；作者不写它也一样，写了就替他收掉 */
+  .xh-scope-timeline[data-part='item']:last-child .xh-scope-timeline[data-part='connector'] {
+    display: none;
+  }
+
+  /* —— 内容 —— */
+  .xh-scope-timeline[data-part='content'] {
+    display: flex;
+    flex-direction: column;
+    gap: var(--xh-timeline-content-gap, var(--xh-space-1));
+    min-inline-size: 0;
+  }
+
+  .xh-scope-timeline[data-part='content'][hidden] {
+    display: none;
+  }
+
+  /* 条目之间的留白由内容自己的边距撑出来，连线的那一列因此能一路连到下一条 */
+  .xh-scope-timeline[data-part='item'] .xh-scope-timeline[data-part='content'] {
+    grid-column: 2;
+    grid-row: 1 / -1;
+    padding-block-end: var(--xh-timeline-item-gap, var(--xh-_timeline-item-gap));
+  }
+
+  /* 末条的留白同样收掉：它后面已经没有要隔开的东西 */
+  .xh-scope-timeline[data-part='item']:last-child .xh-scope-timeline[data-part='content'] {
+    padding-block-end: 0;
+  }
+
+  /* —— 侧别 —— */
+  /* 不写 placement 时内容落在结束侧，即上面那几条基础规则。
+     start 把线挪到结束侧、内容挪到起始侧，文字一并靠向线 */
+  .xh-scope-timeline[data-part='item'][data-orientation='vertical'][data-placement='start'] {
+    grid-template-columns: minmax(0, 1fr) auto;
+  }
+
+  .xh-scope-timeline[data-part='item'][data-orientation='vertical'][data-placement='start'] .xh-scope-timeline[data-part='indicator'],
+  .xh-scope-timeline[data-part='item'][data-orientation='vertical'][data-placement='start'] .xh-scope-timeline[data-part='connector'] {
+    grid-column: 2;
+  }
+
+  .xh-scope-timeline[data-part='item'][data-orientation='vertical'][data-placement='start'] .xh-scope-timeline[data-part='content'] {
+    grid-column: 1;
+    align-items: flex-end;
+    text-align: end;
+  }
+
+  /* alternate：线走中间，奇数条在结束侧、偶数条在起始侧 */
+  .xh-scope-timeline[data-part='item'][data-orientation='vertical'][data-placement='alternate'] {
+    grid-template-columns: minmax(0, 1fr) auto minmax(0, 1fr);
+  }
+
+  .xh-scope-timeline[data-part='item'][data-orientation='vertical'][data-placement='alternate'] .xh-scope-timeline[data-part='indicator'],
+  .xh-scope-timeline[data-part='item'][data-orientation='vertical'][data-placement='alternate'] .xh-scope-timeline[data-part='connector'] {
+    grid-column: 2;
+  }
+
+  .xh-scope-timeline[data-part='item'][data-orientation='vertical'][data-placement='alternate'] .xh-scope-timeline[data-part='content'] {
+    grid-column: 3;
+  }
+
+  .xh-scope-timeline[data-part='item'][data-orientation='vertical'][data-placement='alternate']:nth-child(even) .xh-scope-timeline[data-part='content'] {
+    grid-column: 1;
+    align-items: flex-end;
+    text-align: end;
+  }
+
+  /* —— 坐标 —— */
+  /* 与内容对置的那一列。竖排三种侧别各给它一条轨道，横排不单开轨道、按流排在末尾 */
+  .xh-scope-timeline[data-part='label'] {
+    grid-column: var(--xh-_timeline-label-col, auto);
+    grid-row: var(--xh-_timeline-label-row, auto);
+    align-self: start;
+    min-inline-size: 0;
+    color: var(--xh-timeline-label-fg, var(--xh-fg-subtle));
+    font-size: var(--xh-timeline-label-font-size, var(--xh-_timeline-caption-font-size));
+    /* 等宽数字：日期里的 1 与 7 在比例字体里宽度不同，不定住会让整列坐标左右抖一格 */
+    font-variant-numeric: tabular-nums;
+    /* 坐标的行盒与标题首行同高，小一号的坐标字落在标题那一行的中线上 */
+    line-height: var(--xh-_timeline-line-h);
+    text-align: var(--xh-_timeline-label-align, end);
+  }
+
+  /* 内容落在结束侧时坐标占线之前的那一列，圆点与连线让到第二列 */
+  .xh-scope-timeline[data-part='item'][data-orientation='vertical']:where(:not([data-placement]), [data-placement='end']):has(> .xh-scope-timeline[data-part='label']) {
+    --xh-_timeline-label-col: 1;
+    --xh-_timeline-label-row: 1;
+
+    grid-template-columns: auto auto minmax(0, 1fr);
+  }
+
+  .xh-scope-timeline[data-part='item'][data-orientation='vertical']:where(:not([data-placement]), [data-placement='end']):has(> .xh-scope-timeline[data-part='label']) > .xh-scope-timeline[data-part='indicator'],
+  .xh-scope-timeline[data-part='item'][data-orientation='vertical']:where(:not([data-placement]), [data-placement='end']):has(> .xh-scope-timeline[data-part='label']) > .xh-scope-timeline[data-part='connector'] {
+    grid-column: 2;
+  }
+
+  .xh-scope-timeline[data-part='item'][data-orientation='vertical']:where(:not([data-placement]), [data-placement='end']):has(> .xh-scope-timeline[data-part='label']) > .xh-scope-timeline[data-part='content'] {
+    grid-column: 3;
+  }
+
+  /* 横排的窄档摆成上下两格，坐标照竖排那样占线之前的一列。
+     不给这条轨道的话坐标会自动落进圆点那一列，把它撑宽，圆点与连线因此错开 */
+  .xh-scope-timeline[data-part='item'][data-orientation='horizontal']:has(> .xh-scope-timeline[data-part='label']) {
+    --xh-_timeline-label-col: 1;
+    --xh-_timeline-label-row: 1;
+
+    grid-template-columns: auto auto minmax(0, 1fr);
+  }
+
+  .xh-scope-timeline[data-part='item'][data-orientation='horizontal']:has(> .xh-scope-timeline[data-part='label']) > .xh-scope-timeline[data-part='indicator'],
+  .xh-scope-timeline[data-part='item'][data-orientation='horizontal']:has(> .xh-scope-timeline[data-part='label']) > .xh-scope-timeline[data-part='connector'] {
+    grid-column: 2;
+  }
+
+  .xh-scope-timeline[data-part='item'][data-orientation='horizontal']:has(> .xh-scope-timeline[data-part='label']) > .xh-scope-timeline[data-part='content'] {
+    grid-column: 3;
+  }
+
+  /* 内容落在起始侧时坐标占线之后的那一列 */
+  .xh-scope-timeline[data-part='item'][data-orientation='vertical'][data-placement='start']:has(> .xh-scope-timeline[data-part='label']) {
+    --xh-_timeline-label-col: 3;
+    --xh-_timeline-label-row: 1;
+    --xh-_timeline-label-align: start;
+
+    grid-template-columns: minmax(0, 1fr) auto auto;
+  }
+
+  /* 逐条交替时坐标恒在内容的对面，时间戳因此不跟着内容左右横跳 */
+  .xh-scope-timeline[data-part='item'][data-orientation='vertical'][data-placement='alternate'] {
+    --xh-_timeline-label-col: 1;
+    --xh-_timeline-label-row: 1;
+  }
+
+  .xh-scope-timeline[data-part='item'][data-orientation='vertical'][data-placement='alternate']:nth-child(even) {
+    --xh-_timeline-label-col: 3;
+    --xh-_timeline-label-align: start;
+  }
+
+  /* —— 横排的宽档 —— */
+  /* 上面那份两列的摆法是两个朝向共同的窄档。视口宽到放得下一行事件时，
+     横排在这里把圆点与连线转回同一行、内容落到下一行。
+     手机档停在窄档：一条一行，事件仍逐条读得完 */
+  @media (min-width: 768px) {
+    /* 每条等分整行 */
+    .xh-scope-timeline[data-part='item'][data-orientation='horizontal'] {
+      flex: 1;
+    }
+
+    /* 每条规则都带一条 :has(坐标) 的分支：窄档那条坐标轨道的选择器更重，
+       不把它写进来的话带坐标的那些条目会停在窄档的摆法上 */
+    .xh-scope-timeline[data-part='item'][data-orientation='horizontal'] .xh-scope-timeline[data-part='indicator'],
+    .xh-scope-timeline[data-part='item'][data-orientation='horizontal']:has(> .xh-scope-timeline[data-part='label']) > .xh-scope-timeline[data-part='indicator'] {
+      grid-column: 1;
+      grid-row: 1;
+      /* 圆点与内容不再上下对位，窄档那半行的下移收掉 */
+      margin-block-start: 0;
+    }
+
+    /* 线转成横的一条，与圆点同一行；窄档那几条竖着走的取值一并收掉 */
+    .xh-scope-timeline[data-part='item'][data-orientation='horizontal'] .xh-scope-timeline[data-part='connector'],
+    .xh-scope-timeline[data-part='item'][data-orientation='horizontal']:has(> .xh-scope-timeline[data-part='label']) > .xh-scope-timeline[data-part='connector'] {
+      grid-column: 2;
+      grid-row: 1;
+      align-self: center;
+      justify-self: stretch;
+      inline-size: auto;
+      min-inline-size: var(--xh-timeline-connector-min-length, var(--xh-space-4));
+      block-size: var(--xh-timeline-connector-thickness, var(--xh-stroke-thin));
+      min-block-size: 0;
+      margin-block-start: 0;
+      margin-inline: var(--xh-space-1_5) var(--xh-space-1);
+    }
+
+    .xh-scope-timeline[data-part='item'][data-orientation='horizontal'] .xh-scope-timeline[data-part='content'],
+    .xh-scope-timeline[data-part='item'][data-orientation='horizontal']:has(> .xh-scope-timeline[data-part='label']) > .xh-scope-timeline[data-part='content'] {
+      grid-column: 1 / -1;
+      grid-row: 2;
+      padding-block-start: var(--xh-timeline-content-pt, var(--xh-space-4));
+      padding-block-end: 0;
+      padding-inline-end: var(--xh-timeline-item-gap, var(--xh-_timeline-item-gap));
+    }
+
+    /* 末条的留白同样收掉：它后面已经没有要隔开的东西 */
+    .xh-scope-timeline[data-part='item'][data-orientation='horizontal']:last-child .xh-scope-timeline[data-part='content'] {
+      padding-inline-end: 0;
+    }
+
+    /* 宽档不给坐标单开轨道，它按流排在末尾；窄档那条轨道在这里收掉 */
+    .xh-scope-timeline[data-part='item'][data-orientation='horizontal']:has(> .xh-scope-timeline[data-part='label']) {
+      --xh-_timeline-label-col: auto;
+      --xh-_timeline-label-row: auto;
+
+      grid-template-columns: auto minmax(0, 1fr);
+    }
+
+    /* 横排的 start 是把内容挪到线的上方，内容贴着线的那一边对齐 */
+    .xh-scope-timeline[data-part='item'][data-orientation='horizontal'][data-placement='start'] {
+      grid-template-rows: minmax(0, 1fr) auto;
+    }
+
+    .xh-scope-timeline[data-part='item'][data-orientation='horizontal'][data-placement='start'] .xh-scope-timeline[data-part='indicator'],
+    .xh-scope-timeline[data-part='item'][data-orientation='horizontal'][data-placement='start'] .xh-scope-timeline[data-part='connector'] {
+      grid-row: 2;
+    }
+
+    .xh-scope-timeline[data-part='item'][data-orientation='horizontal'][data-placement='start'] .xh-scope-timeline[data-part='content'] {
+      grid-row: 1;
+      align-self: end;
+      padding-block-start: 0;
+      padding-block-end: var(--xh-timeline-content-pb, var(--xh-space-4));
+    }
+
+    .xh-scope-timeline[data-part='item'][data-orientation='horizontal'][data-placement='alternate'] {
+      grid-template-rows: minmax(0, 1fr) auto minmax(0, 1fr);
+    }
+
+    .xh-scope-timeline[data-part='item'][data-orientation='horizontal'][data-placement='alternate'] .xh-scope-timeline[data-part='indicator'],
+    .xh-scope-timeline[data-part='item'][data-orientation='horizontal'][data-placement='alternate'] .xh-scope-timeline[data-part='connector'] {
+      grid-row: 2;
+    }
+
+    .xh-scope-timeline[data-part='item'][data-orientation='horizontal'][data-placement='alternate'] .xh-scope-timeline[data-part='content'] {
+      grid-row: 3;
+      align-self: start;
+    }
+
+    .xh-scope-timeline[data-part='item'][data-orientation='horizontal'][data-placement='alternate']:nth-child(even) .xh-scope-timeline[data-part='content'] {
+      grid-row: 1;
+      align-self: end;
+      padding-block-start: 0;
+      padding-block-end: var(--xh-timeline-content-pb, var(--xh-space-4));
+    }
+  }
+
+  /* —— 文字 —— */
+  /* 中间没有断点的长串——单号、路径、无空格的标识——在框内断开。
+     每条的宽度由内容的最小宽度定，断不开就会把整条轴顶出容器 */
+  .xh-scope-timeline:is([data-part='title'], [data-part='description'], [data-part='time'], [data-part='label']) {
+    overflow-wrap: anywhere;
+  }
+
+  .xh-scope-timeline[data-part='title'] {
+    color: var(--xh-timeline-title-fg, var(--xh-fg-default));
+    font-size: var(--xh-timeline-title-font-size, var(--xh-_timeline-title-font-size));
+    font-weight: var(--xh-timeline-title-font-weight, var(--xh-text-label-weight));
+    line-height: var(--xh-leading-normal);
+  }
+
+  .xh-scope-timeline[data-part='description'] {
+    color: var(--xh-timeline-description-fg, var(--xh-fg-muted));
+    font-size: var(--xh-timeline-description-font-size, var(--xh-text-secondary-size));
+    line-height: var(--xh-leading-normal);
+  }
+
+  .xh-scope-timeline[data-part='time'] {
+    color: var(--xh-timeline-time-fg, var(--xh-fg-subtle));
+    font-size: var(--xh-timeline-time-font-size, var(--xh-_timeline-caption-font-size));
+    /* 等宽数字：时刻里的 1 与 7 在比例字体里宽度不同，不定住会让整列时间左右抖一格 */
+    font-variant-numeric: tabular-nums;
+    line-height: var(--xh-leading-normal);
+  }
+
+  /*
+   * 打印：底色被丢掉，圆点与连线整个是底色画出来的，纸上这条轴的骨架就此不见，
+   * 只剩几段没有次序的文字。两处都改由描边承载：圆点成一个空心圈，
+   * 连线的两条边合起来就是那条线（线本身只有一个描边厚，两边各画一半正好填满）。
+   */
+  /* 强制色：圆点与连线都是底色画的，系统会把底色换成 Canvas，整条轴就此消失。
+     两处退出强制换色、直接写系统色；圆点里的序号字取 Canvas 压在 CanvasText 上 */
+  @media (forced-colors: active) {
+    .xh-scope-timeline[data-part='indicator'] {
+      forced-color-adjust: none;
+      background: CanvasText;
+      color: Canvas;
+    }
+
+    .xh-scope-timeline[data-part='connector'] {
+      forced-color-adjust: none;
+      background: CanvasText;
+    }
+  }
+
+  @media print {
+    .xh-scope-timeline[data-part='indicator'] {
+      border: var(--xh-stroke-thick) solid currentColor;
+    }
+
+    .xh-scope-timeline[data-part='connector'] {
+      border: var(--xh-stroke-thin) solid currentColor;
+    }
+  }
+}

package/dist/css/timer.css

@@ -0,0 +1,123 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 timer 样式。 */
+
+/* Timer 独立皮肤同时传递引入起停钮的动作控件配方；full bundle 递归去重。 */
+@import '../family/action-control.css';
+
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  .xh-scope-timer {
+    --xh-timer-skin: 1;
+  }
+
+  /* 三个尺寸档只换这两个私有槽，各部件从 root 继承它们，换档不必给每个部件各写一条选择器；
+     起停钮的档位由连接层直接投给家族，这里不再中转 */
+  .xh-scope-timer[data-part='root'] {
+    --xh-_timer-digit-size: var(--xh-text-heading-1-size);
+    --xh-_timer-gap: var(--xh-space-3);
+
+    display: inline-flex;
+    align-items: center;
+    gap: var(--xh-timer-gap, var(--xh-_timer-gap));
+    color: var(--xh-timer-fg, var(--xh-fg-default));
+  }
+
+  /* 上面声明了 display，会盖掉 UA 的 [hidden] 规则，收起态要在这里接回来 */
+  .xh-scope-timer[data-part='root'][hidden] {
+    display: none;
+  }
+
+  /* —— 尺寸 —— */
+  .xh-scope-timer[data-part='root'][data-size='sm'] {
+    --xh-_timer-digit-size: var(--xh-text-heading-2-size);
+    --xh-_timer-gap: var(--xh-space-2);
+  }
+
+  .xh-scope-timer[data-part='root'][data-size='lg'] {
+    --xh-_timer-digit-size: var(--xh-text-display-size);
+    --xh-_timer-gap: var(--xh-space-4);
+  }
+
+  /* —— 时间区 —— */
+  /* 等宽数字：逐位宽度一致，秒数换位时分隔符与后面的段都不会左右挪动。
+     direction 钉成 ltr：每段是一个独立的 flex 项，主轴方向跟着文字方向走，
+     不钉住的话 rtl 页面上时分秒会整体倒过来排——时间串的读序两个方向都一样。 */
+  .xh-scope-timer[data-part='display'] {
+    display: inline-flex;
+    align-items: baseline;
+    direction: ltr;
+    color: var(--xh-timer-display-fg, var(--xh-fg-default));
+    /* 嵌在一句话里或摆在别人的数值槽里时把 --xh-timer-digit-font-size 写成 inherit，
+       数字就跟着上下文的字号走，不再自带展示档字号 */
+    font-size: var(--xh-timer-digit-font-size, var(--xh-_timer-digit-size));
+    font-variant-numeric: tabular-nums;
+    font-weight: var(--xh-font-weight-semibold);
+    line-height: var(--xh-leading-tight);
+    /* 走到点那一刻前景退一档，这里让它淡过去而不是硬跳 */
+    transition: color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  .xh-scope-timer[data-part='display'][hidden] {
+    display: none;
+  }
+
+  /* 走完之后这串数字不再是活的信息，退一档；暂停在半路的仍是要盯着看的数，不退 */
+  .xh-scope-timer[data-part='display'][data-state='completed'] {
+    color: var(--xh-timer-completed-fg, var(--xh-fg-muted));
+  }
+
+  /* 数字段自己一个前景槽，与记号那个成对。
+     缺省是 inherit 而不是某个具体前景：时间区走完会整体退一档，
+     数字段照着继承下来才跟得上，写死取值就跟不动了 */
+  .xh-scope-timer[data-part='item'] {
+    color: var(--xh-timer-item-fg, inherit);
+  }
+
+  /* 记号只是排版，比数字弱一档、两侧留一点气口 */
+  .xh-scope-timer[data-part='separator'] {
+    padding-inline: var(--xh-timer-separator-px, var(--xh-space-0_5));
+    color: var(--xh-timer-separator-fg, var(--xh-fg-subtle));
+    font-weight: var(--xh-font-weight-regular);
+  }
+
+  /* —— 起停按钮 ——
+     带文案（或图标）的离散动作钮：盒几何、悬停 / 按下与 0.97 按压、粗指针热区、焦点环、禁用面全由
+     Action Control 的 text outline 档给（连接层按 size 投档，缺省 md 一个控件高），组件只映射既有使用者槽。
+     中性描边、透明底；白底承载 hover 100 → pressed 200，不抬升；焦点边由家族给，不随语气 */
+  .xh-scope-timer[data-part='control'] {
+    --xh-action-visual-size: var(--xh-timer-control-h, var(--xh-_action-profile-visual-size));
+    --xh-action-padding-inline: var(--xh-timer-control-px, var(--xh-_action-profile-padding-inline));
+    --xh-action-gap: var(--xh-timer-control-gap, var(--xh-_action-profile-gap));
+    --xh-action-radius: var(--xh-timer-control-radius, var(--xh-shape-control));
+    --xh-action-bg-rest: var(--xh-timer-control-bg, var(--xh-_action-variant-bg-rest));
+    --xh-action-bg-hover: var(--xh-timer-control-bg-hover, var(--xh-_action-variant-bg-hover));
+    --xh-action-bg-pressed: var(--xh-timer-control-bg-active, var(--xh-_action-variant-bg-pressed));
+    --xh-action-bg-disabled: var(--xh-timer-control-bg-disabled, var(--xh-_action-variant-bg-disabled));
+    --xh-action-fg-rest: var(--xh-timer-control-fg, var(--xh-_action-variant-fg-rest));
+    --xh-action-fg-hover: var(--xh-timer-control-fg, var(--xh-_action-variant-fg-hover));
+    --xh-action-fg-pressed: var(--xh-timer-control-fg, var(--xh-_action-variant-fg-pressed));
+    --xh-action-border-rest: var(--xh-timer-control-border, var(--xh-_action-variant-border-rest));
+    --xh-action-border-hover: var(--xh-timer-control-border-hover, var(--xh-_action-variant-border-hover));
+    --xh-action-border-pressed: var(--xh-timer-control-border-hover, var(--xh-_action-variant-border-pressed));
+    --xh-action-border-focus-visible: var(--xh-timer-control-border-focus, var(--xh-_action-variant-border-focus-visible));
+    --xh-action-border-disabled: var(--xh-timer-control-border-disabled, var(--xh-_action-variant-border-disabled));
+    --xh-action-highlight-rest: transparent;
+    --xh-action-shadow-rest: none;
+    --xh-action-shadow-hover: var(--xh-timer-control-shadow-hover, none);
+    --xh-action-shadow-pressed: var(--xh-timer-control-shadow-active, none);
+    --xh-action-font-size: var(--xh-text-label-size);
+    /* 作者塞进钮里的图标按档取字形尺寸，与文案同一把尺 */
+    --xh-icon-size: var(--xh-timer-icon-size, var(--xh-_action-profile-glyph-size));
+
+    font-weight: var(--xh-text-label-weight);
+  }
+
+  /* 家族那条 display 会把 UA 的 [hidden]{display:none} 盖掉，作者收起它时要的是这一条 */
+  .xh-scope-timer[data-part='control'][hidden] {
+    display: none;
+  }
+}

package/dist/css/timestamp.css

@@ -0,0 +1,34 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 timestamp 样式。 */
+
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  .xh-scope-timestamp {
+    --xh-timestamp-skin: 1;
+  }
+
+  .xh-scope-timestamp[data-part='root'] {
+    color: var(--xh-timestamp-fg, var(--xh-fg-default));
+    /* 等宽数字：秒数跳动时后面的字符不会左右挪 */
+    font-variant-numeric: tabular-nums;
+    /* 一个时间戳不该被拆到两行去 */
+    white-space: nowrap;
+    /* 时刻换成认不出的值时前景要换档，这里让它淡过去而不是硬跳 */
+    transition: color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  /* 相对说法是一句话不是一串数字，等宽数字反而把字距拉开 */
+  .xh-scope-timestamp[data-part='root'][data-relative] {
+    font-variant-numeric: normal;
+  }
+
+  /* 没给时刻、或给了认不出的时刻：这时显示的是作者写在节点里的兜底文案，退成弱前景 */
+  .xh-scope-timestamp[data-part='root'][data-state='empty'],
+  .xh-scope-timestamp[data-part='root'][data-state='invalid'] {
+    color: var(--xh-timestamp-placeholder-fg, var(--xh-fg-muted));
+  }
+}