@chenzy-design/svelte 0.1.0

package/src/transfer/TransferKbdFixture.svelte

@@ -0,0 +1,23 @@
+<!--
+  仅供 Transfer.kbd.test.ts（browser project）使用的双 listbox roving 键盘 e2e 夹具。
+  受控 value + onChange 回写，使「移动到对侧」真实生效（红线 #1：组件不自改 value）。
+  左侧为 SOURCE（role=listbox），条目 role=option + data-transfer-key；
+  验证：列内 ↑↓ 真实移动焦点到相邻 option、Space 勾选、Enter 移动后焦点保留在源列合理位置。
+-->
+<script lang="ts">
+  import { LocaleProvider } from '../locale-provider/index.js';
+  import Transfer from './Transfer.svelte';
+
+  const dataSource = [
+    { key: 'a', label: 'Apple' },
+    { key: 'b', label: 'Banana' },
+    { key: 'c', label: 'Cherry' },
+    { key: 'd', label: 'Date' },
+  ];
+
+  let value = $state<string[]>([]);
+</script>
+
+<LocaleProvider locale="en_US">
+  <Transfer {dataSource} {value} onChange={(next) => (value = next as string[])} />
+</LocaleProvider>

package/src/transfer/group.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest';
+import { buildGroups, hasGroups, isGrouped, normalizeData } from './group.js';
+import type { TransferGroup, TransferItem } from './types.js';
+
+describe('transfer/group', () => {
+  const flat: TransferItem[] = [
+    { key: 'a', label: '北京' },
+    { key: 'b', label: '上海' },
+  ];
+  const grouped: TransferGroup[] = [
+    { title: '华东', items: [{ key: 'hz', label: '杭州' }, { key: 'sh', label: '上海' }] },
+    { title: '华南', items: [{ key: 'gz', label: '广州' }] },
+  ];
+
+  it('isGrouped distinguishes flat vs grouped', () => {
+    expect(isGrouped(flat)).toBe(false);
+    expect(isGrouped(grouped)).toBe(true);
+    expect(isGrouped([])).toBe(false);
+  });
+
+  it('normalizeData keeps flat data untouched', () => {
+    expect(normalizeData(flat)).toEqual(flat);
+    expect(hasGroups(normalizeData(flat))).toBe(false);
+  });
+
+  it('normalizeData flattens grouped data and stamps group from title', () => {
+    const items = normalizeData(grouped);
+    expect(items.map((i) => i.key)).toEqual(['hz', 'sh', 'gz']);
+    expect(items.map((i) => i.group)).toEqual(['华东', '华东', '华南']);
+    expect(hasGroups(items)).toBe(true);
+  });
+
+  it('group title wins over a pre-set group on item', () => {
+    const src: TransferGroup[] = [
+      { title: 'X', items: [{ key: '1', label: 'one', group: 'Y' }] },
+    ];
+    expect(normalizeData(src)[0]!.group).toBe('X');
+  });
+
+  it('buildGroups preserves first-seen order and drops empty groups', () => {
+    const items = normalizeData(grouped);
+    // simulate a filter that removes all of 华南
+    const filtered = items.filter((i) => i.group === '华东');
+    const out = buildGroups(filtered, 'fallback');
+    expect(out.map((g) => g.title)).toEqual(['华东']);
+    expect(out[0]!.items.map((i) => i.key)).toEqual(['hz', 'sh']);
+  });
+
+  it('buildGroups buckets ungrouped items under fallback title', () => {
+    const out = buildGroups(flat, '源');
+    expect(out).toHaveLength(1);
+    expect(out[0]!.title).toBe('源');
+    expect(out[0]!.items).toEqual(flat);
+  });
+});

package/src/transfer/group.ts

@@ -0,0 +1,61 @@
+import type { TransferGroup, TransferItem, TransferRenderGroup } from './types.js';
+
+/**
+ * Normalize either a flat `TransferItem[]` or a grouped `TransferGroup[]` into a
+ * single flat list of items. Grouped input stamps `item.group` from the group
+ * title (the group title wins over any pre-set `group` on the item). Flat input
+ * is returned as-is so backward-compatible (ungrouped) behavior is untouched.
+ */
+export function normalizeData(
+  dataSource: TransferItem[] | TransferGroup[],
+): TransferItem[] {
+  if (isGrouped(dataSource)) {
+    const out: TransferItem[] = [];
+    for (const grp of dataSource) {
+      for (const item of grp.items) out.push({ ...item, group: grp.title });
+    }
+    return out;
+  }
+  return dataSource;
+}
+
+/** A grouped data source is an array whose entries have `items` (not `key`). */
+export function isGrouped(
+  dataSource: TransferItem[] | TransferGroup[],
+): dataSource is TransferGroup[] {
+  return (
+    dataSource.length > 0 &&
+    Array.isArray((dataSource[0] as TransferGroup).items) &&
+    (dataSource[0] as TransferItem).key === undefined
+  );
+}
+
+/**
+ * Build render groups from a list of (already-filtered) items, preserving the
+ * first-seen order of group names. Items without a `group` fall into a single
+ * ungrouped bucket keyed by `fallbackTitle`. Empty groups are naturally absent
+ * because the input is the post-filter item list.
+ */
+export function buildGroups(
+  items: TransferItem[],
+  fallbackTitle: string,
+): TransferRenderGroup[] {
+  const order: string[] = [];
+  const map = new Map<string, TransferItem[]>();
+  for (const item of items) {
+    const title = item.group ?? fallbackTitle;
+    let bucket = map.get(title);
+    if (!bucket) {
+      bucket = [];
+      map.set(title, bucket);
+      order.push(title);
+    }
+    bucket.push(item);
+  }
+  return order.map((title) => ({ title, items: map.get(title)! }));
+}
+
+/** True when any normalized item carries a `group` tag. */
+export function hasGroups(items: TransferItem[]): boolean {
+  return items.some((i) => i.group !== undefined);
+}

package/src/transfer/index.ts

@@ -0,0 +1,3 @@
+export { default as Transfer } from './Transfer.svelte';
+export { meta as transferMeta } from './meta.js';
+export type { TransferItem, TransferGroup, TransferTreeNode } from './types.js';

package/src/transfer/meta.ts

@@ -0,0 +1,55 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * See specs/00-foundation/ai-friendly.spec.md.
+ */
+export const meta = {
+  name: 'Transfer',
+  category: 'input',
+  description: '穿梭框，双栏列表间移动条目，支持多选、移动按钮、本地搜索过滤、分组（groupList）、树状源面板（treeList）、单向迁移（oneWay）、目标列拖拽重排（draggable）、虚拟化（virtualize）与远程搜索（onSearch）。',
+  props: [
+    { name: 'value', type: '(string|number)[]', default: 'undefined', desc: '受控已选 key 数组；提供则为受控' },
+    { name: 'defaultValue', type: '(string|number)[]', default: '[]', desc: '非受控初始已选 key' },
+    { name: 'dataSource', type: 'TransferItem[] | TransferGroup[] | TransferTreeNode[]', default: '[]', desc: '平铺条目（key/label/disabled/group）、分组结构 {title, items}[]，或树结构 {key,label,children}[]（treeList）；树模式下源面板按树渲染，仅叶子可迁移到平铺目标面板，已迁移叶子在源树置灰' },
+    { name: 'filter', type: 'boolean', default: 'true', desc: '是否显示本地搜索框' },
+    { name: 'searchPlaceholder', type: 'string', default: "'搜索'" },
+    { name: 'size', type: "'small'|'default'|'large'", default: 'default' },
+    { name: 'status', type: "'default'|'warning'|'error'", default: 'default' },
+    { name: 'disabled', type: 'boolean', default: 'false' },
+    { name: 'showPanelTitle', type: 'boolean', default: 'true', desc: '是否显示面板标题与计数' },
+    { name: 'titles', type: '[string, string]', default: "['源', '已选']" },
+    { name: 'oneWay', type: 'boolean', default: 'false', desc: '单向迁移：仅左→右；目标项各带「移除」按钮移回左侧，不显示右→左批量按钮' },
+    { name: 'draggable', type: 'boolean', default: 'false', desc: '目标（已选）列项可鼠标拖拽重排（HTML5 DnD）；新顺序经 reorder 纯函数算出仅通过 onChange 通知，受控 value 不回写' },
+    { name: 'virtualize', type: 'boolean', default: 'false', desc: '虚拟化两侧平铺面板：大数据下仅渲染视口内项（复用 core fixedRange）；分组/树源面板回退全量渲染' },
+    { name: 'itemHeight', type: 'number', default: '32', desc: '虚拟化行高（px），需与实际行高一致' },
+    { name: 'onSearch', type: "(query: string, direction: 'left'|'right') => void", default: 'undefined', desc: '远程搜索：提供后切换远程模式，输入防抖（searchDebounce ms）回调并由外部更新 dataSource，本地不再过滤' },
+    { name: 'loading', type: 'boolean', default: 'false', desc: '远程加载中：每侧列表顶部显示 spinner 行' },
+    { name: 'searchDebounce', type: 'number', default: '300', desc: 'onSearch 防抖毫秒' },
+    { name: 'onChange', type: '(targetKeys: (string|number)[]) => void', default: 'undefined' },
+    { name: 'type', type: "'list'|'groupList'|'treeList'", default: "'list'", desc: '数据形态：平铺/分组/树' },
+    { name: 'emptyContent', type: '{ left?: Snippet|string; right?: Snippet|string; search?: Snippet|string }', default: 'undefined', desc: '自定义空态' },
+    { name: 'inputProps', type: 'object', default: 'undefined', desc: '透传给搜索框 Input 的额外参数' },
+    { name: 'treeProps', type: 'object', default: 'undefined', desc: 'type=treeList 时透传给左侧 Tree 组件的参数' },
+    { name: 'showPath', type: 'boolean', default: 'false', desc: 'type=treeList 时右侧已选项显示完整路径' },
+    { name: 'pagination', type: '{ pageSize?: number; currentPage?: number; defaultCurrentPage?: number; onPageChange?: (page) => void }', default: 'undefined', desc: '左侧面板分页（仅 list/groupList）' },
+    { name: 'onSelect', type: '(item: TransferItem) => void', default: 'undefined', desc: '勾选单项时回调' },
+    { name: 'onDeselect', type: '(item: TransferItem) => void', default: 'undefined', desc: '取消勾选单项时回调' },
+    { name: 'renderSourceItem', type: 'Snippet<[{item, onChange, checked}]>', default: 'undefined', desc: '自定义左侧条目渲染' },
+    { name: 'renderSelectedItem', type: 'Snippet<[{item, onRemove, sortableHandle}]>', default: 'undefined', desc: '自定义右侧条目渲染' },
+    { name: 'renderSourceHeader', type: 'Snippet<[SourceHeaderProps]>', default: 'undefined', desc: '自定义左侧面板头部' },
+    { name: 'renderSelectedHeader', type: 'Snippet<[SelectedHeaderProps]>', default: 'undefined', desc: '自定义右侧面板头部' },
+    { name: 'renderSourcePanel', type: 'Snippet<[SourcePanelProps]>', default: 'undefined', desc: '完全自定义左侧面板' },
+    { name: 'renderSelectedPanel', type: 'Snippet<[SelectedPanelProps]>', default: 'undefined', desc: '完全自定义右侧面板' },
+  ],
+  a11y: {
+    role: 'group',
+    pattern: 'dual-listbox',
+    notes: [
+      '容器 role=group；每侧平铺列表 role=listbox + aria-multiselectable，aria-labelledby 指向栏标题',
+      '条目 role=option + aria-selected + aria-disabled，roving tabindex（每个 listbox 单一 Tab 停靠点）',
+      '列内键盘：↑↓ 漫游、Home/End 跳首末、Space 切换勾选、Shift+↑↓/Shift+Click 范围选择、Enter 移动到对侧',
+      '移动后焦点保留在源列表相邻 option；移动经 useLiveAnnouncer 播报',
+      '移动按钮有 aria-label；分组/树面板保留原 Checkbox 语义',
+    ],
+  },
+  tokens: ['--cd-transfer-*', '--cd-focus-ring', '--cd-color-*', '--cd-spacing-*'],
+} as const;

package/src/transfer/reorder.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest';
+import { computeInsertSide, reorder } from './reorder.js';
+
+describe('transfer/computeInsertSide', () => {
+  it('上半区 → before，下半区 → after，中线归 after', () => {
+    expect(computeInsertSide(0, 40)).toBe('before');
+    expect(computeInsertSide(19, 40)).toBe('before');
+    expect(computeInsertSide(20, 40)).toBe('after');
+    expect(computeInsertSide(39, 40)).toBe('after');
+  });
+});
+
+describe('transfer/reorder', () => {
+  const base = ['a', 'b', 'c', 'd'];
+
+  it('前移：把 c 放到 a 之前', () => {
+    expect(reorder(base, 2, 0, 'before')).toEqual(['c', 'a', 'b', 'd']);
+  });
+
+  it('后移：把 a 放到 c 之后', () => {
+    expect(reorder(base, 0, 2, 'after')).toEqual(['b', 'c', 'a', 'd']);
+  });
+
+  it('相邻互换：a 放到 b 之后', () => {
+    expect(reorder(base, 0, 1, 'after')).toEqual(['b', 'a', 'c', 'd']);
+  });
+
+  it('移动后位置不变 → 返回浅拷贝且等值', () => {
+    const out = reorder(base, 1, 1, 'before');
+    expect(out).toEqual(base);
+    expect(out).not.toBe(base);
+  });
+
+  it('放到自身之后等价于不动', () => {
+    expect(reorder(base, 1, 0, 'after')).toEqual(base);
+  });
+
+  it('越界返回浅拷贝', () => {
+    expect(reorder(base, -1, 2, 'before')).toEqual(base);
+    expect(reorder(base, 0, 9, 'after')).toEqual(base);
+  });
+
+  it('不可变：不修改入参', () => {
+    const copy = base.slice();
+    reorder(base, 0, 3, 'after');
+    expect(base).toEqual(copy);
+  });
+
+  it('末位拖到首位之前', () => {
+    expect(reorder(base, 3, 0, 'before')).toEqual(['d', 'a', 'b', 'c']);
+  });
+});

package/src/transfer/reorder.ts

@@ -0,0 +1,42 @@
+/**
+ * Transfer 目标列拖拽重排的纯函数 (红线 #2)：不触碰组件状态，仅做数组计算，便于单测。
+ * 目标列为垂直列表，故插入侧以指针在目标项内的「垂直」位置判定。
+ */
+
+/** dragover 时根据指针在目标项内的垂直位置判断插入在其「前」或「后」。 */
+export type InsertSide = 'before' | 'after';
+
+/**
+ * 以目标项中线为界：指针在上半区插入到目标之前，下半区插入到目标之后。
+ * @param offsetY 指针相对目标项上边缘的垂直偏移
+ * @param height 目标项高度
+ */
+export function computeInsertSide(offsetY: number, height: number): InsertSide {
+  return offsetY < height / 2 ? 'before' : 'after';
+}
+
+/**
+ * 把 `from` 处的元素移动到目标 `to` 的 `before`/`after` 侧，返回新数组（不可变）。
+ * 越界或目标即自身（移动后位置不变）时原样返回原数组的浅拷贝。
+ */
+export function reorder<T>(
+  list: readonly T[],
+  from: number,
+  to: number,
+  side: InsertSide,
+): T[] {
+  const n = list.length;
+  if (from < 0 || from >= n || to < 0 || to >= n) return list.slice();
+
+  // 目标插入下标（在「移除 from 之前」的坐标系中）。
+  let insert = side === 'before' ? to : to + 1;
+  // 移除被拖项后，位于其右侧的插入点需左移一位。
+  if (from < insert) insert -= 1;
+
+  if (insert === from) return list.slice();
+
+  const next = list.slice();
+  const removed = next.splice(from, 1);
+  next.splice(insert, 0, ...removed);
+  return next;
+}

package/src/transfer/tree.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest';
+import { collectLeafKeys, flattenLeaves, isTreeData } from './tree.js';
+import type { TransferItem, TransferTreeNode } from './types.js';
+
+describe('transfer/tree', () => {
+  const tree: TransferTreeNode[] = [
+    {
+      key: 'east',
+      label: '华东',
+      children: [
+        { key: 'hz', label: '杭州' },
+        { key: 'sh', label: '上海' },
+      ],
+    },
+    {
+      key: 'south',
+      label: '华南',
+      disabled: true,
+      children: [{ key: 'gz', label: '广州' }],
+    },
+    { key: 'solo', label: '独立项' },
+  ];
+  const flat: TransferItem[] = [
+    { key: 'a', label: '北京' },
+    { key: 'b', label: '上海' },
+  ];
+
+  it('isTreeData detects tree vs flat', () => {
+    expect(isTreeData(tree)).toBe(true);
+    expect(isTreeData(flat)).toBe(false);
+    expect(isTreeData([])).toBe(false);
+  });
+
+  it('collectLeafKeys returns only leaves in document order', () => {
+    expect(collectLeafKeys(tree)).toEqual(['hz', 'sh', 'gz', 'solo']);
+  });
+
+  it('flattenLeaves returns leaf items and inherits parent disabled', () => {
+    const leaves = flattenLeaves(tree);
+    expect(leaves.map((l) => l.key)).toEqual(['hz', 'sh', 'gz', 'solo']);
+    expect(leaves.find((l) => l.key === 'gz')?.disabled).toBe(true);
+    expect(leaves.find((l) => l.key === 'hz')?.disabled).toBe(false);
+  });
+});

package/src/transfer/tree.ts

@@ -0,0 +1,52 @@
+import type { TransferItem, TransferTreeNode } from './types.js';
+
+type Key = string | number;
+
+/**
+ * A tree data source is an array whose entries carry `children` somewhere, or
+ * more precisely: entries that look like tree nodes (have `key`+`label`) AND at
+ * least one of them declares a `children` field. We accept a single root with
+ * children too. Flat `TransferItem[]` has no `children`, so this stays false and
+ * backward-compatible behavior is untouched.
+ */
+export function isTreeData(
+  dataSource: readonly unknown[],
+): dataSource is TransferTreeNode[] {
+  return dataSource.some(
+    (n) =>
+      !!n &&
+      typeof n === 'object' &&
+      Array.isArray((n as TransferTreeNode).children),
+  );
+}
+
+/** Collect the keys of all leaf nodes (no children) under the tree, in order. */
+export function collectLeafKeys(data: readonly TransferTreeNode[]): Key[] {
+  const out: Key[] = [];
+  function walk(nodes: readonly TransferTreeNode[]): void {
+    for (const node of nodes) {
+      if (node.children && node.children.length > 0) walk(node.children);
+      else out.push(node.key);
+    }
+  }
+  walk(data);
+  return out;
+}
+
+/**
+ * Flatten the tree into a flat `TransferItem[]` of leaves only (the migratable
+ * units), preserving document order. Used to render the target panel and to map
+ * a leaf key back to its label.
+ */
+export function flattenLeaves(data: readonly TransferTreeNode[]): TransferItem[] {
+  const out: TransferItem[] = [];
+  function walk(nodes: readonly TransferTreeNode[], parentDisabled: boolean): void {
+    for (const node of nodes) {
+      const disabled = parentDisabled || !!node.disabled;
+      if (node.children && node.children.length > 0) walk(node.children, disabled);
+      else out.push({ key: node.key, label: node.label, disabled });
+    }
+  }
+  walk(data, false);
+  return out;
+}

package/src/transfer/types.ts

@@ -0,0 +1,32 @@
+export interface TransferItem {
+  key: string | number;
+  label: string;
+  disabled?: boolean;
+  /** Optional group name; items sharing a group render under one group header. */
+  group?: string;
+}
+
+/** Grouped data source: each group renders a header + its items. */
+export interface TransferGroup {
+  /** Group title shown as the group header. */
+  title: string;
+  items: TransferItem[];
+}
+
+/** A computed group used for rendering one panel side. */
+export interface TransferRenderGroup {
+  title: string;
+  items: TransferItem[];
+}
+
+/**
+ * Tree data source node (`treeList`): the source panel renders a tree. Checking a
+ * parent conducts to all enabled leaf descendants; only leaf keys are migrated to
+ * the target panel (which stays flat). A node with `children` is a parent.
+ */
+export interface TransferTreeNode {
+  key: string | number;
+  label: string;
+  disabled?: boolean;
+  children?: TransferTreeNode[];
+}

package/src/tree/Tree.a11y.test.ts

@@ -0,0 +1,63 @@
+// Tree a11y：层级树控件。
+// 容器 role=tree（aria-multiselectable），每行 role=treeitem 含 aria-level/expanded/selected。
+import { describe, it, expect } from 'vitest';
+import { renderWithLocale, expectNoAxeViolations } from '../test-utils/a11y.js';
+import Tree from './Tree.svelte';
+
+const treeData = [
+  {
+    key: 'parent',
+    label: 'Parent',
+    children: [
+      { key: 'child-1', label: 'Child 1' },
+      { key: 'child-2', label: 'Child 2' },
+    ],
+  },
+  { key: 'leaf', label: 'Leaf' },
+];
+
+describe('Tree a11y', () => {
+  it('默认渲染：role=tree + treeitem，无 axe violations', async () => {
+    const { container } = renderWithLocale(Tree, {
+      props: { treeData, ariaLabel: 'File tree' },
+    });
+    const tree = container.querySelector('[role="tree"]');
+    expect(tree).not.toBeNull();
+    expect(tree?.getAttribute('aria-label')).toBe('File tree');
+    expect(container.querySelectorAll('[role="treeitem"]').length).toBeGreaterThanOrEqual(2);
+    await expectNoAxeViolations(container);
+  });
+
+  it('展开节点：aria-expanded 反映展开态 + aria-level', async () => {
+    const { container } = renderWithLocale(Tree, {
+      props: { treeData, ariaLabel: 'Tree', defaultExpandAll: true },
+    });
+    const expanded = container.querySelector('[role="treeitem"][aria-expanded="true"]');
+    expect(expanded?.textContent).toContain('Parent');
+    expect(expanded?.getAttribute('aria-level')).toBe('1');
+    // 展开后子节点可见，aria-level=2
+    const child = Array.from(container.querySelectorAll('[role="treeitem"]')).find((el) =>
+      el.textContent?.includes('Child 1'),
+    );
+    expect(child?.getAttribute('aria-level')).toBe('2');
+    await expectNoAxeViolations(container);
+  });
+
+  it('checkable：treeitem aria-checked + 容器 aria-multiselectable', async () => {
+    const { container } = renderWithLocale(Tree, {
+      props: { treeData, ariaLabel: 'Tree', checkable: true, defaultExpandAll: true },
+    });
+    expect(container.querySelector('[role="tree"]')?.getAttribute('aria-multiselectable')).toBe('true');
+    expect(container.querySelector('[role="treeitem"][aria-checked]')).not.toBeNull();
+    await expectNoAxeViolations(container);
+  });
+
+  it('选中态：selectable 节点 aria-selected', async () => {
+    const { container } = renderWithLocale(Tree, {
+      props: { treeData, ariaLabel: 'Tree', defaultValue: 'leaf' },
+    });
+    const selected = container.querySelector('[role="treeitem"][aria-selected="true"]');
+    expect(selected?.textContent).toContain('Leaf');
+    await expectNoAxeViolations(container);
+  });
+});

package/src/tree/Tree.kbd.test.ts

@@ -0,0 +1,91 @@
+// Tree 键盘 e2e（browser project / 真实 chromium），aria-activedescendant 模型。
+// Tree 遵循 WAI-ARIA APG Tree View：单一 tab stop（role=tree 容器 tabindex=0）+
+// aria-activedescendant 漫游。焦点恒留在容器上，treeitem tabindex=-1 从不真实聚焦，
+// 高亮由容器 aria-activedescendant 指向的 treeitem id 表达。故断言 activedescendant
+// 指向的 treeitem 文本变化，而非 toHaveFocus（参照 TreeSelect 样板）。
+//   1. 容器真实聚焦后首次 ↓ 高亮首项；↑↓ 相邻移动；Home/End 跳可见列表首/末。
+//   2. typeahead：输入字符按 label 前缀跳到匹配节点（核心价值）。
+//   3. `*` 展开当前层级全部可展开同级节点（这里仅 Date 可展开 → 其子节点变可见）。
+import { describe, it, expect } from 'vitest';
+import { page } from 'vitest/browser';
+import { renderKbdFixture, userEvent } from '../test-utils/kbd.js';
+import TreeKbdFixture from './TreeKbdFixture.svelte';
+
+function loc(el: Element) {
+  return page.elementLocator(el);
+}
+
+// typeahead 缓冲超时为 600ms：连续按键在缓冲内累积为前缀（c+b → 'cb' 无匹配）。
+// 测「单字符独立跳转」须在每次跳转间等待缓冲清空，故 sleep > 超时。
+const TYPEAHEAD_TIMEOUT = 600;
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+// 读 role=tree 容器 aria-activedescendant 指向的 treeitem，断言其可见 label 文本。
+function activeNodeText(tree: HTMLElement): string | null {
+  const id = tree.getAttribute('aria-activedescendant');
+  if (!id) return null;
+  const el = document.getElementById(id);
+  // label 在 .cd-tree__label 内（含 switcher/icon 等兄弟），只取 label 文本。
+  return el?.querySelector('.cd-tree__label')?.textContent?.trim() ?? null;
+}
+
+describe('Tree 键盘 e2e（aria-activedescendant roving + typeahead）', () => {
+  it('容器聚焦 + ↑↓/Home/End 移高亮（activedescendant）', async () => {
+    const { baseElement } = renderKbdFixture(TreeKbdFixture);
+
+    const tree = baseElement.querySelector('[role="tree"]') as HTMLElement;
+    expect(tree).not.toBeNull();
+    expect(tree.tabIndex).toBe(0);
+    const items = Array.from(tree.querySelectorAll<HTMLElement>('[role="treeitem"]'));
+    // 顶层 4 项可见（Date 未展开）。
+    expect(items.length).toBe(4);
+    expect(items.every((n) => n.tabIndex === -1)).toBe(true);
+
+    // 容器真实聚焦（单一 tab stop）。
+    tree.focus();
+    await expect.element(loc(tree)).toHaveFocus();
+
+    // 1. 首次 ↓ 高亮首项 Apple。
+    await userEvent.keyboard('{ArrowDown}');
+    expect(activeNodeText(tree)).toBe('Apple');
+    await userEvent.keyboard('{ArrowDown}');
+    expect(activeNodeText(tree)).toBe('Banana');
+    await userEvent.keyboard('{ArrowUp}');
+    expect(activeNodeText(tree)).toBe('Apple');
+
+    // End 跳末项 Date；Home 回首项 Apple。焦点始终在容器上（activedescendant 模型）。
+    await userEvent.keyboard('{End}');
+    expect(activeNodeText(tree)).toBe('Date');
+    await userEvent.keyboard('{Home}');
+    expect(activeNodeText(tree)).toBe('Apple');
+    await expect.element(loc(tree)).toHaveFocus();
+  });
+
+  it('typeahead 输入字符跳到首字母匹配节点 + `*` 展开同级', async () => {
+    const { baseElement } = renderKbdFixture(TreeKbdFixture);
+
+    const tree = baseElement.querySelector('[role="tree"]') as HTMLElement;
+    tree.focus();
+    await expect.element(loc(tree)).toHaveFocus();
+
+    // 2. typeahead：无活动项时输入 'c' → 跳到 Cherry。
+    await userEvent.keyboard('c');
+    expect(activeNodeText(tree)).toBe('Cherry');
+    // 等缓冲清空后输入 'b' → 跳到 Banana（否则 'c'+'b' 累积为前缀 'cb' 无匹配）。
+    await sleep(TYPEAHEAD_TIMEOUT + 100);
+    await userEvent.keyboard('b');
+    expect(activeNodeText(tree)).toBe('Banana');
+    // 等缓冲清空后输入 'd' → 跳到 Date。
+    await sleep(TYPEAHEAD_TIMEOUT + 100);
+    await userEvent.keyboard('d');
+    expect(activeNodeText(tree)).toBe('Date');
+
+    // 3. `*` 展开当前层级全部可展开同级：Date 展开 → 子节点 Deglet/Medjool 可见。
+    await userEvent.keyboard('*');
+    const labels = Array.from(
+      tree.querySelectorAll<HTMLElement>('.cd-tree__label'),
+    ).map((n) => n.textContent?.trim());
+    expect(labels).toContain('Deglet');
+    expect(labels).toContain('Medjool');
+  });
+});