vane-waterfall 2.0.2 → 2.0.3

package/dist/custom-plugins/A11yPlugin/doc.json.d.ts

@@ -1,52 +1,76 @@
-declare const _default: {
-  "name": "A11yPlugin",
-  "description": "把瀑布流补成读屏可理解的列表：容器 `role=list` + `aria-label`，每项 `role=listitem` + `aria-posinset` / `aria-setsize`，并可选加 `tabIndex` 让键盘能逐项聚焦。",
-  "since": "2.0.0",
-  "tags": [
-    "ui",
-    "a11y"
-  ],
-  "config": [
+declare const _default: {
+  "name": "A11yPlugin",
+  "description": "把瀑布流补成读屏可理解的列表：容器 `role=list` + `aria-label`，每项 `role=listitem` + `aria-posinset` / `aria-setsize`，并可选加 `tabIndex` 让键盘能逐项聚焦。",
+  "since": "2.0.0",
+  "tags": [
+    "ui",
+    "a11y"
+  ],
+  "events": [
     {
-      "name": "containerRole",
-      "type": "string",
-      "default": "\"list\"",
-      "description": "容器 role"
+      "name": "onMount",
+      "when": "瀑布流挂载完成",
+      "description": "初始化观察器与滚动监听，返回清理函数"
     },
     {
-      "name": "itemRole",
-      "type": "string",
-      "default": "\"listitem\"",
-      "description": "项 role"
+      "name": "onItemClick",
+      "when": "单个卡片被点击",
+      "description": "卡片级跳转与点击埋点"
     },
     {
-      "name": "enableTabIndex",
-      "type": "boolean",
-      "default": "true",
-      "description": "项是否可 Tab 聚焦"
+      "name": "onLayoutComplete",
+      "when": "DOM 落位完成（可安全测量）",
+      "description": "测量真实高度、懒加载判定、曝光上报"
     },
     {
-      "name": "containerLabel",
-      "type": "string",
-      "default": "\"Waterfall list\"",
-      "description": "容器 aria-label"
+      "name": "renderItemWrapper",
+      "when": "渲染每个卡片时包裹其内容",
+      "description": "给单卡加包裹层（拖拽、无障碍语义、占位骨架）"
     }
   ],
-  "example": "// 给容器与项补 ARIA role / label / posinset，支持键盘 Tab 遍历。\nconst Waterfall = withPlugins(WaterfallCore, [\n  createA11yPlugin({\n    containerRole: \"list\",\n    itemRole: \"listitem\",\n    enableTabIndex: true,\n  }),\n]);\n\n<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;",
-  "features": [
-    "容器 / 项 role 成对补齐",
-    "aria-posinset + aria-setsize 正确标注序号",
-    "键盘可逐项聚焦"
-  ],
-  "useCases": [
-    "政务 / 金融等合规站点",
-    "读屏用户可用的信息流",
-    "键盘操作优先的桌面端"
-  ],
-  "notes": [
-    "项数很多时 `tabIndex=0` 会让 Tab 变长，建议配合「跳转主内容」链接使用。"
-  ]
-}
+  "methods": [],
+  "methodsNote": "只读取 context 字段（props / state / data），不调用上下文方法",
+  "config": [
+    {
+      "name": "containerRole",
+      "type": "string",
+      "default": "\"list\"",
+      "description": "容器 role"
+    },
+    {
+      "name": "itemRole",
+      "type": "string",
+      "default": "\"listitem\"",
+      "description": "项 role"
+    },
+    {
+      "name": "enableTabIndex",
+      "type": "boolean",
+      "default": "true",
+      "description": "项是否可 Tab 聚焦"
+    },
+    {
+      "name": "containerLabel",
+      "type": "string",
+      "default": "\"Waterfall list\"",
+      "description": "容器 aria-label"
+    }
+  ],
+  "example": "// 给容器与项补 ARIA role / label / posinset，支持键盘 Tab 遍历。\nconst Waterfall = withPlugins(WaterfallCore, [\n  createA11yPlugin({\n    containerRole: \"list\",\n    itemRole: \"listitem\",\n    enableTabIndex: true,\n  }),\n]);\n\n<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;",
+  "features": [
+    "容器 / 项 role 成对补齐",
+    "aria-posinset + aria-setsize 正确标注序号",
+    "键盘可逐项聚焦"
+  ],
+  "useCases": [
+    "政务 / 金融等合规站点",
+    "读屏用户可用的信息流",
+    "键盘操作优先的桌面端"
+  ],
+  "notes": [
+    "项数很多时 `tabIndex=0` 会让 Tab 变长，建议配合「跳转主内容」链接使用。"
+  ]
+}
 ;
 
 export default _default;

package/dist/custom-plugins/A11yPlugin/index.js

@@ -1,4 +1,4 @@
-import { c as e, d as t } from "../../chunks/doc-BCmEnh39.js";
+import { c as e, d as t } from "../../chunks/doc-CkuMr8Ca.js";
 const c = Object.assign(e, { meta: t });
 export {
   c as createA11yPlugin

package/dist/custom-plugins/AlignmentPlugin/doc.json.d.ts

@@ -1,34 +1,48 @@
-declare const _default: {
-  "name": "AlignmentPlugin",
-  "description": "设置瀑布流的列分配策略。shortest 让每列尽量等高（视觉最自然），balanced 让每列项数接近，sequential 按 index 轮转（可预测位置，适合需要与外部索引对齐的场景）。",
-  "since": "2.0.0",
-  "tags": [
-    "layout",
-    "布局"
-  ],
-  "config": [
+declare const _default: {
+  "name": "AlignmentPlugin",
+  "description": "设置瀑布流的列分配策略。shortest 让每列尽量等高（视觉最自然），balanced 让每列项数接近，sequential 按 index 轮转（可预测位置，适合需要与外部索引对齐的场景）。",
+  "since": "2.0.0",
+  "tags": [
+    "layout",
+    "布局"
+  ],
+  "events": [
+    {
+      "name": "onResize",
+      "when": "容器宽度变化触发重排前",
+      "description": "按新宽度调整列数或卡片密度"
+    },
     {
-      "name": "mode",
-      "type": "\"shortest\" | \"balanced\" | \"sequential\"",
-      "default": "shortest",
-      "description": "列分配策略"
+      "name": "transformProps",
+      "when": "渲染前链式改写瀑布流 props",
+      "description": "补 gap / columns 默认值、按断点覆盖配置"
     }
   ],
-  "example": "// 指定列分配策略：最矮列优先（shortest）/ 项数均衡（balanced）/ 顺序轮转（sequential）。\nconst Waterfall = withPlugins(WaterfallCore, [\n  createAlignmentPlugin({\n    mode: \"shortest\",\n  }),\n]);\n\n<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;",
-  "features": [
-    "三种列分配策略",
-    "只改 props.alignmentMode，不影响其他配置",
-    "与 ResponsiveColumns / AutoColumn 正交"
-  ],
-  "useCases": [
-    "内容流：默认 shortest",
-    "等长卡片：balanced 更整齐",
-    "需要与后端顺序对齐：sequential"
-  ],
-  "notes": [
-    "balanced 与 shortest 在列高相同时都取最左列，视觉上左偏是预期行为。"
-  ]
-}
+  "methods": [],
+  "methodsNote": "只读取 context 字段（props / state / data），不调用上下文方法",
+  "config": [
+    {
+      "name": "mode",
+      "type": "\"shortest\" | \"balanced\" | \"sequential\"",
+      "default": "shortest",
+      "description": "列分配策略"
+    }
+  ],
+  "example": "// 指定列分配策略：最矮列优先（shortest）/ 项数均衡（balanced）/ 顺序轮转（sequential）。\nconst Waterfall = withPlugins(WaterfallCore, [\n  createAlignmentPlugin({\n    mode: \"shortest\",\n  }),\n]);\n\n<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;",
+  "features": [
+    "三种列分配策略",
+    "只改 props.alignmentMode，不影响其他配置",
+    "与 ResponsiveColumns / AutoColumn 正交"
+  ],
+  "useCases": [
+    "内容流：默认 shortest",
+    "等长卡片：balanced 更整齐",
+    "需要与后端顺序对齐：sequential"
+  ],
+  "notes": [
+    "balanced 与 shortest 在列高相同时都取最左列，视觉上左偏是预期行为。"
+  ]
+}
 ;
 
 export default _default;

package/dist/custom-plugins/AlignmentPlugin/index.js

@@ -1,4 +1,4 @@
-import { c as e, d as t } from "../../chunks/doc-gTAsLjVx.js";
+import { c as e, d as t } from "../../chunks/doc-CYxwSuG6.js";
 const a = Object.assign(e, { meta: t });
 export {
   a as createAlignmentPlugin

package/dist/custom-plugins/AutoColumnPlugin/doc.json.d.ts

@@ -1,50 +1,59 @@
-declare const _default: {
-  "name": "AutoColumnPlugin",
-  "description": "按「容器可用宽度 ÷ 最小列宽」自动决定列数，取代写死 3 列。走 D1-A 布局钩子（calculateColumns），拿到的是真实容器宽度，不是 window.innerWidth。",
-  "since": "2.0.0",
-  "tags": [
-    "layout",
-    "layout-hook",
-    "响应式"
-  ],
-  "config": [
-    {
-      "name": "minColumnWidth",
-      "type": "number",
-      "default": "—",
-      "description": "每列最小宽度 px（必填）"
-    },
-    {
-      "name": "maxColumns",
-      "type": "number",
-      "default": "Infinity",
-      "description": "列数上限"
-    },
+declare const _default: {
+  "name": "AutoColumnPlugin",
+  "description": "按「容器可用宽度 ÷ 最小列宽」自动决定列数，取代写死 3 列。走 D1-A 布局钩子（calculateColumns），拿到的是真实容器宽度，不是 window.innerWidth。",
+  "since": "2.0.0",
+  "tags": [
+    "layout",
+    "layout-hook",
+    "响应式"
+  ],
+  "events": [
     {
-      "name": "minColumns",
-      "type": "number",
-      "default": "1",
-      "description": "列数下限"
+      "name": "calculateColumns",
+      "when": "每次布局前，询问列数",
+      "description": "返回列数则覆盖 props.columns；返回 undefined 沿用配置"
     }
   ],
-  "example": "// 按容器宽与最小列宽自动算列数，窄屏自动降列。\nconst Waterfall = withPlugins(WaterfallCore, [\n  createAutoColumnPlugin({\n    maxColumns: \"Infinity\",\n    minColumns: 1,\n  }),\n]);\n\n<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;",
-  "conflicts": [
-    "ResponsiveColumnsPlugin"
-  ],
-  "features": [
-    "按容器宽度（不是视口宽度）算列数",
-    "列数上下限可夹",
-    "与 Gap / Padding 一起算，留白不吞列宽"
-  ],
-  "useCases": [
-    "响应式信息流",
-    "侧边栏宽度可拖动的后台看板",
-    "移动端 → 桌面端同一套代码"
-  ],
-  "notes": [
-    "与 ResponsiveColumnsPlugin 同时装会互相覆盖列数，只选一个。"
-  ]
-}
+  "methods": [],
+  "methodsNote": "只读取 context 字段（props / state / data），不调用上下文方法",
+  "config": [
+    {
+      "name": "minColumnWidth",
+      "type": "number",
+      "default": "—",
+      "description": "每列最小宽度 px（必填）"
+    },
+    {
+      "name": "maxColumns",
+      "type": "number",
+      "default": "Infinity",
+      "description": "列数上限"
+    },
+    {
+      "name": "minColumns",
+      "type": "number",
+      "default": "1",
+      "description": "列数下限"
+    }
+  ],
+  "example": "// 按容器宽与最小列宽自动算列数，窄屏自动降列。\nconst Waterfall = withPlugins(WaterfallCore, [\n  createAutoColumnPlugin({\n    maxColumns: \"Infinity\",\n    minColumns: 1,\n  }),\n]);\n\n<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;",
+  "conflicts": [
+    "ResponsiveColumnsPlugin"
+  ],
+  "features": [
+    "按容器宽度（不是视口宽度）算列数",
+    "列数上下限可夹",
+    "与 Gap / Padding 一起算，留白不吞列宽"
+  ],
+  "useCases": [
+    "响应式信息流",
+    "侧边栏宽度可拖动的后台看板",
+    "移动端 → 桌面端同一套代码"
+  ],
+  "notes": [
+    "与 ResponsiveColumnsPlugin 同时装会互相覆盖列数，只选一个。"
+  ]
+}
 ;
 
 export default _default;

package/dist/custom-plugins/AutoColumnPlugin/index.js

@@ -1,4 +1,4 @@
-import { c as o, d as t } from "../../chunks/doc-CTUoMe7o.js";
+import { c as o, d as t } from "../../chunks/doc-eYhNJy97.js";
 const a = Object.assign(o, { meta: t });
 export {
   a as createAutoColumnPlugin

package/dist/custom-plugins/BookmarkPlugin/doc.json.d.ts

@@ -1,41 +1,50 @@
-declare const _default: {
-  "name": "BookmarkPlugin",
-  "description": "长列表读到一半要跳走时按 **B** 存位置，回来按 **R** 复原。焦点在输入框/可编辑区域时不拦截按键。",
-  "since": "2.0.0",
-  "tags": [
-    "ui",
-    "滚动",
-    "快捷键"
-  ],
-  "config": [
-    {
-      "name": "storageKey",
-      "type": "string",
-      "default": "\"waterfall-bookmark\"",
-      "description": "localStorage 键名"
-    },
+declare const _default: {
+  "name": "BookmarkPlugin",
+  "description": "长列表读到一半要跳走时按 **B** 存位置，回来按 **R** 复原。焦点在输入框/可编辑区域时不拦截按键。",
+  "since": "2.0.0",
+  "tags": [
+    "ui",
+    "滚动",
+    "快捷键"
+  ],
+  "events": [
     {
-      "name": "scrollBehavior",
-      "type": "\"auto\" | \"smooth\"",
-      "default": "\"smooth\"",
-      "description": "恢复时的滚动行为"
+      "name": "onMount",
+      "when": "瀑布流挂载完成",
+      "description": "初始化观察器与滚动监听，返回清理函数"
     }
   ],
-  "example": "// 按 B 记录滚动位置、按 R 跳回（localStorage），忽略输入框按键。\nconst Waterfall = withPlugins(WaterfallCore, [\n  createBookmarkPlugin({\n    storageKey: \"waterfall-bookmark\",\n    scrollBehavior: \"smooth\",\n  }),\n]);\n\n<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;",
-  "features": [
-    "B 存 / R 取，零 UI 侵入",
-    "自动区分容器滚动与页面滚动",
-    "输入框内不误触"
-  ],
-  "useCases": [
-    "长文列表阅读",
-    "后台大表格浏览",
-    "演示时快速复位"
-  ],
-  "notes": [
-    "键名全局共用，一个页面里多处瀑布流请各自传不同的 storageKey。"
-  ]
-}
+  "methods": [],
+  "methodsNote": "只读取 context 字段（props / state / data），不调用上下文方法",
+  "config": [
+    {
+      "name": "storageKey",
+      "type": "string",
+      "default": "\"waterfall-bookmark\"",
+      "description": "localStorage 键名"
+    },
+    {
+      "name": "scrollBehavior",
+      "type": "\"auto\" | \"smooth\"",
+      "default": "\"smooth\"",
+      "description": "恢复时的滚动行为"
+    }
+  ],
+  "example": "// 按 B 记录滚动位置、按 R 跳回（localStorage），忽略输入框按键。\nconst Waterfall = withPlugins(WaterfallCore, [\n  createBookmarkPlugin({\n    storageKey: \"waterfall-bookmark\",\n    scrollBehavior: \"smooth\",\n  }),\n]);\n\n<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;",
+  "features": [
+    "B 存 / R 取，零 UI 侵入",
+    "自动区分容器滚动与页面滚动",
+    "输入框内不误触"
+  ],
+  "useCases": [
+    "长文列表阅读",
+    "后台大表格浏览",
+    "演示时快速复位"
+  ],
+  "notes": [
+    "键名全局共用，一个页面里多处瀑布流请各自传不同的 storageKey。"
+  ]
+}
 ;
 
 export default _default;

package/dist/custom-plugins/BookmarkPlugin/index.js

@@ -1,4 +1,4 @@
-import { c as o, d as a } from "../../chunks/doc-D_ozEn0Q.js";
+import { c as o, d as a } from "../../chunks/doc-BrEd0oZB.js";
 const r = Object.assign(o, { meta: a });
 export {
   r as createBookmarkPlugin

package/dist/custom-plugins/ClickAnalyticsPlugin/doc.json.d.ts

@@ -6,6 +6,35 @@ declare const _default: {
     "interaction",
     "埋点"
   ],
+  "events": [
+    {
+      "name": "onMount",
+      "when": "瀑布流挂载完成",
+      "description": "初始化观察器与滚动监听，返回清理函数"
+    },
+    {
+      "name": "onItemClick",
+      "when": "单个卡片被点击",
+      "description": "卡片级跳转与点击埋点"
+    },
+    {
+      "name": "onLayoutComplete",
+      "when": "DOM 落位完成（可安全测量）",
+      "description": "测量真实高度、懒加载判定、曝光上报"
+    },
+    {
+      "name": "renderOverlay",
+      "when": "每次渲染，滚动容器内的内容层之上",
+      "description": "回到顶部、加载提示、浮层工具"
+    },
+    {
+      "name": "analytics:click",
+      "when": "卡片点击后",
+      "description": "广播 { index, key, item, event, total } 点击埋点"
+    }
+  ],
+  "methods": [],
+  "methodsNote": "只读取 context 字段（props / state / data），不调用上下文方法",
   "config": [
     {
       "name": "log",

package/dist/custom-plugins/ClickAnalyticsPlugin/index.js

@@ -1,4 +1,4 @@
-import { c, d as t } from "../../chunks/doc-KN6Bvmty.js";
+import { c, d as t } from "../../chunks/doc-DEN2WTDh.js";
 const i = Object.assign(c, { meta: t });
 export {
   i as createClickAnalyticsPlugin

package/dist/custom-plugins/DebounceLayoutPlugin/doc.json.d.ts

@@ -1,34 +1,43 @@
-declare const _default: {
-  "name": "DebounceLayoutPlugin",
-  "description": "只调 debounceDelay：容器宽度连续变化（抽屉展开、分栏拖拽）时，等变化停下来再算一次布局，避免每帧重排。",
-  "since": "2.0.0",
-  "tags": [
-    "perf",
-    "性能"
-  ],
-  "config": [
+declare const _default: {
+  "name": "DebounceLayoutPlugin",
+  "description": "只调 debounceDelay：容器宽度连续变化（抽屉展开、分栏拖拽）时，等变化停下来再算一次布局，避免每帧重排。",
+  "since": "2.0.0",
+  "tags": [
+    "perf",
+    "性能"
+  ],
+  "events": [
     {
-      "name": "delay",
-      "type": "number",
-      "default": "—",
-      "description": "布局防抖 ms（必填）"
+      "name": "transformProps",
+      "when": "渲染前链式改写瀑布流 props",
+      "description": "补 gap / columns 默认值、按断点覆盖配置"
     }
   ],
-  "example": "// 单独放大布局防抖，容器频繁变宽时（抽屉/侧栏动画）不抖。\nconst Waterfall = withPlugins(WaterfallCore, [\n  createDebounceLayoutPlugin(),\n]);\n\n<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;",
-  "features": [
-    "只影响布局时机，不影响渲染",
-    "可被 ThrottlePlugin 覆盖",
-    "对移动端软键盘弹出也有效"
-  ],
-  "useCases": [
-    "可折叠侧栏",
-    "分栏宽度拖拽",
-    "横竖屏切换"
-  ],
-  "notes": [
-    "delay 过大会让「展开后布局」明显滞后，建议 120–250ms。"
-  ]
-}
+  "methods": [],
+  "methodsNote": "只读取 context 字段（props / state / data），不调用上下文方法",
+  "config": [
+    {
+      "name": "delay",
+      "type": "number",
+      "default": "—",
+      "description": "布局防抖 ms（必填）"
+    }
+  ],
+  "example": "// 单独放大布局防抖，容器频繁变宽时（抽屉/侧栏动画）不抖。\nconst Waterfall = withPlugins(WaterfallCore, [\n  createDebounceLayoutPlugin(),\n]);\n\n<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;",
+  "features": [
+    "只影响布局时机，不影响渲染",
+    "可被 ThrottlePlugin 覆盖",
+    "对移动端软键盘弹出也有效"
+  ],
+  "useCases": [
+    "可折叠侧栏",
+    "分栏宽度拖拽",
+    "横竖屏切换"
+  ],
+  "notes": [
+    "delay 过大会让「展开后布局」明显滞后，建议 120–250ms。"
+  ]
+}
 ;
 
 export default _default;

package/dist/custom-plugins/DebounceLayoutPlugin/index.js

@@ -1,4 +1,4 @@
-import { c as e, d as o } from "../../chunks/doc-BIzjYAZW.js";
+import { c as e, d as o } from "../../chunks/doc-DudYCn_-.js";
 const a = Object.assign(e, { meta: o });
 export {
   a as createDebounceLayoutPlugin

package/dist/custom-plugins/DragReorderPlugin/doc.json.d.ts

@@ -6,6 +6,20 @@ declare const _default: {
     "interaction",
     "拖拽"
   ],
+  "events": [
+    {
+      "name": "renderItemWrapper",
+      "when": "渲染每个卡片时包裹其内容",
+      "description": "给单卡加包裹层（拖拽、无障碍语义、占位骨架）"
+    },
+    {
+      "name": "drag:reorder",
+      "when": "拖拽排序完成后",
+      "description": "广播 { from, to }，供业务层同步顺序"
+    }
+  ],
+  "methods": [],
+  "methodsNote": "只读取 context 字段（props / state / data），不调用上下文方法",
   "config": [
     {
       "name": "enabled",

package/dist/custom-plugins/DragReorderPlugin/index.js

@@ -1,4 +1,4 @@
-import { c as e, d as r } from "../../chunks/doc-BXElhF2h.js";
+import { c as e, d as r } from "../../chunks/doc-CiCso5Ti.js";
 const o = Object.assign(e, { meta: r });
 export {
   o as createDragReorderPlugin