@chenzy-design/svelte 0.3.1 → 0.4.1

package/dist/list/List.svelte

@@ -1,920 +1,253 @@
 <!--
-  List — see specs/components/show/List.spec.md
-  基础子集：dataSource + renderItem、header/footer（string|Snippet）、bordered/split、
-    loading（骨架/spinner）、empty、loadMore（内置按钮/自定义）、grid 网格布局。
-  pagination：复用 Pagination 组件，对 dataSource 切片渲染当页（受控 current 不回写，红线 #1）。
-  进阶子集：
-    - 虚拟化（virtualized）：大数据只渲染视口内行，复用 core fixedRange/dynamicRange/
-      scrollOffsetForIndex（与 VirtualList 同一套区间数学）。命令式滚动监听 + rAF 节流 +
-      cleanup（红线 #3）；区间/总高纯 $derived，仅依赖本地 $state（红线 #2）。virtualized
-      与 grid/pagination 互斥（优先生效，对全量 dataSource 虚拟化）。
-    - selectable（'single'|'multiple'）：行可选，选中态受控 selectedKeys + onSelectionChange，
-      不回写仅回调（红线 #1）。容器 role=listbox（multiple 时 aria-multiselectable），
-      行 role=option + aria-selected。shift 连选（multiple）。
-    - 声明式 List.Item / List.Item.Meta：不传 dataSource 时渲染 children（内嵌 <List.Item>），
-      通过 context 暴露 selectable 状态给子项（getter 保持响应性，子项不写 $state，避免
-      effect 自循环——红线 #2）。
+  List — 严格对齐 Semi Design（@douyinfe/semi-ui/list）。
+  DOM/API/class/token 一比一镜像 semi-ui/list/index.tsx + semi-foundation/list/list.scss。
+
+  API（与 Semi List 完全一致）：
+    bordered / className(class) / dataSource / renderItem / emptyContent / footer /
+    header / layout('vertical'|'horizontal') / loadMore / loading / size / split /
+    style / onClick / onRightClick / children。
+    grid：复用 Grid（Row/Col），gutter/align/justify/wrap → Row，span/offset/xs.. → Col。
+    loading：复用 Spin 包裹列表体。emptyContent 缺省回退 locale List.emptyText。
+
+  结构：<div.cd-list [-flex|-size|-grid|-split|-bordered]>
+          <div.cd-list-header>?  →  Spin{ Row|ul.cd-list-items{ items|children } }  →  <div.cd-list-footer>?  →  loadMore?
+
+  破坏性重写（无向后兼容）：移除 selectable/virtualized/pagination/skeleton/rowKey/
+  List.Meta 等 Semi List 本体不存在的能力——这些在 Semi 里都是组合其他组件/第三方库的
+  demo，不是 List 组件的 prop。
 -->
 <script lang="ts" generics="T">
-  import { untrack, type Snippet } from 'svelte';
-  import {
-    fixedRange,
-    buildOffsets,
-    totalFromOffsets,
-    dynamicRange,
-    scrollOffsetForIndex,
-    toggleSelection,
-    rangeSelection,
-    useLiveAnnouncer,
-    type ScrollAlign,
-    type ListKey,
-  } from '@chenzy-design/core';
-  import Empty from '../empty/Empty.svelte';
-  import { Button } from '../button/index.js';
-  import { Pagination } from '../pagination/index.js';
+  import type { Snippet } from 'svelte';
+  import { Row } from '../grid/index.js';
+  import Spin from '../spin/Spin.svelte';
   import { useLocale } from '../locale-provider/index.js';
-  import { setListContext } from './context.js';
+  import { setListContext, type ListGrid } from './context.js';
 
   type ListSize = 'small' | 'default' | 'large';
-  type GridConfig = number | { column?: number; gutter?: number };
-  type SelectableMode = false | 'single' | 'multiple';
-  type VirtualConfig = {
-    /** 行高（px），默认 40；传 'auto' 启用动态测高。 */
-    itemSize?: number | 'auto';
-    /** 动态测高初始估算行高（px）。 */
-    estimatedItemSize?: number;
-    /** 视口高度（px 数字，或 CSS 字符串如 '60vh'）。 */
-    height: number | string;
-    /** 上下缓冲行数，默认 3。 */
-    overscan?: number;
-  };
+  type Layout = 'vertical' | 'horizontal';
 
-  // 泛型组件 props 用内联类型而非具名 interface Props：在 declaration:true 下，
-  // 引用泛型参数 T 的具名 interface 会被当作私有名泄漏进生成的 .d.ts 公共签名而报错。
+  // 泛型组件 props 用内联类型而非具名 interface：declaration:true 下引用泛型 T 的
+  // 具名 interface 会被当作私有名泄漏进 .d.ts 公共签名而报错。
   let {
-    dataSource = [],
-    renderItem,
-    rowKey = 'key',
-    size = 'default',
     bordered = false,
-    split = true,
-    header,
+    dataSource,
+    renderItem,
+    emptyContent,
     footer,
+    header,
+    layout = 'vertical',
+    loadMore,
     loading = false,
-    loadingSkeleton = false,
-    skeletonCount = 3,
-    emptyContent,
+    size = 'default',
+    split = true,
     grid,
-    loadMore,
-    onLoadMore,
-    loadingMore = false,
-    hasMore = false,
-    pagination,
-    virtualized = false,
-    selectable = false,
-    selectedKeys,
-    defaultSelectedKeys = [],
-    onSelectionChange,
-    ariaLabel,
+    style,
+    onClick,
+    onRightClick,
     children,
-    layout = 'vertical',
-    onListScroll,
     class: className = '',
   }: {
+    /** 是否显示外框。 */
+    bordered?: boolean;
+    /** 列表数据源。 */
     dataSource?: T[];
+    /** 使用 dataSource 时自定义渲染列表项。 */
     renderItem?: Snippet<[item: T, index: number]>;
-    rowKey?: string | ((item: T) => string | number);
-    size?: ListSize;
-    bordered?: boolean;
-    split?: boolean;
-    header?: string | Snippet;
-    footer?: string | Snippet;
-    loading?: boolean;
-    loadingSkeleton?: boolean;
-    skeletonCount?: number;
+    /** 空列表展示内容（string 或 Snippet），缺省回退 locale List.emptyText。 */
     emptyContent?: string | Snippet;
-    /** 网格布局：列数或 { column, gutter } */
-    grid?: GridConfig;
-    /** 自定义底部加载区（优先于内置按钮） */
+    /** 列表底部（string 或 Snippet）。 */
+    footer?: string | Snippet;
+    /** 列表头部（string 或 Snippet）。 */
+    header?: string | Snippet;
+    /** 列表布局：vertical（默认）/ horizontal。 */
+    layout?: Layout;
+    /** 加载更多按钮区（Snippet）。 */
     loadMore?: Snippet;
-    /** 内置「加载更多」按钮回调 */
-    onLoadMore?: () => void;
-    /** 内置按钮 loading 态 */
-    loadingMore?: boolean;
-    /** 是否还有更多（控制内置按钮显隐） */
-    hasMore?: boolean;
-    /** 分页：复用 Pagination，对 dataSource 切片渲染当页（与 loadMore 互斥，优先生效） */
-    pagination?:
-      | false
-      | {
-          pageSize?: number;
-          current?: number;
-          defaultCurrent?: number;
-          onChange?: (page: number) => void;
-        };
-    /** 虚拟化：大数据只渲染视口内行（与 grid/pagination 互斥，优先生效）。 */
-    virtualized?: false | VirtualConfig;
-    /** 行可选：'single' 单选 / 'multiple' 多选。 */
-    selectable?: SelectableMode;
-    /** 受控选中 key 集合（不回写，仅 onSelectionChange 回调，红线 #1）。 */
-    selectedKeys?: ListKey[];
-    /** 非受控初始选中 key 集合。 */
-    defaultSelectedKeys?: ListKey[];
-    /** 选中态变更回调（受控/非受控均触发）。 */
-    onSelectionChange?: (
-      keys: ListKey[],
-      info: { item: T | undefined; key: ListKey; selected: boolean },
-    ) => void;
-    /** selectable 模式 listbox 容器可访问名（缺省回退 i18n List.selectableLabel）。 */
-    ariaLabel?: string;
-    /** 声明式用法：内嵌 <List.Item>（不传 dataSource 时生效）。 */
+    /** 是否处于加载中，为 true 时列表体外包裹 Spin。 */
+    loading?: boolean;
+    /** 列表尺寸：small / default / large。 */
+    size?: ListSize;
+    /** 是否展示分割线。 */
+    split?: boolean;
+    /** 栅格配置：复用 Grid（Row/Col），传入即启用栅格列表。 */
+    grid?: ListGrid;
+    /** 根容器行内样式。 */
+    style?: string;
+    /** 列表项点击回调（经 context 下发给 Item 作为回退）。 */
+    onClick?: (e: MouseEvent) => void;
+    /** 列表项右键回调（经 context 下发给 Item 作为回退）。 */
+    onRightClick?: (e: MouseEvent) => void;
+    /** 声明式用法：直接内嵌 <List.Item>（不传 dataSource 时）。 */
     children?: Snippet;
-    /** 整体布局方向：'vertical'（默认）每 item 内容纵向排列；'horizontal' 横向排列。 */
-    layout?: 'horizontal' | 'vertical';
-    /** 列表容器滚动事件。 */
-    onListScroll?: (e: Event) => void;
+    /** 根类名。 */
     class?: string;
   } = $props();
 
   const loc = useLocale();
-  // 单例 live region（polite）：selectable 模式选中/取消时播报（红线 #3：命令式）。
-  const announcer = useLiveAnnouncer();
 
   function isSnippet(v: unknown): v is Snippet {
     return typeof v === 'function';
   }
 
-  function keyOf(item: T, index: number): string | number {
-    if (typeof rowKey === 'function') return rowKey(item);
-    const rec = item as unknown as Record<string, unknown>;
-    const k = rec?.[rowKey];
-    if (typeof k === 'string' || typeof k === 'number') return k;
-    return index;
-  }
-
-  // 声明式用法：未传 dataSource 且存在 children（内嵌 <List.Item>）。优先级低于 dataSource。
-  const useDeclarative = $derived(dataSource.length === 0 && children != null);
-
-  const isEmpty = $derived(!loading && !useDeclarative && dataSource.length === 0);
-  const skeletonRows = $derived(Array.from({ length: Math.max(0, skeletonCount) }, (_, i) => i));
-
-  // --- selectable 选中态：受控 selectedKeys 不回写，本地 inner 兜底（红线 #1） ---
-  const selectMode = $derived<'single' | 'multiple' | null>(
-    selectable === 'single' || selectable === 'multiple' ? selectable : null,
-  );
-  const isSelectControlled = $derived(selectedKeys !== undefined);
-  let innerSelected = $state<ListKey[]>(untrack(() => [...defaultSelectedKeys]));
-  // 当前选中集合（受控优先）；用 Set 做 O(1) 命中判定（红线 #2：纯派生）。
-  const selectedSet = $derived<ReadonlySet<ListKey>>(
-    new Set(selectedKeys !== undefined ? selectedKeys : innerSelected),
-  );
-  // shift 连选锚点（普通簿记变量，不参与 render 响应式）。
-  let anchorIndex = -1;
-
-  function keyToItem(key: ListKey): T | undefined {
-    for (let i = 0; i < dataSource.length; i += 1) {
-      const it = dataSource[i]!;
-      if (keyOf(it, i) === key) return it;
-    }
-    return undefined;
-  }
-
-  // 命令式选中切换：算出下一集合 → 仅回调 onSelectionChange（受控不回写，红线 #1）。
-  function toggleKey(key: ListKey, shiftKey: boolean): void {
-    if (!selectMode) return;
-    let next: Set<ListKey>;
-    if (shiftKey && selectMode === 'multiple' && anchorIndex >= 0) {
-      const orderedKeys = dataSource.map((it, i) => keyOf(it, i));
-      const targetIndex = orderedKeys.indexOf(key);
-      next = rangeSelection(selectedSet, orderedKeys, anchorIndex, targetIndex);
-    } else {
-      next = toggleSelection(selectedSet, key, selectMode);
-      // 仅非 shift 单击更新锚点。
-      if (selectMode === 'multiple') {
-        anchorIndex = dataSource.findIndex((it, i) => keyOf(it, i) === key);
-      }
-    }
-    const selected = next.has(key);
-    if (!isSelectControlled) innerSelected = [...next];
-    onSelectionChange?.([...next], { item: keyToItem(key), key, selected });
-    // polite 播报当前操作项的选中/取消状态。label 取常见文本字段，回退到 key。
-    const label = selectionLabel(key);
-    announcer.announce(
-      loc().t(selected ? 'List.selectAnnounce' : 'List.deselectAnnounce', { label }),
-    );
-  }
-
-  // 选中播报用可读名：优先 item 的字符串本体或 label/title/name 字段，回退到 key。
-  function selectionLabel(key: ListKey): string {
-    const item = keyToItem(key);
-    if (typeof item === 'string' || typeof item === 'number') return String(item);
-    const rec = item as unknown as Record<string, unknown> | undefined;
-    const text = rec?.label ?? rec?.title ?? rec?.name;
-    if (typeof text === 'string' || typeof text === 'number') return String(text);
-    return String(key);
-  }
-
-  // 向声明式 <List.Item> 暴露 selectable 状态（getter 保持响应性；红线 #2：子项不写 $state）。
-  setListContext({
-    getSelectable: () => selectable,
-    isSelected: (key) => selectedSet.has(key),
-    toggle: (key, shiftKey) => toggleKey(key, shiftKey),
-    getSize: () => size,
-    rowTabindex: (key) => itemTabindex(key),
-    onRowKeydown: (e, key) => onItemKeydown(e, key),
-    onRowFocus: (key) => onRowFocus(key),
-  });
-
-  // --- 虚拟化几何（复用 core 区间数学；红线 #2/#3） ---
-  const virtualOn = $derived(virtualized !== false && virtualized !== undefined);
-  const vCfg = $derived<VirtualConfig>(
-    virtualized && virtualized !== undefined
-      ? virtualized
-      : { height: 400 },
-  );
-  const vDynamic = $derived(virtualOn && vCfg.itemSize === 'auto');
-  const vItemSize = $derived(typeof vCfg.itemSize === 'number' ? vCfg.itemSize : 40);
-  const vEstimated = $derived(vCfg.estimatedItemSize ?? 40);
-  const vOverscan = $derived(vCfg.overscan ?? 3);
-  const vHeightStyle = $derived(
-    typeof vCfg.height === 'number' ? `${vCfg.height}px` : vCfg.height,
-  );
-
-  // viewport 元素普通引用（bind:this），不参与响应式几何读取。
-  let viewportEl = $state<HTMLDivElement | null>(null);
-  // 本地响应式状态：仅由命令式回调 / ResizeObserver 写入，render 期只读。
-  let vScrollTop = $state(0);
-  let vMeasuredH = $state(0);
-  let vHeights = $state<Record<number, number>>({});
-  let vRafId = 0;
-
-  // 有效视口高：number 直接用，字符串用测量值。
-  const vViewportH = $derived(
-    typeof vCfg.height === 'number' ? vCfg.height : vMeasuredH,
-  );
-
-  // dynamic：合并实测/估算每项高度 → 前缀和 offsets（render-safe，仅依赖 $state）。
-  const vOffsets = $derived.by(() => {
-    if (!vDynamic) return [] as number[];
-    const arr = new Array<number>(dataSource.length);
-    for (let i = 0; i < dataSource.length; i += 1) arr[i] = vHeights[i] ?? vEstimated;
-    return buildOffsets(arr);
+  const hasData = $derived(!!dataSource && dataSource.length > 0);
+  // 无数据且无声明式 children 时展示空态（对齐 Semi renderEmpty 触发条件）。
+  const showEmpty = $derived(!hasData && !children);
+
+  // grid 拆分：gutter/align/justify/wrap 归 Row；其余（span/offset/xs..）经 context 给 Col。
+  const rowProps = $derived.by(() => {
+    if (!grid) return undefined;
+    const { gutter, align, justify, wrap } = grid;
+    const p: Record<string, unknown> = {};
+    if (gutter !== undefined) p.gutter = gutter;
+    if (align !== undefined) p.align = align;
+    if (justify !== undefined) p.justify = justify;
+    if (wrap !== undefined) p.wrap = wrap;
+    return p;
   });
-  const vTotalHeight = $derived(
-    vDynamic ? totalFromOffsets(vOffsets) : dataSource.length * vItemSize,
-  );
-  const vRange = $derived(
-    vDynamic
-      ? dynamicRange(vOffsets, vScrollTop, vViewportH, vOverscan)
-      : fixedRange(vScrollTop, vViewportH, vItemSize, dataSource.length, vOverscan),
-  );
-  const vStart = $derived(vRange.startIndex);
-  const vEnd = $derived(vRange.endIndex);
-  const vVisible = $derived(dataSource.slice(vStart, vEnd));
 
-  function vItemOffset(index: number): number {
-    if (vDynamic) return vOffsets[index] ?? index * vEstimated;
-    return index * vItemSize;
-  }
-  function vItemMainSize(index: number): number {
-    if (vDynamic) return vHeights[index] ?? vEstimated;
-    return vItemSize;
-  }
-  function vItemStyle(index: number): string {
-    const off = vItemOffset(index);
-    if (vDynamic) return `transform:translateY(${off}px)`;
-    return `transform:translateY(${off}px); block-size:${vItemSize}px`;
-  }
-
-  /**
-   * 命令式滚动到指定索引项（红线 #3：直接写 DOM scrollTop，非 render 期）。
-   */
-  export function scrollToIndex(
-    index: number,
-    opts?: { align?: ScrollAlign },
-  ): void {
-    const el = viewportEl;
-    if (!el || !virtualOn || dataSource.length === 0) return;
-    const i = Math.max(0, Math.min(dataSource.length - 1, Math.floor(index)));
-    const totalMain = vDynamic ? totalFromOffsets(vOffsets) : dataSource.length * vItemSize;
-    const target = scrollOffsetForIndex(
-      vItemOffset(i),
-      vItemMainSize(i),
-      el.clientHeight,
-      totalMain,
-      opts?.align ?? 'start',
-    );
-    el.scrollTop = target;
-    vScrollTop = target;
-  }
-
-  // 虚拟化滚动监听（命令式 + rAF 节流 + cleanup；红线 #3）。
-  $effect(() => {
-    const el = viewportEl;
-    if (!el || !virtualOn) return;
-    function onScroll() {
-      if (vRafId) return;
-      vRafId = requestAnimationFrame(() => {
-        vRafId = 0;
-        if (el) vScrollTop = el.scrollTop;
-      });
-    }
-    el.addEventListener('scroll', onScroll, { passive: true });
-    return () => {
-      el.removeEventListener('scroll', onScroll);
-      if (vRafId) {
-        cancelAnimationFrame(vRafId);
-        vRafId = 0;
-      }
-    };
-  });
-
-  // 视口高度测量：仅 height 非数字（字符串）时启用 ResizeObserver。
-  $effect(() => {
-    const el = viewportEl;
-    if (!el || !virtualOn || typeof vCfg.height === 'number') return;
-    vMeasuredH = el.clientHeight;
-    const ro = new ResizeObserver((entries) => {
-      for (const entry of entries) vMeasuredH = entry.contentRect.height;
-    });
-    ro.observe(el);
-    return () => ro.disconnect();
-  });
-
-  // dynamic 行高实测 + 偏移补偿（命令式 ResizeObserver，cleanup disconnect；红线 #2/#3）。
-  $effect(() => {
-    const el = viewportEl;
-    if (!el || !virtualOn || !vDynamic) return;
-    void vVisible; // 依赖渲染行集合变化重建 observer。
-
-    function measure(node: Element) {
-      const idx = Number((node as HTMLElement).dataset.vindex);
-      if (Number.isNaN(idx)) return;
-      const h = (node as HTMLElement).getBoundingClientRect().height;
-      if (h <= 0) return;
-      const prev = vHeights[idx];
-      if (prev !== undefined && Math.abs(prev - h) < 0.5) return;
-      const before = prev ?? vEstimated;
-      const delta = h - before;
-      vHeights[idx] = h;
-      if (delta !== 0 && el && vItemOffset(idx) < vScrollTop) {
-        el.scrollTop += delta;
-        vScrollTop = el.scrollTop;
-      }
-    }
-
-    const ro = new ResizeObserver((entries) => {
-      for (const entry of entries) measure(entry.target);
-    });
-    const rows = el.querySelectorAll<HTMLElement>('[data-vindex]');
-    rows.forEach((node) => {
-      measure(node);
-      ro.observe(node);
-    });
-    return () => ro.disconnect();
-  });
-
-  // selectable 行点击/键盘（dataSource 模式用；声明式由 List.Item 自身处理）。
-  function onRowActivate(item: T, index: number, shiftKey: boolean): void {
-    toggleKey(keyOf(item, index), shiftKey);
-  }
-
-  // --- roving tabindex（a11y §6 / Listbox APG）：selectable 行组为单一 Tab 停靠点。 ---
-  // rootEl 普通引用（bind:this），命令式 focus() 用，非 render 期读 DOM；
-  // 声明式 / 虚拟化 / 普通三种渲染路径的行都带 data-list-key，统一按 DOM 顺序漫游
-  // （红线 #2：不用 $state 数组收集子项，避免 effect 自循环）。
-  let rootEl = $state<HTMLElement | null>(null);
-  // 当前焦点行的 key；null = 尚无焦点 -> 首行作为 Tab 停靠点。
-  let focusedRowKey = $state<ListKey | null>(null);
-
-  // selectable 模式下行的有序 key 列表（用于 roving 首末 / PageUp/Down 计算）。
-  const rowKeys = $derived<ListKey[]>(
-    selectMode ? dataSource.map((it, i) => keyOf(it, i)) : [],
-  );
-
-  // 纯派生 tabindex：焦点行（或无焦点时首行）为 0，其余 -1（红线 #2：render 期只读）。
-  function rowTabindex(key: ListKey): 0 | -1 {
-    if (!selectMode) return 0;
-    return (focusedRowKey ?? rowKeys[0]) === key ? 0 : -1;
-  }
-
-  function focusRowByKey(key: ListKey): void {
-    rootEl
-      ?.querySelector<HTMLElement>(
-        `[data-list-key="${CSS.escape(String(key))}"]`,
-      )
-      ?.focus();
-  }
-
-  // DOM 顺序的行 key 列表（声明式 <List.Item> 用：行不在 dataSource 内，按 DOM 漫游）。
-  function domRowKeys(): string[] {
-    if (!rootEl) return [];
-    return [...rootEl.querySelectorAll<HTMLElement>('[data-list-key]')].map(
-      (el) => el.dataset.listKey ?? '',
-    );
-  }
-
-  // 翻一屏的行数（虚拟化按可视区估算，否则固定 10 行兜底）。
-  function pageStep(): number {
-    if (virtualOn && vItemSize > 0) {
-      return Math.max(1, Math.floor(vViewportH / vItemSize));
-    }
-    return 10;
-  }
-
-  // 行 keydown：↑↓ roving、Home/End 跳首末、PageUp/Down 翻屏、Space/Enter 激活。
-  // Shift+↑↓（multiple）连选。命令式 focus() 在事件回调（非 render 期）。
-  function onRowKeydown(e: KeyboardEvent, item: T, index: number): void {
-    const key = keyOf(item, index);
-    if (e.key === ' ' || e.key === 'Enter') {
-      e.preventDefault();
-      onRowActivate(item, index, e.shiftKey);
-      return;
-    }
-    if (!selectMode) return;
-    const keys = rowKeys;
-    if (keys.length === 0) return;
-    const cur = keys.indexOf(key);
-    let target = -1;
-    if (e.key === 'ArrowDown') target = Math.min(keys.length - 1, cur + 1);
-    else if (e.key === 'ArrowUp') target = Math.max(0, cur - 1);
-    else if (e.key === 'Home') target = 0;
-    else if (e.key === 'End') target = keys.length - 1;
-    else if (e.key === 'PageDown') target = Math.min(keys.length - 1, cur + pageStep());
-    else if (e.key === 'PageUp') target = Math.max(0, cur - pageStep());
-    else return;
-    e.preventDefault();
-    const targetKey = keys[target];
-    if (targetKey == null) return;
-    focusedRowKey = targetKey;
-    // multiple 模式 Shift+方向键：移动焦点同时连选（范围以锚点为基准）。
-    if (e.shiftKey && selectMode === 'multiple') {
-      toggleKey(targetKey, true);
-    }
-    focusRowByKey(targetKey);
-  }
-  function onRowFocus(key: ListKey): void {
-    focusedRowKey = key;
-  }
-
-  // 声明式 <List.Item> keydown：按 DOM 顺序 roving（行不在 dataSource 内）。
-  // Space/Enter 由 List.Item 自身的 activate 处理，这里只管方向键 / Home/End / PageUp/Down。
-  function onItemKeydown(e: KeyboardEvent, key: ListKey): void {
-    if (!selectMode) return;
-    const keys = domRowKeys();
-    if (keys.length === 0) return;
-    const cur = keys.indexOf(String(key));
-    if (cur < 0) return;
-    let target = -1;
-    if (e.key === 'ArrowDown') target = Math.min(keys.length - 1, cur + 1);
-    else if (e.key === 'ArrowUp') target = Math.max(0, cur - 1);
-    else if (e.key === 'Home') target = 0;
-    else if (e.key === 'End') target = keys.length - 1;
-    else if (e.key === 'PageDown') target = Math.min(keys.length - 1, cur + pageStep());
-    else if (e.key === 'PageUp') target = Math.max(0, cur - pageStep());
-    else return;
-    e.preventDefault();
-    const targetKey = keys[target];
-    if (targetKey == null) return;
-    focusedRowKey = targetKey;
-    if (e.shiftKey && selectMode === 'multiple') toggleKey(targetKey, true);
-    focusRowByKey(targetKey);
-  }
-  // 声明式行 tabindex：焦点行 / 首个 DOM 行为 0，其余 -1（红线 #2：render 期只读）。
-  // 挂载前 rootEl 为空、DOM 顺序未知，回退为 0 保证可 Tab 进入；挂载后由 DOM 查询收敛为单一停靠点。
-  function itemTabindex(key: ListKey): 0 | -1 {
-    if (!selectMode) return 0;
-    if (focusedRowKey != null) return focusedRowKey === key ? 0 : -1;
-    const keys = domRowKeys();
-    if (keys.length === 0) return 0;
-    return keys[0] === String(key) ? 0 : -1;
-  }
-
-  // --- 分页：受控 current 不回写 (红线 #1)，本地 inner 兜底 ---
-  const paginationOn = $derived(pagination !== undefined && pagination !== false);
-  const pageSize = $derived(pagination ? (pagination.pageSize ?? 10) : 10);
-  const isPageControlled = $derived(!!pagination && pagination.current !== undefined);
-  let innerPage = $state(untrack(() => (pagination ? (pagination.defaultCurrent ?? 1) : 1)));
-  const currentPage = $derived(
-    pagination && pagination.current !== undefined ? pagination.current : innerPage,
-  );
-  // 当前页切片数据；未分页时为全量。
-  const pagedData = $derived.by<T[]>(() => {
-    if (!paginationOn) return dataSource;
-    const start = (currentPage - 1) * pageSize;
-    return dataSource.slice(start, start + pageSize);
+  // 向 <List.Item> 下发 grid 与 List 级 onClick/onRightClick（getter 保持响应性）。
+  setListContext({
+    getGrid: () => grid,
+    getOnClick: () => onClick,
+    getOnRightClick: () => onRightClick,
   });
-  function onPageChange(page: number) {
-    if (!isPageControlled) innerPage = page;
-    if (pagination) pagination.onChange?.(page);
-  }
-
-  // grid 布局：解析列数/间距，生成 inline CSS（CSS grid）。
-  const gridOn = $derived(grid !== undefined);
-  const gridColumn = $derived(
-    typeof grid === 'number' ? grid : (grid?.column ?? 4),
-  );
-  const gridGutter = $derived(
-    typeof grid === 'object' ? (grid.gutter ?? 16) : 16,
-  );
-  const gridStyle = $derived(
-    gridOn
-      ? `display:grid;grid-template-columns:repeat(${gridColumn},minmax(0,1fr));gap:${gridGutter}px`
-      : undefined,
-  );
 
+  // 对齐 semi-ui/list/index.tsx wrapperCls：-flex(horizontal)/-size/-grid/-split/-bordered。
   const cls = $derived(
     [
       'cd-list',
-      `cd-list--${size}`,
-      bordered && 'cd-list--bordered',
-      split && 'cd-list--split',
-      selectMode && 'cd-list--selectable',
-      layout === 'horizontal' && 'cd-list--horizontal',
+      layout === 'horizontal' && 'cd-list-flex',
+      size && `cd-list-${size}`,
+      grid && 'cd-list-grid',
+      split && 'cd-list-split',
+      bordered && 'cd-list-bordered',
       className,
     ]
       .filter(Boolean)
       .join(' '),
   );
 
-  // selectable 列表语义：role=listbox（multiple 时 aria-multiselectable），否则原生 list。
-  const itemsRole = $derived(selectMode ? 'listbox' : undefined);
-  const itemsMultiselect = $derived(selectMode === 'multiple' ? true : undefined);
-  // listbox 可访问名（aria-input-field-name）：缺省回退 i18n。非 selectable 时不设。
-  const itemsLabel = $derived(
-    selectMode ? (ariaLabel ?? loc().t('List.selectableLabel')) : undefined,
-  );
+  const emptyText = $derived(loc().t('List.emptyText'));
 </script>
 
-<!--
-  selectable 行的勾选指示器：纯视觉（aria-hidden + 无 input），避免 option 内嵌可聚焦控件
-  导致 axe nested-interactive。选中态由行 aria-selected 表达，勾选/取消走行的 Space/Enter。
--->
-{#snippet selectorMark(sel: boolean)}
-  <span class="cd-list__item-selector" aria-hidden="true">
-    <span class="cd-list__check" class:cd-list__check--on={sel}>
-      {#if sel}
-        <svg viewBox="0 0 16 16" width="10" height="10" focusable="false">
-          <path
-            fill="none"
-            stroke="currentColor"
-            stroke-width="2"
-            stroke-linecap="round"
-            stroke-linejoin="round"
-            d="M3.5 8.5 6.5 11.5 12.5 4.5"
-          />
-        </svg>
-      {/if}
-    </span>
-  </span>
-{/snippet}
-
-<div class={cls} aria-busy={loading || undefined} bind:this={rootEl} onscroll={onListScroll}>
+<div class={cls} {style}>
   {#if header !== undefined}
-    <div class="cd-list__header">
+    <div class="cd-list-header">
       {#if isSnippet(header)}{@render header()}{:else}{header}{/if}
     </div>
   {/if}
 
-  <div class="cd-list__body">
-    {#if loading && loadingSkeleton}
-      <ul class="cd-list__items" aria-hidden="true">
-        {#each skeletonRows as i (i)}
-          <li class="cd-list__item cd-list__item--skeleton">
-            <span class="cd-list__skeleton-bar"></span>
-          </li>
-        {/each}
-      </ul>
-    {:else if loading}
-      <div class="cd-list__spinner-wrap">
-        <span class="cd-list__spinner" aria-hidden="true"></span>
-      </div>
-    {:else if isEmpty}
-      <div class="cd-list__empty">
+  <Spin spinning={loading} size="large">
+    {#if showEmpty}
+      <div class="cd-list-empty">
         {#if isSnippet(emptyContent)}
           {@render emptyContent()}
         {:else if emptyContent !== undefined}
           {emptyContent}
         {:else}
-          <Empty image="noData" />
+          {emptyText}
         {/if}
       </div>
-    {:else if useDeclarative}
-      <!-- 声明式：渲染内嵌 <List.Item>（selectable 状态经 context 下发）。 -->
-      <ul
-        class="cd-list__items"
-        role={itemsRole}
-        aria-multiselectable={itemsMultiselect}
-        aria-label={itemsLabel}
-      >
-        {@render children?.()}
-      </ul>
-    {:else if virtualOn}
-      <!-- 虚拟化：仅渲染视口内行，复用 core 区间数学；命令式滚动监听（红线 #2/#3）。 -->
-      <div
-        class="cd-list__virtual"
-        bind:this={viewportEl}
-        role={itemsRole ?? 'list'}
-        aria-multiselectable={itemsMultiselect}
-        aria-label={itemsLabel}
-        style={`block-size:${vHeightStyle}; overflow:auto`}
-      >
-        <div class="cd-list__virtual-spacer" style={`block-size:${vTotalHeight}px`}>
-          {#each vVisible as item, i (keyOf(item, vStart + i))}
-            {@const index = vStart + i}
-            {@const k = keyOf(item, index)}
-            {@const sel = selectMode ? selectedSet.has(k) : false}
-            <!-- svelte-ignore a11y_no_noninteractive_tabindex -->
-            <div
-              class="cd-list__item cd-list__virtual-item"
-              class:cd-list__item--selectable={!!selectMode}
-              class:cd-list__item--selected={sel}
-              data-vindex={index}
-              data-list-key={selectMode ? k : undefined}
-              role={selectMode ? 'option' : 'listitem'}
-              aria-selected={selectMode ? sel : undefined}
-              aria-setsize={dataSource.length}
-              aria-posinset={index + 1}
-              tabindex={selectMode ? rowTabindex(k) : undefined}
-              style={vItemStyle(index)}
-              onclick={selectMode ? (e) => onRowActivate(item, index, e.shiftKey) : undefined}
-              onkeydown={selectMode ? (e) => onRowKeydown(e, item, index) : undefined}
-              onfocus={selectMode ? () => onRowFocus(k) : undefined}
-            >
-              {#if selectMode}
-                {@render selectorMark(sel)}
-              {/if}
-              <div class="cd-list__item-content">
-                {#if renderItem}{@render renderItem(item, index)}{/if}
-              </div>
-            </div>
+    {:else if grid}
+      <!-- 栅格列表：复用 Row 容器，Item 自身用 Col 包裹（经 context）。 -->
+      <Row {...rowProps}>
+        {#if hasData && renderItem}
+          {#each dataSource! as item, index (index)}
+            {@render renderItem(item, index)}
           {/each}
-        </div>
-      </div>
+        {/if}
+        {@render children?.()}
+      </Row>
     {:else}
-      <ul
-        class="cd-list__items"
-        class:cd-list__items--grid={gridOn}
-        style={gridStyle}
-        role={itemsRole}
-        aria-multiselectable={itemsMultiselect}
-        aria-label={itemsLabel}
-      >
-        {#each pagedData as item, index (keyOf(item, index))}
-          {@const realIndex = paginationOn ? (currentPage - 1) * pageSize + index : index}
-          {@const k = keyOf(item, realIndex)}
-          {@const sel = selectMode ? selectedSet.has(k) : false}
-          {#if selectMode}
-            <li
-              class="cd-list__item cd-list__item--selectable"
-              class:cd-list__item--selected={sel}
-              class:cd-list__item--grid={gridOn}
-              data-list-key={k}
-              role="option"
-              aria-selected={sel}
-              tabindex={rowTabindex(k)}
-              onclick={(e) => onRowActivate(item, realIndex, e.shiftKey)}
-              onkeydown={(e) => onRowKeydown(e, item, realIndex)}
-              onfocus={() => onRowFocus(k)}
-            >
-              {@render selectorMark(sel)}
-              <div class="cd-list__item-content">
-                {#if renderItem}{@render renderItem(item, realIndex)}{/if}
-              </div>
-            </li>
-          {:else}
-            <li class="cd-list__item" class:cd-list__item--grid={gridOn}>
-              {#if renderItem}{@render renderItem(item, realIndex)}{/if}
-            </li>
-          {/if}
-        {/each}
+      <ul class="cd-list-items">
+        {#if hasData && renderItem}
+          {#each dataSource! as item, index (index)}
+            {@render renderItem(item, index)}
+          {/each}
+        {/if}
+        {@render children?.()}
       </ul>
-
-      {#if paginationOn}
-        <div class="cd-list__pagination">
-          <Pagination
-            total={dataSource.length}
-            currentPage={currentPage}
-            {pageSize}
-            size={size === 'large' ? 'default' : size}
-            onChange={onPageChange}
-          />
-        </div>
-      {:else if loadMore}
-        <div class="cd-list__load-more">{@render loadMore()}</div>
-      {:else if onLoadMore !== undefined && (hasMore || loadingMore)}
-        <div class="cd-list__load-more">
-          <Button
-            loading={loadingMore}
-            disabled={!hasMore && !loadingMore}
-            onclick={() => onLoadMore?.()}
-          >
-            {loc().t('List.loadMore')}
-          </Button>
-        </div>
-      {/if}
     {/if}
-  </div>
+  </Spin>
 
   {#if footer !== undefined}
-    <div class="cd-list__footer">
+    <div class="cd-list-footer">
       {#if isSnippet(footer)}{@render footer()}{:else}{footer}{/if}
     </div>
   {/if}
+
+  {#if loadMore}{@render loadMore()}{/if}
 </div>
 
 <style>
+  /* 严格镜像 semi-foundation/list/list.scss。字号用常规正文（Semi @include font-size-regular）。 */
   .cd-list {
-    background: var(--cd-list-bg);
-    color: var(--cd-list-item-color);
-    --cd-list-pad-y: var(--cd-list-item-padding);
-  }
-  .cd-list--small {
-    --cd-list-pad-y: var(--cd-list-item-padding-small);
-  }
-  .cd-list--bordered {
-    border: 1px solid var(--cd-list-border);
-    border-radius: var(--cd-list-radius);
-    overflow: hidden;
-  }
-
-  /* horizontal layout: item 内容横向排列 */
-  .cd-list--horizontal .cd-list__item {
-    display: flex;
-    flex-direction: row;
-    align-items: flex-start;
-    gap: var(--cd-spacing-base-tight, 12px);
-  }
-
-  .cd-list__header {
-    padding-block: var(--cd-list-pad-y);
-    padding-inline: var(--cd-list-item-padding);
-    color: var(--cd-list-header-color);
-    border-block-end: 1px solid var(--cd-list-split-color);
-  }
-  .cd-list__footer {
-    padding-block: var(--cd-list-pad-y);
-    padding-inline: var(--cd-list-item-padding);
-    border-block-start: 1px solid var(--cd-list-split-color);
+    font-size: var(--cd-font-size-regular, 14px);
+    line-height: var(--cd-line-height-regular, 20px);
   }
 
-  .cd-list__items {
+  .cd-list-items {
     margin: 0;
     padding: 0;
     list-style: none;
   }
-  .cd-list__item {
-    padding-block: var(--cd-list-pad-y);
-    padding-inline: var(--cd-list-item-padding);
-  }
-  .cd-list--split .cd-list__item + .cd-list__item {
-    border-block-start: 1px solid var(--cd-list-split-color);
-  }
-  /* grid 模式：取消 split 分隔线与行内边距，由 grid gap 控制间距 */
-  .cd-list__items--grid {
-    padding-block: var(--cd-list-pad-y);
-  }
-  .cd-list--split .cd-list__item--grid + .cd-list__item--grid {
-    border-block-start: none;
-  }
-  .cd-list__item--grid {
-    padding: 0;
-  }
 
-  /* selectable 行：内置 checkbox + 主内容横向布局，选中/hover/focus 强调。 */
-  .cd-list__item--selectable {
-    display: flex;
-    align-items: flex-start;
-    gap: var(--cd-spacing-tight, 8px);
-    cursor: pointer;
-    outline: none;
-  }
-  .cd-list__item--selectable:hover {
-    background: var(--cd-color-fill-0, rgba(0, 0, 0, 0.03));
+  .cd-list-header,
+  .cd-list-footer {
+    padding: var(--cd-spacing-list-footer-paddingx) var(--cd-spacing-list-footer-paddingy);
   }
-  .cd-list__item--selectable:focus-visible {
-    box-shadow: inset 0 0 0 2px var(--cd-color-primary, #0066ff);
-  }
-  .cd-list__item--selected {
-    background: var(--cd-color-primary-light-default, rgba(0, 102, 255, 0.1));
+
+  .cd-list-empty {
+    padding: var(--cd-spacing-list-empty-paddingx) var(--cd-spacing-list-empty-paddingy);
+    color: var(--cd-color-list-empty-text-default);
+    width: 100%;
+    text-align: center;
   }
-  .cd-list__item-selector {
-    flex: none;
-    display: flex;
-    align-items: center;
-    pointer-events: none;
+
+  /* split：行/头/尾分隔线用列表描边色（对齐 &-split &-item / &-header / &-footer）。 */
+  .cd-list-split :global(.cd-list-item) {
+    border-bottom: 1px solid var(--cd-color-list-default-border-default);
   }
-  /* 纯视觉勾选框（无 input；选中态走行 aria-selected，避免 nested-interactive）。 */
-  .cd-list__check {
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
-    flex: none;
-    inline-size: 16px;
-    block-size: 16px;
-    border: 1px solid var(--cd-color-border);
-    border-radius: var(--cd-radius-small, 4px);
-    color: var(--cd-color-bg-0, #fff);
-    background: var(--cd-color-bg-0, #fff);
+  .cd-list-split :global(.cd-list-item:last-child) {
+    border-bottom: none;
   }
-  .cd-list__check--on {
-    background: var(--cd-color-primary, #0066ff);
-    border-color: var(--cd-color-primary, #0066ff);
+  .cd-list-split .cd-list-header {
+    border-bottom: 1px solid var(--cd-color-list-default-border-default);
   }
-  .cd-list__item-content {
-    flex: 1;
-    min-inline-size: 0;
+  .cd-list-split .cd-list-footer {
+    border-top: 1px solid var(--cd-color-list-default-border-default);
   }
 
-  /* 虚拟化：视口自身滚动，撑高占位 + 绝对定位行。 */
-  .cd-list__virtual {
-    position: relative;
-    inline-size: 100%;
-    scrollbar-color: var(--cd-virtual-list-scrollbar, currentColor) transparent;
-  }
-  .cd-list__virtual-spacer {
-    position: relative;
-    inline-size: 100%;
+  /* 尺寸：item padding（header/footer 在 small/large 下同步，对齐 scss）。 */
+  .cd-list-small :global(.cd-list-item),
+  .cd-list-small .cd-list-header,
+  .cd-list-small .cd-list-footer {
+    padding: var(--cd-spacing-list-small-paddingx) var(--cd-spacing-list-small-paddingy);
   }
-  .cd-list__virtual-item {
-    position: absolute;
-    inset-block-start: 0;
-    inset-inline: 0;
+  .cd-list-large :global(.cd-list-item),
+  .cd-list-large .cd-list-header,
+  .cd-list-large .cd-list-footer {
+    padding: var(--cd-spacing-list-large-paddingx) var(--cd-spacing-list-large-paddingy);
   }
 
-  .cd-list__load-more {
-    display: flex;
-    justify-content: center;
-    padding-block: var(--cd-list-item-padding);
-  }
-  .cd-list__pagination {
-    display: flex;
-    justify-content: flex-end;
-    padding-block: var(--cd-list-item-padding);
-    padding-inline: var(--cd-list-item-padding);
+  /* grid：item 去内边距（由 Row/Col gutter 控距）。 */
+  .cd-list-grid :global(.cd-list-item) {
+    padding: 0;
   }
 
-  .cd-list__empty {
-    padding-block: var(--cd-list-item-padding);
-    display: flex;
-    justify-content: center;
+  .cd-list-bordered {
+    border: 1px solid var(--cd-color-list-default-border-default);
   }
 
-  .cd-list__spinner-wrap {
+  /* horizontal(-flex)：items 横向排列；split 改右边框。 */
+  .cd-list-flex .cd-list-items {
     display: flex;
-    align-items: center;
-    justify-content: center;
-    padding-block: calc(var(--cd-list-item-padding) * 2);
-  }
-  .cd-list__spinner {
-    inline-size: 1.5em;
-    block-size: 1.5em;
-    border: 2px solid var(--cd-list-split-color);
-    border-block-start-color: var(--cd-color-primary, currentColor);
-    border-radius: var(--cd-border-radius-full);
-    animation: cd-list-spin 0.7s linear infinite;
-  }
-
-  .cd-list__skeleton-bar {
-    display: block;
-    block-size: 1em;
-    inline-size: 100%;
-    border-radius: var(--cd-radius-small);
-    background: var(--cd-list-split-color);
-    position: relative;
-    overflow: hidden;
   }
-  .cd-list__skeleton-bar::after {
-    content: '';
-    position: absolute;
-    inset: 0;
-    transform: translateX(-100%);
-    background: linear-gradient(
-      90deg,
-      transparent,
-      var(--cd-list-bg),
-      transparent
-    );
-    animation: cd-list-shimmer 1.2s ease-in-out infinite;
+  .cd-list-flex.cd-list-split :global(.cd-list-item) {
+    border-bottom: none;
+    border-right: 1px solid var(--cd-color-list-default-border-default);
   }
-
-  @keyframes cd-list-spin {
-    to {
-      transform: rotate(360deg);
-    }
-  }
-  @keyframes cd-list-shimmer {
-    100% {
-      transform: translateX(100%);
-    }
-  }
-
-  @media (prefers-reduced-motion: reduce) {
-    .cd-list__spinner {
-      animation: none;
-    }
-    .cd-list__skeleton-bar::after {
-      animation: none;
-    }
+  .cd-list-flex.cd-list-split :global(.cd-list-item:last-child) {
+    border-right: none;
   }
 </style>