@chenzy-design/svelte 0.1.0

package/src/upload/UploadA11yFixture.svelte

@@ -0,0 +1,23 @@
+<!--
+  Upload a11y 测试夹具：在 LocaleProvider 内渲染 Upload，不传 children。
+  说明：LocaleHarness 总会注入一个 children 插槽，会命中 Upload 的 {#if children}
+  分支，使触发按钮/拖拽区跳过内置 locale 文案（渲染空插槽），故这里直接包
+  LocaleProvider 渲染、不经 harness。仅供 Upload.a11y.test.ts 使用，不对外导出。
+-->
+<script lang="ts">
+  import { LocaleProvider } from '../locale-provider/index.js';
+  import Upload from './Upload.svelte';
+  import type { UploadFileItem } from './types.js';
+
+  interface Props {
+    drag?: boolean;
+    value?: UploadFileItem[];
+    locale?: string;
+  }
+
+  let { drag = false, value, locale = 'en_US' }: Props = $props();
+</script>
+
+<LocaleProvider {locale}>
+  <Upload {drag} {...(value !== undefined ? { value } : {})} />
+</LocaleProvider>

package/src/upload/index.ts

@@ -0,0 +1,3 @@
+export { default as Upload } from './Upload.svelte';
+export { meta as uploadMeta } from './meta.js';
+export type { UploadFileItem, UploadStatus } from './types.js';

package/src/upload/meta.ts

@@ -0,0 +1,64 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * See specs/00-foundation/ai-friendly.spec.md.
+ */
+export const meta = {
+  name: 'Upload',
+  category: 'input',
+  description: '文件上传，支持点击与拖拽选择、文件列表（名称/大小/状态/移除）。本轮不做真实网络上传。',
+  props: [
+    { name: 'value', type: 'UploadFileItem[]', default: 'undefined', desc: '受控文件列表；提供则为受控' },
+    { name: 'defaultValue', type: 'UploadFileItem[]', default: '[]', desc: '非受控初始文件列表' },
+    { name: 'accept', type: 'string', default: 'undefined', desc: '接受的文件类型（input accept）' },
+    { name: 'multiple', type: 'boolean', default: 'false' },
+    { name: 'directory', type: 'boolean', default: 'false', desc: '上传整个目录（webkitdirectory），递归选择目录下所有文件，保留 relativePath' },
+    { name: 'limit', type: 'number', default: 'undefined', desc: '最大文件数；超出触发 onExceed' },
+    { name: 'maxSize', type: 'number', default: 'undefined', desc: '单文件最大体积（KB）；超限标记 error' },
+    { name: 'minSize', type: 'number', default: 'undefined', desc: '单文件最小体积（KB）；过小标记 error' },
+    { name: 'disabled', type: 'boolean', default: 'false' },
+    { name: 'size', type: "'small'|'default'|'large'", default: "'default'", desc: '组件级尺寸（触发按钮/拖拽区/列表项），区别于文件项的 file.size 体积' },
+    { name: 'status', type: "'default'|'warning'|'error'", default: "'default'", desc: '组件级校验态（表单联动，影响上传区/边框色），区别于文件项的 file.status 上传进度态' },
+    { name: 'listType', type: "'text'|'image'|'picture-card'|'none'", default: 'text', desc: 'image/picture-card 显示缩略图网格' },
+    { name: 'drag', type: 'boolean', default: 'false', desc: 'true 渲染拖拽区，false 渲染按钮' },
+    { name: 'action', type: 'string', default: 'undefined', desc: '上传地址；有则选文件后自动 XHR 上传' },
+    { name: 'uploadName', type: 'string', default: "'file'", desc: '表单字段名' },
+    { name: 'headers', type: 'Record<string,string>', default: 'undefined', desc: '额外请求头' },
+    { name: 'uploadData', type: 'Record<string,string>', default: 'undefined', desc: '额外表单字段' },
+    { name: 'concurrency', type: 'number', default: '0', desc: '同时进行的上传数上限；0/不传=不限，超出排队、完成补位' },
+    { name: 'beforeUpload', type: '(file: File, fileList: File[]) => boolean | File | Promise<boolean | File>', default: 'undefined', desc: '上传前异步校验/转换：false/reject 跳过该文件，返回 File 替换，true 正常上传' },
+    { name: 'customRequest', type: '(item: UploadFileItem) => void | Promise<void>', default: 'undefined', desc: '提供则由外部接管上传（优先于 action）；返回 Promise 时受 concurrency 调度' },
+    { name: 'onChange', type: '(list: UploadFileItem[]) => void', default: 'undefined' },
+    { name: 'onExceed', type: '(files: File[]) => void', default: 'undefined' },
+    { name: 'onSuccess', type: '(response: string, item: UploadFileItem) => void', default: 'undefined' },
+    { name: 'onError', type: '(item: UploadFileItem) => void', default: 'undefined' },
+    { name: 'children', type: 'Snippet', default: 'undefined', desc: '自定义触发器内容' },
+    { name: 'showRetry', type: 'boolean', default: 'true', desc: '上传失败是否显示重试按钮' },
+    { name: 'showReplace', type: 'boolean', default: 'false', desc: '是否允许替换已有文件（单文件模式下显示"替换"而不是"添加"）' },
+    { name: 'showClear', type: 'boolean', default: 'false', desc: '是否显示批量清除按钮' },
+    { name: 'onClear', type: '() => void', default: 'undefined', desc: '清除按钮点击回调' },
+    { name: 'fileListTitle', type: 'string | false', default: 'undefined', desc: '文件列表标题文字；false 则不渲染' },
+    { name: 'showTooltip', type: 'boolean', default: 'true', desc: '文件名超长是否展示 Tooltip（title 属性）' },
+    { name: 'prompt', type: 'string | Snippet', default: 'undefined', desc: '上传区提示内容（文字或 Snippet）' },
+    { name: 'promptPosition', type: "'left'|'right'|'bottom'", default: "'bottom'", desc: '提示位置：left/right 水平排列，bottom 下方' },
+    { name: 'onDrop', type: '(e: DragEvent, files: File[], rejectFiles: File[]) => void', default: 'undefined', desc: '拖拽放下回调' },
+    { name: 'onOpenFileDialog', type: '() => void', default: 'undefined', desc: '打开文件选择弹窗时回调' },
+    { name: 'onPreviewClick', type: '(fileItem: UploadFileItem) => void', default: 'undefined', desc: '预览图点击回调（image/picture-card listType）' },
+    { name: 'onAcceptInvalid', type: '(files: File[]) => void', default: 'undefined', desc: 'accept 校验失败（文件类型不符）的回调' },
+    { name: 'onRetry', type: '(file: UploadFileItem) => void', default: 'undefined', desc: '重试回调' },
+    { name: 'onSizeError', type: "(file: UploadFileItem, validResult: 'max' | 'min') => void", default: 'undefined', desc: '大小校验失败回调' },
+    { name: 'validateMessage', type: 'string', default: 'undefined', desc: '校验失败统一文案（覆盖 i18n 默认文案）' },
+    { name: 'withCredentials', type: 'boolean', default: 'false', desc: 'XHR withCredentials（跨域凭证）' },
+    { name: 'transformFile', type: '(file: File) => Promise<File>', default: 'undefined', desc: '上传前文件转换（async，返回转换后的 File）' },
+    { name: 'dragIcon', type: 'Snippet', default: 'undefined', desc: '拖拽区自定义图标 Snippet' },
+    { name: 'dragMainText', type: 'string | Snippet', default: 'undefined', desc: '拖拽区主文案' },
+    { name: 'dragSubText', type: 'string | Snippet', default: 'undefined', desc: '拖拽区副文案' },
+    { name: 'addOnPasting', type: 'boolean', default: 'false', desc: '粘贴添加文件（监听 document paste）' },
+    { name: 'hotSpotLocation', type: "'start'|'end'|'none'", default: "'start'", desc: "触发热点位置：'start'=前置，'end'=后置，'none'=隐藏触发器" },
+  ],
+  a11y: {
+    role: 'button',
+    keyboard: ['Enter', 'Space'],
+    notes: ['隐藏的 file input（visually-hidden）', '触发器为 button', '移除按钮 aria-label「移除」', 'dragger role=button + tabindex + 键盘 Enter/Space'],
+  },
+  tokens: ['--cd-upload-*', '--cd-upload-border-warning', '--cd-upload-border-error', '--cd-button-height-*', '--cd-focus-ring', '--cd-color-warning', '--cd-color-danger', '--cd-spacing-*'],
+} as const;

package/src/upload/types.ts

@@ -0,0 +1,16 @@
+export type UploadStatus = 'ready' | 'uploading' | 'success' | 'error';
+
+export interface UploadFileItem {
+  uid: string;
+  name: string;
+  size: number;
+  status: UploadStatus;
+  percent?: number;
+  file?: File;
+  /** 远程预览地址（image/picture-card 列表优先用它，否则由 file 生成 objectURL） */
+  url?: string;
+  /** 校验失败时的本地化提示（如大小超限/过小）；status==='error' 时展示 */
+  error?: string;
+  /** 目录上传时文件相对路径（webkitRelativePath，若可用） */
+  relativePath?: string;
+}

package/src/virtual-list/VirtualList.svelte

@@ -0,0 +1,401 @@
+<!--
+  VirtualList — see specs/components/show/VirtualList.spec.md
+  子集：vertical + overscan + 内部容器滚动（scrollTarget='self'）。
+    - fixed 定高：itemSize 为 number（默认）。区间 O(1)。
+    - dynamic 不定高：itemSize='auto'（或不传 itemSize 时用 estimatedItemSize 估算）。
+      用 estimatedItemSize 估算初始高度/总高，渲染后 ResizeObserver 实测每项真实高度，
+      缓存到 heights 表，据此（前缀和 offsets）修正各项偏移与可视区间；
+      实测与估算不同导致当前可视项偏移变化时做偏移补偿，滚动不跳动。
+  horizontal: 横向虚拟化沿 x 轴——itemSize 作列宽、横向排列、读/写 scrollLeft、
+    可视区间按宽度算；方向无关的 core 区间纯函数（fixedRange/buildOffsets/…）直接复用，
+    仅把 height→width、scrollTop→scrollLeft 抽象。horizontal 仅支持 fixed 定宽
+    （dynamic+horizontal 暂不支持：dynamic 用 itemSize='auto'，与 horizontal 组合时
+    退化为 fixed，按 estimatedItemSize 列宽渲染——见下方 dynamic 判定）。
+  scrollToIndex(index, opts?): 命令式 API——根据该 index 的 offset（fixed 用
+    index*itemSize；dynamic 用 offsets 前缀和）+ align 计算目标滚动位置，直接写
+    滚动容器 scrollTop（horizontal 则 scrollLeft）。放导出函数（非 render），属命令式 DOM 写。
+  scrollTarget='self'（默认）| 'window'：
+    - 'self'：内部容器自身 overflow 滚动（默认，向后兼容，行为不变）。
+    - 'window'：容器不再自身滚动，撑开总高靠窗口（document）滚动，适合整页长列表。
+      虚拟化基于窗口几何：容器顶相对文档位置（getBoundingClientRect().top + scrollY）
+      + window.scrollY + window.innerHeight，经 core 纯函数 windowScrollTop 折算为本地
+      scrollTop 再喂给 fixedRange/dynamicRange（区间数学完全复用）。监听 window 的
+      scroll/resize（命令式 addEventListener + rAF 节流，cleanup removeEventListener）。
+      window 模式为纵向窗口滚动场景，horizontal 在 window 模式下退化为 self（横向窗口
+      滚动罕见且语义不清）；fixed/dynamic 行高路径均复用。
+
+  ⚠️ 死循环红线：
+    - 滚动监听用 $effect 内命令式 addEventListener('scroll', ..., {passive:true})
+      + rAF 节流，cleanup 时 removeEventListener + cancelAnimationFrame。
+    - 几何测量（视口高度 + dynamic 行高）一律 ResizeObserver / getBoundingClientRect，
+      在 $effect 内创建 observer + 绑定，cleanup 里 disconnect。绝不用响应式 attachment。
+    - 测量结果写入本地 $state（measuredH / heights），render 期只读派生；
+      render 不触发新测量、不读 effect 写的状态形成新一轮测量循环。
+    - 受控 prop（itemSize/estimatedItemSize/data…）不回写。
+-->
+<script lang="ts" generics="T">
+  // 泛型组件 props 用内联匿名类型而非具名 interface Props：在 declaration:true 下，
+  // 引用泛型参数 T 的具名 interface 会被当作私有名泄漏进生成的 .d.ts 公共签名而报错。
+  import type { Snippet } from 'svelte';
+  import {
+    fixedRange,
+    buildOffsets,
+    totalFromOffsets,
+    dynamicRange,
+    scrollOffsetForIndex,
+    windowScrollTop,
+    type ScrollAlign,
+  } from '@chenzy-design/core';
+
+  let {
+    data = [],
+    getKey = (_item: T, index: number) => index,
+    itemSize = 40,
+    estimatedItemSize = 40,
+    overscan = 3,
+    height = 400,
+    horizontal = false,
+    scrollTarget = 'self',
+    renderItem,
+    class: className = '',
+  }: {
+    data?: T[];
+    getKey?: (item: T, index: number) => string | number;
+    /** 固定行高/列宽（px）；传 'auto' 启用 dynamic 不定高测量（horizontal 暂不支持 dynamic）。 */
+    itemSize?: number | 'auto';
+    /** dynamic 模式初始估算行高（px），用于首屏占位与总高估算。 */
+    estimatedItemSize?: number;
+    overscan?: number;
+    /** 视口主轴尺寸（vertical 为高度、horizontal 为宽度）；数字按 px，字符串用 ResizeObserver 测量。 */
+    height?: number | string;
+    /** 横向虚拟化：沿 x 轴排列、读/写 scrollLeft。默认 false（vertical）。 */
+    horizontal?: boolean;
+    /**
+     * 滚动源：'self'（默认）内部容器自身滚动；'window' 用窗口（document）滚动、
+     * 容器撑开总高，适合整页长列表（纵向）。horizontal 在 window 下退化为 self。
+     */
+    scrollTarget?: 'self' | 'window';
+    renderItem: Snippet<[item: T, index: number]>;
+    class?: string;
+  } = $props();
+
+  // window 模式判定：scrollTarget='window' 且非 horizontal（横向窗口滚动罕见，退化为 self）。
+  const windowMode = $derived(scrollTarget === 'window' && !horizontal);
+  // dynamic 模式判定：itemSize='auto'。horizontal 暂不支持 dynamic，强制走 fixed。
+  const dynamic = $derived(itemSize === 'auto' && !horizontal);
+  // fixed 路径行高（dynamic 时该值不参与几何）。
+  const fixedSize = $derived(typeof itemSize === 'number' ? itemSize : estimatedItemSize);
+
+  // viewport 元素普通引用（bind:this），不参与响应式几何读取。
+  let viewportEl = $state<HTMLDivElement | null>(null);
+
+  // 本地响应式状态：仅由命令式回调 / ResizeObserver 写入，render 期只读。
+  // 主轴滚动偏移：vertical 为 scrollTop、horizontal 为 scrollLeft（方向无关命名沿用 scrollTop）。
+  let scrollTop = $state(0);
+  // 测量得到的视口主轴尺寸：self 模式仅 height 为字符串时由 ResizeObserver 回填；
+  // window 模式由 scroll/resize 回调写入 window.innerHeight（命令式，非 render 期）。
+  let measuredH = $state(0);
+  // 有效视口主轴尺寸：window 模式用测量的窗口视口高；self 模式 height 为数字直接用
+  // prop，否则用测量值（纯 $derived）。
+  const viewportH = $derived(
+    windowMode ? measuredH : typeof height === 'number' ? height : measuredH,
+  );
+
+  // dynamic：实测行高缓存表。索引 → 真实高度（px）；未测得为 undefined（用估算）。
+  // 普通对象 $state，由 ResizeObserver 命令式写入；render 期只读。
+  let heights = $state<Record<number, number>>({});
+
+  // 普通（非响应式）变量：rAF 节流句柄。
+  let rafId = 0;
+
+  const heightStyle = $derived(typeof height === 'number' ? `${height}px` : height);
+
+  // dynamic：合并实测/估算的每项高度数组 → 前缀和 offsets（render-safe，仅依赖 $state）。
+  const offsets = $derived.by(() => {
+    if (!dynamic) return [] as number[];
+    const arr = new Array<number>(data.length);
+    for (let i = 0; i < data.length; i += 1) {
+      arr[i] = heights[i] ?? estimatedItemSize;
+    }
+    return buildOffsets(arr);
+  });
+
+  // 总撑高占位。fixed 为 O(1)；dynamic 取 offsets 末项（估算+实测混合）。
+  const totalHeight = $derived(
+    dynamic ? totalFromOffsets(offsets) : data.length * fixedSize,
+  );
+
+  // 可视区间：纯 $derived，仅依赖本地 $state，render-safe（不读 DOM）。
+  const range = $derived(
+    dynamic
+      ? dynamicRange(offsets, scrollTop, viewportH, overscan)
+      : fixedRange(scrollTop, viewportH, fixedSize, data.length, overscan),
+  );
+  const startIndex = $derived(range.startIndex);
+  const endIndex = $derived(range.endIndex);
+  const visible = $derived(data.slice(startIndex, endIndex));
+
+  // 某项的主轴偏移：fixed 为 index*size；dynamic 查 offsets 前缀和。
+  function itemOffset(index: number): number {
+    if (dynamic) return offsets[index] ?? index * estimatedItemSize;
+    return index * fixedSize;
+  }
+
+  // 某项的主轴尺寸：dynamic 查实测/估算高度；fixed 为定尺寸。
+  function itemMainSize(index: number): number {
+    if (dynamic) return heights[index] ?? estimatedItemSize;
+    return fixedSize;
+  }
+
+  /**
+   * 命令式滚动到指定索引项（红线 #3：直接写 DOM scrollTop/scrollLeft 的命令式操作，
+   * 不在 render 期执行，由父组件 bind 后主动调用）。
+   * @param index 目标索引（自动 clamp 到 [0, data.length - 1]）
+   * @param opts.align 'start'（默认）| 'center' | 'end'：目标项在视口内的对齐方式
+   */
+  export function scrollToIndex(
+    index: number,
+    opts?: { align?: ScrollAlign },
+  ): void {
+    const el = viewportEl;
+    if (!el || data.length === 0) return;
+    const i = Math.max(0, Math.min(data.length - 1, Math.floor(index)));
+    // 总主轴尺寸：dynamic 取 offsets 末项；fixed 为 count*size。
+    const totalMain = dynamic ? totalFromOffsets(offsets) : data.length * fixedSize;
+    // 目标本地偏移（相对内容顶）。window 模式视口高用 innerHeight。
+    const target = scrollOffsetForIndex(
+      itemOffset(i),
+      itemMainSize(i),
+      windowMode
+        ? window.innerHeight
+        : horizontal
+          ? el.clientWidth
+          : el.clientHeight,
+      totalMain,
+      opts?.align ?? 'start',
+    );
+    if (windowMode) {
+      // 窗口滚动：本地偏移 + 容器相对文档顶位置（命令式读几何，非 render 期）。
+      const containerStart = el.getBoundingClientRect().top + window.scrollY;
+      window.scrollTo({ top: containerStart + target });
+      scrollTop = target;
+      return;
+    }
+    if (horizontal) el.scrollLeft = target;
+    else el.scrollTop = target;
+    // 同步本地 state（DOM 滚动事件随后也会触发，这里立即更新避免一帧延迟）。
+    scrollTop = target;
+  }
+
+  // self 模式滚动监听（命令式 + rAF 节流 + cleanup）。
+  $effect(() => {
+    const el = viewportEl;
+    if (!el || windowMode) return;
+
+    function onScroll() {
+      if (rafId) return;
+      rafId = requestAnimationFrame(() => {
+        rafId = 0;
+        // 主轴滚动读取发生在回调中（非 render 期）；horizontal 读 scrollLeft。
+        if (el) scrollTop = horizontal ? el.scrollLeft : el.scrollTop;
+      });
+    }
+
+    el.addEventListener('scroll', onScroll, { passive: true });
+    return () => {
+      el.removeEventListener('scroll', onScroll);
+      if (rafId) {
+        cancelAnimationFrame(rafId);
+        rafId = 0;
+      }
+    };
+  });
+
+  // window 模式：监听 window 的 scroll/resize（命令式 + rAF 节流 + cleanup）。
+  // 用容器相对文档顶位置 + window.scrollY + innerHeight，经 core windowScrollTop
+  // 折算为本地 scrollTop 喂给区间数学；measuredH 回填 innerHeight 作视口高。
+  $effect(() => {
+    const el = viewportEl;
+    if (!el || !windowMode) return;
+
+    // 总主轴尺寸（读 $derived，非 DOM 几何）；用于 clamp 本地偏移。
+    function totalMain(): number {
+      return dynamic ? totalFromOffsets(offsets) : data.length * fixedSize;
+    }
+
+    function recompute() {
+      if (!el) return;
+      // 命令式读几何（非 render 期）：容器顶相对文档位置 + 窗口滚动 + 视口高。
+      const containerStart = el.getBoundingClientRect().top + window.scrollY;
+      measuredH = window.innerHeight;
+      scrollTop = windowScrollTop(containerStart, window.scrollY, totalMain());
+    }
+
+    function onScroll() {
+      if (rafId) return;
+      rafId = requestAnimationFrame(() => {
+        rafId = 0;
+        recompute();
+      });
+    }
+
+    // 立即算一次（首屏定位）。
+    recompute();
+    window.addEventListener('scroll', onScroll, { passive: true });
+    window.addEventListener('resize', onScroll, { passive: true });
+    return () => {
+      window.removeEventListener('scroll', onScroll);
+      window.removeEventListener('resize', onScroll);
+      if (rafId) {
+        cancelAnimationFrame(rafId);
+        rafId = 0;
+      }
+    };
+  });
+
+  // self 模式视口高度测量：仅当 height 非数字（字符串/百分比）时启用 ResizeObserver。
+  $effect(() => {
+    const el = viewportEl;
+    if (!el || windowMode || typeof height === 'number') return;
+
+    // 立即测一次主轴尺寸（命令式，非 render 期）；horizontal 测 clientWidth。
+    measuredH = horizontal ? el.clientWidth : el.clientHeight;
+
+    const ro = new ResizeObserver((entries) => {
+      for (const entry of entries) {
+        measuredH = horizontal ? entry.contentRect.width : entry.contentRect.height;
+      }
+    });
+    ro.observe(el);
+    return () => ro.disconnect();
+  });
+
+  // dynamic 行高实测 + 偏移补偿（命令式 ResizeObserver，cleanup disconnect）。
+  // 每个已渲染行元素带 data-vindex，observer 实测真实高度回写 heights；
+  // 若变更的行位于当前滚动位置之上，则总高/偏移随之变化——补偿 scrollTop 保持视图稳定。
+  $effect(() => {
+    const el = viewportEl;
+    if (!el || !dynamic) return;
+    // 依赖 visible：渲染行集合变化（滚动/数据更新）后重建 observer，observe 新行。
+    // 读取仅作依赖追踪，不在此读 DOM 几何。
+    void visible;
+
+    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 = heights[idx];
+      if (prev !== undefined && Math.abs(prev - h) < 0.5) return;
+
+      // 估算→实测差值；该行若在当前 scrollTop 之上，需补偿避免视图跳动。
+      const before = prev ?? estimatedItemSize;
+      const delta = h - before;
+      heights[idx] = h;
+
+      if (delta !== 0 && el && itemOffset(idx) < scrollTop) {
+        // 命令式补偿，避免视图跳动（非 render 期）。
+        if (windowMode) {
+          // 窗口模式：滚动文档而非内部容器；下一帧 onScroll 同步本地 state。
+          window.scrollBy(0, delta);
+          scrollTop += delta;
+        } else {
+          el.scrollTop += delta;
+          scrollTop = el.scrollTop;
+        }
+      }
+    }
+
+    const ro = new ResizeObserver((entries) => {
+      for (const entry of entries) measure(entry.target);
+    });
+
+    // 命令式遍历当前已渲染行并 observe（render 期不读几何，这里在 effect 内）。
+    const rows = el.querySelectorAll<HTMLElement>('[data-vindex]');
+    rows.forEach((node) => {
+      measure(node);
+      ro.observe(node);
+    });
+
+    return () => ro.disconnect();
+  });
+
+  const cls = $derived(
+    ['cd-virtual-list', horizontal && 'cd-virtual-list--horizontal', className]
+      .filter(Boolean)
+      .join(' '),
+  );
+
+  // 视口主轴尺寸样式：window 模式容器不自身滚动（无 overflow/无固定高，撑开总高靠窗口
+  // 滚动）；self 模式 vertical 用高度、horizontal 用宽度并 overflow:auto。
+  const viewportStyle = $derived(
+    windowMode
+      ? ''
+      : horizontal
+        ? `inline-size:${heightStyle}; overflow:auto`
+        : `block-size:${heightStyle}; overflow:auto`,
+  );
+  // 撑高/撑宽占位主轴尺寸样式。
+  const spacerStyle = $derived(
+    horizontal ? `inline-size:${totalHeight}px` : `block-size:${totalHeight}px`,
+  );
+
+  // 每项主轴定位/尺寸样式（render 期只读派生，不触发测量）。
+  function itemStyle(idx: number): string {
+    const off = itemOffset(idx);
+    if (horizontal) {
+      // 横向：translateX 定位 + 列宽（fixed），高度撑满视口。
+      return `transform:translateX(${off}px); inline-size:${fixedSize}px`;
+    }
+    if (dynamic) return `transform:translateY(${off}px)`;
+    return `transform:translateY(${off}px); block-size:${fixedSize}px`;
+  }
+</script>
+
+<div class={cls} bind:this={viewportEl} role="list" style={viewportStyle}>
+  <div class="cd-virtual-list__spacer" style={spacerStyle}>
+    {#each visible as item, i (getKey(item, startIndex + i))}
+      <div
+        class="cd-virtual-list__item"
+        role="listitem"
+        data-vindex={startIndex + i}
+        aria-setsize={data.length}
+        aria-posinset={startIndex + i + 1}
+        style={itemStyle(startIndex + i)}
+      >
+        {@render renderItem(item, startIndex + i)}
+      </div>
+    {/each}
+  </div>
+</div>
+
+<style>
+  .cd-virtual-list {
+    position: relative;
+    inline-size: 100%;
+    background: var(--cd-virtual-list-bg);
+    scrollbar-color: var(--cd-virtual-list-scrollbar) transparent;
+  }
+  .cd-virtual-list__spacer {
+    position: relative;
+    inline-size: 100%;
+  }
+  .cd-virtual-list__item {
+    position: absolute;
+    inset-block-start: 0;
+    inset-inline: 0;
+  }
+  /* horizontal：视口主轴为宽度（block-size 撑满父容器高度）；项沿 x 轴绝对定位、纵向撑满。 */
+  .cd-virtual-list--horizontal {
+    block-size: 100%;
+  }
+  .cd-virtual-list--horizontal .cd-virtual-list__spacer {
+    block-size: 100%;
+    inline-size: auto;
+  }
+  .cd-virtual-list--horizontal .cd-virtual-list__item {
+    inset-block: 0;
+    inset-inline-start: 0;
+    inset-inline-end: auto;
+  }
+</style>

package/src/virtual-list/index.ts

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

package/src/virtual-list/meta.ts

@@ -0,0 +1,106 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * VirtualList — see specs/components/show/VirtualList.spec.md
+ */
+export const meta = {
+  name: 'VirtualList',
+  category: 'show',
+  description:
+    "虚拟滚动列表底座（泛型）：仅渲染可视区 + overscan 缓冲区高性能渲染超长列表。fixed 定高 O(1) 区间；dynamic 不定高（itemSize='auto'）用 estimatedItemSize 估算 + ResizeObserver 实测回填高度表，前缀和修正偏移/区间并做滚动偏移补偿。支持 vertical/horizontal（horizontal 仅 fixed 定宽，dynamic 退化为按 estimatedItemSize 的定宽）。scrollTarget='self'（默认）内部容器滚动；'window' 用窗口（document）滚动、容器撑高，适合整页长列表（纵向；horizontal 下退化为 self，fixed/dynamic 均复用窗口几何 windowScrollTop）。提供 scrollToIndex 命令式跳转 API。自身无视觉，行渲染由 renderItem 提供。",
+  exports: ['VirtualList'],
+  props: [
+    { name: 'data', type: 'T[]', default: '[]', desc: '列表数据数组' },
+    {
+      name: 'getKey',
+      type: '(item: T, index: number) => string | number',
+      default: '(_, i) => i',
+      desc: '行唯一标识，用于 each key',
+    },
+    {
+      name: 'itemSize',
+      type: "number | 'auto'",
+      default: '40',
+      desc: "固定行高（px，fixed 定高）；传 'auto' 启用 dynamic 不定高测量",
+    },
+    {
+      name: 'estimatedItemSize',
+      type: 'number',
+      default: '40',
+      desc: 'dynamic 模式初始估算行高（px），用于首屏占位与总高估算',
+    },
+    { name: 'overscan', type: 'number', default: '3', desc: '可视区上下缓冲行数，消除白屏' },
+    {
+      name: 'height',
+      type: 'number | string',
+      default: '400',
+      desc: '视口主轴尺寸（vertical 为高度、horizontal 为宽度）；数字按 px，字符串/百分比时用 ResizeObserver 测量',
+    },
+    {
+      name: 'horizontal',
+      type: 'boolean',
+      default: 'false',
+      desc: '横向虚拟化：沿 x 轴排列、itemSize 作列宽、读/写 scrollLeft（仅支持 fixed 定宽）',
+    },
+    {
+      name: 'scrollTarget',
+      type: "'self' | 'window'",
+      default: "'self'",
+      desc: "滚动源：'self' 内部容器自身滚动（默认，向后兼容）；'window' 用窗口（document）滚动、容器撑开总高，适合整页长列表（纵向）。horizontal 在 window 下退化为 self。",
+    },
+    {
+      name: 'renderItem',
+      type: 'Snippet<[item: T, index: number]>',
+      default: 'required',
+      desc: '行渲染 Snippet（必填）',
+    },
+    { name: 'class', type: 'string', default: "''", desc: '根类名透传' },
+  ],
+  events: [],
+  methods: [
+    {
+      name: 'scrollToIndex',
+      type: "(index: number, opts?: { align?: 'start' | 'center' | 'end' }) => void",
+      desc: '命令式滚动到指定索引项（bind:this 后调用）。align 默认 start；horizontal 时写 scrollLeft。index 自动 clamp。',
+    },
+  ],
+  slots: [{ name: 'renderItem', desc: '行渲染（item, index）' }],
+  a11y: {
+    role: 'list',
+    focusable: false,
+    notes: [
+      '视口 role=list，可见行 role=listitem',
+      '行带 aria-setsize（总数）与 aria-posinset（1 基序号）',
+      '滚动监听命令式 + rAF 节流，不读 render 期 DOM 几何',
+      'dynamic 行高用 ResizeObserver 命令式实测，cleanup 时 disconnect',
+      'scrollToIndex 为命令式 DOM 写（scrollTop/scrollLeft），放导出函数，不在 render 期',
+    ],
+  },
+  tokens: ['--cd-virtual-list-bg', '--cd-virtual-list-scrollbar'],
+  examples: [
+    {
+      title: '基础',
+      code:
+        '{#snippet row(item, i)}<div>{i}: {item.label}</div>{/snippet}\n<VirtualList data={rows} itemSize={48} height={400} renderItem={row} />',
+    },
+    {
+      title: 'dynamic 不定高',
+      code:
+        "{#snippet row(item, i)}<div>{item.text}</div>{/snippet}\n<VirtualList data={rows} itemSize=\"auto\" estimatedItemSize={48} height={300} renderItem={row} />",
+    },
+    {
+      title: 'horizontal 横向',
+      code:
+        '{#snippet col(item, i)}<div style="width:100%">{i}</div>{/snippet}\n<VirtualList data={rows} horizontal itemSize={120} height={400} renderItem={col} />',
+    },
+    {
+      title: 'scrollToIndex 命令式跳转',
+      code:
+        "let vl;\n<button onclick={() => vl.scrollToIndex(500, { align: 'center' })}>跳到第 500 项</button>\n<VirtualList bind:this={vl} data={rows} itemSize={36} renderItem={row} />",
+    },
+    {
+      title: 'window 窗口滚动（整页长列表）',
+      code:
+        '{#snippet row(item, i)}<div>{i}: {item.label}</div>{/snippet}\n<VirtualList data={rows} scrollTarget="window" itemSize={48} renderItem={row} />',
+    },
+  ],
+} as const;