@chenzy-design/svelte 0.1.0 → 0.2.0

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

@@ -1,40 +0,0 @@
-// 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

@@ -1,314 +0,0 @@
-<!--
-  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

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

package/src/back-top/meta.ts

@@ -1,108 +0,0 @@
-/**
- * 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

@@ -1,35 +0,0 @@
-// 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);
-  });
-});