@zhang_jifan/fanui 2.1.0

package/src/components/_capabilities.scss

@@ -0,0 +1,463 @@
+// =============================================================================
+// fanUI · 能力补齐组件（Capabilities）
+// -----------------------------------------------------------------------------
+// 补齐主流 UI 库普遍具备、此前缺失的 7 项能力：
+//   .fanui-virtual-list   虚拟滚动列表（JS: FanUI.virtualList）
+//   .fanui-lightbox       图片预览 / 灯箱（JS: FanUI.lightbox）
+//   .fanui-watermark      水印（JS: FanUI.watermark）
+//   .fanui-tour           引导 Tour（JS: FanUI.tour）
+//   .fanui-splitter       可拖拽分割面板（JS: FanUI.splitter）
+//   .fanui-affix          吸顶容器（JS: FanUI.affix）
+//   .fanui-backtop        回到顶部（JS: FanUI.backTop）
+//
+// 约定：
+//   · 全部行内轴属性使用**逻辑属性**（inline-start/end），[dir="rtl"] 自动镜像；
+//   · 所有动效在 prefers-reduced-motion: reduce 下降级为「无过渡」；
+//   · 交互组件保留原生键盘可达性（role / tabindex / aria-*）。
+// =============================================================================
+
+@use "../functions" as fn;
+@use "../variables" as v;
+@use "../mixins" as mx;
+
+// -----------------------------------------------------------------------------
+// 1. 虚拟滚动列表 virtual-list
+//    结构：容器（滚动） > __inner（撑满总高） > __item（绝对定位 + translateY）
+// -----------------------------------------------------------------------------
+
+.fanui-virtual-list {
+  position: relative;
+  overflow: auto;
+  overscroll-behavior: contain;
+  height: fn.fanui-var("vl-height", 320px);
+  max-height: 100%;
+  border: 1px solid fn.fanui-var("color-border");
+  border-radius: fn.fanui-var("radius-md");
+  background-color: fn.fanui-var("color-surface");
+  contain: strict;
+
+  &__inner { position: relative; width: 100%; }
+
+  &__item {
+    position: absolute;
+    inset-inline: 0;
+    top: 0;
+    display: flex;
+    align-items: center;
+    gap: fn.fanui-var("space-3");
+    padding: fn.fanui-var("space-2") fn.fanui-var("space-4");
+    box-sizing: border-box;
+    border-bottom: 1px solid fn.fanui-var("color-border-subtle");
+    color: fn.fanui-var("color-text");
+    will-change: transform;
+
+    &:hover { background-color: fn.fanui-var("color-surface-raised"); }
+    &.is-selected {
+      background-color: fn.fanui-var("primary-soft");
+      color: fn.fanui-var("primary-ink");
+      font-weight: 600;
+    }
+  }
+
+  // 原始数据源：**默认可见**，作为「SSR 直出 / 未启用 JS」时的可读降级；
+  // JS 接管（容器被加上 .is-virtualized）后才隐藏，改由 __inner 承担渲染。
+  // ⚠️ 不要写成无条件的 display:none —— 那会让服务端直出的行全部不可见，
+  //    与本组件「渐进增强」的设计意图相反。
+  &__source { display: block; }
+  &.is-virtualized &__source { display: none; }
+
+  &__empty {
+    display: grid;
+    place-items: center;
+    height: 100%;
+    color: fn.fanui-var("color-text-muted");
+  }
+
+  // 首屏未启用 JS 的降级：正常流式展示（SSR 直出即可读，不再锁死 320px 高 + 滚动容器）
+  &:not(.is-virtualized) {
+    height: auto;
+    max-height: none;
+    contain: none;
+  }
+  &:not(.is-virtualized) &__inner { height: auto; }
+  &:not(.is-virtualized) &__item { position: static; transform: none; }
+}
+
+// -----------------------------------------------------------------------------
+// 2. 图片预览 / 灯箱 lightbox
+// -----------------------------------------------------------------------------
+
+.fanui-lightbox {
+  position: fixed;
+  inset: 0;
+  z-index: fn.fanui-var("z-modal", v.$fanui-zindex-modal);
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+
+  &__backdrop {
+    position: absolute;
+    inset: 0;
+    background-color: fn.fanui-var("lb-backdrop", rgba(2, 6, 23, 0.88));
+    backdrop-filter: blur(6px);
+    animation: fanui-fade-in fn.fanui-var("duration-base") fn.fanui-var("ease-out") both;
+  }
+
+  &__stage {
+    position: relative;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 100%;
+    height: 100%;
+    overflow: hidden;
+    touch-action: none;
+  }
+
+  &__img {
+    max-width: 92vw;
+    max-height: 84vh;
+    border-radius: fn.fanui-var("radius-lg");
+    box-shadow: fn.fanui-var("shadow-2xl");
+    cursor: grab;
+    user-select: none;
+    transition: transform fn.fanui-var("duration-base") fn.fanui-var("ease-out");
+    animation: fanui-lightbox-in fn.fanui-var("duration-slow") fn.fanui-var("ease-spring") both;
+
+    &.is-dragging { cursor: grabbing; transition: none; }
+  }
+
+  &__caption {
+    position: absolute;
+    inset-inline: 0;
+    bottom: fn.fanui-var("space-5");
+    text-align: center;
+    font-size: fn.fanui-var("font-size-sm");
+    color: rgba(255, 255, 255, 0.82);
+    pointer-events: none;
+  }
+
+  &__counter {
+    position: absolute;
+    top: fn.fanui-var("space-5");
+    inset-inline-start: fn.fanui-var("space-5");
+    padding: 2px fn.fanui-var("space-3");
+    border-radius: fn.fanui-var("radius-full");
+    background-color: rgba(255, 255, 255, 0.14);
+    color: #ffffff;
+    font-size: fn.fanui-var("font-size-xs");
+    font-variant-numeric: tabular-nums;
+  }
+
+  &__toolbar {
+    position: absolute;
+    top: fn.fanui-var("space-4");
+    inset-inline-end: fn.fanui-var("space-4");
+    display: flex;
+    gap: fn.fanui-var("space-2");
+    z-index: 2;
+  }
+
+  &__btn {
+    display: grid;
+    place-items: center;
+    width: 36px;
+    height: 36px;
+    padding: 0;
+    border: 1px solid rgba(255, 255, 255, 0.18);
+    border-radius: fn.fanui-var("radius-md");
+    background-color: rgba(255, 255, 255, 0.1);
+    color: #ffffff;
+    font-size: 15px;
+    line-height: 1;
+    cursor: pointer;
+    @include mx.fanui-transition((background-color, border-color, transform), v.$fanui-duration-fast, v.$fanui-ease-out);
+
+    &:hover { background-color: rgba(255, 255, 255, 0.2); }
+    &:active { transform: scale(0.94); }
+    &:focus-visible { outline: 2px solid #ffffff; outline-offset: 2px; }
+  }
+
+  &__nav {
+    position: absolute;
+    top: 50%;
+    transform: translateY(-50%);
+    z-index: 2;
+
+    &--prev { inset-inline-start: fn.fanui-var("space-4"); }
+    &--next { inset-inline-end: fn.fanui-var("space-4"); }
+  }
+
+  &__thumbstrip {
+    position: absolute;
+    bottom: fn.fanui-var("space-4");
+    display: flex;
+    gap: fn.fanui-var("space-2");
+    max-width: 90vw;
+    padding: fn.fanui-var("space-2");
+    overflow-x: auto;
+    border-radius: fn.fanui-var("radius-md");
+    background-color: rgba(255, 255, 255, 0.08);
+
+    img {
+      width: 48px;
+      height: 48px;
+      object-fit: cover;
+      border-radius: fn.fanui-var("radius-base");
+      opacity: 0.55;
+      cursor: pointer;
+      &.is-active { opacity: 1; outline: 2px solid #ffffff; }
+    }
+  }
+
+  // 触发器：任意带 data-fanui-lightbox 的元素
+  &-trigger { cursor: zoom-in; }
+}
+
+@keyframes fanui-lightbox-in {
+  from { opacity: 0; transform: scale(0.94); }
+  to   { opacity: 1; transform: scale(1); }
+}
+
+// -----------------------------------------------------------------------------
+// 3. 水印 watermark
+// -----------------------------------------------------------------------------
+
+.fanui-watermark {
+  position: absolute;
+  inset: 0;
+  z-index: fn.fanui-var("wm-z", 1);
+  pointer-events: none;
+  background-repeat: repeat;
+  background-position: 0 0;
+
+  &__host { position: relative; }
+}
+
+// -----------------------------------------------------------------------------
+// 4. 引导 Tour
+// -----------------------------------------------------------------------------
+
+.fanui-tour {
+  position: fixed;
+  inset: 0;
+  z-index: fn.fanui-var("z-modal", v.$fanui-zindex-modal);
+
+  &__mask {
+    position: absolute;
+    inset: 0;
+    background-color: fn.fanui-var("tour-mask", rgba(2, 6, 23, 0.62));
+    animation: fanui-fade-in fn.fanui-var("duration-base") fn.fanui-var("ease-out") both;
+  }
+
+  // 聚光灯：靠 4 个方向遮罩或 box-shadow 挖孔，这里用 box-shadow 挖孔（性能更好）
+  &__spotlight {
+    position: absolute;
+    border-radius: fn.fanui-var("radius-md");
+    box-shadow: 0 0 0 9999px fn.fanui-var("tour-mask", rgba(2, 6, 23, 0.62));
+    transition: all fn.fanui-var("duration-base") fn.fanui-var("ease-out");
+    pointer-events: none;
+  }
+
+  &__popover {
+    position: absolute;
+    width: min(92vw, 340px);
+    padding: fn.fanui-var("space-5");
+    border: 1px solid fn.fanui-var("color-border");
+    border-radius: fn.fanui-var("radius-lg");
+    background-color: fn.fanui-var("color-surface");
+    box-shadow: fn.fanui-var("shadow-xl");
+    color: fn.fanui-var("color-text");
+    animation: fanui-tour-in fn.fanui-var("duration-base") fn.fanui-var("ease-spring") both;
+    z-index: 1;
+  }
+
+  &__arrow {
+    position: absolute;
+    width: 10px;
+    height: 10px;
+    background-color: fn.fanui-var("color-surface");
+    border: 1px solid fn.fanui-var("color-border");
+    transform: rotate(45deg);
+  }
+
+  &__head { display: flex; align-items: flex-start; gap: fn.fanui-var("space-3"); }
+  &__title { flex: 1 1 auto; margin: 0; font-size: fn.fanui-var("font-size-lg"); font-weight: 700; color: fn.fanui-var("color-text-strong"); }
+  &__desc { margin: fn.fanui-var("space-2") 0 0; font-size: fn.fanui-var("font-size-sm"); color: fn.fanui-var("color-text-muted"); line-height: 1.7; }
+
+  &__close {
+    flex: 0 0 auto;
+    width: 26px;
+    height: 26px;
+    padding: 0;
+    border: 0;
+    border-radius: fn.fanui-var("radius-base");
+    background: transparent;
+    color: fn.fanui-var("color-text-muted");
+    cursor: pointer;
+    &:hover { background-color: fn.fanui-var("color-surface-raised"); color: fn.fanui-var("color-text"); }
+  }
+
+  &__footer {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: fn.fanui-var("space-3");
+    margin-top: fn.fanui-var("space-4");
+  }
+
+  &__dots { display: flex; gap: 6px; align-items: center; }
+
+  &__dot {
+    width: 7px;
+    height: 7px;
+    padding: 0;
+    border: 0;
+    border-radius: 50%;
+    background-color: fn.fanui-var("color-border-strong");
+    cursor: pointer;
+    &.is-active { width: 18px; border-radius: fn.fanui-var("radius-full"); background-color: fn.fanui-var("primary"); }
+  }
+
+  &__actions { display: flex; gap: fn.fanui-var("space-2"); margin-inline-start: auto; }
+}
+
+@keyframes fanui-tour-in {
+  from { opacity: 0; transform: translateY(6px) scale(0.97); }
+  to   { opacity: 1; transform: translateY(0) scale(1); }
+}
+
+// -----------------------------------------------------------------------------
+// 5. 分割面板 splitter
+// -----------------------------------------------------------------------------
+
+.fanui-splitter {
+  display: flex;
+  width: 100%;
+  min-height: 120px;
+  overflow: hidden;
+  border: 1px solid fn.fanui-var("color-border");
+  border-radius: fn.fanui-var("radius-md");
+  background-color: fn.fanui-var("color-surface");
+
+  &--vertical { flex-direction: column; }
+
+  &__pane {
+    min-width: 0;
+    min-height: 0;
+    overflow: auto;
+    padding: fn.fanui-var("space-4");
+    box-sizing: border-box;
+    flex: 0 0 var(--fanui-splitter-size, 50%);
+  }
+
+  &__bar {
+    position: relative;
+    flex: 0 0 auto;
+    display: grid;
+    place-items: center;
+    background-color: fn.fanui-var("color-border");
+    cursor: col-resize;
+    @include mx.fanui-transition((background-color), v.$fanui-duration-fast, v.$fanui-ease-out);
+
+    // 纵向分割时改为行方向拖动
+    .fanui-splitter--vertical & { cursor: row-resize; }
+
+    &:hover,
+    &.is-active { background-color: fn.fanui-var("primary"); }
+
+    &:focus-visible { outline: 2px solid fn.fanui-var("primary"); outline-offset: 2px; }
+  }
+
+  &__bar-handle {
+    width: 3px;
+    height: 28px;
+    border-radius: fn.fanui-var("radius-full");
+    background-color: fn.fanui-var("color-text-subtle");
+    opacity: 0.55;
+
+    .fanui-splitter--vertical & { width: 28px; height: 3px; }
+  }
+
+  // 拖动中的全局保护：避免选中文本与 pointer 丢失
+  &.is-resizing { user-select: none; cursor: col-resize; }
+  &.is-resizing.fanui-splitter--vertical { cursor: row-resize; }
+}
+
+// -----------------------------------------------------------------------------
+// 6. 吸顶 affix
+// -----------------------------------------------------------------------------
+
+.fanui-affix {
+  // 占位块：吸顶期间撑住原位置，避免页面跳动
+  &__placeholder { display: block; }
+
+  // 被吸顶的目标元素（JS 会加上 .fanui-affix__inner 与 .is-affixed）
+  &__inner.is-affixed {
+    position: fixed;
+    z-index: fn.fanui-var("z-sticky", v.$fanui-zindex-sticky);
+    inset-inline: 0;
+    background-color: fn.fanui-var("color-surface");
+    box-shadow: fn.fanui-var("shadow-sm");
+
+    &.is-affixed-bottom { position: absolute; top: auto; }
+  }
+}
+
+// -----------------------------------------------------------------------------
+// 7. 回到顶部 backtop
+// -----------------------------------------------------------------------------
+
+.fanui-backtop {
+  position: fixed;
+  inset-inline-end: fn.fanui-var("space-5");
+  bottom: fn.fanui-var("space-5");
+  z-index: fn.fanui-var("z-fixed", v.$fanui-zindex-fixed);
+  display: grid;
+  place-items: center;
+  width: 44px;
+  height: 44px;
+  padding: 0;
+  border: 1px solid fn.fanui-var("color-border");
+  border-radius: 50%;
+  background-color: fn.fanui-var("color-surface");
+  color: fn.fanui-var("color-text");
+  box-shadow: fn.fanui-var("shadow-lg");
+  cursor: pointer;
+  opacity: 0;
+  visibility: hidden;
+  transform: translateY(8px);
+  @include mx.fanui-transition((opacity, visibility, transform, background-color), v.$fanui-duration-base, v.$fanui-ease-out);
+
+  &.is-visible { opacity: 1; visibility: visible; transform: translateY(0); }
+  &:hover { background-color: fn.fanui-var("primary"); color: fn.fanui-var("primary-fg"); border-color: transparent; }
+  &:focus-visible { outline: 2px solid fn.fanui-var("primary"); outline-offset: 2px; }
+
+  &__ring {
+    position: absolute;
+    inset: -3px;
+    border-radius: 50%;
+    background: conic-gradient(fn.fanui-var("primary") var(--fanui-backtop-progress, 0%), transparent 0);
+    mask: radial-gradient(farthest-side, transparent calc(100% - 3px), #000 0);
+    pointer-events: none;
+  }
+
+  &__icon { position: relative; font-size: 16px; line-height: 1; }
+}
+
+// -----------------------------------------------------------------------------
+// 8. 降级：减少动效
+// -----------------------------------------------------------------------------
+
+@media (prefers-reduced-motion: reduce) {
+  .fanui-lightbox__img,
+  .fanui-lightbox__backdrop,
+  .fanui-tour__mask,
+  .fanui-tour__popover,
+  .fanui-tour__spotlight,
+  .fanui-backtop {
+    animation: none !important;
+    transition: none !important;
+  }
+}