@chenzy-design/svelte 0.3.0 → 0.4.1

package/dist/overflow-list/OverflowList.svelte.d.ts

@@ -1,64 +1,61 @@
 import type { Snippet } from 'svelte';
-declare function $$render<T>(): {
+declare function $$render<T extends Record<string, any>>(): {
     props: {
+        /** 数据驱动的渲染项；scroll 模式要求每项含 key（或提供 itemKey） */
         items?: T[];
-        size?: "small" | "default" | "large";
-        /** collapse 折叠溢出项为 +N（默认）；scroll 不折叠，可见层可滚动查看 */
-        mode?: "collapse" | "scroll";
-        /** 主轴方向：horizontal 横向（默认）/ vertical 纵向 */
-        direction?: "horizontal" | "vertical";
-        /** collapse 模式下从尾部（end，默认）还是头部（start）折叠 */
-        collapseFrom?: "end" | "start";
-        gap?: number;
+        /** 渲染模式：collapse 折叠（默认）/ scroll 滚动 */
+        renderMode?: "collapse" | "scroll";
+        /** collapse 模式折叠方向：end 尾部（默认）/ start 头部 */
+        collapseFrom?: "start" | "end";
+        /** collapse 模式最小可见项数目 */
         minVisibleItems?: number;
-        alwaysVisibleIndexes?: number[];
+        /** scroll 模式触发溢出回调的 IntersectionObserver 阈值 */
         threshold?: number;
-        item?: Snippet<[{
-            item: T;
-            index: number;
-        }]>;
-        overflow?: Snippet<[{
-            overflowItems: T[];
-            overflowCount: number;
-        }]>;
-        onOverflowChange?: (info: {
-            overflowCount: number;
-            visibleCount: number;
-            overflowItems: T[];
-        }) => void;
-        ariaLabel?: string;
+        /** 取项 key：字段名或函数；缺省取 item.key */
+        itemKey?: (string | number) | ((item: T) => string | number);
+        /** 可见项渲染模板（对齐 Semi visibleItemRenderer，Svelte 用 Snippet） */
+        visibleItemRenderer?: Snippet<[T, number]>;
+        /**
+         * 溢出项渲染模板（对齐 Semi overflowRenderer，Svelte 用 Snippet）。
+         * collapse 模式收到全部溢出项；scroll 模式收到 [头部溢出项, 尾部溢出项] 二元组，
+         * 需分别在两端渲染（与 Semi overflowRenderer 返回数组一致）。
+         */
+        overflowRenderer?: Snippet<[T[]]>;
+        /** collapse 模式溢出项变化回调 */
+        onOverflow?: (overflowItems: T[]) => void;
+        /** scroll 模式相交状态回调 */
+        onIntersect?: (res: Record<string, IntersectionObserverEntry>) => void;
+        /** scroll 模式可见状态变化回调 */
+        onVisibleStateChange?: (visibleState: Map<string, boolean>) => void;
+        /** scroll 模式滚动 wrapper 类名（对齐 Semi wrapperClassName） */
+        wrapperClass?: string;
+        /** scroll 模式滚动 wrapper 内联样式（对齐 Semi wrapperStyle） */
+        wrapperStyle?: string;
+        /** 根节点内联样式 */
+        style?: string;
+        /** 根节点附加类名 */
         class?: string;
     };
-    exports: {
-        forceMeasure: () => void;
-        scrollTo: (index: number, opts?: {
-            align?: "start" | "center" | "end";
-        }) => void;
-    };
+    exports: {};
     bindings: "";
     slots: {};
     events: {};
 };
-declare class __sveltets_Render<T> {
+declare class __sveltets_Render<T extends Record<string, any>> {
     props(): ReturnType<typeof $$render<T>>['props'];
     events(): ReturnType<typeof $$render<T>>['events'];
     slots(): ReturnType<typeof $$render<T>>['slots'];
     bindings(): "";
-    exports(): {
-        forceMeasure: () => void;
-        scrollTo: (index: number, opts?: {
-            align?: "start" | "center" | "end";
-        } | undefined) => void;
-    };
+    exports(): {};
 }
 interface $$IsomorphicComponent {
-    new <T>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+    new <T extends Record<string, any>>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
         $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
     } & ReturnType<__sveltets_Render<T>['exports']>;
-    <T>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    <T extends Record<string, any>>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
     z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
 }
 declare const OverflowList: $$IsomorphicComponent;
-type OverflowList<T> = InstanceType<typeof OverflowList<T>>;
+type OverflowList<T extends Record<string, any>> = InstanceType<typeof OverflowList<T>>;
 export default OverflowList;
 //# sourceMappingURL=OverflowList.svelte.d.ts.map

package/dist/overflow-list/OverflowList.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OverflowList.svelte.d.ts","sourceRoot":"","sources":["../../src/overflow-list/OverflowList.svelte.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAItC,iBAAS,QAAQ,CAAC,CAAC;;gBAQP,CAAC,EAAE;eACJ,OAAO,GAAG,SAAS,GAAG,OAAO;QACpC,iDAAiD;eAC1C,UAAU,GAAG,QAAQ;QAC5B,0CAA0C;oBAC9B,YAAY,GAAG,UAAU;QACrC,2CAA2C;uBAC5B,KAAK,GAAG,OAAO;cACxB,MAAM;0BACM,MAAM;+BACD,MAAM,EAAE;oBACnB,MAAM;eACX,OAAO,CAAC,CAAC;YAAE,IAAI,EAAE,CAAC,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;mBACjC,OAAO,CAAC,CAAC;YAAE,aAAa,EAAE,CAAC,EAAE,CAAC;YAAC,aAAa,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;2BAChD,CAAC,IAAI,EAAE;YACxB,aAAa,EAAE,MAAM,CAAC;YACtB,YAAY,EAAE,MAAM,CAAC;YACrB,aAAa,EAAE,CAAC,EAAE,CAAC;SACpB,KAAK,IAAI;oBACE,MAAM;gBACV,MAAM;;aAmVmD;QAAE,YAAY,QA5IvD,IAAI,CA4IyE;QAAA,QAAQ,UA7HtG,MAAM,SACN;YAAE,KAAK,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAA;SAAE,KAC5C,IAAI,CA2HyH;KAAE;;;;EAA+D;AACnM,cAAM,iBAAiB,CAAC,CAAC;IACrB,KAAK,IAAI,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;IAChD,MAAM,IAAI,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;IAClD,KAAK,IAAI,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;IAChD,QAAQ;IACR,OAAO;4BAlJiB,IAAI;0BAerB,MAAM;oBACI,OAAO,GAAG,QAAQ,GAAG,KAAK;0BAC1C,IAAI;;CAkIR;AAED,UAAU,qBAAqB;IAC3B,KAAK,CAAC,EAAE,OAAO,EAAE,OAAO,QAAQ,EAAE,2BAA2B,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,QAAQ,EAAE,eAAe,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,UAAU,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,UAAU,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG;QAAE,UAAU,CAAC,EAAE,UAAU,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAA;KAAE,GAAG,UAAU,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;IAC5X,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,GAAG,UAAU,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;IAC3H,YAAY,CAAC,EAAE,UAAU,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;CACjE;AACD,QAAA,MAAM,YAAY,EAAE,qBAAmC,CAAC;AACtC,KAAK,YAAY,CAAC,CAAC,IAAI,YAAY,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9D,eAAe,YAAY,CAAC"}
+{"version":3,"file":"OverflowList.svelte.d.ts","sourceRoot":"","sources":["../../src/overflow-list/OverflowList.svelte.ts"],"names":[],"mappings":"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"}

package/dist/overflow-list/meta.d.ts

@@ -1,125 +1,125 @@
 /**
  * Machine-readable component metadata for AI/docs consumption.
- * OverflowList — see specs/components/show/OverflowList.spec.md
+ * OverflowList — 严格镜像 Semi Design OverflowList。
  */
 export declare const meta: {
     readonly name: "OverflowList";
     readonly category: "show";
-    readonly description: "溢出列表：collapse 折叠模式把溢出项收纳进 +N 折叠节点（collapseFrom 决定从尾 end / 头 start 折叠），或 scroll 滚动模式不折叠改为可滚动容器；direction 支持 horizontal 横向 / vertical 纵向。ResizeObserver 命令式测量 + requestAnimationFrame 合批 + hysteresis 滞后防抖动，复用 @chenzy-design/core 收纳算法（computeOverflowPartition）。命令式方法（bind:this 暴露）：forceMeasure() 强制立即重测重算（容器尺寸变化未被 RO 捕获时手动触发）；scrollTo(index, opts?) scroll 模式滚动到指定项（opts.align start/center/end）。";
+    readonly description: "溢出折叠列表，严格镜像 Semi OverflowList。行为组件：展示列表并自适应展示尽可能多的项目，因过长而溢出的项折叠为一个元素，容器 resize 时重新计算可见项。renderMode=\"collapse\"（默认）用 ResizeObserver 累加各项宽度找折叠点，溢出项收纳进 overflowRenderer 返回的节点，collapseFrom 决定从尾（end）/头（start）折叠，minVisibleItems 保底可见数；renderMode=\"scroll\" 不折叠，可见层为可横向滚动容器，用 IntersectionObserver 观测各项，threshold 控制阈值，onIntersect/onVisibleStateChange 上报可见状态。渲染函数以 Svelte Snippet 形式提供（visibleItemRenderer/overflowRenderer）。";
     readonly exports: readonly ["OverflowList"];
     readonly props: readonly [{
         readonly name: "items";
         readonly type: "T[]";
         readonly default: "[]";
-        readonly desc: "数据驱动的列表项";
+        readonly desc: "数据驱动的渲染项；scroll 模式要求每项含 key（或提供 itemKey）";
     }, {
-        readonly name: "size";
-        readonly type: "'small'|'default'|'large'";
-        readonly default: "'default'";
-        readonly desc: "影响 gap（small 4 / default 8 / large 12 px）";
-    }, {
-        readonly name: "mode";
+        readonly name: "renderMode";
         readonly type: "'collapse'|'scroll'";
         readonly default: "'collapse'";
-        readonly desc: "collapse 折叠溢出项为 +N（默认）；scroll 不折叠，可见层沿主轴可滚动";
-    }, {
-        readonly name: "direction";
-        readonly type: "'horizontal'|'vertical'";
-        readonly default: "'horizontal'";
-        readonly desc: "主轴方向：横向（测项宽 + clientWidth）/ 纵向（测项高 + clientHeight，根容器需有高度约束）";
+        readonly desc: "渲染模式：collapse 折叠（默认）/ scroll 滚动";
     }, {
         readonly name: "collapseFrom";
-        readonly type: "'end'|'start'";
+        readonly type: "'start'|'end'";
         readonly default: "'end'";
-        readonly desc: "collapse 模式下从尾部（end）还是头部（start）折叠；start 时折叠节点渲染在头部，尾部项保持可见";
-    }, {
-        readonly name: "gap";
-        readonly type: "number";
-        readonly default: "undefined";
-        readonly desc: "显式覆盖项间距（px）";
+        readonly desc: "collapse 模式折叠方向：end 尾部（默认）/ start 头部";
     }, {
         readonly name: "minVisibleItems";
         readonly type: "number";
         readonly default: "0";
-        readonly desc: "永不折叠到少于该数量的可见项";
-    }, {
-        readonly name: "alwaysVisibleIndexes";
-        readonly type: "number[]";
-        readonly default: "[]";
-        readonly desc: "永不被折叠的项索引";
+        readonly desc: "collapse 模式最小可见项数目";
     }, {
         readonly name: "threshold";
         readonly type: "number";
-        readonly default: "8";
-        readonly desc: "hysteresis 滞后阈值（px），抑制边界宽度抖动";
+        readonly default: "0.75";
+        readonly desc: "scroll 模式触发溢出回调的 IntersectionObserver 阈值";
     }, {
-        readonly name: "item";
-        readonly type: "Snippet<[{ item: T; index: number }]>";
+        readonly name: "itemKey";
+        readonly type: "string|number|((item: T) => string|number)";
         readonly default: "undefined";
-        readonly desc: "渲染单个可见项";
+        readonly desc: "取项 key：字段名或函数；缺省取 item.key";
     }, {
-        readonly name: "overflow";
-        readonly type: "Snippet<[{ overflowItems: T[]; overflowCount: number }]>";
+        readonly name: "visibleItemRenderer";
+        readonly type: "Snippet<[item: T, index: number]>";
         readonly default: "undefined";
-        readonly desc: "自定义折叠节点；缺省渲染 +N 按钮";
+        readonly desc: "可见项渲染模板（对齐 Semi visibleItemRenderer）";
     }, {
-        readonly name: "onOverflowChange";
-        readonly type: "(info: { overflowCount: number; visibleCount: number; overflowItems: T[] }) => void";
+        readonly name: "overflowRenderer";
+        readonly type: "Snippet<[overflowItems: T[]]>";
         readonly default: "undefined";
-        readonly desc: "收纳结果变化时通知（去重，仅真实变化触发）";
+        readonly desc: "溢出项渲染模板（对齐 Semi overflowRenderer）。collapse 收全部溢出项；scroll 分别收 [头部溢出, 尾部溢出] 二次调用渲染在两端";
     }, {
-        readonly name: "ariaLabel";
-        readonly type: "string";
+        readonly name: "onOverflow";
+        readonly type: "(overflowItems: T[]) => void";
+        readonly default: "undefined";
+        readonly desc: "collapse 模式溢出项变化回调（去重）";
+    }, {
+        readonly name: "onIntersect";
+        readonly type: "(res: Record<string, IntersectionObserverEntry>) => void";
         readonly default: "undefined";
-        readonly desc: "容器无障碍标签";
+        readonly desc: "scroll 模式相交状态回调";
+    }, {
+        readonly name: "onVisibleStateChange";
+        readonly type: "(visibleState: Map<string, boolean>) => void";
+        readonly default: "undefined";
+        readonly desc: "scroll 模式可见状态变化回调";
+    }, {
+        readonly name: "wrapperClass";
+        readonly type: "string";
+        readonly default: "''";
+        readonly desc: "scroll 模式滚动 wrapper 类名（对齐 Semi wrapperClassName）";
+    }, {
+        readonly name: "wrapperStyle";
+        readonly type: "string";
+        readonly default: "''";
+        readonly desc: "scroll 模式滚动 wrapper 内联样式（对齐 Semi wrapperStyle）";
+    }, {
+        readonly name: "style";
+        readonly type: "string";
+        readonly default: "''";
+        readonly desc: "根节点内联样式";
     }, {
         readonly name: "class";
         readonly type: "string";
         readonly default: "''";
-        readonly desc: "附加根类名";
+        readonly desc: "根节点附加类名";
     }];
     readonly events: readonly [{
-        readonly name: "onOverflowChange";
-        readonly desc: "可见数 / 溢出数变化时回调，携带 overflowItems";
-    }];
-    readonly methods: readonly [{
-        readonly name: "forceMeasure";
-        readonly type: "() => void";
-        readonly desc: "命令式强制立即重新测量 + 重算可见/溢出划分（bind:this 后调用）。用于容器尺寸变化未被 ResizeObserver 捕获的场景：父级 display 切回、字体加载、缩放等。同步执行，去重 onOverflowChange 同样生效。";
-    }, {
-        readonly name: "scrollTo";
-        readonly type: "(index: number, opts?: { align?: 'start' | 'center' | 'end' }) => void";
-        readonly desc: "scroll 模式下命令式滚动到指定项（bind:this 后调用）。align 默认 start；vertical 写 scrollTop，horizontal 写 scrollLeft；index 自动 clamp。collapse 模式为 no-op。";
+        readonly name: "onOverflow";
+        readonly desc: "collapse 模式溢出项变化时回调，携带 overflowItems";
+    }, {
+        readonly name: "onIntersect";
+        readonly desc: "scroll 模式各项相交状态回调，携带 { key: IntersectionObserverEntry }";
+    }, {
+        readonly name: "onVisibleStateChange";
+        readonly desc: "scroll 模式可见状态 Map 变化回调";
     }];
+    readonly methods: readonly [];
     readonly slots: readonly [{
-        readonly name: "item";
-        readonly desc: "单个可见项渲染模板";
+        readonly name: "visibleItemRenderer";
+        readonly desc: "单个可见项渲染模板（item, index）";
     }, {
-        readonly name: "overflow";
-        readonly desc: "自定义 +N 折叠节点";
+        readonly name: "overflowRenderer";
+        readonly desc: "溢出节点渲染模板（overflowItems）";
     }];
     readonly a11y: {
         readonly hasRole: false;
         readonly focusable: false;
-        readonly note: "根容器 role=group 透明保留子项语义；折叠节点为 button + aria-label「显示其余 N 项」；离屏测量层 aria-hidden 且不进 Tab 序（tabindex=-1）；被折叠项随之移出 Tab 序。";
+        readonly note: "行为组件，不注入语义角色（对齐 Semi）；DOM 结构 cd-overflow-list > cd-overflow-list-item / cd-overflow-list-overflow / cd-overflow-list-scroll-wrapper；可见/溢出/焦点语义由 visibleItemRenderer/overflowRenderer 提供的宿主内容决定。";
     };
-    readonly tokens: readonly ["--cd-overflow-list-gap", "--cd-overflow-list-gap-small", "--cd-overflow-list-gap-large", "--cd-overflow-list-overflow-color", "--cd-overflow-list-overflow-color-hover", "--cd-overflow-list-overflow-bg", "--cd-overflow-list-overflow-bg-hover", "--cd-overflow-list-overflow-radius", "--cd-overflow-list-focus-ring"];
+    readonly tokens: readonly [];
     readonly responsive: true;
     readonly examples: readonly [{
-        readonly title: "基础工具栏收纳";
-        readonly code: "<OverflowList items={tags}>{#snippet item({ item })}<Tag>{item}</Tag>{/snippet}</OverflowList>";
-    }, {
-        readonly title: "自定义折叠节点";
-        readonly code: "<OverflowList {items}>\n  {#snippet item({ item })}<Tag>{item}</Tag>{/snippet}\n  {#snippet overflow({ overflowCount })}<Dropdown>更多 {overflowCount}</Dropdown>{/snippet}\n</OverflowList>";
+        readonly title: "折叠模式（默认）";
+        readonly code: "<OverflowList {items}>\n  {#snippet visibleItemRenderer(item)}<Tag color=\"blue\">{item.key}</Tag>{/snippet}\n  {#snippet overflowRenderer(rest)}{#if rest.length}<Tag>+{rest.length}</Tag>{/if}{/snippet}\n</OverflowList>";
     }, {
-        readonly title: "start 头部折叠（保留尾部最新项）";
-        readonly code: "<OverflowList {items} collapseFrom=\"start\">{#snippet item({ item })}<Tag>{item}</Tag>{/snippet}</OverflowList>";
+        readonly title: "折叠方向 collapseFrom=\"start\"";
+        readonly code: "<OverflowList {items} collapseFrom=\"start\">\n  {#snippet visibleItemRenderer(item)}<Tag>{item.key}</Tag>{/snippet}\n  {#snippet overflowRenderer(rest)}{#if rest.length}<Tag>+{rest.length}</Tag>{/if}{/snippet}\n</OverflowList>";
     }, {
-        readonly title: "scroll 滚动模式（不折叠）";
-        readonly code: "<OverflowList {items} mode=\"scroll\">{#snippet item({ item })}<Tag>{item}</Tag>{/snippet}</OverflowList>";
+        readonly title: "最小展示数目 minVisibleItems";
+        readonly code: "<OverflowList {items} minVisibleItems={3}>…</OverflowList>";
     }, {
-        readonly title: "vertical 纵向（容器需有高度）";
-        readonly code: "<div style=\"height:200px\"><OverflowList {items} direction=\"vertical\">{#snippet item({ item })}<Tag>{item}</Tag>{/snippet}</OverflowList></div>";
+        readonly title: "滚动模式 renderMode=\"scroll\"";
+        readonly code: "<OverflowList {items} renderMode=\"scroll\">\n  {#snippet visibleItemRenderer(item)}<Tag>{item.key}</Tag>{/snippet}\n  {#snippet overflowRenderer(rest)}{#each rest as it}<Tag>{it.key}</Tag>{/each}{/snippet}\n</OverflowList>";
     }];
 };
 //# sourceMappingURL=meta.d.ts.map

package/dist/overflow-list/meta.d.ts.map

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

package/dist/overflow-list/meta.js

@@ -1,137 +1,122 @@
 /**
  * Machine-readable component metadata for AI/docs consumption.
- * OverflowList — see specs/components/show/OverflowList.spec.md
+ * OverflowList — 严格镜像 Semi Design OverflowList。
  */
 export const meta = {
     name: 'OverflowList',
     category: 'show',
-    description: '溢出列表：collapse 折叠模式把溢出项收纳进 +N 折叠节点（collapseFrom 决定从尾 end / 头 start 折叠），或 scroll 滚动模式不折叠改为可滚动容器；direction 支持 horizontal 横向 / vertical 纵向。ResizeObserver 命令式测量 + requestAnimationFrame 合批 + hysteresis 滞后防抖动，复用 @chenzy-design/core 收纳算法（computeOverflowPartition）。命令式方法（bind:this 暴露）：forceMeasure() 强制立即重测重算（容器尺寸变化未被 RO 捕获时手动触发）；scrollTo(index, opts?) scroll 模式滚动到指定项（opts.align start/center/end）。',
+    description: '溢出折叠列表，严格镜像 Semi OverflowList。行为组件：展示列表并自适应展示尽可能多的项目，因过长而溢出的项折叠为一个元素，容器 resize 时重新计算可见项。renderMode="collapse"（默认）用 ResizeObserver 累加各项宽度找折叠点，溢出项收纳进 overflowRenderer 返回的节点，collapseFrom 决定从尾（end）/头（start）折叠，minVisibleItems 保底可见数；renderMode="scroll" 不折叠，可见层为可横向滚动容器，用 IntersectionObserver 观测各项，threshold 控制阈值，onIntersect/onVisibleStateChange 上报可见状态。渲染函数以 Svelte Snippet 形式提供（visibleItemRenderer/overflowRenderer）。',
     exports: ['OverflowList'],
     props: [
-        { name: 'items', type: 'T[]', default: '[]', desc: '数据驱动的列表项' },
+        { name: 'items', type: 'T[]', default: '[]', desc: '数据驱动的渲染项；scroll 模式要求每项含 key（或提供 itemKey）' },
         {
-            name: 'size',
-            type: "'small'|'default'|'large'",
-            default: "'default'",
-            desc: '影响 gap（small 4 / default 8 / large 12 px）',
-        },
-        {
-            name: 'mode',
+            name: 'renderMode',
             type: "'collapse'|'scroll'",
             default: "'collapse'",
-            desc: 'collapse 折叠溢出项为 +N（默认）；scroll 不折叠，可见层沿主轴可滚动',
-        },
-        {
-            name: 'direction',
-            type: "'horizontal'|'vertical'",
-            default: "'horizontal'",
-            desc: '主轴方向：横向（测项宽 + clientWidth）/ 纵向（测项高 + clientHeight，根容器需有高度约束）',
+            desc: '渲染模式：collapse 折叠（默认）/ scroll 滚动',
         },
         {
             name: 'collapseFrom',
-            type: "'end'|'start'",
+            type: "'start'|'end'",
             default: "'end'",
-            desc: 'collapse 模式下从尾部（end）还是头部（start）折叠；start 时折叠节点渲染在头部，尾部项保持可见',
+            desc: 'collapse 模式折叠方向：end 尾部（默认）/ start 头部',
         },
-        { name: 'gap', type: 'number', default: 'undefined', desc: '显式覆盖项间距（px）' },
         {
             name: 'minVisibleItems',
             type: 'number',
             default: '0',
-            desc: '永不折叠到少于该数量的可见项',
-        },
-        {
-            name: 'alwaysVisibleIndexes',
-            type: 'number[]',
-            default: '[]',
-            desc: '永不被折叠的项索引',
+            desc: 'collapse 模式最小可见项数目',
         },
         {
             name: 'threshold',
             type: 'number',
-            default: '8',
-            desc: 'hysteresis 滞后阈值（px），抑制边界宽度抖动',
+            default: '0.75',
+            desc: 'scroll 模式触发溢出回调的 IntersectionObserver 阈值',
         },
         {
-            name: 'item',
-            type: 'Snippet<[{ item: T; index: number }]>',
+            name: 'itemKey',
+            type: 'string|number|((item: T) => string|number)',
             default: 'undefined',
-            desc: '渲染单个可见项',
+            desc: '取项 key：字段名或函数；缺省取 item.key',
         },
         {
-            name: 'overflow',
-            type: 'Snippet<[{ overflowItems: T[]; overflowCount: number }]>',
+            name: 'visibleItemRenderer',
+            type: 'Snippet<[item: T, index: number]>',
             default: 'undefined',
-            desc: '自定义折叠节点；缺省渲染 +N 按钮',
+            desc: '可见项渲染模板（对齐 Semi visibleItemRenderer）',
         },
         {
-            name: 'onOverflowChange',
-            type: '(info: { overflowCount: number; visibleCount: number; overflowItems: T[] }) => void',
+            name: 'overflowRenderer',
+            type: 'Snippet<[overflowItems: T[]]>',
             default: 'undefined',
-            desc: '收纳结果变化时通知（去重，仅真实变化触发）',
+            desc: '溢出项渲染模板（对齐 Semi overflowRenderer）。collapse 收全部溢出项；scroll 分别收 [头部溢出, 尾部溢出] 二次调用渲染在两端',
         },
-        { name: 'ariaLabel', type: 'string', default: 'undefined', desc: '容器无障碍标签' },
-        { name: 'class', type: 'string', default: "''", desc: '附加根类名' },
-    ],
-    events: [
         {
-            name: 'onOverflowChange',
-            desc: '可见数 / 溢出数变化时回调，携带 overflowItems',
+            name: 'onOverflow',
+            type: '(overflowItems: T[]) => void',
+            default: 'undefined',
+            desc: 'collapse 模式溢出项变化回调（去重）',
         },
-    ],
-    methods: [
         {
-            name: 'forceMeasure',
-            type: '() => void',
-            desc: '命令式强制立即重新测量 + 重算可见/溢出划分（bind:this 后调用）。用于容器尺寸变化未被 ResizeObserver 捕获的场景：父级 display 切回、字体加载、缩放等。同步执行，去重 onOverflowChange 同样生效。',
+            name: 'onIntersect',
+            type: '(res: Record<string, IntersectionObserverEntry>) => void',
+            default: 'undefined',
+            desc: 'scroll 模式相交状态回调',
         },
         {
-            name: 'scrollTo',
-            type: "(index: number, opts?: { align?: 'start' | 'center' | 'end' }) => void",
-            desc: 'scroll 模式下命令式滚动到指定项（bind:this 后调用）。align 默认 start；vertical 写 scrollTop，horizontal 写 scrollLeft；index 自动 clamp。collapse 模式为 no-op。',
+            name: 'onVisibleStateChange',
+            type: '(visibleState: Map<string, boolean>) => void',
+            default: 'undefined',
+            desc: 'scroll 模式可见状态变化回调',
+        },
+        {
+            name: 'wrapperClass',
+            type: 'string',
+            default: "''",
+            desc: 'scroll 模式滚动 wrapper 类名（对齐 Semi wrapperClassName）',
+        },
+        {
+            name: 'wrapperStyle',
+            type: 'string',
+            default: "''",
+            desc: 'scroll 模式滚动 wrapper 内联样式（对齐 Semi wrapperStyle）',
         },
+        { name: 'style', type: 'string', default: "''", desc: '根节点内联样式' },
+        { name: 'class', type: 'string', default: "''", desc: '根节点附加类名' },
     ],
+    events: [
+        { name: 'onOverflow', desc: 'collapse 模式溢出项变化时回调，携带 overflowItems' },
+        { name: 'onIntersect', desc: 'scroll 模式各项相交状态回调，携带 { key: IntersectionObserverEntry }' },
+        { name: 'onVisibleStateChange', desc: 'scroll 模式可见状态 Map 变化回调' },
+    ],
+    methods: [],
     slots: [
-        { name: 'item', desc: '单个可见项渲染模板' },
-        { name: 'overflow', desc: '自定义 +N 折叠节点' },
+        { name: 'visibleItemRenderer', desc: '单个可见项渲染模板（item, index）' },
+        { name: 'overflowRenderer', desc: '溢出节点渲染模板（overflowItems）' },
     ],
     a11y: {
         hasRole: false,
         focusable: false,
-        note: '根容器 role=group 透明保留子项语义；折叠节点为 button + aria-label「显示其余 N 项」；离屏测量层 aria-hidden 且不进 Tab 序（tabindex=-1）；被折叠项随之移出 Tab 序。',
+        note: '行为组件，不注入语义角色（对齐 Semi）；DOM 结构 cd-overflow-list > cd-overflow-list-item / cd-overflow-list-overflow / cd-overflow-list-scroll-wrapper；可见/溢出/焦点语义由 visibleItemRenderer/overflowRenderer 提供的宿主内容决定。',
     },
-    tokens: [
-        '--cd-overflow-list-gap',
-        '--cd-overflow-list-gap-small',
-        '--cd-overflow-list-gap-large',
-        '--cd-overflow-list-overflow-color',
-        '--cd-overflow-list-overflow-color-hover',
-        '--cd-overflow-list-overflow-bg',
-        '--cd-overflow-list-overflow-bg-hover',
-        '--cd-overflow-list-overflow-radius',
-        '--cd-overflow-list-focus-ring',
-    ],
+    tokens: [],
     responsive: true,
     examples: [
         {
-            title: '基础工具栏收纳',
-            code: '<OverflowList items={tags}>{#snippet item({ item })}<Tag>{item}</Tag>{/snippet}</OverflowList>',
-        },
-        {
-            title: '自定义折叠节点',
-            code: '<OverflowList {items}>\n  {#snippet item({ item })}<Tag>{item}</Tag>{/snippet}\n  {#snippet overflow({ overflowCount })}<Dropdown>更多 {overflowCount}</Dropdown>{/snippet}\n</OverflowList>',
+            title: '折叠模式（默认）',
+            code: '<OverflowList {items}>\n  {#snippet visibleItemRenderer(item)}<Tag color="blue">{item.key}</Tag>{/snippet}\n  {#snippet overflowRenderer(rest)}{#if rest.length}<Tag>+{rest.length}</Tag>{/if}{/snippet}\n</OverflowList>',
         },
         {
-            title: 'start 头部折叠（保留尾部最新项）',
-            code: '<OverflowList {items} collapseFrom="start">{#snippet item({ item })}<Tag>{item}</Tag>{/snippet}</OverflowList>',
+            title: '折叠方向 collapseFrom="start"',
+            code: '<OverflowList {items} collapseFrom="start">\n  {#snippet visibleItemRenderer(item)}<Tag>{item.key}</Tag>{/snippet}\n  {#snippet overflowRenderer(rest)}{#if rest.length}<Tag>+{rest.length}</Tag>{/if}{/snippet}\n</OverflowList>',
         },
         {
-            title: 'scroll 滚动模式（不折叠）',
-            code: '<OverflowList {items} mode="scroll">{#snippet item({ item })}<Tag>{item}</Tag>{/snippet}</OverflowList>',
+            title: '最小展示数目 minVisibleItems',
+            code: '<OverflowList {items} minVisibleItems={3}>…</OverflowList>',
         },
         {
-            title: 'vertical 纵向（容器需有高度）',
-            code: '<div style="height:200px"><OverflowList {items} direction="vertical">{#snippet item({ item })}<Tag>{item}</Tag>{/snippet}</OverflowList></div>',
+            title: '滚动模式 renderMode="scroll"',
+            code: '<OverflowList {items} renderMode="scroll">\n  {#snippet visibleItemRenderer(item)}<Tag>{item.key}</Tag>{/snippet}\n  {#snippet overflowRenderer(rest)}{#each rest as it}<Tag>{it.key}</Tag>{/each}{/snippet}\n</OverflowList>',
         },
     ],
 };