@chenzy-design/svelte 0.1.0

package/dist/transfer/Transfer.svelte.d.ts

@@ -0,0 +1,129 @@
+import type { Snippet } from 'svelte';
+import type { TransferGroup, TransferItem, TransferTreeNode } from './types.js';
+type TransferKey = string | number;
+type Size = 'small' | 'default' | 'large';
+type Status = 'default' | 'warning' | 'error';
+type TransferType = 'list' | 'groupList' | 'treeList';
+/** emptyContent: custom empty state renderers */
+interface EmptyContent {
+    left?: Snippet | string;
+    right?: Snippet | string;
+    search?: Snippet | string;
+}
+/** pagination config for left panel */
+interface PaginationConfig {
+    pageSize?: number;
+    currentPage?: number;
+    defaultCurrentPage?: number;
+    onPageChange?: (page: number) => void;
+}
+/** Source panel header render args */
+interface SourceHeaderProps {
+    totalContent: string;
+    allContent: string;
+    onAllClick: () => void;
+    title: string;
+    allChecked: boolean;
+    showButton: boolean;
+    leafOnlyNum?: number | undefined;
+}
+/** Selected panel header render args */
+interface SelectedHeaderProps {
+    totalContent: string;
+    allContent: string;
+    onAllClick: () => void;
+    title: string;
+}
+/** renderSourcePanel args */
+interface SourcePanelProps {
+    dataSource: TransferItem[];
+    selectedItems: TransferItem[];
+    onChange: (keys: TransferKey[]) => void;
+    onSearch: (v: string) => void;
+    inputValue: string;
+    searchResult: TransferItem[];
+}
+/** renderSelectedPanel args */
+interface SelectedPanelProps {
+    selectedItems: TransferItem[];
+    onRemove: (key: TransferKey) => void;
+    onSortEnd: (keys: TransferKey[]) => void;
+}
+interface Props {
+    value?: TransferKey[];
+    defaultValue?: TransferKey[];
+    dataSource?: TransferItem[] | TransferGroup[] | TransferTreeNode[];
+    /** 'list' | 'groupList' | 'treeList' — controls source panel render mode. */
+    type?: TransferType;
+    filter?: boolean;
+    searchPlaceholder?: string;
+    size?: Size;
+    status?: Status;
+    disabled?: boolean;
+    showPanelTitle?: boolean;
+    titles?: [string, string];
+    /** Left→right only: target rows get a remove button, no right→left batch. */
+    oneWay?: boolean;
+    /**
+     * Reorder target (selected) rows by mouse drag (HTML5 DnD). New order is
+     * propagated only via `onChange` (controlled `value` is never written).
+     * Ignored in tree mode (target panel stays flat but DnD reorder applies).
+     */
+    draggable?: boolean;
+    /**
+     * Virtualize both flat panels: render only the in-viewport slice for large
+     * lists. Reuses core `fixedRange`. Ignored for grouped/tree source panels.
+     */
+    virtualize?: boolean;
+    /** Virtualized row height (px, default 32); must match the real row height. */
+    itemHeight?: number;
+    /**
+     * Remote search: providing this switches to remote mode — input is debounced
+     * (`searchDebounce` ms) then this is called with the query and which panel
+     * fired it; the parent updates `dataSource`, local filtering is skipped.
+     */
+    onSearch?: (query: string, direction: 'left' | 'right') => void;
+    /** Remote loading: shows a spinner row in each panel list. */
+    loading?: boolean;
+    /** onSearch debounce in ms (default 300). */
+    searchDebounce?: number;
+    onChange?: (targetKeys: TransferKey[]) => void;
+    /** Custom empty state renderers for left/right/search empty states. */
+    emptyContent?: EmptyContent;
+    /** Extra props passed to the search Input component. */
+    inputProps?: Record<string, unknown>;
+    /** Props passed to the Tree component when type='treeList'. */
+    treeProps?: Record<string, unknown>;
+    /** When type='treeList', show full path in right panel selected items. */
+    showPath?: boolean;
+    /** Left panel pagination config (only for list/groupList). */
+    pagination?: PaginationConfig;
+    /** Called when a single item is checked (not bulk select). */
+    onSelect?: (item: TransferItem) => void;
+    /** Called when a single item is unchecked (not bulk select). */
+    onDeselect?: (item: TransferItem) => void;
+    /** Custom render for left panel source items. */
+    renderSourceItem?: Snippet<[{
+        item: TransferItem;
+        onChange: () => void;
+        checked: boolean;
+    }]>;
+    /** Custom render for right panel selected items. */
+    renderSelectedItem?: Snippet<[{
+        item: TransferItem;
+        onRemove: () => void;
+        sortableHandle?: unknown;
+    }]>;
+    /** Custom render for left panel header. */
+    renderSourceHeader?: Snippet<[SourceHeaderProps]>;
+    /** Custom render for right panel header. */
+    renderSelectedHeader?: Snippet<[SelectedHeaderProps]>;
+    /** Fully custom left panel renderer. */
+    renderSourcePanel?: Snippet<[SourcePanelProps]>;
+    /** Fully custom right panel renderer. */
+    renderSelectedPanel?: Snippet<[SelectedPanelProps]>;
+}
+declare const Transfer: import("svelte").Component<Props, {}, "">;
+type Transfer = ReturnType<typeof Transfer>;
+export default Transfer;
+//# sourceMappingURL=Transfer.svelte.d.ts.map

package/dist/transfer/Transfer.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Transfer.svelte.d.ts","sourceRoot":"","sources":["../../src/transfer/Transfer.svelte.ts"],"names":[],"mappings":"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"}

package/dist/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/dist/transfer/TransferKbdFixture.svelte.d.ts

@@ -0,0 +1,4 @@
+declare const TransferKbdFixture: import("svelte").Component<Record<string, never>, {}, "">;
+type TransferKbdFixture = ReturnType<typeof TransferKbdFixture>;
+export default TransferKbdFixture;
+//# sourceMappingURL=TransferKbdFixture.svelte.d.ts.map

package/dist/transfer/TransferKbdFixture.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TransferKbdFixture.svelte.d.ts","sourceRoot":"","sources":["../../src/transfer/TransferKbdFixture.svelte.ts"],"names":[],"mappings":"AA2BA,QAAA,MAAM,kBAAkB,2DAAwC,CAAC;AACjE,KAAK,kBAAkB,GAAG,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAChE,eAAe,kBAAkB,CAAC"}

package/dist/transfer/group.d.ts

@@ -0,0 +1,20 @@
+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 declare function normalizeData(dataSource: TransferItem[] | TransferGroup[]): TransferItem[];
+/** A grouped data source is an array whose entries have `items` (not `key`). */
+export declare function isGrouped(dataSource: TransferItem[] | TransferGroup[]): dataSource is TransferGroup[];
+/**
+ * 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 declare function buildGroups(items: TransferItem[], fallbackTitle: string): TransferRenderGroup[];
+/** True when any normalized item carries a `group` tag. */
+export declare function hasGroups(items: TransferItem[]): boolean;
+//# sourceMappingURL=group.d.ts.map

package/dist/transfer/group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"group.d.ts","sourceRoot":"","sources":["../../src/transfer/group.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEnF;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,YAAY,EAAE,GAAG,aAAa,EAAE,GAC3C,YAAY,EAAE,CAShB;AAED,gFAAgF;AAChF,wBAAgB,SAAS,CACvB,UAAU,EAAE,YAAY,EAAE,GAAG,aAAa,EAAE,GAC3C,UAAU,IAAI,aAAa,EAAE,CAM/B;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,YAAY,EAAE,EACrB,aAAa,EAAE,MAAM,GACpB,mBAAmB,EAAE,CAcvB;AAED,2DAA2D;AAC3D,wBAAgB,SAAS,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,OAAO,CAExD"}

package/dist/transfer/group.js

@@ -0,0 +1,48 @@
+/**
+ * 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) {
+    if (isGrouped(dataSource)) {
+        const out = [];
+        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) {
+    return (dataSource.length > 0 &&
+        Array.isArray(dataSource[0].items) &&
+        dataSource[0].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, fallbackTitle) {
+    const order = [];
+    const map = new Map();
+    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) {
+    return items.some((i) => i.group !== undefined);
+}

package/dist/transfer/group.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=group.test.d.ts.map

package/dist/transfer/group.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"group.test.d.ts","sourceRoot":"","sources":["../../src/transfer/group.test.ts"],"names":[],"mappings":""}

package/dist/transfer/group.test.js

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import { buildGroups, hasGroups, isGrouped, normalizeData } from './group.js';
+describe('transfer/group', () => {
+    const flat = [
+        { key: 'a', label: '北京' },
+        { key: 'b', label: '上海' },
+    ];
+    const grouped = [
+        { 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 = [
+            { 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/dist/transfer/index.d.ts

@@ -0,0 +1,4 @@
+export { default as Transfer } from './Transfer.svelte';
+export { meta as transferMeta } from './meta.js';
+export type { TransferItem, TransferGroup, TransferTreeNode } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/transfer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/transfer/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,WAAW,CAAC;AACjD,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC"}

package/dist/transfer/index.js

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

package/dist/transfer/meta.d.ts

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

package/dist/transfer/meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.d.ts","sourceRoot":"","sources":["../../src/transfer/meta.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkDP,CAAC"}

package/dist/transfer/meta.js

@@ -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-*'],
+};

package/dist/transfer/reorder.d.ts

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

package/dist/transfer/reorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reorder.d.ts","sourceRoot":"","sources":["../../src/transfer/reorder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,6CAA6C;AAC7C,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE5C;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAE7E;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,CAAC,EACvB,IAAI,EAAE,SAAS,CAAC,EAAE,EAClB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,UAAU,GACf,CAAC,EAAE,CAeL"}

package/dist/transfer/reorder.js

@@ -0,0 +1,32 @@
+/**
+ * Transfer 目标列拖拽重排的纯函数 (红线 #2)：不触碰组件状态，仅做数组计算，便于单测。
+ * 目标列为垂直列表，故插入侧以指针在目标项内的「垂直」位置判定。
+ */
+/**
+ * 以目标项中线为界：指针在上半区插入到目标之前，下半区插入到目标之后。
+ * @param offsetY 指针相对目标项上边缘的垂直偏移
+ * @param height 目标项高度
+ */
+export function computeInsertSide(offsetY, height) {
+    return offsetY < height / 2 ? 'before' : 'after';
+}
+/**
+ * 把 `from` 处的元素移动到目标 `to` 的 `before`/`after` 侧，返回新数组（不可变）。
+ * 越界或目标即自身（移动后位置不变）时原样返回原数组的浅拷贝。
+ */
+export function reorder(list, from, to, side) {
+    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/dist/transfer/reorder.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=reorder.test.d.ts.map

package/dist/transfer/reorder.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reorder.test.d.ts","sourceRoot":"","sources":["../../src/transfer/reorder.test.ts"],"names":[],"mappings":""}