vane-waterfall 2.0.1 → 2.0.2

package/dist/chunks/withPlugins-DG3YpSgL.js

@@ -0,0 +1,655 @@
+import { jsxs as he, Fragment as pe, jsx as re } from "react/jsx-runtime";
+import we, { useRef as L, useState as A, useCallback as E, useMemo as U, useLayoutEffect as ie, createContext as ye, forwardRef as ve, useEffect as X } from "react";
+function be() {
+  const o = /* @__PURE__ */ new Map(), t = /* @__PURE__ */ new Map(), i = (e, a) => {
+    const l = o.get(e);
+    if (l)
+      for (const r of [...l])
+        try {
+          r(a);
+        } catch (s) {
+          console.warn(`[PluginBus] handler error for event "${e}"`, s);
+        }
+  }, g = (e, a) => {
+    let l = o.get(e);
+    return l || (l = /* @__PURE__ */ new Set(), o.set(e, l)), l.add(a), () => {
+      l?.delete(a);
+    };
+  }, d = (e, a) => {
+    const l = (r) => {
+      a(r), u(e, l);
+    };
+    return g(e, l);
+  }, u = (e, a) => {
+    if (!a) {
+      o.delete(e);
+      return;
+    }
+    o.get(e)?.delete(a);
+  };
+  return { emit: i, on: g, once: d, off: u, getData: (e) => t.get(e), setData: (e, a) => {
+    const l = t.get(e);
+    t.set(e, a), l !== a && i(e, a);
+  }, deleteData: (e) => {
+    const a = t.has(e);
+    t.delete(e), a && i(e, void 0);
+  }, hasData: (e) => t.has(e), getAll: () => {
+    const e = {};
+    return t.forEach((a, l) => {
+      e[l] = a;
+    }), e;
+  }, clear: () => {
+    o.clear(), t.clear();
+  } };
+}
+function fe(o) {
+  const t = new Map(o.map((a) => [a.name, a])), i = [];
+  for (const a of o)
+    for (const l of a.dependencies ?? [])
+      t.has(l) || i.push(`${a.name} -> ${l}`);
+  const g = [], d = /* @__PURE__ */ new Set(), u = [...o], e = (a) => (a.dependencies ?? []).every((l) => d.has(l) || !t.has(l));
+  for (; u.length > 0; ) {
+    const a = u.filter(e);
+    if (a.length === 0)
+      throw new Error(
+        `[vane/plugin-core] 插件循环依赖: ${u.map((r) => r.name).join(" <-> ")}`
+      );
+    let l = a[0];
+    for (const r of a)
+      (r.priority ?? 0) > (l.priority ?? 0) && (l = r);
+    g.push(l), d.add(l.name), u.splice(u.indexOf(l), 1);
+  }
+  return i.length > 0 && console.warn(
+    `[vane/plugin-core] 以下插件依赖未注册，将被忽略:
+  ${i.join(`
+  `)}`
+  ), g;
+}
+async function Pe(o, t = {}) {
+  const { timeout: i = 3e3, name: g = "anonymous", hook: d = "unknown" } = t;
+  if (!i || i <= 0)
+    return await o();
+  let u;
+  const e = new Promise((a, l) => {
+    u = setTimeout(() => {
+      l(new Error(`[vane/plugin-core] 插件 ${g} 的钩子 ${d} 超时(${i}ms)`));
+    }, i);
+  });
+  try {
+    return await Promise.race([Promise.resolve().then(o), e]);
+  } finally {
+    u && clearTimeout(u);
+  }
+}
+const Ie = /* @__PURE__ */ new Set(["onMount", "onUnmount", "onPropsChange", "onError"]);
+function ke(o = {}) {
+  const t = o.logger ?? console, i = o.sandbox ?? !0, g = o.timeout ?? 3e3, d = [], u = [], e = /* @__PURE__ */ new Map(), a = () => fe([...e.values()].filter((r) => r.enabled !== !1)), l = (r) => {
+    e.set(r.name, { ...r, enabled: r.enabled ?? !0 }), r.init && Promise.resolve(r.init()).catch((s) => {
+      t.warn(`[PluginManager] init failed for ${r.name}`, s);
+    });
+  };
+  return {
+    register: l,
+    registerAll: (r) => {
+      for (const s of r) l(s);
+    },
+    unregister: (r) => {
+      const s = e.get(r);
+      s && (s.destroy && Promise.resolve(s.destroy()).catch((x) => {
+        t.warn(`[PluginManager] destroy failed for ${s.name}`, x);
+      }), e.delete(r));
+    },
+    getPlugin: (r) => e.get(r),
+    getAllPlugins: () => [...e.values()],
+    getEnabledPlugins: () => [...e.values()].filter((r) => r.enabled !== !1),
+    getExecutionOrder: a,
+    enable: (r) => {
+      const s = e.get(r);
+      s && (s.enabled = !0);
+    },
+    disable: (r) => {
+      const s = e.get(r);
+      s && (s.enabled = !1);
+    },
+    has: (r) => e.has(r),
+    executeHook: async (r, s, ...x) => {
+      for (const p of a()) {
+        const H = p.hooks?.[r];
+        if (typeof H != "function") continue;
+        const D = p.sandbox ?? i, z = p.timeout ?? g;
+        let R;
+        try {
+          R = D ? await Pe(
+            () => H(s, ...x),
+            { timeout: z, name: p.name, hook: String(r) }
+          ) : await H(s, ...x);
+        } catch ($) {
+          if (d.push({ plugin: p.name, hook: String(r), error: $ }), t.warn(
+            `[PluginManager] hook ${String(r)} failed in ${p.name}`,
+            $
+          ), o.onError?.(p.name, String(r), $), r === "onError") break;
+          continue;
+        }
+        if (Ie.has(String(r)) && typeof R == "function") {
+          u.push(R);
+          continue;
+        }
+        if (R === !1) return !1;
+        if (R !== void 0 && R !== !0) return R;
+      }
+    },
+    clear: () => {
+      const r = u.splice(0);
+      for (const s of r.reverse())
+        try {
+          s();
+        } catch (x) {
+          t.warn("[PluginManager] cleanup failed", x);
+        }
+      for (const s of e.values())
+        s.destroy && Promise.resolve(s.destroy()).catch((x) => {
+          t.warn(`[PluginManager] destroy failed for ${s.name}`, x);
+        });
+      e.clear();
+    },
+    getErrors: () => [...d]
+  };
+}
+var Me = Object.defineProperty, xe = (o, t, i) => t in o ? Me(o, t, { enumerable: !0, configurable: !0, writable: !0, value: i }) : o[t] = i, Ce = (o, t, i) => xe(o, t + "", i);
+class me extends we.Component {
+  constructor() {
+    super(...arguments), Ce(this, "state", { error: null });
+  }
+  static getDerivedStateFromError(t) {
+    return { error: t };
+  }
+  componentDidCatch(t, i) {
+    console.warn("[vane/plugin-core] 插件渲染错误已被隔离", t, i), this.props.onError?.(t, i);
+  }
+  render() {
+    const { error: t } = this.state;
+    return t ? this.props.fallback ? this.props.fallback(t) : null : this.props.children;
+  }
+}
+let Z = null;
+function Le(o = !1) {
+  if (Z && !o) return Z;
+  const t = typeof window < "u" ? window.innerWidth : 1024, i = typeof window < "u" ? window.innerHeight : 768, g = typeof window < "u" && window.devicePixelRatio || 1, d = typeof navigator < "u" && navigator.userAgent || "", u = /iPad|Tablet/i.test(d), e = /Mobile|Android|iPhone/i.test(d), a = typeof window < "u" && ("ontouchstart" in window || (navigator.maxTouchPoints ?? 0) > 0);
+  return Z = {
+    type: u ? "tablet" : e ? "mobile" : "desktop",
+    os: d,
+    browser: d,
+    devicePixelRatio: g,
+    viewportWidth: t,
+    viewportHeight: i,
+    isTouchDevice: a,
+    isRetina: g >= 2
+  }, Z;
+}
+function le(o, t) {
+  if (Object.is(o, t)) return !0;
+  if (typeof o != "object" || typeof t != "object" || o === null || t === null)
+    return !1;
+  const i = Object.keys(o), g = Object.keys(t);
+  return i.length !== g.length ? !1 : i.every(
+    (d) => Object.is(o[d], t[d])
+  );
+}
+function Re(o) {
+  const {
+    plugins: t,
+    props: i,
+    data: g,
+    initialState: d,
+    containerRef: u,
+    enableDebug: e = !1,
+    managerOptions: a,
+    extendContext: l
+  } = o, r = L(null), s = u ?? r, x = L(null);
+  x.current || (x.current = ke(a));
+  const p = x.current, H = L(null);
+  H.current || (H.current = be());
+  const D = H.current, z = L(/* @__PURE__ */ new Map()), [R, $] = A(d ?? {}), [, te] = A(0), q = E(() => te((k) => k + 1), []), N = U(() => Le(), []), F = L(t), G = F.current;
+  (G.length !== t.length || t.some((k, v) => k !== G[v])) && (F.current = t);
+  const j = F.current, ae = j.map((k) => k.name).join("|");
+  ie(() => {
+    p.clear(), p.registerAll(j), e && console.debug("[vane/plugin-core] plugins registered:", ae);
+  }, [j]), ie(
+    () => () => {
+      p.executeHook("onUnmount", S.current), p.clear();
+    },
+    [p]
+  );
+  const P = U(
+    () => fe(j),
+    [j]
+  ), S = L(null), w = L(i);
+  le(w.current, i) || (w.current = i);
+  const V = w.current, Y = L(g);
+  le(Y.current, g) || (Y.current = g);
+  const J = Y.current, O = U(() => {
+    const k = {
+      props: V,
+      data: J,
+      bus: D,
+      refs: { container: s, getContainer: () => s.current },
+      state: R,
+      setState: (v) => $((W) => ({ ...W, ...v })),
+      shared: z.current,
+      deviceInfo: N,
+      forceUpdate: q,
+      getSize: () => {
+        const v = s.current;
+        return v ? { width: v.offsetWidth, height: v.offsetHeight } : { width: 0, height: 0 };
+      },
+      logger: console
+    };
+    return l ? l(k) : k;
+  }, [V, J, R, N, D, l]);
+  S.current = O;
+  const y = E(
+    (k) => {
+      let v = k;
+      for (const W of P) {
+        const B = W.hooks?.transformProps;
+        if (typeof B == "function")
+          try {
+            v = B(v);
+          } catch (_) {
+            (S.current?.logger ?? console).warn(
+              `[plugin-core] ${W.name}.transformProps 执行失败，已跳过`,
+              _
+            );
+          }
+      }
+      return v;
+    },
+    [P]
+  ), Q = E(
+    (k) => {
+      let v = k;
+      for (const W of P) {
+        const B = W.hooks?.transformData;
+        if (typeof B == "function")
+          try {
+            v = B(S.current, v);
+          } catch (_) {
+            (S.current?.logger ?? console).warn(
+              `[plugin-core] ${W.name}.transformData 执行失败，已跳过`,
+              _
+            );
+          }
+      }
+      return v;
+    },
+    [P]
+  ), ne = E(
+    (k, ...v) => p.executeHook(k, S.current, ...v),
+    [p]
+  );
+  return {
+    manager: p,
+    bus: D,
+    context: O,
+    state: R,
+    setState: O.setState,
+    execute: ne,
+    transformProps: y,
+    transformData: Q,
+    orderedPlugins: P
+  };
+}
+ye(null);
+function ee(o, t, i) {
+  const { hook: g, position: d = "after" } = i;
+  return o.filter((u) => u.enabled !== !1).filter((u) => typeof u.hooks?.[g] == "function").filter((u) => {
+    const e = u.config?.slotPosition;
+    return d === "before" ? e === "before" : d === "footer" ? e === void 0 || e === "after" || e === "footer" : e === void 0 || e === "after";
+  }).sort(
+    (u, e) => (u.config?.order ?? 0) - (e.config?.order ?? 0) || (e.priority ?? 0) - (u.priority ?? 0)
+  ).map((u) => {
+    try {
+      const e = u.hooks[g](t);
+      return e == null ? null : /* @__PURE__ */ re(me, { children: e }, `vane-slot-${u.name}`);
+    } catch (e) {
+      return console.warn(`[vane/plugin-core] 插件 ${u.name} 的 ${g} 渲染失败`, e), null;
+    }
+  });
+}
+function Se(o, t, i) {
+  return /* @__PURE__ */ he(pe, { children: [
+    ee(o, t, { hook: "renderHeader", position: "before" }),
+    i,
+    ee(o, t, { hook: "renderOverlay" }),
+    ee(o, t, { hook: "renderHeader", position: "after" }),
+    ee(o, t, { hook: "renderFooter", position: "footer" })
+  ] });
+}
+const Te = {
+  columns: 0,
+  columnWidth: 0,
+  gap: 0,
+  columnHeights: [],
+  totalHeight: 0,
+  containerWidth: 0,
+  containerHeight: 0
+}, Ee = {
+  scrollTop: 0,
+  scrollLeft: 0,
+  scrollHeight: 0,
+  scrollWidth: 0,
+  clientHeight: 0,
+  clientWidth: 0,
+  isScrolling: !1,
+  direction: null
+};
+function T(o, t, ...i) {
+  if (typeof t == "function")
+    try {
+      return t(...i);
+    } catch (g) {
+      console.warn(`[vane-waterfall] ${o} 回调抛错，已忽略`, g);
+      return;
+    }
+}
+async function ce(o, t, ...i) {
+  if (typeof t == "function")
+    try {
+      return await t(...i);
+    } catch (g) {
+      console.warn(`[vane-waterfall] ${o} 回调抛错，已忽略`, g);
+      return;
+    }
+}
+function He() {
+  const o = typeof navigator < "u" ? navigator : void 0, t = o?.connection || o?.mozConnection || o?.webkitConnection;
+  if (t)
+    return {
+      effectiveType: t.effectiveType || "4g",
+      downlink: Number(t.downlink || 10),
+      rtt: Number(t.rtt || 50),
+      saveData: !!t.saveData,
+      online: o?.onLine !== !1
+    };
+}
+function ue(o, t, i) {
+  let g = Number.POSITIVE_INFINITY, d = -1;
+  return o.forEach((u, e) => {
+    Math.max(
+      0,
+      Math.min(t + i, u.y + u.height) - Math.max(t, u.y)
+    ) > 0 && (e < g && (g = e), e > d && (d = e));
+  }), d < 0 ? { start: 0, end: 0 } : { start: g, end: d };
+}
+function Be(o, t) {
+  const i = Array.isArray(t) ? { plugins: t } : t, { plugins: g, enableDebug: d = !1 } = i, u = ve(
+    (e, a) => {
+      const l = L(null), r = L(/* @__PURE__ */ new Map()), s = L(null), x = U(() => He(), []), p = L(null), [H, D] = A(Te), [z, R] = A(
+        () => /* @__PURE__ */ new Map()
+      ), [$, te] = A(Ee), [q, N] = A(!1), [F, G] = A(0), j = E(
+        (n) => {
+          const f = () => s.current?.getLayoutInfo() ?? H, h = () => s.current?.getAllItemPositions() ?? z, b = () => s.current?.getViewportInfo() ?? $, c = () => p.current?.items ?? n.props?.items ?? [], C = () => n.props?.items ?? [], I = () => {
+            const m = s.current?.getVisibleItems();
+            if (m && m.size > 0) return m;
+            const K = b(), se = /* @__PURE__ */ new Set();
+            return h().forEach((oe, de) => {
+              Math.max(
+                0,
+                Math.min(K.scrollTop + K.clientHeight, oe.y + oe.height) - Math.max(K.scrollTop, oe.y)
+              ) > 0 && se.add(de);
+            }), se;
+          }, M = {
+            ...n,
+            items: c(),
+            itemCount: c().length,
+            rawItems: C(),
+            containerRef: l,
+            itemRefs: r.current,
+            getItemRef: (m) => r.current.get(m) ?? null,
+            layout: f(),
+            itemPositions: h(),
+            getItemPosition: (m) => h().get(m) ?? null,
+            viewport: b(),
+            visibleItems: I(),
+            visibleRange: ue(
+              h(),
+              b().scrollTop,
+              b().clientHeight
+            ),
+            isLayouting: q,
+            isScrolling: $.isScrolling,
+            isDragging: !!n.state?.dragInfo?.isDragging,
+            isLoading: !!(n.state?.isLoading ?? !1),
+            hasMore: !!(n.state?.hasMore ?? !0),
+            error: n.state?.error ?? null,
+            sharedData: n.shared,
+            networkInfo: x,
+            dragInfo: n.state?.dragInfo,
+            relayout: () => s.current?.relayout(),
+            scrollToItem: (m, K) => s.current?.scrollToItem(m, K),
+            scrollToTop: (m) => s.current?.scrollToTop(m),
+            scrollToBottom: (m) => s.current?.scrollToBottom(m),
+            measureItem: (m) => s.current?.measureItem(m) ?? Promise.resolve({ width: 0, height: 0 })
+          };
+          return Object.defineProperties(M, {
+            layout: { get: f, enumerable: !0, configurable: !0 },
+            itemPositions: { get: h, enumerable: !0, configurable: !0 },
+            viewport: { get: b, enumerable: !0, configurable: !0 },
+            items: { get: c, enumerable: !0, configurable: !0 },
+            itemCount: {
+              get: () => c().length,
+              enumerable: !0,
+              configurable: !0
+            },
+            rawItems: { get: C, enumerable: !0, configurable: !0 },
+            visibleItems: { get: I, enumerable: !0, configurable: !0 },
+            // 宿主 props 优先：`hasMore` / `isLoading` 从「恒 true / 恒 false」改成
+            // 「props 能覆盖插件状态」，页面不用 hand-roll 一个插件就能控制（P2-2）
+            hasMore: {
+              get: () => p.current?.hasMore ?? n.state?.hasMore ?? !0,
+              enumerable: !0,
+              configurable: !0
+            },
+            isLoading: {
+              get: () => p.current?.isLoading ?? n.state?.isLoading ?? !1,
+              enumerable: !0,
+              configurable: !0
+            },
+            props: {
+              get: () => p.current ?? n.props,
+              enumerable: !0,
+              configurable: !0
+            },
+            visibleRange: {
+              get: () => {
+                const m = b();
+                return ue(h(), m.scrollTop, m.clientHeight);
+              },
+              enumerable: !0,
+              configurable: !0
+            }
+          }), M;
+        },
+        [H, z, $, q, x]
+      ), P = Re({
+        plugins: g,
+        props: e,
+        enableDebug: d,
+        containerRef: l,
+        extendContext: j
+      }), S = L(P.context);
+      ie(() => {
+        S.current = P.context;
+      }), X(
+        () => P.bus.on("props:invalidate", () => G((n) => n + 1)),
+        [P.bus]
+      );
+      const w = E(
+        (n, ...f) => P.execute(n, ...f),
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+        [P.manager]
+      ), V = P.orderedPlugins, Y = g.map((n) => n.name).join("|"), J = U(() => {
+        const n = V.filter(
+          (c) => typeof c.hooks?.calculateColumns == "function"
+        ), f = V.filter(
+          (c) => typeof c.hooks?.calculateColumnWidth == "function"
+        ), h = V.filter(
+          (c) => typeof c.hooks?.calculateItemPosition == "function"
+        );
+        if (!n.length && !f.length && !h.length)
+          return;
+        const b = (c, C, I) => console.warn(`[vane-waterfall] ${c} 的 ${C} 执行失败`, I);
+        return {
+          calculateColumns: n.length ? (c) => {
+            const C = S.current?.containerRef?.current?.clientWidth ?? 0;
+            for (const I of n)
+              try {
+                const M = I.hooks.calculateColumns(S.current, C);
+                if (typeof M == "number" && Number.isFinite(M)) return M;
+              } catch (M) {
+                b(I.name, "calculateColumns", M);
+              }
+          } : void 0,
+          calculateColumnWidth: f.length ? (c, C, I) => {
+            for (const M of f)
+              try {
+                const m = M.hooks.calculateColumnWidth(
+                  S.current,
+                  I,
+                  C
+                );
+                if (typeof m == "number" && Number.isFinite(m)) return m;
+              } catch (m) {
+                b(M.name, "calculateColumnWidth", m);
+              }
+          } : void 0,
+          calculateItemPosition: h.length ? (c, C, I) => {
+            for (const M of h)
+              try {
+                const m = M.hooks.calculateItemPosition(
+                  S.current,
+                  c,
+                  C,
+                  I
+                );
+                if (m) return m;
+              } catch (m) {
+                b(M.name, "calculateItemPosition", m);
+              }
+          } : void 0
+        };
+      }, [V]), O = E(() => {
+        const n = s.current;
+        if (!n) return;
+        const f = n.getLayoutInfo(), h = n.getAllItemPositions(), b = n.getViewportInfo();
+        D(
+          (c) => c.totalHeight === f.totalHeight && c.columns === f.columns && c.columnWidth === f.columnWidth && c.containerWidth === f.containerWidth ? c : f
+        ), R((c) => {
+          if (c === h) return c;
+          if (c.size !== h.size) return h;
+          let C = !0;
+          return h.forEach((I, M) => {
+            if (C === !1) return;
+            const m = c.get(M);
+            (!m || m.x !== I.x || m.y !== I.y || m.width !== I.width || m.height !== I.height || m.column !== I.column) && (C = !1);
+          }), C ? c : h;
+        }), te(
+          (c) => c.scrollTop === b.scrollTop && c.clientHeight === b.clientHeight && c.scrollHeight === b.scrollHeight && c.isScrolling === b.isScrolling ? c : b
+        );
+      }, []), y = U(() => P.transformProps(e), [P.transformProps, e, F]);
+      X(() => {
+        g.some((n) => n.name === "PaginationPlugin") && g.some((n) => n.name === "InfiniteScrollPlugin") && console.warn(
+          "[vane-waterfall] PaginationPlugin 与 InfiniteScrollPlugin 互斥：两者都会改写 items，请只保留一个"
+        );
+      }, [Y]), X(() => {
+        w("onMount");
+      }, [w]);
+      const Q = L(e);
+      X(() => {
+        const n = Q.current;
+        n !== e && (Q.current = e, w("onPropsChange", n, e));
+      }, [e, w]), p.current = y;
+      const ne = E(async () => (N(!0), await w("onBeforeLayout") === !1 ? (N(!1), !1) : !0), [w]), k = E(() => {
+        w("onLayout");
+      }, [w]), v = E(() => {
+        N(!1), w("onLayoutComplete"), Promise.resolve().then(O);
+      }, [w, O]), W = U(
+        () => V.filter((n) => typeof n.hooks?.renderItemWrapper == "function"),
+        [V]
+      ), B = y.renderItem, _ = E(
+        (n, f) => {
+          let h = B?.(n, f) ?? null;
+          for (const b of W)
+            try {
+              const c = b.hooks.renderItemWrapper(S.current, h, f);
+              c != null && (h = c);
+            } catch (c) {
+              console.warn(`[vane-waterfall] ${b.name} 的 renderItemWrapper 失败`, c);
+            }
+          return h;
+        },
+        // 身份保持稳定（插件链与基础 renderItem 不变时不变）：Core 里项单元是 memo 的，
+        // 这里每次渲染都给新函数等于把 memo 全部击穿（P2-11）
+        [B, W]
+      ), ge = {
+        ...y,
+        containerRefExternal: l,
+        itemRefsExternal: r,
+        debug: y.debug ?? d,
+        layoutHooks: J ?? y.layoutHooks,
+        renderItem: _,
+        children: /* @__PURE__ */ re(me, { children: Se(P.orderedPlugins, P.context, y.children) }),
+        onMount: () => {
+          T("onMount", y.onMount);
+        },
+        onUnmount: () => {
+          T("onUnmount", y.onUnmount);
+        },
+        onBeforeLayout: async () => await ne() === !1 ? !1 : await ce("onBeforeLayout", y.onBeforeLayout) ?? !0,
+        onLayout: () => {
+          T("onLayout", y.onLayout), k();
+        },
+        onLayoutComplete: () => {
+          T("onLayoutComplete", y.onLayoutComplete), v();
+        },
+        onItemMount: (n, f) => {
+          T("onItemMount", y.onItemMount, n, f), w("onItemMount", n, f);
+        },
+        onItemUnmount: (n) => {
+          T("onItemUnmount", y.onItemUnmount, n), w("onItemUnmount", n);
+        },
+        onItemEnterViewport: (n, f) => {
+          T("onItemEnterViewport", y.onItemEnterViewport, n, f), w("onItemEnterViewport", n, f);
+        },
+        onItemLeaveViewport: (n, f) => {
+          T("onItemLeaveViewport", y.onItemLeaveViewport, n, f), w("onItemLeaveViewport", n, f);
+        },
+        onScroll: (n, f) => {
+          T("onScroll", y.onScroll, n, f), w("onScroll", n, f), O();
+        },
+        onResize: (n, f) => {
+          T("onResize", y.onResize, n, f), w("onResize", n, f);
+        },
+        onReachBottom: async (n) => {
+          await ce("onReachBottom", y.onReachBottom, n), await w("onReachBottom", n);
+        },
+        onItemClick: (n, f, h) => {
+          T("onItemClick", y.onItemClick, n, f, h), w("onItemClick", n, f, h);
+        }
+      };
+      return /* @__PURE__ */ re(
+        o,
+        {
+          ref: (n) => {
+            s.current = n, typeof a == "function" ? a(n) : a && (a.current = n);
+          },
+          ...ge
+        }
+      );
+    }
+  );
+  return u.displayName = "WithPlugins(WaterfallCore)", u;
+}
+export {
+  Be as w
+};

package/dist/components/WaterfallPlugin/WaterfallCore.d.ts

@@ -39,6 +39,23 @@ export interface WaterfallCoreProps<T = any> {
      * 无限滚动类插件靠它提前预加载（旧版写死 100，插件配多大都没用）。
      */
     reachBottomOffset?: number;
+    /**
+     * 零高度项的最小占位高度，默认 48（设 0 关闭，退回旧行为：该项不占位且不可见）。
+     *
+     * 图片 404 / 懒加载尚未解码 / 字体度量未就绪时首测 `offsetHeight` 为 0，
+     * 旧实现直接跳过 → 该DOM 节点被 `opacity:0` 隐藏、不在 `positions` 里，
+     * `scrollToItem` / `onItemEnterViewport` 也永远命中不到。
+     */
+    minItemHeight?: number;
+    /**
+     * 滚动锚定：布局前后补偿 `scrollTop`，让第一个可见项在屏幕上的位置不变，默认 true。
+     * 视口上方的项从估值变成真高时，不补偿会让内容整体「跳一下」。
+     */
+    scrollAnchor?: boolean;
+    /** 是否还有更多数据（`InfiniteScrollPlugin` 读取），优先于插件内部状态 */
+    hasMore?: boolean;
+    /** 数据是否在加载中（`aria-busy` 等读取），优先于插件内部状态 */
+    isLoading?: boolean;
     /**
      * 虚拟化：只渲染视口附近的项。
      * 千项以上、项高度可估（图片卡、商品卡）时开；与 `RecyclePlugin` 不要同开。
@@ -101,6 +118,8 @@ export interface WaterfallCoreRef {
         start: number;
         end: number;
     };
+    /** 当前与视口有重叠的索引集合（滚动时维护，供插件上下文使用） */
+    getVisibleItems: () => Set<number>;
     forceUpdate: () => void;
     getContainer: () => HTMLDivElement | null;
     getItemElement: (index: number) => HTMLElement | null;