@chenzy-design/svelte 0.1.0

package/src/back-top/BackTop.a11y.test.ts

@@ -0,0 +1,40 @@
+// BackTop a11y：回到顶部悬浮按钮。
+//  - button[type=button] 带可访问名（ariaLabel 或 locale BackTop.ariaLabel）。
+//  - announceOnArrive 时渲染视觉隐藏的 role=status / aria-live=polite live region。
+// jsdom 只断言静态 ARIA + axe（scroll 显隐 / 回顶动画留给真实浏览器）。
+import { describe, it, expect } from 'vitest';
+import { renderWithLocale, expectNoAxeViolations } from '../test-utils/a11y.js';
+import BackTop from './BackTop.svelte';
+
+describe('BackTop a11y', () => {
+  it('默认渲染：button 有 locale 可访问名，无 axe violations', async () => {
+    const { container } = renderWithLocale(BackTop, {});
+    const btn = container.querySelector('button.cd-backtop');
+    expect(btn).not.toBeNull();
+    expect(btn?.getAttribute('type')).toBe('button');
+    // 缺省走 locale，应为非空可访问名（不是 key 原样）。
+    const label = btn?.getAttribute('aria-label');
+    expect(label).toBeTruthy();
+    expect(label).not.toBe('BackTop.ariaLabel');
+    await expectNoAxeViolations(container);
+  });
+
+  it('自定义 ariaLabel 覆盖可访问名', async () => {
+    const { container } = renderWithLocale(BackTop, {
+      props: { ariaLabel: 'Scroll to top' },
+    });
+    const btn = container.querySelector('button.cd-backtop');
+    expect(btn?.getAttribute('aria-label')).toBe('Scroll to top');
+    await expectNoAxeViolations(container);
+  });
+
+  it('announceOnArrive：渲染 role=status / aria-live=polite live region', async () => {
+    const { container } = renderWithLocale(BackTop, {
+      props: { announceOnArrive: true },
+    });
+    const live = container.querySelector('.cd-sr-only');
+    expect(live?.getAttribute('role')).toBe('status');
+    expect(live?.getAttribute('aria-live')).toBe('polite');
+    await expectNoAxeViolations(container);
+  });
+});

package/src/back-top/BackTop.svelte

@@ -0,0 +1,314 @@
+<!--
+  BackTop — 回到顶部悬浮按钮。
+  支持：自定义 target 滚动容器 / window + 阈值显隐 + 受控 visible + 平滑缓动回顶
+        + announceOnArrive 到顶播报 + 三尺寸。
+
+  ⚠️ 死循环红线：
+    - 滚动监听用 $effect 内命令式 addEventListener('scroll', ..., {passive:true})
+      + rAF 节流，cleanup 时 removeEventListener + cancelAnimationFrame；target 变化时重绑。
+    - autoVisible 仅在 scroll 回调（非 render 期）写入本地 $state。
+    - render 期只读派生的 visible（受控值或 autoVisible），绝不读 scrollTop 几何。
+    - 受控 visible：仅读 prop + 触发 onVisibleChange 回调，绝不回写。
+    - 回顶动画亦为命令式 rAF 循环；卸载时在 $effect cleanup 中 cancel。
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import { isAboveThreshold, scrollPositionAt } from '@chenzy-design/core';
+  import { useLocale } from '../locale-provider/index.js';
+
+  type Size = 'small' | 'default' | 'large';
+
+  interface Props {
+    /**
+     * 监听并回顶的滚动容器。返回 HTMLElement | CSS 选择器字符串 | null。
+     * 不传或返回 null/window 时监听 window（默认行为，向后兼容）。
+     */
+    target?: () => HTMLElement | string | Window | null;
+    /**
+     * 受控显隐：传入时由外部决定按钮显隐（内部阈值判定仅用于触发 onVisibleChange）；
+     * 不传则内部按 visibilityHeight 阈值自动显隐。
+     */
+    visible?: boolean;
+    /** 回到顶部后用 ARIA live region 播报（文案经 locale BackTop.arrived）。 */
+    announceOnArrive?: boolean;
+    /** 滚动超过此高度(px)显示按钮 */
+    visibilityHeight?: number;
+    /** 回顶动画时长(ms)，0 表示瞬时 */
+    duration?: number;
+    /** 距底偏移，number → px */
+    bottom?: number | string;
+    /** 距 inline-end 偏移，number → px */
+    right?: number | string;
+    size?: Size;
+    ariaLabel?: string;
+    /** 替换图标（保留圆形按钮外壳） */
+    icon?: Snippet<[{ size: Size }]>;
+    /** 完全自定义按钮内容 */
+    children?: Snippet<[{ visible: boolean }]>;
+    onClick?: (e: MouseEvent) => void;
+    onVisibleChange?: (info: { visible: boolean }) => void;
+    onScrollEnd?: () => void;
+    class?: string;
+  }
+
+  let {
+    target,
+    visible: controlledVisible,
+    announceOnArrive = false,
+    visibilityHeight = 400,
+    duration = 450,
+    bottom = 40,
+    right = 40,
+    size = 'default',
+    ariaLabel,
+    icon,
+    children,
+    onClick,
+    onVisibleChange,
+    onScrollEnd,
+    class: className = '',
+  }: Props = $props();
+
+  const loc = useLocale();
+
+  // 本地响应式状态：仅由命令式 scroll 回调写入，render 期只读（非受控时驱动显隐）。
+  let autoVisible = $state(false);
+
+  // 派生显隐（红线 #2 纯函数）：受控时取 prop，否则取内部阈值态。render 期只读。
+  const visible = $derived(controlledVisible ?? autoVisible);
+
+  // 到顶播报文案（live region 命令式写入，初始为空）。
+  let announceText = $state('');
+
+  // 偏移样式：number → px。
+  const bottomPx = $derived(typeof bottom === 'number' ? `${bottom}px` : bottom);
+  const rightPx = $derived(typeof right === 'number' ? `${right}px` : right);
+
+  /**
+   * 把 target 原始返回值规整为「滚动元素 | window」。null 视为 window；
+   * 选择器字符串经 querySelector 解析，解析失败回退 window。
+   */
+  function normalizeScroller(raw: HTMLElement | string | Window | null | undefined): HTMLElement | Window {
+    if (raw == null || raw === window) return window;
+    if (typeof raw === 'string') {
+      if (typeof document === 'undefined') return window;
+      return (document.querySelector<HTMLElement>(raw)) ?? window;
+    }
+    return raw;
+  }
+
+  /**
+   * 响应式解析的滚动容器：在 $derived 内调用 target?.()，使其依赖被追踪——
+   * target 通常 `() => someBoundEl`，bind:this 在挂载后才赋值，借此让监听 $effect
+   * 在元素就绪后重新求值并重绑（红线 #3）。无 target 时恒为 window。
+   */
+  const scroller = $derived(normalizeScroller(target?.()));
+
+  /** scrollToTop 等命令式路径用：即时解析（不依赖响应式快照）。 */
+  function resolveScroller(): HTMLElement | Window {
+    return normalizeScroller(target?.());
+  }
+
+  /** 读取某滚动容器当前 scrollTop（window 走 scrollY）。命令式，仅回调期调用。 */
+  function getScrollTop(scroller: HTMLElement | Window): number {
+    return scroller === window ? window.scrollY : (scroller as HTMLElement).scrollTop;
+  }
+
+  // 减弱动效偏好（命令式读取，仅 client）。
+  const reduced =
+    typeof window !== 'undefined' &&
+    window.matchMedia?.('(prefers-reduced-motion: reduce)').matches === true;
+
+  // 滚动监听（命令式 + rAF 节流 + cleanup）。$effect 仅 client 运行，SSR 安全。
+  // 依赖 scroller（含 target 求值）/ visibilityHeight：变化时 cleanup 旧绑定并重绑（红线 #3）。
+  $effect(() => {
+    const node = scroller; // 响应式：容器(或 window)变化时重绑
+    const threshold = visibilityHeight; // 追踪阈值
+    let rafId = 0;
+
+    function onScroll() {
+      if (rafId) return; // rAF 节流
+      rafId = requestAnimationFrame(() => {
+        rafId = 0;
+        // scrollTop 读取发生在回调中（非 render 期）。
+        const top = getScrollTop(node);
+        const next = isAboveThreshold(top, threshold);
+        // 内部阈值态：受控时不驱动 render，但仍维护以触发 onVisibleChange。
+        if (next !== autoVisible) {
+          autoVisible = next;
+          onVisibleChange?.({ visible: next });
+        }
+      });
+    }
+
+    node.addEventListener('scroll', onScroll, { passive: true });
+    onScroll(); // 初始判定一次
+    return () => {
+      node.removeEventListener('scroll', onScroll);
+      if (rafId) cancelAnimationFrame(rafId);
+    };
+  });
+
+  // 回顶动画的 rAF 句柄（组件级，供卸载 cleanup 取消）。
+  let scrollRaf = 0;
+
+  $effect(() => {
+    // 仅注册卸载时取消未完成的回顶动画。
+    return () => {
+      if (scrollRaf) cancelAnimationFrame(scrollRaf);
+    };
+  });
+
+  /** 把容器/window 滚到指定 y（命令式）。 */
+  function scrollToY(scroller: HTMLElement | Window, y: number) {
+    if (scroller === window) window.scrollTo(0, y);
+    else (scroller as HTMLElement).scrollTop = y;
+  }
+
+  /** 到顶后写入 live region 播报（announceOnArrive 开启时）。先清空确保重复可重播。 */
+  function announceArrived() {
+    if (!announceOnArrive) return;
+    announceText = '';
+    // 微任务后再写入，确保 DOM 先清空再赋值，触发 AT 重新播报。
+    queueMicrotask(() => {
+      announceText = loc().t('BackTop.arrived');
+    });
+  }
+
+  function finishScroll() {
+    scrollRaf = 0;
+    onScrollEnd?.();
+    announceArrived();
+  }
+
+  function scrollToTop(e: MouseEvent) {
+    onClick?.(e);
+    const scroller = resolveScroller();
+    const from = getScrollTop(scroller);
+    if (duration <= 0 || reduced) {
+      scrollToY(scroller, 0);
+      finishScroll();
+      return;
+    }
+    if (scrollRaf) cancelAnimationFrame(scrollRaf);
+    const start = performance.now();
+    const step = (now: number) => {
+      const elapsed = now - start;
+      scrollToY(scroller, scrollPositionAt(from, elapsed, duration));
+      if (elapsed < duration) {
+        scrollRaf = requestAnimationFrame(step);
+      } else {
+        finishScroll();
+      }
+    };
+    scrollRaf = requestAnimationFrame(step);
+  }
+</script>
+
+<button
+  type="button"
+  class="cd-backtop cd-backtop--{size} {className}"
+  class:cd-backtop--visible={visible}
+  aria-label={ariaLabel ?? loc().t('BackTop.ariaLabel')}
+  aria-hidden={!visible}
+  tabindex={visible ? 0 : -1}
+  style="--cd-backtop-offset-bottom:{bottomPx}; --cd-backtop-offset-inline-end:{rightPx}"
+  onclick={scrollToTop}
+>
+  {#if children}
+    {@render children({ visible })}
+  {:else if icon}
+    {@render icon({ size })}
+  {:else}
+    <svg class="cd-backtop__icon" viewBox="0 0 24 24" aria-hidden="true">
+      <path
+        fill="none"
+        stroke="currentColor"
+        stroke-width="2"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+        d="M12 19V5M5 12l7-7 7 7"
+      />
+    </svg>
+  {/if}
+</button>
+
+{#if announceOnArrive}
+  <!-- 到顶播报 live region：视觉隐藏，仅供辅助技术读取（红线 #2：render 期只读 $state）。 -->
+  <div class="cd-sr-only" role="status" aria-live="polite" aria-atomic="true">
+    {announceText}
+  </div>
+{/if}
+
+<style>
+  .cd-backtop {
+    position: fixed;
+    inset-block-end: var(--cd-backtop-offset-bottom, 40px);
+    inset-inline-end: var(--cd-backtop-offset-inline-end, 40px);
+    inline-size: var(--cd-backtop-size);
+    block-size: var(--cd-backtop-size);
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    padding: 0;
+    border: 1px solid transparent;
+    border-radius: var(--cd-backtop-radius);
+    background: var(--cd-backtop-bg);
+    color: var(--cd-backtop-color);
+    box-shadow: var(--cd-backtop-shadow);
+    cursor: pointer;
+    z-index: var(--cd-backtop-z);
+    /* 隐藏态（默认） */
+    opacity: 0;
+    visibility: hidden;
+    pointer-events: none;
+    transform: translateY(8px);
+    transition:
+      opacity var(--cd-backtop-motion-duration) ease,
+      transform var(--cd-backtop-motion-duration) ease,
+      visibility var(--cd-backtop-motion-duration) ease;
+  }
+
+  .cd-backtop--visible {
+    opacity: 1;
+    visibility: visible;
+    pointer-events: auto;
+    transform: translateY(0);
+  }
+
+  .cd-backtop--small {
+    inline-size: var(--cd-backtop-size-small);
+    block-size: var(--cd-backtop-size-small);
+  }
+
+  .cd-backtop--large {
+    inline-size: var(--cd-backtop-size-large);
+    block-size: var(--cd-backtop-size-large);
+  }
+
+  .cd-backtop:hover {
+    background: var(--cd-backtop-bg-hover);
+  }
+
+  .cd-backtop:active {
+    background: var(--cd-backtop-bg-active);
+  }
+
+  .cd-backtop:focus-visible {
+    outline: 2px solid var(--cd-backtop-focus-ring);
+    outline-offset: 2px;
+  }
+
+  .cd-backtop__icon {
+    inline-size: 50%;
+    block-size: 50%;
+  }
+
+  /* 到顶播报 live region 复用 tokens.css 全局 .cd-sr-only：视觉隐藏但 AT 可读。 */
+
+  @media (prefers-reduced-motion: reduce) {
+    .cd-backtop {
+      transition: none;
+    }
+  }
+</style>

package/src/back-top/index.ts

@@ -0,0 +1,2 @@
+export { default as BackTop } from './BackTop.svelte';
+export { meta as backTopMeta } from './meta.js';

package/src/back-top/meta.ts

@@ -0,0 +1,108 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * BackTop — see specs/components/other/BackTop.spec.md
+ */
+export const meta = {
+  name: 'BackTop',
+  category: 'other',
+  description:
+    '回到顶部悬浮按钮：滚动超阈值显隐 + 平滑缓动(easeInOutCubic)回顶，三尺寸(small/default/large)，原生 button 支持 Enter/Space，prefers-reduced-motion 下瞬时回顶，RTL 友好(inset-inline-end)。默认监听 window 滚动，可经 target 指定自定义滚动容器；支持受控 visible 与 announceOnArrive 到顶 ARIA live 播报。',
+  exports: ['BackTop'],
+  props: [
+    {
+      name: 'target',
+      type: '() => HTMLElement | string | Window | null',
+      default: 'undefined',
+      desc: '监听并回顶的滚动容器，返回元素/CSS 选择器/window；不传监听 window',
+    },
+    {
+      name: 'visible',
+      type: 'boolean',
+      default: 'undefined',
+      desc: '受控显隐：传入则由外部控制按钮显隐（仅读不回写），不传按 visibilityHeight 自动',
+    },
+    {
+      name: 'announceOnArrive',
+      type: 'boolean',
+      default: 'false',
+      desc: '回到顶部后经 ARIA live region 播报（文案取 locale BackTop.arrived）',
+    },
+    {
+      name: 'visibilityHeight',
+      type: 'number',
+      default: '400',
+      desc: '滚动超过此高度(px)显示按钮',
+    },
+    { name: 'duration', type: 'number', default: '450', desc: '回顶动画时长(ms)，0 瞬时' },
+    { name: 'bottom', type: 'number|string', default: '40', desc: '距底偏移，number→px' },
+    {
+      name: 'right',
+      type: 'number|string',
+      default: '40',
+      desc: '距 inline-end 偏移，number→px',
+    },
+    { name: 'size', type: "'small'|'default'|'large'", default: "'default'" },
+    { name: 'ariaLabel', type: 'string', default: "'回到顶部'", desc: '无障碍标签' },
+    {
+      name: 'icon',
+      type: 'Snippet<[{ size }]>',
+      default: 'undefined',
+      desc: '替换图标(保留圆形按钮外壳)',
+    },
+    {
+      name: 'children',
+      type: 'Snippet<[{ visible }]>',
+      default: 'undefined',
+      desc: '完全自定义按钮内容',
+    },
+    { name: 'onClick', type: '(e: MouseEvent) => void', default: 'undefined' },
+    {
+      name: 'onVisibleChange',
+      type: '(info: { visible: boolean }) => void',
+      default: 'undefined',
+      desc: '显隐切换通知',
+    },
+    {
+      name: 'onScrollEnd',
+      type: '() => void',
+      default: 'undefined',
+      desc: '回顶动画结束通知',
+    },
+    { name: 'class', type: 'string', default: "''" },
+  ],
+  events: [
+    { name: 'onClick', desc: '按钮点击' },
+    { name: 'onVisibleChange', desc: '显隐切换' },
+    { name: 'onScrollEnd', desc: '回顶动画结束' },
+  ],
+  slots: [
+    { name: 'children', desc: '完全自定义按钮内容，入参 { visible }' },
+    { name: 'icon', desc: '替换默认图标，入参 { size }，保留圆形按钮外壳' },
+  ],
+  a11y: {
+    hasRole: true,
+    focusable: true,
+    note: '原生 button 自带 button role + Enter/Space 触发；aria-label 文本；隐藏态 aria-hidden=true + tabindex=-1 移出 Tab 序与 a11y 树；focus-visible 焦点环。',
+  },
+  tokens: [
+    '--cd-backtop-size',
+    '--cd-backtop-size-small',
+    '--cd-backtop-size-large',
+    '--cd-backtop-bg',
+    '--cd-backtop-bg-hover',
+    '--cd-backtop-bg-active',
+    '--cd-backtop-color',
+    '--cd-backtop-border',
+    '--cd-backtop-shadow',
+    '--cd-backtop-radius',
+    '--cd-backtop-z',
+    '--cd-backtop-focus-ring',
+    '--cd-backtop-motion-duration',
+  ],
+  responsive: false,
+  examples: [
+    { title: '基础', code: '<BackTop />' },
+    { title: '小尺寸', code: '<BackTop size="small" />' },
+    { title: '自定义偏移', code: '<BackTop bottom={80} right={24} />' },
+  ],
+} as const;

package/src/badge/Badge.a11y.test.ts

@@ -0,0 +1,35 @@
+// Badge a11y：独立状态点 role=status；count 模式 <sup aria-label>。
+// 经 BadgeA11yFixture（不注入 children，使 standalone 形态生效；harness 会恒注入空 children）。
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/svelte';
+import { expectNoAxeViolations } from '../test-utils/a11y.js';
+import BadgeA11yFixture from './BadgeA11yFixture.svelte';
+
+describe('Badge a11y', () => {
+  it('独立状态点：role=status，无 axe violations', async () => {
+    const { container } = render(BadgeA11yFixture, {
+      props: { props: { status: 'success', count: 'Online' } },
+    });
+    const root = container.querySelector('.cd-badge--status');
+    expect(root?.getAttribute('role')).toBe('status');
+    await expectNoAxeViolations(container);
+  });
+
+  it('count 角标：sup 带 aria-label（计数文本），无 axe violations', async () => {
+    const { container } = render(BadgeA11yFixture, {
+      props: { props: { count: 5 } },
+    });
+    const sup = container.querySelector('.cd-badge__sup');
+    expect(sup?.getAttribute('aria-label')).toBe('5');
+    await expectNoAxeViolations(container);
+  });
+
+  it('overflow 角标：超出 overflowCount 显示 99+，无 axe violations', async () => {
+    const { container } = render(BadgeA11yFixture, {
+      props: { props: { count: 200, overflowCount: 99 } },
+    });
+    const sup = container.querySelector('.cd-badge__sup');
+    expect(sup?.getAttribute('aria-label')).toBe('99+');
+    await expectNoAxeViolations(container);
+  });
+});