@chenzy-design/svelte 0.1.0

package/src/tooltip/Tooltip.kbd.test.ts

@@ -0,0 +1,37 @@
+// Tooltip 键盘 e2e（browser project / 真实 chromium）。
+// 测 useDismiss(escape:true) 的真实 Esc 关闭——浮层 portal 到 body，role=tooltip：
+//   1. 聚焦触发按钮（trigger='focus'）→ focusin 显示浮层（document 范围查 role=tooltip）。
+//   2. 按 Esc → useDismiss 关闭浮层；焦点仍在触发按钮上（Esc 不移动焦点）。
+//
+// WCAG 1.4.13（Content on Hover or Focus）：focus 浮层须可由 Esc 关闭。
+import { describe, it, expect } from 'vitest';
+import { page } from 'vitest/browser';
+import { renderKbdFixture, userEvent } from '../test-utils/kbd.js';
+import TooltipKbdFixture from './TooltipKbdFixture.svelte';
+
+function loc(el: Element) {
+  return page.elementLocator(el);
+}
+
+describe('Tooltip 键盘 e2e（Esc 关闭）', () => {
+  it('聚焦显示浮层；Esc 关闭浮层且焦点留在触发器', async () => {
+    const { baseElement } = renderKbdFixture(TooltipKbdFixture);
+
+    const trigger = baseElement.querySelector('[data-testid="trigger"]') as HTMLButtonElement;
+    expect(trigger).not.toBeNull();
+
+    // 1. 聚焦触发按钮 → focusin 打开浮层。浮层 portal 到 body，在 document 范围查询。
+    trigger.focus();
+    await expect.element(loc(trigger)).toHaveFocus();
+    const tip = page.getByRole('tooltip');
+    await expect.element(tip).toBeInTheDocument();
+    await expect.element(tip).toHaveTextContent('More info');
+
+    // 2. Esc 关闭浮层（useDismiss escape:true 对 focus 触发亦生效）。
+    await userEvent.keyboard('{Escape}');
+    await expect.element(tip).not.toBeInTheDocument();
+
+    // Esc 不移动焦点：焦点仍在触发按钮上。
+    await expect.element(loc(trigger)).toHaveFocus();
+  });
+});

package/src/tooltip/Tooltip.svelte

@@ -0,0 +1,416 @@
+<!--
+  Tooltip — see specs/components/show/Tooltip.spec.md
+  基础子集：hover/focus/click 触发、12 方位、箭头、延迟、dark/light 主题。
+  定位：portal 到 body + position:fixed，core computePosition 计算坐标 +
+  autoAdjustOverflow flip 碰撞避让（脱离 overflow:hidden 裁剪）。
+  arrowPointAtCenter：start/end 对齐时箭头改为指向触发器中心（默认贴对齐边）。
+  status：default|warning|error，非 default 时内容前渲染语义图标（aria-label 经 locale）。
+  custom trigger：显隐完全由受控 open + onOpenChange 控制，不自动 hover/click/focus（供调用方自定义触发）。
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import { untrack } from 'svelte';
+  import { useId, useDismiss, useScrollLock, type Placement } from '@chenzy-design/core';
+  import { getGlobalPopupContainer } from '../config-provider/index.js';
+  import { floating } from '../_floating/use-floating.js';
+  import { resolveSide } from './placement.js';
+  import { useLocale } from '../locale-provider/index.js';
+
+  type TriggerKind = 'hover' | 'focus' | 'click' | 'custom';
+  type Theme = 'dark' | 'light';
+  type Status = 'default' | 'warning' | 'error';
+
+  interface Props {
+    content?: string | Snippet;
+    open?: boolean;
+    defaultOpen?: boolean;
+    trigger?: TriggerKind | Array<TriggerKind>;
+    placement?: Placement;
+    /** 视口溢出时翻转到对侧 */
+    autoAdjustOverflow?: boolean;
+    mouseEnterDelay?: number;
+    mouseLeaveDelay?: number;
+    showArrow?: boolean;
+    /** start/end 对齐时箭头指向触发器中心（默认 false：贴对齐边） */
+    arrowPointAtCenter?: boolean;
+    theme?: Theme;
+    /** 语义态：非 default 时内容前渲染对应状态图标 */
+    status?: Status;
+    maxWidth?: number | string;
+    disabled?: boolean;
+    /** 浮层 z-index（覆盖 CSS token --cd-tooltip-z） */
+    zIndex?: number;
+    /** 阻止浮层上的点击事件冒泡，默认 true */
+    stopPropagation?: boolean;
+    /** 显示时阻止页面滚动 */
+    preventScroll?: boolean;
+    /** 浮层完全关闭（动画结束）后的回调 */
+    afterClose?: () => void;
+    /** 自定义浮层挂载容器（缺省回退 ConfigProvider 全局，再回退 body） */
+    getPopupContainer?: () => HTMLElement | null | undefined;
+    onOpenChange?: (open: boolean) => void;
+    children?: Snippet;
+  }
+
+  let {
+    content,
+    open,
+    defaultOpen = false,
+    trigger = ['hover', 'focus'],
+    placement = 'top',
+    autoAdjustOverflow = true,
+    mouseEnterDelay = 100,
+    mouseLeaveDelay = 100,
+    showArrow = true,
+    arrowPointAtCenter = false,
+    theme = 'dark',
+    status = 'default',
+    maxWidth = 300,
+    disabled = false,
+    zIndex,
+    stopPropagation = true,
+    preventScroll = false,
+    afterClose,
+    getPopupContainer,
+    onOpenChange,
+    children,
+  }: Props = $props();
+
+  const tipId = useId('cd-tooltip');
+  const loc = useLocale();
+
+  // ConfigProvider 全局浮层容器默认；自身 getPopupContainer prop 优先。
+  const globalPopupContainer = getGlobalPopupContainer();
+  const resolvePopupContainer = $derived(getPopupContainer ?? globalPopupContainer);
+
+  // --- 受控 open (红线 #1)：不无条件回写 open，仅 onOpenChange ---
+  const isControlled = $derived(open !== undefined);
+  // eslint-disable-next-line -- 仅取 defaultOpen 初值作为非受控初始态
+  let innerOpen = $state(untrack(() => defaultOpen));
+  const triggers = $derived(Array.isArray(trigger) ? trigger : [trigger]);
+  const hasContent = $derived(content !== undefined && content !== '');
+  const isOpen = $derived(
+    !disabled && hasContent && (isControlled ? !!open : innerOpen),
+  );
+
+  function setOpen(next: boolean) {
+    if (next === (isControlled ? !!open : innerOpen)) return;
+    if (!isControlled) innerOpen = next;
+    onOpenChange?.(next);
+  }
+
+  const maxWidthCss = $derived(
+    typeof maxWidth === 'number' ? `${maxWidth}px` : maxWidth,
+  );
+
+  const contentText = $derived(
+    typeof content === 'string' ? content : undefined,
+  );
+  const contentSnippet = $derived(
+    typeof content === 'function' ? content : undefined,
+  );
+
+  // status：非 default 时内容前渲染语义图标（纯派生，红线 #2）
+  const hasStatusIcon = $derived(status === 'warning' || status === 'error');
+  const statusLabel = $derived(
+    status === 'warning'
+      ? loc().t('Tooltip.warningLabel')
+      : status === 'error'
+        ? loc().t('Tooltip.errorLabel')
+        : undefined,
+  );
+
+  // --- hover 延迟开关：setTimeout 存普通变量，cleanup 清除 ---
+  let enterTimer: ReturnType<typeof setTimeout> | undefined;
+  let leaveTimer: ReturnType<typeof setTimeout> | undefined;
+
+  function clearTimers() {
+    if (enterTimer !== undefined) {
+      clearTimeout(enterTimer);
+      enterTimer = undefined;
+    }
+    if (leaveTimer !== undefined) {
+      clearTimeout(leaveTimer);
+      leaveTimer = undefined;
+    }
+  }
+
+  function onPointerEnter() {
+    if (disabled || !triggers.includes('hover')) return;
+    clearTimers();
+    enterTimer = setTimeout(() => setOpen(true), mouseEnterDelay);
+  }
+
+  function onPointerLeave() {
+    if (disabled || !triggers.includes('hover')) return;
+    clearTimers();
+    leaveTimer = setTimeout(() => setOpen(false), mouseLeaveDelay);
+  }
+
+  function onFocusIn() {
+    if (disabled || !triggers.includes('focus')) return;
+    setOpen(true);
+  }
+
+  function onFocusOut() {
+    if (disabled || !triggers.includes('focus')) return;
+    setOpen(false);
+  }
+
+  function onClick() {
+    if (disabled || !triggers.includes('click')) return;
+    setOpen(!isOpen);
+  }
+
+  // --- DOM 引用：触发包裹（浮层定位由 use:floating action 接管）---
+  let rootEl = $state<HTMLSpanElement | null>(null);
+  let popEl = $state<HTMLDivElement | null>(null);
+
+  // 解析后的实际方位（flip 后），驱动箭头朝向 class。初值仅取 placement 一次。
+  let resolvedPlacement = $state<Placement>(untrack(() => placement));
+  const resolvedSide = $derived(resolveSide(resolvedPlacement));
+  let arrowOffset = $state(0);
+
+  // use:floating 的稳定参数：仅含原始输入（placement/trigger 不随 resolved 变化），
+  // onPlacement 为稳定函数引用，避免 action update 触发重建循环。
+  function onPlacement(info: { placement: Placement; arrowOffset: number }) {
+    resolvedPlacement = info.placement;
+    arrowOffset = info.arrowOffset;
+  }
+
+  // --- useDismiss (红线 #3)：Esc 对所有触发模式生效（WCAG 1.4.13 Content on Hover：
+  // hover/focus 浮层也须可由 Esc 关闭）；外部点击关闭仅 click 触发需要（hover/focus 自然关）。
+  // popup portal 列入 extraTargets。
+  $effect(() => {
+    if (!isOpen || !rootEl) return;
+    const allowOutsideClick = triggers.includes('click');
+    const cleanup = useDismiss(rootEl, {
+      onDismiss: () => setOpen(false),
+      escape: true,
+      outsideClick: allowOutsideClick,
+      extraTargets: [popEl],
+    });
+    return cleanup;
+  });
+
+  // cleanup hover 定时器
+  $effect(() => clearTimers);
+
+  // --- preventScroll：显示时锁定背景滚动（红线 #3：命令式 + cleanup）---
+  $effect(() => {
+    if (!isOpen || !preventScroll) return;
+    const release = useScrollLock();
+    return release;
+  });
+
+  // --- afterClose：浮层关闭后（isOpen 变 false）异步回调，确保动画有机会结束 ---
+  // 记录上一帧 isOpen，避免首次挂载时误触发（初始值与 isOpen 一致不触发）。
+  let prevOpenRef = { value: false };
+  $effect(() => {
+    const current = isOpen;
+    if (prevOpenRef.value && !current) {
+      // 用 requestAnimationFrame 延后一帧，让 CSS 过渡先触发
+      requestAnimationFrame(() => afterClose?.());
+    }
+    prevOpenRef.value = current;
+  });
+
+  // 浮层根内联样式：自定义 zIndex 覆盖 token 层级。
+  const popStyle = $derived(
+    [
+      `max-inline-size:${maxWidthCss}`,
+      zIndex !== undefined ? `z-index:${zIndex}` : '',
+    ]
+      .filter(Boolean)
+      .join(';'),
+  );
+
+  // stopPropagation：浮层内点击停止冒泡。
+  function onPopClick(e: MouseEvent) {
+    if (stopPropagation) e.stopPropagation();
+  }
+
+  // 箭头沿交叉轴的定位样式：top/bottom 用 inline-start，left/right 用 block-start。
+  const arrowStyle = $derived(
+    resolvedSide === 'top' || resolvedSide === 'bottom'
+      ? `inset-inline-start:${arrowOffset}px`
+      : `inset-block-start:${arrowOffset}px`,
+  );
+</script>
+
+<!-- 触发包裹 span 仅转发宿主事件给真正可交互的 children；自身无障碍语义忽略 -->
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<!-- svelte-ignore a11y_click_events_have_key_events -->
+<span
+  class="cd-tooltip"
+  bind:this={rootEl}
+  onpointerenter={onPointerEnter}
+  onpointerleave={onPointerLeave}
+  onfocusin={onFocusIn}
+  onfocusout={onFocusOut}
+  onclick={onClick}
+>
+  <span
+    class="cd-tooltip__trigger"
+    aria-describedby={isOpen ? tipId : undefined}
+  >
+    {@render children?.()}
+  </span>
+
+  {#if isOpen}
+    <!-- svelte-ignore a11y_click_events_have_key_events -->
+    <!-- svelte-ignore a11y_no_static_element_interactions -->
+    <!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+    <div
+      id={tipId}
+      role="tooltip"
+      bind:this={popEl}
+      use:floating={{ trigger: rootEl, placement, autoAdjust: autoAdjustOverflow, offset: 8, arrowPointAtCenter, onPlacement, getContainer: resolvePopupContainer }}
+      class="cd-tooltip__pop cd-tooltip__pop--{resolvedSide} cd-tooltip__pop--{theme}"
+      class:cd-tooltip__pop--no-arrow={!showArrow}
+      class:cd-tooltip__pop--with-status={hasStatusIcon}
+      style={popStyle}
+      onclick={onPopClick}
+    >
+      {#if hasStatusIcon}
+        <span class="cd-tooltip__status cd-tooltip__status--{status}" aria-label={statusLabel} role="img">
+          {#if status === 'warning'}
+            <svg class="cd-tooltip__status-svg" viewBox="0 0 16 16" focusable="false">
+              <path
+                fill="none"
+                stroke="currentColor"
+                stroke-width="1.4"
+                stroke-linejoin="round"
+                d="M8 1.8l6.4 11.4H1.6z"
+              />
+              <path stroke="currentColor" stroke-width="1.4" stroke-linecap="round" d="M8 6v3.4" />
+              <circle cx="8" cy="11.4" r="0.85" fill="currentColor" />
+            </svg>
+          {:else}
+            <svg class="cd-tooltip__status-svg" viewBox="0 0 16 16" focusable="false">
+              <circle cx="8" cy="8" r="7" fill="none" stroke="currentColor" stroke-width="1.4" />
+              <path
+                stroke="currentColor"
+                stroke-width="1.6"
+                stroke-linecap="round"
+                d="M5.5 5.5l5 5M10.5 5.5l-5 5"
+              />
+            </svg>
+          {/if}
+        </span>
+      {/if}
+      <span class="cd-tooltip__content">
+        {#if contentSnippet}
+          {@render contentSnippet()}
+        {:else}
+          {contentText}
+        {/if}
+      </span>
+      {#if showArrow}
+        <span class="cd-tooltip__arrow" style={arrowStyle} aria-hidden="true"></span>
+      {/if}
+    </div>
+  {/if}
+</span>
+
+<style>
+  .cd-tooltip {
+    position: relative;
+    display: inline-block;
+  }
+  .cd-tooltip__trigger {
+    display: inline-block;
+  }
+  /* 浮层 portal 到 body，由 JS 写 position:fixed + transform 定位 */
+  .cd-tooltip__pop {
+    z-index: var(--cd-tooltip-z);
+    inline-size: max-content;
+    padding: var(--cd-tooltip-padding);
+    border-radius: var(--cd-tooltip-radius);
+    font-size: var(--cd-tooltip-font-size);
+    line-height: var(--cd-line-height-1, 1.5);
+    word-wrap: break-word;
+    pointer-events: none;
+  }
+
+  /* --- status：图标 + 内容横向排布 --- */
+  .cd-tooltip__pop--with-status {
+    display: inline-flex;
+    align-items: flex-start;
+    gap: var(--cd-spacing-1);
+  }
+  .cd-tooltip__status {
+    display: inline-flex;
+    flex: 0 0 auto;
+    align-items: center;
+    justify-content: center;
+    inline-size: 1em;
+    block-size: 1em;
+    margin-block-start: 0.1em;
+  }
+  .cd-tooltip__status-svg {
+    inline-size: 100%;
+    block-size: 100%;
+  }
+  .cd-tooltip__status--warning {
+    color: var(--cd-tooltip-status-warning);
+  }
+  .cd-tooltip__status--error {
+    color: var(--cd-tooltip-status-error);
+  }
+  .cd-tooltip__content {
+    min-inline-size: 0;
+  }
+
+  /* --- 主题 --- */
+  .cd-tooltip__pop--dark {
+    background: var(--cd-tooltip-bg-dark);
+    color: var(--cd-tooltip-color-dark);
+  }
+  .cd-tooltip__pop--light {
+    background: var(--cd-tooltip-bg-light);
+    color: var(--cd-tooltip-color-light);
+    box-shadow: var(--cd-tooltip-shadow);
+  }
+
+  /* --- 箭头：方块旋转 45deg，交叉轴偏移由内联 style 控制 --- */
+  .cd-tooltip__arrow {
+    position: absolute;
+    inline-size: var(--cd-tooltip-arrow-size);
+    block-size: var(--cd-tooltip-arrow-size);
+    background: inherit;
+    transform: rotate(45deg);
+  }
+  /* 交叉轴居中补偿：仅在交叉轴方向回退半个箭头尺寸 */
+  .cd-tooltip__pop--top .cd-tooltip__arrow,
+  .cd-tooltip__pop--bottom .cd-tooltip__arrow {
+    margin-inline-start: calc(var(--cd-tooltip-arrow-size) / -2);
+  }
+  .cd-tooltip__pop--left .cd-tooltip__arrow,
+  .cd-tooltip__pop--right .cd-tooltip__arrow {
+    margin-block-start: calc(var(--cd-tooltip-arrow-size) / -2);
+  }
+  .cd-tooltip__pop--dark .cd-tooltip__arrow {
+    background: var(--cd-tooltip-bg-dark);
+  }
+  .cd-tooltip__pop--light .cd-tooltip__arrow {
+    background: var(--cd-tooltip-bg-light);
+  }
+
+  /* 箭头吸附到浮层贴近触发器的那条边（按解析后的 side） */
+  .cd-tooltip__pop--top .cd-tooltip__arrow {
+    inset-block-end: calc(var(--cd-tooltip-arrow-size) / -2);
+  }
+  .cd-tooltip__pop--bottom .cd-tooltip__arrow {
+    inset-block-start: calc(var(--cd-tooltip-arrow-size) / -2);
+  }
+  .cd-tooltip__pop--left .cd-tooltip__arrow {
+    inset-inline-end: calc(var(--cd-tooltip-arrow-size) / -2);
+  }
+  .cd-tooltip__pop--right .cd-tooltip__arrow {
+    inset-inline-start: calc(var(--cd-tooltip-arrow-size) / -2);
+  }
+  .cd-tooltip__pop--no-arrow .cd-tooltip__arrow {
+    display: none;
+  }
+</style>

package/src/tooltip/TooltipA11yFixture.svelte

@@ -0,0 +1,31 @@
+<!--
+  Tooltip a11y 测试夹具：在 LocaleProvider 内渲染 Tooltip，
+  并提供一个真实可聚焦的触发按钮作为 children（trigger 文案）。
+  仅供 Tooltip.a11y.test.ts 使用，不对外导出。
+-->
+<script lang="ts">
+  import { LocaleProvider } from '../locale-provider/index.js';
+  import Tooltip from './Tooltip.svelte';
+
+  interface Props {
+    open?: boolean;
+    content?: string;
+    status?: 'default' | 'warning' | 'error';
+    trigger?: 'hover' | 'focus' | 'click' | 'custom';
+    locale?: string;
+  }
+
+  let {
+    open = false,
+    content = 'More info',
+    status = 'default',
+    trigger = 'custom',
+    locale = 'en_US',
+  }: Props = $props();
+</script>
+
+<LocaleProvider {locale}>
+  <Tooltip {open} {content} {status} {trigger}>
+    <button type="button">Hover me</button>
+  </Tooltip>
+</LocaleProvider>

package/src/tooltip/TooltipKbdFixture.svelte

@@ -0,0 +1,16 @@
+<!--
+  仅供 Tooltip.kbd.test.ts（browser project）使用的 Esc 关闭键盘 e2e 夹具。
+  trigger='focus'：聚焦触发按钮即显示浮层（focusin），便于在真实浏览器里用键盘驱动；
+  浮层 portal 到 document.body（use:floating），role=tooltip。
+  验证：聚焦显示后按 Esc，useDismiss(escape:true) 关闭浮层。
+-->
+<script lang="ts">
+  import { LocaleProvider } from '../locale-provider/index.js';
+  import Tooltip from './Tooltip.svelte';
+</script>
+
+<LocaleProvider locale="en_US">
+  <Tooltip content="More info" trigger="focus">
+    <button type="button" data-testid="trigger">Hover me</button>
+  </Tooltip>
+</LocaleProvider>

package/src/tooltip/index.ts

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

package/src/tooltip/meta.ts

@@ -0,0 +1,59 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * See specs/00-foundation/ai-friendly.spec.md.
+ */
+export const meta = {
+  name: 'Tooltip',
+  category: 'show',
+  description:
+    '文字提示，鼠标悬停/聚焦/点击触发元素时展示简短说明。支持常用 placement、箭头、延迟、dark/light 主题、status 语义图标与 custom 完全受控触发，浮层命令式定位。',
+  props: [
+    { name: 'content', type: 'string | Snippet', default: 'undefined', desc: '提示内容，为空不显示' },
+    { name: 'open', type: 'boolean', default: 'undefined', desc: '受控显隐' },
+    { name: 'defaultOpen', type: 'boolean', default: 'false', desc: '非受控初始显隐' },
+    {
+      name: 'trigger',
+      type: "'hover'|'focus'|'click'|'custom'|Array<'hover'|'focus'|'click'|'custom'>",
+      default: "['hover','focus']",
+      desc: "触发方式，可组合；'custom' 完全受控（仅 open + onOpenChange，不自动 hover/click/focus）",
+    },
+    {
+      name: 'placement',
+      type: "'top'|'topLeft'|'topRight'|'bottom'|'bottomLeft'|'bottomRight'|'left'|'right'",
+      default: 'top',
+      desc: '浮层方位',
+    },
+    { name: 'mouseEnterDelay', type: 'number', default: '100', desc: 'hover 进入延迟(ms)' },
+    { name: 'mouseLeaveDelay', type: 'number', default: '100', desc: 'hover 离开延迟(ms)' },
+    { name: 'showArrow', type: 'boolean', default: 'true', desc: '是否显示箭头' },
+    {
+      name: 'arrowPointAtCenter',
+      type: 'boolean',
+      default: 'false',
+      desc: 'start/end 对齐时箭头指向触发器中心',
+    },
+    { name: 'theme', type: "'dark'|'light'", default: 'dark', desc: '主题' },
+    {
+      name: 'status',
+      type: "'default'|'warning'|'error'",
+      default: 'default',
+      desc: '语义态：非 default 时内容前渲染对应状态图标（图标 aria-label 经 locale）',
+    },
+    { name: 'maxWidth', type: 'number | string', default: '300', desc: '浮层最大宽度' },
+    { name: 'disabled', type: 'boolean', default: 'false', desc: '禁用触发' },
+    { name: 'onOpenChange', type: '(open: boolean) => void', default: 'undefined' },
+    { name: 'children', type: 'Snippet', default: 'undefined', desc: '触发元素（必填）' },
+  ],
+  a11y: {
+    role: 'tooltip',
+    keyboard: ['Escape'],
+    notes: [
+      '浮层 role=tooltip，使用 useId 生成唯一 id',
+      '触发元素 open 时加 aria-describedby 指向浮层',
+      'focus 触发支持键盘聚焦展示，click 触发用 useDismiss 处理 Escape 与外部点击',
+      'custom 触发不绑定 hover/click/focus，显隐完全由受控 open + onOpenChange 控制',
+      'status 非 default 时状态图标用 role=img + aria-label（经 locale）',
+    ],
+  },
+  tokens: ['--cd-tooltip-*', '--cd-focus-ring', '--cd-motion-*'],
+} as const;

package/src/tooltip/placement.ts

@@ -0,0 +1,6 @@
+import { parsePlacement, type Placement, type Side } from '@chenzy-design/core';
+
+/** 取 placement 的主方向 side（驱动箭头朝向的 class）。 */
+export function resolveSide(placement: Placement): Side {
+  return parsePlacement(placement).side;
+}

package/src/transfer/Transfer.a11y.test.ts

@@ -0,0 +1,63 @@
+// Transfer a11y：双栏穿梭框（dual-listbox）。
+// 容器 role=group；每侧平铺列表 role=listbox + aria-multiselectable；
+// 条目 role=option + aria-selected。
+//
+// 组件 a11y 修复（原 axe violations 已消除）：
+//   1. [aria-toggle-field-name] role=option 条目原可访问名为空（label 在 aria-hidden 子树内）：
+//      已给 role=option 的 <li> 加 aria-label={item.label}，提供可访问名（视觉勾选框仍 aria-hidden）。
+//   2. [aria-required-children]/[listitem] 空 listbox 仅含空态 <li>：空态时该 <ul> 退化为普通
+//      容器（去掉 role=listbox 及 listbox-only ARIA），空态 <li> 成为合法 listitem。
+import { describe, it, expect } from 'vitest';
+import { renderWithLocale, expectNoAxeViolations } from '../test-utils/a11y.js';
+import Transfer from './Transfer.svelte';
+
+const dataSource = [
+  { key: 'a', label: 'Apple' },
+  { key: 'b', label: 'Banana' },
+  { key: 'c', label: 'Cherry' },
+  { key: 'd', label: 'Date' },
+];
+
+describe('Transfer a11y', () => {
+  it('默认渲染：role=group + 非空面板为 listbox + option role/aria（不跑 axe）', () => {
+    const { container } = renderWithLocale(Transfer, {
+      props: { dataSource },
+    });
+    expect(container.querySelector('[role="group"]')).not.toBeNull();
+    // 默认无选中：源面板有项 → listbox；目标面板为空 → 退化为普通容器（非 listbox，
+    // 避免 axe aria-required-children）。故此处仅 1 个 listbox。
+    const listboxes = container.querySelectorAll('[role="listbox"]');
+    expect(listboxes.length).toBe(1);
+    const lb = listboxes[0];
+    expect(lb?.getAttribute('aria-multiselectable')).toBe('true');
+    // listbox 由栏标题 aria-labelledby 命名
+    expect(lb?.getAttribute('aria-labelledby')).toBeTruthy();
+    // 源面板 4 个 option，均带 aria-selected + aria-label（可访问名）
+    const options = container.querySelectorAll('[role="option"]');
+    expect(options.length).toBe(4);
+    options.forEach((opt) => {
+      expect(opt.hasAttribute('aria-selected')).toBe(true);
+      expect(opt.getAttribute('aria-label')).toBeTruthy();
+    });
+  });
+
+  it('带选中：两侧均非空 → 双 listbox，右侧含已选项 + aria-selected（不跑 axe）', () => {
+    const { container } = renderWithLocale(Transfer, {
+      props: { dataSource, defaultValue: ['b'] },
+    });
+    const listboxes = container.querySelectorAll('[role="listbox"]');
+    expect(listboxes.length).toBe(2);
+    const right = listboxes[1];
+    expect(right).toBeDefined();
+    expect(right?.textContent).toContain('Banana');
+    expect(right?.querySelectorAll('[role="option"]').length).toBe(1);
+  });
+
+  // axe 0 violations：组件已修复（option aria-label 提供可访问名；空 listbox 退化为普通容器）。
+  it('axe 0 violations（option 可访问名 + 空 listbox 处理后）', async () => {
+    const { container } = renderWithLocale(Transfer, {
+      props: { dataSource, defaultValue: ['b'] },
+    });
+    await expectNoAxeViolations(container);
+  });
+});