@chenzy-design/svelte 0.1.0 → 0.2.0

package/src/upload/UploadA11yFixture.svelte

@@ -1,23 +0,0 @@
-<!--
-  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

@@ -1,3 +0,0 @@
-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

@@ -1,64 +0,0 @@
-/**
- * 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

@@ -1,16 +0,0 @@
-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

@@ -1,401 +0,0 @@
-<!--
-  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

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

package/src/virtual-list/meta.ts

@@ -1,106 +0,0 @@
-/**
- * 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;