@xihan-ui/styles 3.0.0 → 3.2.0

package/dist/css/signature-pad.css

@@ -0,0 +1,179 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 signature pad 样式。 */
+
+@import '../family/action-control.css';
+
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  .xh-scope-signature-pad {
+    --xh-signature-pad-skin: 1;
+  }
+
+  /* position 是给表单影子做定位基准的：那份输入被连接层内联写成绝对定位，
+     根上不留基准它就会贴到更外层的定位祖先上，原生校验提示跟着飘到页面别处。 */
+  .xh-scope-signature-pad[data-part='root'] {
+    position: relative;
+    display: flex;
+    flex-direction: column;
+    /* 画布到清空按钮与状态句的距离；标签到画布另有一档，见 label */
+    gap: var(--xh-signature-pad-gap, var(--xh-space-2));
+  }
+
+  /* 复合单字段的标签：14 / 500 / fg-default，不随档；贴画布 space-1——
+     容器的 gap 归画布之后的部件，标签在它之上补一段差值把距离收成目标值 */
+  .xh-scope-signature-pad[data-part='label'] {
+    margin-block-end: calc(
+      var(--xh-signature-pad-label-gap, var(--xh-space-1))
+      - var(--xh-signature-pad-gap, var(--xh-space-2))
+    );
+    color: var(--xh-signature-pad-label-fg, var(--xh-fg-default));
+    font-size: var(--xh-signature-pad-label-font-size, var(--xh-text-label-size));
+    font-weight: var(--xh-signature-pad-label-font-weight, var(--xh-text-label-weight));
+  }
+
+  .xh-scope-signature-pad[data-part='label'][data-disabled] {
+    color: var(--xh-signature-pad-label-fg-disabled, var(--xh-fg-subtle));
+  }
+
+  /* 画布是块状的写字区：宽度铺满外层，高度由宽高比决定。
+     控件行高那把尺量的是一行控件，一块要写字的面积用不上它。
+     touch-action 由连接层内联写死，触摸落笔才不会被页面滚动抢走。
+     外壳按字段规则自绘（登记的画布型字段例外：字段家族配方钉死控件行高，画布按宽高比撑高吃不下它）：
+     静息透明底 + border-control 描边 + control 圆角 + 无影 */
+  .xh-scope-signature-pad[data-part='control'] {
+    display: block;
+    inline-size: 100%;
+    aspect-ratio: var(--xh-signature-pad-aspect-ratio, 5 / 2);
+    border: var(--xh-stroke-thin) solid var(--xh-signature-pad-border, var(--xh-border-control));
+    border-radius: var(--xh-signature-pad-radius, var(--xh-shape-control));
+    background: var(--xh-signature-pad-bg, transparent);
+    cursor: crosshair;
+    /* 一划就会把画布连同旁边的文字一起刷成选中态 */
+    user-select: none;
+    /* 落笔、校验不过与禁用三档各换一次描边或底色，换的过程要看得出来 */
+    transition:
+      border-color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
+      background-color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  .xh-scope-signature-pad[data-part='control'][data-invalid] {
+    border-color: var(--xh-signature-pad-control-border-invalid, var(--xh-border-invalid));
+  }
+
+  /* 落笔期间把描边压深一档。border-strong 是装饰梯度里的一档，比 border-control 更淡，
+     用在这儿会让描边在落笔时反而变弱 */
+  .xh-scope-signature-pad[data-part='control'][data-drawing] {
+    border-color: var(--xh-signature-pad-border-drawing, var(--xh-border-control-hover));
+  }
+
+  /* 只读仍看得见签名，只是改不动：收掉手型，别暗示"在这儿能写"；
+     面按字段只读规则只换到淡底，描边不动 */
+  .xh-scope-signature-pad[data-part='control'][data-readonly]:not([data-disabled]) {
+    background: var(--xh-signature-pad-bg-readonly, var(--xh-bg-subtle));
+    cursor: default;
+  }
+
+  /* 字段禁用面：描边退到 border-default、底换淡底 */
+  .xh-scope-signature-pad[data-part='control'][data-disabled] {
+    border-color: var(--xh-signature-pad-border-disabled, var(--xh-border-default));
+    background: var(--xh-signature-pad-bg-disabled, var(--xh-bg-subtle));
+    cursor: not-allowed;
+  }
+
+  /* 基准线：位置由连接层按百分比给出，这里只管它长什么样。
+     它是"请在这条线上签"的功能性提示，不是装饰，颜色走控件描边那一档才看得见 */
+  .xh-scope-signature-pad[data-part='guide'] {
+    stroke: var(--xh-signature-pad-guide-stroke, var(--xh-border-control));
+    stroke-width: var(--xh-stroke-thin);
+    stroke-dasharray: 6 6;
+  }
+
+  /* 笔迹是一条填充路径（每一笔是它的一条子路径），不是描边：
+     粗细要随压感变，而 stroke-width 全线只有一个值 */
+  .xh-scope-signature-pad[data-part='path'] {
+    fill: var(--xh-signature-pad-ink, var(--xh-fg-default));
+    stroke: none;
+  }
+
+  /*
+   * 清空按钮是画布旁的独立文字按钮：盒型、sm 档几何、outline 四态面、0.97 按压与粗指针命中区由家族配方
+   * 按连接层投影的 data-xh-action-variant / -size 给出（缺省 outline，白底承载阶梯 100 → 200）。这里只把公开槽
+   * 桥接到矩阵之前（使用者槽 → 形态矩阵 → 家族缺省）与几何槽映射，矩阵各态无影（淡底与阴影互斥）。
+   */
+  .xh-scope-signature-pad[data-part='clear-trigger'] {
+    --xh-action-bg-rest: var(--xh-signature-pad-clear-bg, var(--xh-_action-variant-bg-rest));
+    --xh-action-bg-hover: var(--xh-signature-pad-clear-bg-hover, var(--xh-_action-variant-bg-hover));
+    --xh-action-bg-pressed: var(--xh-signature-pad-clear-bg-active, var(--xh-_action-variant-bg-pressed));
+    --xh-action-bg-focus-visible: var(--xh-signature-pad-clear-bg, var(--xh-_action-variant-bg-focus-visible));
+    --xh-action-bg-disabled: var(--xh-signature-pad-clear-bg-disabled, var(--xh-_action-variant-bg-disabled));
+    --xh-action-fg-rest: var(--xh-signature-pad-clear-fg, var(--xh-_action-variant-fg-rest));
+    --xh-action-fg-hover: var(--xh-signature-pad-clear-fg, var(--xh-_action-variant-fg-hover));
+    --xh-action-fg-pressed: var(--xh-signature-pad-clear-fg, var(--xh-_action-variant-fg-pressed));
+    --xh-action-fg-focus-visible: var(--xh-signature-pad-clear-fg, var(--xh-_action-variant-fg-focus-visible));
+    --xh-action-border-rest: var(--xh-signature-pad-clear-border, var(--xh-_action-variant-border-rest));
+    --xh-action-border-hover: var(--xh-signature-pad-clear-border-hover, var(--xh-_action-variant-border-hover));
+    --xh-action-border-pressed: var(--xh-signature-pad-clear-border-hover, var(--xh-_action-variant-border-pressed));
+    --xh-action-border-focus-visible: var(--xh-signature-pad-clear-border, var(--xh-_action-variant-border-focus-visible));
+    /* 矩阵各态无影：悬停不再抬影（raised 只给 Button），使用者槽仍可自行加 */
+    --xh-action-shadow-hover: var(--xh-signature-pad-clear-shadow-hover, none);
+    --xh-action-radius: var(--xh-signature-pad-clear-radius, var(--xh-shape-control));
+    --xh-action-visual-size: var(--xh-signature-pad-clear-h, var(--xh-_action-profile-visual-size));
+    --xh-action-padding-inline: var(--xh-signature-pad-clear-px, var(--xh-_action-profile-padding-inline));
+    --xh-action-gap: var(--xh-signature-pad-clear-gap, var(--xh-_action-profile-gap));
+    --xh-action-font-size: var(--xh-signature-pad-clear-font-size, var(--xh-_action-profile-font-size));
+    /* 作者塞进来的图标随档取字形尺（sm = 16px） */
+    --xh-icon-size: var(--xh-signature-pad-clear-icon-size, var(--xh-_action-profile-glyph-size));
+
+    /* 竖排容器里不铺满一行：按钮只占自己的宽 */
+    align-self: flex-start;
+  }
+
+  /* 空画布时按钮照常可按（收起它会让焦点掉回 body），只把静息前景压淡一档；悬停与按下仍回到默认前景 */
+  .xh-scope-signature-pad[data-part='clear-trigger'][data-empty] {
+    --xh-action-fg-rest: var(--xh-signature-pad-clear-fg-empty, var(--xh-fg-muted));
+  }
+
+  /*
+   * 撤销与重做按钮与清空按钮同一身份：盒型、sm 档几何、outline 四态面、0.97 按压与粗指针命中区全由家族配方给出。
+   * 没有可撤销或可重做的一步时连接层投影 data-disabled + aria-disabled，家族给置灰面，焦点仍留在钮上。
+   */
+  .xh-scope-signature-pad[data-part='undo-trigger'],
+  .xh-scope-signature-pad[data-part='redo-trigger'] {
+    /* 作者塞进来的图标随档取字形尺（sm = 16px） */
+    --xh-icon-size: var(--xh-_action-profile-glyph-size);
+
+    /* 竖排容器里不铺满一行：按钮只占自己的宽 */
+    align-self: flex-start;
+  }
+
+  /* 面是实心的，环色与面同族，画在面里就看不出来；环改取面自己的前景色 */
+  .xh-scope-signature-pad[data-part='clear-trigger'][data-xh-action-variant='solid']:focus-visible {
+    --xh-action-ring-color-focus-visible: currentColor;
+  }
+
+  /* 签没签的那句话是说明角色：13 / fg-muted / leading-normal。读屏靠它播报，看得见的人也用得上，因此不做视觉隐藏 */
+  .xh-scope-signature-pad[data-part='status'] {
+    color: var(--xh-signature-pad-status-fg, var(--xh-fg-muted));
+    font-size: var(--xh-signature-pad-status-font-size, var(--xh-text-secondary-size));
+    line-height: var(--xh-leading-normal);
+  }
+
+  /* 表单影子的视觉隐藏（绝对定位 + 1px + clip-path）连接层内联给全了，这里不重复也不覆盖，
+     只掐掉指针命中：那个 1px 的框压在画布上会截走本该落到画布上的落笔。 */
+  .xh-scope-signature-pad[data-part='hidden-input'] {
+    pointer-events: none;
+  }
+
+  /* display 会盖掉 UA 的 [hidden]{display:none}，凡是被赋了 display 的角色节点都要显式让位 */
+  .xh-scope-signature-pad[data-part='root'][hidden],
+  .xh-scope-signature-pad[data-part='control'][hidden],
+  .xh-scope-signature-pad[data-part='undo-trigger'][hidden],
+  .xh-scope-signature-pad[data-part='redo-trigger'][hidden],
+  .xh-scope-signature-pad[data-part='clear-trigger'][hidden] {
+    display: none;
+  }
+}

package/dist/css/skeleton.css

@@ -0,0 +1,161 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 skeleton 样式。 */
+
+/* 共享关键帧由 family/motion.css 提供，本皮肤 @import 它，单独引入仍成立。 */
+@import '../family/motion.css';
+
+@layer xihan.motion {
+  /* 呼吸档：整根条子在原色与禁用档之间来回淡。往返由 alternate 给，帧里只写一端 */
+  @keyframes xh-skeleton-pulse {
+    to {
+      opacity: var(--xh-state-disabled-opacity);
+    }
+  }
+}
+
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  .xh-scope-skeleton {
+    --xh-skeleton-skin: 1;
+  }
+
+  /* 骨架容器：竖着码放各根骨架条 */
+  .xh-scope-skeleton[data-part='root'] {
+    display: flex;
+    flex-direction: column;
+    gap: var(--xh-skeleton-gap, var(--xh-space-3));
+  }
+
+  /* 声明了 display 就盖掉了 UA 的 [hidden]{display:none}，补这条兜住加载结束后的收起态 */
+  .xh-scope-skeleton[data-part='root'][hidden] {
+    display: none;
+  }
+
+  /* 刚加载完：机器已把骨架原地抬出文档流、钉住原来的尺寸，真实内容补上它空出来的位置；
+     骨架盖在内容之上淡出，播完才收起，不挡内容的指针。挂载时就已加载完的直接收起，不播这一段 */
+  .xh-scope-skeleton[data-part='root'][data-state='loaded']:not([hidden]) {
+    pointer-events: none;
+    animation: xh-fade-out var(--xh-motion-duration-exit) var(--xh-motion-ease-exit) forwards;
+  }
+
+  /*
+   * 单根骨架条。底色与微光两层叠在一起：
+   * background-color 是静止时看到的那层，background-image 是扫过去的那道光。
+   * 微光取比底亮一档的那支面色：浅色下比 bg-subtle 亮、深色下同样比它亮，
+   * 两个主题里扫过去的都是一道亮带，而不是浅色下反倒扫出一道暗带。
+   */
+  .xh-scope-skeleton[data-part='item'] {
+    inline-size: 100%;
+    pointer-events: none;
+    border-radius: var(--xh-skeleton-radius, var(--xh-shape-control));
+    background-color: var(--xh-skeleton-bg, var(--xh-bg-subtle));
+    background-image: linear-gradient(
+      90deg,
+      transparent 20%,
+      var(--xh-skeleton-sheen, var(--xh-bg-surface-raised)) 50%,
+      transparent 80%
+    );
+    background-repeat: no-repeat;
+    background-size: 200% 100%;
+    /* 扫光与思考中文字、工具调用进行中同一段共享关键帧：同屏时亮带扫过的距离与节奏一致 */
+    animation: xh-shimmer var(--xh-skeleton-duration, var(--xh-motion-loop-shimmer)) var(--xh-motion-ease-loop) infinite;
+  }
+
+  /* 一行文字的高度取正文字号，圆角拉满，看起来就是一行还没排出来的字 */
+  .xh-scope-skeleton[data-part='item'][data-shape='text'] {
+    block-size: var(--xh-skeleton-text-block-size, var(--xh-text-caption-size));
+    border-radius: var(--xh-skeleton-text-radius, var(--xh-shape-pill));
+  }
+
+  /* 头像位：正方形加满圆角。宽度定死不跟着容器拉长，高度也不许被主轴压扁 */
+  .xh-scope-skeleton[data-part='item'][data-shape='circle'] {
+    flex: none;
+    inline-size: var(--xh-skeleton-circle-size, var(--xh-control-h-lg));
+    aspect-ratio: 1;
+    border-radius: var(--xh-skeleton-circle-radius, var(--xh-shape-circle));
+  }
+
+  /* 图片、卡片这类成块的占位：给个最小高度，撑开由作者决定 */
+  .xh-scope-skeleton[data-part='item'][data-shape='rect'] {
+    min-block-size: var(--xh-skeleton-rect-block-size, var(--xh-control-h-lg));
+    border-radius: var(--xh-skeleton-rect-radius, var(--xh-shape-surface));
+  }
+
+  /*
+   * 呼吸档：撤掉微光那层，整根条子在原色与禁用档之间来回淡。
+   * 微光扫的是一道亮带，呼吸改的是整根的浓淡——两者都表达"还在等"，
+   * 换哪一档由作者定，缺省仍是微光。
+   */
+  .xh-scope-skeleton[data-part='root'][data-animation='pulse'] [data-part='item']:where(.xh-scope-skeleton) {
+    background-image: none;
+    animation: xh-skeleton-pulse var(--xh-skeleton-pulse-duration, var(--xh-motion-loop-shimmer)) var(--xh-motion-ease-sweep) infinite alternate;
+  }
+
+  /* 静止档：底色留着，两层动效都撤掉 */
+  .xh-scope-skeleton[data-part='root'][data-animation='none'] [data-part='item']:where(.xh-scope-skeleton) {
+    background-image: none;
+    animation: none;
+  }
+
+  /* 呼吸档自带一条动画，压不住下面基础降级里的 animation: none，这一档各自再写一份。
+     两组规则是同一件事的两个触发条件：系统偏好与作者打的 data-motion */
+  @media (prefers-reduced-motion: reduce) {
+    .xh-scope-skeleton[data-part='root'][data-animation='pulse'] [data-part='item']:where(.xh-scope-skeleton) {
+      animation: none;
+    }
+  }
+
+  :where([data-motion='reduce']) .xh-scope-skeleton[data-part='root'][data-animation='pulse'] [data-part='item']:where(.xh-scope-skeleton) {
+    animation: none;
+  }
+
+  @media print {
+    .xh-scope-skeleton[data-part='root'][data-animation='pulse'] [data-part='item']:where(.xh-scope-skeleton) {
+      animation: none;
+    }
+  }
+
+  /*
+   * 减少动效：撤掉微光那层，只留静态底色。
+   * 骨架屏是自己冒出来、会一直循环到数据回来为止的动效，正是最容易引发不适的那一类；
+   * 这里不能只把时长压到接近零——那样光带会停在某一帧上，留下一道说不清的渐变。
+   * 两条规则是同一件事的两个触发条件：系统偏好与作者打的 data-motion。
+   */
+  @media (prefers-reduced-motion: reduce) {
+    .xh-scope-skeleton[data-part='item'] {
+      background-image: none;
+      animation: none;
+    }
+  }
+
+  :where([data-motion='reduce']) .xh-scope-skeleton[data-part='item'] {
+    background-image: none;
+    animation: none;
+  }
+
+  @media print {
+    /* 打印：动画会被定格在任意一帧——转了一半的圈、扫到一半的微光。这里换成静止的表达，
+       取值与减弱动效那一档相同。两档各写一块、不并进一条媒体查询列表：减弱动效另有一份
+       :where([data-motion='reduce']) 的钩子版本与它成对，打印没有对应的钩子可配，
+       并成一条之后这层配对关系在文本上就断了。 */
+    .xh-scope-skeleton[data-part='item'] {
+      background-image: none;
+      animation: none;
+    }
+  }
+
+  /*
+   * 高对比档：骨架条整根靠底色画出来，这一档里底色与微光一起被系统换掉，
+   * 一块什么都没有的空白——正在加载这件事没有了任何表达。改成描一圈边把条子勾出来。
+   */
+  @media (forced-colors: active) {
+    .xh-scope-skeleton[data-part='item'] {
+      border: var(--xh-stroke-thin) solid GrayText;
+      background-image: none;
+    }
+  }
+}