vane-waterfall 2.0.2 → 2.0.3

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

@@ -1,47 +1,61 @@
-declare const _default: {
-  "name": "FilterPlugin",
-  "description": "用谓词函数过滤数据，优先读 `props.filterFn`，没有就用工厂里传入的 predicate。过滤条件变了可以自动滚回顶部（默认不开）。",
-  "since": "2.0.0",
-  "tags": [
-    "data",
-    "数据管线"
-  ],
-  "config": [
-    {
-      "name": "predicate",
-      "type": "(item, index) => boolean",
-      "default": "—",
-      "description": "默认谓词，可被 props.filterFn 覆盖"
-    },
+declare const _default: {
+  "name": "FilterPlugin",
+  "description": "用谓词函数过滤数据，优先读 `props.filterFn`，没有就用工厂里传入的 predicate。过滤条件变了可以自动滚回顶部（默认不开）。",
+  "since": "2.0.0",
+  "tags": [
+    "data",
+    "数据管线"
+  ],
+  "events": [
     {
-      "name": "scrollToTop",
-      "type": "boolean",
-      "default": "false",
-      "description": "条件变化后回顶"
+      "name": "onPropsChange",
+      "when": "props 变化后",
+      "description": "数据或配置变化时请求重排"
     },
     {
-      "name": "scrollBehavior",
-      "type": "\"auto\" | \"smooth\"",
-      "default": "\"auto\"",
-      "description": "回顶行为"
+      "name": "transformProps",
+      "when": "渲染前链式改写瀑布流 props",
+      "description": "补 gap / columns 默认值、按断点覆盖配置"
     }
   ],
-  "example": "// 按谓词过滤 items，参数变化可自动回顶。\nconst Waterfall = withPlugins(WaterfallCore, [\n  createFilterPlugin({\n    scrollToTop: false,\n    scrollBehavior: \"auto\",\n  }),\n]);\n\n<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;",
-  "features": [
-    "谓词抛错时按「保留」处理，不会整表消失",
-    "props.filterFn 优先，便于页面动态换过滤条件",
-    "可与 Sort / Search / Pagination 串联"
-  ],
-  "useCases": [
-    "分类 Tab 切换",
-    "只看有货 / 只看促销",
-    "价格区间筛选"
-  ],
-  "notes": [
-    "数据管线的执行顺序由 priority 决定：Filter(40) → Sort(30) → Search(20) → Pagination(10)。",
-    "先过滤再分页，页码总数才是过滤后的总数——顺序反了会出现「第 2 页空」。"
-  ]
-}
+  "methods": [],
+  "methodsNote": "只读取 context 字段（props / state / data），不调用上下文方法",
+  "config": [
+    {
+      "name": "predicate",
+      "type": "(item, index) => boolean",
+      "default": "—",
+      "description": "默认谓词，可被 props.filterFn 覆盖"
+    },
+    {
+      "name": "scrollToTop",
+      "type": "boolean",
+      "default": "false",
+      "description": "条件变化后回顶"
+    },
+    {
+      "name": "scrollBehavior",
+      "type": "\"auto\" | \"smooth\"",
+      "default": "\"auto\"",
+      "description": "回顶行为"
+    }
+  ],
+  "example": "// 按谓词过滤 items，参数变化可自动回顶。\nconst Waterfall = withPlugins(WaterfallCore, [\n  createFilterPlugin({\n    scrollToTop: false,\n    scrollBehavior: \"auto\",\n  }),\n]);\n\n<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;",
+  "features": [
+    "谓词抛错时按「保留」处理，不会整表消失",
+    "props.filterFn 优先，便于页面动态换过滤条件",
+    "可与 Sort / Search / Pagination 串联"
+  ],
+  "useCases": [
+    "分类 Tab 切换",
+    "只看有货 / 只看促销",
+    "价格区间筛选"
+  ],
+  "notes": [
+    "数据管线的执行顺序由 priority 决定：Filter(40) → Sort(30) → Search(20) → Pagination(10)。",
+    "先过滤再分页，页码总数才是过滤后的总数——顺序反了会出现「第 2 页空」。"
+  ]
+}
 ;
 
 export default _default;

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

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

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

@@ -1,34 +1,48 @@
-declare const _default: {
-  "name": "FixedHeightPlugin",
-  "description": "把数据里带 height 字段的项统一改写为固定高度，瀑布流变成等高网格。适合「图少字多」的卡片流——等高反而更好扫读。",
-  "since": "2.0.0",
-  "tags": [
-    "layout",
-    "网格"
-  ],
-  "config": [
+declare const _default: {
+  "name": "FixedHeightPlugin",
+  "description": "把数据里带 height 字段的项统一改写为固定高度，瀑布流变成等高网格。适合「图少字多」的卡片流——等高反而更好扫读。",
+  "since": "2.0.0",
+  "tags": [
+    "layout",
+    "网格"
+  ],
+  "events": [
+    {
+      "name": "onResize",
+      "when": "容器宽度变化触发重排前",
+      "description": "按新宽度调整列数或卡片密度"
+    },
     {
-      "name": "itemHeight",
-      "type": "number",
-      "default": "—",
-      "description": "统一项高 px（必填）"
+      "name": "transformProps",
+      "when": "渲染前链式改写瀑布流 props",
+      "description": "补 gap / columns 默认值、按断点覆盖配置"
     }
   ],
-  "example": "// 把项高度统一成固定值，瀑布流退化为等高网格。\nconst Waterfall = withPlugins(WaterfallCore, [\n  createFixedHeightPlugin(),\n]);\n\n<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;",
-  "features": [
-    "等高网格（严格对齐）",
-    "只改数据里已有的 height 字段",
-    "与 Pagination / Filter 组合仍然成立"
-  ],
-  "useCases": [
-    "商品列表（图固定比例）",
-    "后台看板卡片",
-    "需要严格栅格对齐的页面"
-  ],
-  "notes": [
-    "数据里没有 height 字段时不会生效——高度由 renderItem 自己的内容决定。"
-  ]
-}
+  "methods": [],
+  "methodsNote": "只读取 context 字段（props / state / data），不调用上下文方法",
+  "config": [
+    {
+      "name": "itemHeight",
+      "type": "number",
+      "default": "—",
+      "description": "统一项高 px（必填）"
+    }
+  ],
+  "example": "// 把项高度统一成固定值，瀑布流退化为等高网格。\nconst Waterfall = withPlugins(WaterfallCore, [\n  createFixedHeightPlugin(),\n]);\n\n<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;",
+  "features": [
+    "等高网格（严格对齐）",
+    "只改数据里已有的 height 字段",
+    "与 Pagination / Filter 组合仍然成立"
+  ],
+  "useCases": [
+    "商品列表（图固定比例）",
+    "后台看板卡片",
+    "需要严格栅格对齐的页面"
+  ],
+  "notes": [
+    "数据里没有 height 字段时不会生效——高度由 renderItem 自己的内容决定。"
+  ]
+}
 ;
 
 export default _default;

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

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

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

@@ -1,47 +1,71 @@
-declare const _default: {
-  "name": "GapPlugin",
-  "description": "把 rowGap / columnGap 收敛到一处配置，并支持按窗口宽度切换间距（窄屏 8px、宽屏 16px 这类）。",
-  "since": "2.0.0",
-  "tags": [
-    "layout",
-    "间距"
-  ],
-  "config": [
+declare const _default: {
+  "name": "GapPlugin",
+  "description": "把 rowGap / columnGap 收敛到一处配置，并支持按窗口宽度切换间距（窄屏 8px、宽屏 16px 这类）。",
+  "since": "2.0.0",
+  "tags": [
+    "layout",
+    "间距"
+  ],
+  "events": [
+    {
+      "name": "onMount",
+      "when": "瀑布流挂载完成",
+      "description": "初始化观察器与滚动监听，返回清理函数"
+    },
     {
-      "name": "columnGap",
-      "type": "number",
-      "default": "props.columnGap",
-      "description": "列间距 px"
+      "name": "onResize",
+      "when": "容器宽度变化触发重排前",
+      "description": "按新宽度调整列数或卡片密度"
     },
     {
-      "name": "rowGap",
-      "type": "number",
-      "default": "props.rowGap",
-      "description": "行间距 px"
+      "name": "transformProps",
+      "when": "渲染前链式改写瀑布流 props",
+      "description": "补 gap / columns 默认值、按断点覆盖配置"
     },
     {
-      "name": "responsive",
-      "type": "{ sm?, md?, lg?, xl? }",
-      "default": "—",
-      "description": "断点覆盖（按 window 宽度）"
+      "name": "props:invalidate",
+      "when": "内部布局参数变更需要重排时",
+      "description": "通知宿主刷新 props 触发重新布局"
     }
   ],
-  "example": "// 统一控制行/列间距，支持按断点给不同间距。\nconst Waterfall = withPlugins(WaterfallCore, [\n  createGapPlugin(),\n]);\n\n<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;",
-  "features": [
-    "行列间距一处配置",
-    "断点覆盖（sm/md/lg/xl）",
-    "不填则回退到 props"
-  ],
-  "useCases": [
-    "设计规范里间距随断点变化",
-    "同一组件在不同页面用不同密度"
-  ],
-  "notes": [
-    "断点判断用的是 window.innerWidth（间距通常跟视口走，与列数按容器算不一样）。",
-    "断点是「命中即覆盖」：桌面窗口 ≥1200 又配了 responsive.lg，那就一直是 lg 的值，config.columnGap/rowGap 在这档不起作用；想让手写值生效就别给该档位配 responsive。",
-    "sm 只在小屏（<768）生效，不会被当成兜底档套到桌面端。"
-  ]
-}
+  "methods": [],
+  "methodsNote": "只读取 context 字段（props / state / data），不调用上下文方法",
+  "config": [
+    {
+      "name": "columnGap",
+      "type": "number",
+      "default": "props.columnGap",
+      "description": "列间距 px"
+    },
+    {
+      "name": "rowGap",
+      "type": "number",
+      "default": "props.rowGap",
+      "description": "行间距 px"
+    },
+    {
+      "name": "responsive",
+      "type": "{ sm?, md?, lg?, xl? }",
+      "default": "—",
+      "description": "断点覆盖（按 window 宽度）"
+    }
+  ],
+  "example": "// 统一控制行/列间距，支持按断点给不同间距。\nconst Waterfall = withPlugins(WaterfallCore, [\n  createGapPlugin(),\n]);\n\n<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;",
+  "features": [
+    "行列间距一处配置",
+    "断点覆盖（sm/md/lg/xl）",
+    "不填则回退到 props"
+  ],
+  "useCases": [
+    "设计规范里间距随断点变化",
+    "同一组件在不同页面用不同密度"
+  ],
+  "notes": [
+    "断点判断用的是 window.innerWidth（间距通常跟视口走，与列数按容器算不一样）。",
+    "断点是「命中即覆盖」：桌面窗口 ≥1200 又配了 responsive.lg，那就一直是 lg 的值，config.columnGap/rowGap 在这档不起作用；想让手写值生效就别给该档位配 responsive。",
+    "sm 只在小屏（<768）生效，不会被当成兜底档套到桌面端。"
+  ]
+}
 ;
 
 export default _default;

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

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

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

@@ -1,40 +1,69 @@
-declare const _default: {
-  "name": "GroupingPlugin",
-  "description": "用 groupBy 把项按业务字段分组，结果放进 sharedData 的 `GROUPS`（Map<组键, 索引数组>），供 StickyHeaderPlugin、分组统计条等消费。挂载即算一次，之后 props 变化重算。",
-  "since": "2.0.0",
-  "tags": [
-    "ui",
-    "分组"
-  ],
-  "config": [
+declare const _default: {
+  "name": "GroupingPlugin",
+  "description": "用 groupBy 把项按业务字段分组，结果放进 sharedData 的 `GROUPS`（Map<组键, 索引数组>），供 StickyHeaderPlugin、分组统计条等消费。挂载即算一次，之后 props 变化重算。",
+  "since": "2.0.0",
+  "tags": [
+    "ui",
+    "分组"
+  ],
+  "events": [
+    {
+      "name": "onMount",
+      "when": "瀑布流挂载完成",
+      "description": "初始化观察器与滚动监听，返回清理函数"
+    },
+    {
+      "name": "onPropsChange",
+      "when": "props 变化后",
+      "description": "数据或配置变化时请求重排"
+    },
     {
-      "name": "groupBy",
-      "type": "(item, index) => string | number",
-      "default": "item.category ?? \"default\"",
-      "description": "分组函数"
+      "name": "onLayoutComplete",
+      "when": "DOM 落位完成（可安全测量）",
+      "description": "测量真实高度、懒加载判定、曝光上报"
     },
     {
-      "name": "showOverlay",
-      "type": "boolean",
-      "default": "false",
-      "description": "是否显示分组统计角标"
+      "name": "renderOverlay",
+      "when": "每次渲染，滚动容器内的内容层之上",
+      "description": "回到顶部、加载提示、浮层工具"
+    },
+    {
+      "name": "grouping:change",
+      "when": "分组结果变化时",
+      "description": "广播 { groups } 分组结构"
     }
   ],
-  "example": "// 按字段把项分组，结果写进 sharedData(GROUPS) 供吸顶条 / 统计用。\nconst Waterfall = withPlugins(WaterfallCore, [\n  createGroupingPlugin({\n    groupBy: \"item.category ?? \\\"default\\\"\",\n    showOverlay: false,\n  }),\n]);\n\n<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;",
-  "features": [
-    "挂载即计算（旧版只在 props 变化时算，首屏永远拿不到分组）",
-    "结果写 sharedData，跨插件可读",
-    "统计角标默认关闭"
-  ],
-  "useCases": [
-    "按分类分组的信息流",
-    "按日期分组的时间线",
-    "吸顶条显示当前分组"
-  ],
-  "notes": [
-    "分组只产出索引映射，不改变渲染顺序；要视觉分组请自己按分组建行。"
-  ]
-}
+  "methods": [],
+  "methodsNote": "只读取 context 字段（props / state / data），不调用上下文方法",
+  "config": [
+    {
+      "name": "groupBy",
+      "type": "(item, index) => string | number",
+      "default": "item.category ?? \"default\"",
+      "description": "分组函数"
+    },
+    {
+      "name": "showOverlay",
+      "type": "boolean",
+      "default": "false",
+      "description": "是否显示分组统计角标"
+    }
+  ],
+  "example": "// 按字段把项分组，结果写进 sharedData(GROUPS) 供吸顶条 / 统计用。\nconst Waterfall = withPlugins(WaterfallCore, [\n  createGroupingPlugin({\n    groupBy: \"item.category ?? \\\"default\\\"\",\n    showOverlay: false,\n  }),\n]);\n\n<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;",
+  "features": [
+    "挂载即计算（旧版只在 props 变化时算，首屏永远拿不到分组）",
+    "结果写 sharedData，跨插件可读",
+    "统计角标默认关闭"
+  ],
+  "useCases": [
+    "按分类分组的信息流",
+    "按日期分组的时间线",
+    "吸顶条显示当前分组"
+  ],
+  "notes": [
+    "分组只产出索引映射，不改变渲染顺序；要视觉分组请自己按分组建行。"
+  ]
+}
 ;
 
 export default _default;

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

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

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

@@ -7,6 +7,30 @@ declare const _default: {
     "埋点",
     "曝光"
   ],
+  "events": [
+    {
+      "name": "onItemClick",
+      "when": "单个卡片被点击",
+      "description": "卡片级跳转与点击埋点"
+    },
+    {
+      "name": "onItemEnterViewport",
+      "when": "单个卡片进入视口",
+      "description": "卡片级曝光、视频自动播放等"
+    },
+    {
+      "name": "onLayoutComplete",
+      "when": "DOM 落位完成（可安全测量）",
+      "description": "测量真实高度、懒加载判定、曝光上报"
+    },
+    {
+      "name": "renderOverlay",
+      "when": "每次渲染，滚动容器内的内容层之上",
+      "description": "回到顶部、加载提示、浮层工具"
+    }
+  ],
+  "methods": [],
+  "methodsNote": "只读取 context 字段（props / state / data），不调用上下文方法",
   "config": [
     {
       "name": "showOverlay",

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

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

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

@@ -1,44 +1,63 @@
-declare const _default: {
-  "name": "InfiniteScrollPlugin",
-  "description": "监听 Core 的 onReachBottom，在距底部 `threshold` 像素内触发 onLoadMore。自带并发锁：上一次还没结束不会重复触发。",
-  "since": "2.0.0",
-  "tags": [
-    "data",
-    "加载更多"
-  ],
-  "config": [
+declare const _default: {
+  "name": "InfiniteScrollPlugin",
+  "description": "监听 Core 的 onReachBottom，在距底部 `threshold` 像素内触发 onLoadMore。自带并发锁：上一次还没结束不会重复触发。",
+  "since": "2.0.0",
+  "tags": [
+    "data",
+    "加载更多"
+  ],
+  "events": [
+    {
+      "name": "onUnmount",
+      "when": "瀑布流卸载前",
+      "description": "断开观察器、移除滚动监听"
+    },
     {
-      "name": "threshold",
-      "type": "number",
-      "default": "300",
-      "description": "触发距离 px"
+      "name": "onReachBottom",
+      "when": "滚动触底（distance 为距底像素）",
+      "description": "加载更多、预取下一页"
     },
     {
-      "name": "onLoadMore",
-      "type": "() => void | Promise<void>",
-      "default": "props.onLoadMore",
-      "description": "加载回调"
+      "name": "transformProps",
+      "when": "渲染前链式改写瀑布流 props",
+      "description": "补 gap / columns 默认值、按断点覆盖配置"
     }
   ],
-  "example": "// 滚动到距底部阈值内触发加载更多，带并发锁防重复请求。\nconst Waterfall = withPlugins(WaterfallCore, [\n  createInfiniteScrollPlugin({\n    threshold: 300,\n  }),\n]);\n\n<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;",
-  "conflicts": [
-    "PaginationPlugin"
-  ],
-  "features": [
-    "距底 300px 预加载，滚到底时数据已就位",
-    "并发锁：加载中不重复触发",
-    "context.hasMore 为 false 时自动停"
-  ],
-  "useCases": [
-    "信息流无限滚动",
-    "画廊继续加载",
-    "搜索结果瀑布流"
-  ],
-  "notes": [
-    "阈值不要小于一屏（约 600px），否则用户滚到底会看到空白等待。",
-    "翻页类场景请用 PaginationPlugin，两者不要同装。"
-  ]
-}
+  "methods": [],
+  "methodsNote": "只读取 context 字段（props / state / data），不调用上下文方法",
+  "config": [
+    {
+      "name": "threshold",
+      "type": "number",
+      "default": "300",
+      "description": "触发距离 px"
+    },
+    {
+      "name": "onLoadMore",
+      "type": "() => void | Promise<void>",
+      "default": "props.onLoadMore",
+      "description": "加载回调"
+    }
+  ],
+  "example": "// 滚动到距底部阈值内触发加载更多，带并发锁防重复请求。\nconst Waterfall = withPlugins(WaterfallCore, [\n  createInfiniteScrollPlugin({\n    threshold: 300,\n  }),\n]);\n\n<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;",
+  "conflicts": [
+    "PaginationPlugin"
+  ],
+  "features": [
+    "距底 300px 预加载，滚到底时数据已就位",
+    "并发锁：加载中不重复触发",
+    "context.hasMore 为 false 时自动停"
+  ],
+  "useCases": [
+    "信息流无限滚动",
+    "画廊继续加载",
+    "搜索结果瀑布流"
+  ],
+  "notes": [
+    "阈值不要小于一屏（约 600px），否则用户滚到底会看到空白等待。",
+    "翻页类场景请用 PaginationPlugin，两者不要同装。"
+  ]
+}
 ;
 
 export default _default;

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

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