vane-waterfall 2.0.1 → 2.0.3

package/dist/chunks/{doc-DElLNjIc.js → doc-C206ZwYC.js}

@@ -1,61 +1,70 @@
-function b(e) {
-  const c = Object.values(e.breakpoints).sort((s, n) => s.width - n.width);
+function w(n) {
+  const l = Object.values(n.breakpoints).sort((e, s) => e.width - s.width);
   return {
     name: "ResponsiveColumnsPlugin",
     priority: 55,
     enabled: !0,
     hooks: {
-      calculateColumns: (s, n) => {
-        const t = e.fallbackColumns ?? s.props.columns ?? 3;
-        if (!n) return t;
+      calculateColumns: (e, s) => {
+        const t = n.fallbackColumns ?? e.props.columns ?? 3;
+        if (!s) return t;
         let o = t;
-        for (const l of c)
-          n >= l.width && (o = l.columns);
+        for (const c of l)
+          s >= c.width && (o = c.columns);
         return o;
       }
     }
   };
 }
-const u = "ResponsiveColumnsPlugin", a = "用一张断点表控制列数，命中哪档用哪档。走 D1-A 布局钩子（calculateColumns），按容器宽度匹配断点。", i = "2.0.0", r = [
+const a = "ResponsiveColumnsPlugin", u = "用一张断点表控制列数，命中哪档用哪档。走 D1-A 布局钩子（calculateColumns），按容器宽度匹配断点。", i = "2.0.0", r = [
   "layout",
   "layout-hook",
   "响应式"
 ], m = [
+  {
+    name: "calculateColumns",
+    when: "每次布局前，询问列数",
+    description: "返回列数则覆盖 props.columns；返回 undefined 沿用配置"
+  }
+], p = [], d = "只读取 context 字段（props / state / data），不调用上下文方法", f = [
   {
     name: "breakpoints",
     type: "Record<string, { width: number; columns: number }>",
     default: "—",
     description: "断点表，按 width 升序匹配"
   }
-], p = `// 按断点表决定列数（如 640 → 2 列、1024 → 3 列、1440 → 4 列）。
+], C = `// 按断点表决定列数（如 640 → 2 列、1024 → 3 列、1440 → 4 列）。
 const Waterfall = withPlugins(WaterfallCore, [
   createResponsiveColumnsPlugin(),
 ]);
 
-<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, f = [
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, h = [
   "AutoColumnPlugin"
-], d = [
+], g = [
   "断点表驱动，设计稿几档就写几档",
   "按容器宽度而非视口宽度匹配",
   "未命中任何断点时回退到 props.columns"
-], C = [
+], b = [
   "严格对齐设计断点的站点",
   "同一个组件嵌在不同宽度的容器里"
-], g = [
+], v = [
   "与 AutoColumnPlugin 互斥。"
-], h = {
-  name: u,
-  description: a,
+], P = {
+  name: a,
+  description: u,
   since: i,
   tags: r,
-  config: m,
-  example: p,
-  conflicts: f,
-  features: d,
-  useCases: C,
-  notes: g
+  events: m,
+  methods: p,
+  methodsNote: d,
+  config: f,
+  example: C,
+  conflicts: h,
+  features: g,
+  useCases: b,
+  notes: v
 };
 export {
-  b as c,
-  h as d
+  w as c,
+  P as d
 };

package/dist/chunks/doc-C2L8kkeI.js

@@ -0,0 +1,112 @@
+function p(o, t) {
+  const n = o.responsive || {};
+  return t >= 1200 && n.xl ? n.xl : t >= 992 && n.lg ? n.lg : t >= 768 && n.md ? n.md : t < 768 && n.sm ? n.sm : {};
+}
+function y(o) {
+  let t = 0, n = "";
+  const i = (e) => {
+    const s = e.containerRef?.current?.clientWidth ?? 0;
+    if (s <= 0) return;
+    const a = t;
+    t = s;
+    const r = JSON.stringify(p(o, s));
+    a > 0 && r !== n && e.bus?.emit("props:invalidate"), n = r;
+  };
+  return {
+    name: "GapPlugin",
+    priority: 50,
+    enabled: !0,
+    hooks: {
+      transformProps: (e) => {
+        const s = t > 0 ? t : typeof window < "u" ? window.innerWidth : 1024, a = { columnGap: o.columnGap, rowGap: o.rowGap }, r = p(o, s), c = {
+          columnGap: r.columnGap ?? a.columnGap ?? e.columnGap,
+          rowGap: r.rowGap ?? a.rowGap ?? e.rowGap
+        };
+        return { ...e, ...c };
+      },
+      onMount: (e) => {
+        i(e);
+      },
+      onResize: (e) => {
+        i(e);
+      }
+    }
+  };
+}
+const m = "GapPlugin", u = "把 rowGap / columnGap 收敛到一处配置，并支持按窗口宽度切换间距（窄屏 8px、宽屏 16px 这类）。", l = "2.0.0", d = [
+  "layout",
+  "间距"
+], G = [
+  {
+    name: "onMount",
+    when: "瀑布流挂载完成",
+    description: "初始化观察器与滚动监听，返回清理函数"
+  },
+  {
+    name: "onResize",
+    when: "容器宽度变化触发重排前",
+    description: "按新宽度调整列数或卡片密度"
+  },
+  {
+    name: "transformProps",
+    when: "渲染前链式改写瀑布流 props",
+    description: "补 gap / columns 默认值、按断点覆盖配置"
+  },
+  {
+    name: "props:invalidate",
+    when: "内部布局参数变更需要重排时",
+    description: "通知宿主刷新 props 触发重新布局"
+  }
+], f = [], w = "只读取 context 字段（props / state / data），不调用上下文方法", g = [
+  {
+    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 宽度）"
+  }
+], h = `// 统一控制行/列间距，支持按断点给不同间距。
+const Waterfall = withPlugins(WaterfallCore, [
+  createGapPlugin(),
+]);
+
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, x = [
+  "行列间距一处配置",
+  "断点覆盖（sm/md/lg/xl）",
+  "不填则回退到 props"
+], v = [
+  "设计规范里间距随断点变化",
+  "同一组件在不同页面用不同密度"
+], W = [
+  "断点判断用的是 window.innerWidth（间距通常跟视口走，与列数按容器算不一样）。",
+  "断点是「命中即覆盖」：桌面窗口 ≥1200 又配了 responsive.lg，那就一直是 lg 的值，config.columnGap/rowGap 在这档不起作用；想让手写值生效就别给该档位配 responsive。",
+  "sm 只在小屏（<768）生效，不会被当成兜底档套到桌面端。"
+], P = {
+  name: m,
+  description: u,
+  since: l,
+  tags: d,
+  events: G,
+  methods: f,
+  methodsNote: w,
+  config: g,
+  example: h,
+  features: x,
+  useCases: v,
+  notes: W
+};
+export {
+  y as c,
+  P as d
+};

package/dist/chunks/doc-CE1DGMBV.js

@@ -0,0 +1,166 @@
+import { jsxs as d } from "react/jsx-runtime";
+function V(y = {}) {
+  const w = y.showOverlay ?? y.showOverlaySummary ?? !1, o = /* @__PURE__ */ new Map(), a = /* @__PURE__ */ new Map(), r = /* @__PURE__ */ new Map();
+  let l = !1, c = null;
+  const f = (t) => Array.from(t.values()).reduce((e, s) => e + s, 0), m = (t, e, s) => {
+    try {
+      const n = t.props?.keyExtractor?.(e, s);
+      if (n != null) return String(n);
+    } catch {
+    }
+    return `#${s}`;
+  }, p = (t) => {
+    const e = t.items;
+    (c === null || e !== c) && (c = e, o.clear(), a.clear(), r.clear(), l = !1);
+  };
+  return {
+    name: "HeatmapAnalyticsPlugin",
+    enabled: !0,
+    getStats: () => {
+      const t = /* @__PURE__ */ new Set([...o.keys(), ...a.keys()]);
+      return {
+        totalViews: f(o),
+        totalClicks: f(a),
+        items: Array.from(t).map((e) => ({
+          index: r.get(e) ?? 0,
+          key: e,
+          views: o.get(e) ?? 0,
+          clicks: a.get(e) ?? 0
+        })).sort((e, s) => e.index - s.index || e.key.localeCompare(s.key))
+      };
+    },
+    hooks: {
+      onLayoutComplete: (t) => {
+        if (p(t), l) return;
+        const { start: e, end: s } = t.visibleRange, n = t.items;
+        for (let i = e; i <= s; i++) {
+          const g = n[i];
+          if (g === void 0) continue;
+          const u = m(t, g, i);
+          r.set(u, i), o.set(u, (o.get(u) || 0) + 1);
+        }
+        l = !0;
+      },
+      onItemEnterViewport: (t, e) => {
+        p(t);
+        const s = t.items[e];
+        if (s === void 0) return;
+        const n = m(t, s, e);
+        r.set(n, e), o.set(n, (o.get(n) || 0) + 1);
+      },
+      onItemClick: (t, e, s) => {
+        p(t);
+        const n = m(t, s, e);
+        r.set(n, e), a.set(n, (a.get(n) || 0) + 1), t.forceUpdate?.();
+      },
+      renderOverlay: () => {
+        if (!w) return null;
+        const t = Array.from(o.values()).reduce((s, n) => s + n, 0), e = Array.from(a.values()).reduce((s, n) => s + n, 0);
+        return /* @__PURE__ */ d(
+          "div",
+          {
+            style: {
+              position: "sticky",
+              top: 0,
+              zIndex: 100,
+              display: "flex",
+              gap: 12,
+              alignItems: "center",
+              padding: "6px 10px",
+              background: "rgba(0,0,0,0.6)",
+              color: "white",
+              borderRadius: 8,
+              fontSize: 12,
+              marginBottom: 8
+            },
+            children: [
+              /* @__PURE__ */ d("span", { children: [
+                "曝光总计: ",
+                t
+              ] }),
+              /* @__PURE__ */ d("span", { children: [
+                "点击总计: ",
+                e
+              ] })
+            ]
+          }
+        );
+      }
+    }
+  };
+}
+const h = "HeatmapAnalyticsPlugin", v = "统计每项进入视口次数与点击次数，可选顶部汇总条，`getStats()` 取出每项明细。曝光是瀑布流里最容易统计错的东西（滚动时反复进出视口），交给插件比自己写 IntersectionObserver 少踩坑。", k = "2.0.0", C = [
+  "interaction",
+  "埋点",
+  "曝光"
+], O = [
+  {
+    name: "onItemClick",
+    when: "单个卡片被点击",
+    description: "卡片级跳转与点击埋点"
+  },
+  {
+    name: "onItemEnterViewport",
+    when: "单个卡片进入视口",
+    description: "卡片级曝光、视频自动播放等"
+  },
+  {
+    name: "onLayoutComplete",
+    when: "DOM 落位完成（可安全测量）",
+    description: "测量真实高度、懒加载判定、曝光上报"
+  },
+  {
+    name: "renderOverlay",
+    when: "每次渲染，滚动容器内的内容层之上",
+    description: "回到顶部、加载提示、浮层工具"
+  }
+], I = [], S = "只读取 context 字段（props / state / data），不调用上下文方法", A = [
+  {
+    name: "showOverlay",
+    type: "boolean",
+    default: "false",
+    description: "是否显示顶部汇总条"
+  },
+  {
+    name: "showOverlaySummary",
+    type: "boolean",
+    default: "—",
+    description: "showOverlay 的旧别名"
+  }
+], b = `// 统计每项曝光次数与点击次数，可显示汇总条。
+const Waterfall = withPlugins(WaterfallCore, [
+  createHeatmapAnalyticsPlugin({
+    showOverlay: false,
+  }),
+]);
+
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, P = [
+  "按项的曝光 / 点击双计数",
+  "首屏曝光在 onLayoutComplete 补一次",
+  "getStats() 输出可上报的扁平结构"
+], H = [
+  "信息流曝光分析",
+  "广告位可见性验证",
+  "调试曝光策略"
+], L = [
+  "首屏曝光靠 onLayoutComplete 补一次，否则第一帧显示 0。",
+  "真实上报要自己做去重与批次（插件只负责计数，不区分「同一项第几次进入」）。",
+  "计数只在内存里，刷新即清零 —— 定时取 getStats() 上报。"
+], x = {
+  name: h,
+  description: v,
+  since: k,
+  tags: C,
+  events: O,
+  methods: I,
+  methodsNote: S,
+  config: A,
+  example: b,
+  features: P,
+  useCases: H,
+  notes: L
+};
+export {
+  V as c,
+  x as d
+};

package/dist/chunks/{doc-BXSy2aPP.js → doc-CHbQXLwY.js}

@@ -1,5 +1,5 @@
-function A(t = {}) {
-  const s = t.getAnchorId || ((n) => n?.id);
+function P(o = {}) {
+  const s = o.getAnchorId || ((n) => n?.id);
   let e;
   return {
     name: "ScrollAnchorPlugin",
@@ -7,53 +7,67 @@ function A(t = {}) {
     hooks: {
       onMount: (n) => {
         e = n.bus?.on("anchor:scrollToId", (c) => {
-          const o = (n.props?.items || []).findIndex((i, r) => s(i, r) === c.id);
-          o >= 0 && n.scrollToItem?.(o, { behavior: "smooth", block: "start" });
+          const t = (n.props?.items || []).findIndex((i, r) => s(i, r) === c.id);
+          t >= 0 && n.scrollToItem?.(t, { behavior: "smooth", block: "start" });
         });
       },
       onUnmount: () => e?.()
     }
   };
 }
-const a = "ScrollAnchorPlugin", l = '不需要自己算索引：外部只管 `bus.emit("anchor:scrollToId", { id })`，插件用 getAnchorId 找到对应项并滚过去。适合「从消息跳到某条内容」。', d = "2.0.0", m = [
+const a = "ScrollAnchorPlugin", d = '不需要自己算索引：外部只管 `bus.emit("anchor:scrollToId", { id })`，插件用 getAnchorId 找到对应项并滚过去。适合「从消息跳到某条内容」。', l = "2.0.0", m = [
   "interaction",
   "滚动"
 ], u = [
+  {
+    name: "onMount",
+    when: "瀑布流挂载完成",
+    description: "初始化观察器与滚动监听，返回清理函数"
+  },
+  {
+    name: "onUnmount",
+    when: "瀑布流卸载前",
+    description: "断开观察器、移除滚动监听"
+  }
+], h = [], g = "只读取 context 字段（props / state / data），不调用上下文方法", p = [
   {
     name: "getAnchorId",
     type: "(item, index) => string | number | undefined",
     default: "item.id",
     description: "从项里取锚点 id"
   }
-], g = `// 监听 \`anchor:scrollToId\` 事件，按业务 id 滚动到对应项。
+], f = `// 监听 \`anchor:scrollToId\` 事件，按业务 id 滚动到对应项。
 const Waterfall = withPlugins(WaterfallCore, [
   createScrollAnchorPlugin({
     getAnchorId: "item.id",
   }),
 ]);
 
-<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, h = [
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, I = [
   "按业务 id 定位，不用算下标",
   "onMount 订阅 / onUnmount 退订（不泄漏）",
   "平滑滚动"
-], f = [
+], A = [
   "从通知跳转到具体卡片",
   "目录点击定位",
   "外链深链定位"
-], I = [
+], b = [
   "目标项必须已在 items 里；分页场景请先切到对应页再发事件。"
-], b = {
+], C = {
   name: a,
-  description: l,
-  since: d,
+  description: d,
+  since: l,
   tags: m,
-  config: u,
-  example: g,
-  features: h,
-  useCases: f,
-  notes: I
+  events: u,
+  methods: h,
+  methodsNote: g,
+  config: p,
+  example: f,
+  features: I,
+  useCases: A,
+  notes: b
 };
 export {
-  A as c,
-  b as d
+  P as c,
+  C as d
 };

package/dist/chunks/{doc-BfWnfTst.js → doc-CInpKZNU.js}

@@ -1,35 +1,46 @@
-function g(r = {}) {
+function S(e = {}) {
   return {
     name: "SortPlugin",
     priority: 30,
     enabled: !0,
     hooks: {
       transformProps: (o) => {
-        const e = Array.isArray(o.items) ? o.items : [], t = o.sortComparator || r.comparator;
+        const r = Array.isArray(o.items) ? o.items : [], t = o.sortComparator || e.comparator;
         if (typeof t != "function") return o;
-        const s = [...e].sort((a, n) => {
+        const s = [...r].sort((n, a) => {
           try {
-            return t(a, n);
+            return t(n, a);
           } catch {
             return 0;
           }
         });
         return { ...o, items: s };
       },
-      onPropsChange: (o, e, t) => {
-        const s = e?.sortComparator, a = t?.sortComparator;
-        if (((typeof t?.scrollToTopOnSortChange == "boolean" ? t.scrollToTopOnSortChange : void 0) ?? !!r.scrollToTop) && s !== a) {
-          const l = t?.scrollToTopBehavior ?? r.scrollBehavior ?? "auto";
-          o.scrollToTop?.({ behavior: l });
+      onPropsChange: (o, r, t) => {
+        const s = r?.sortComparator, n = t?.sortComparator;
+        if (((typeof t?.scrollToTopOnSortChange == "boolean" ? t.scrollToTopOnSortChange : void 0) ?? !!e.scrollToTop) && s !== n) {
+          const c = t?.scrollToTopBehavior ?? e.scrollBehavior ?? "auto";
+          o.scrollToTop?.({ behavior: c });
         }
       }
     }
   };
 }
-const c = "SortPlugin", i = "用比较函数排序，优先读 `props.sortComparator`。排序总是在过滤之后、分页之前执行，保证「第 N 页」是排序后的第 N 页。", m = "2.0.0", p = [
+const l = "SortPlugin", i = "用比较函数排序，优先读 `props.sortComparator`。排序总是在过滤之后、分页之前执行，保证「第 N 页」是排序后的第 N 页。", m = "2.0.0", p = [
   "data",
   "数据管线"
-], u = [
+], d = [
+  {
+    name: "onPropsChange",
+    when: "props 变化后",
+    description: "数据或配置变化时请求重排"
+  },
+  {
+    name: "transformProps",
+    when: "渲染前链式改写瀑布流 props",
+    description: "补 gap / columns 默认值、按断点覆盖配置"
+  }
+], u = [], h = "只读取 context 字段（props / state / data），不调用上下文方法", f = [
   {
     name: "comparator",
     type: "(a, b) => number",
@@ -48,7 +59,7 @@ const c = "SortPlugin", i = "用比较函数排序，优先读 `props.sortCompar
     default: '"auto"',
     description: "回顶行为"
   }
-], d = `// 按比较函数排序 items，比较函数变化可自动回顶。
+], C = `// 按比较函数排序 items，比较函数变化可自动回顶。
 const Waterfall = withPlugins(WaterfallCore, [
   createSortPlugin({
     scrollToTop: false,
@@ -56,28 +67,31 @@ const Waterfall = withPlugins(WaterfallCore, [
   }),
 ]);
 
-<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, f = [
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, T = [
   "稳定排序（不改原数组）",
   "比较函数抛错按相等处理",
   "与 Filter / Search 顺序固定"
-], h = [
+], g = [
   "价格 / 时间排序",
   "热度排序",
   "手动置顶项优先"
-], C = [
+], v = [
   "排序会复制数组（`[...items].sort`），不会改调用方传入的 items。"
-], y = {
-  name: c,
+], b = {
+  name: l,
   description: i,
   since: m,
   tags: p,
-  config: u,
-  example: d,
-  features: f,
-  useCases: h,
-  notes: C
+  events: d,
+  methods: u,
+  methodsNote: h,
+  config: f,
+  example: C,
+  features: T,
+  useCases: g,
+  notes: v
 };
 export {
-  g as c,
-  y as d
+  S as c,
+  b as d
 };

package/dist/chunks/{doc-gTAsLjVx.js → doc-CYxwSuG6.js}

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