vane-waterfall 1.0.5 → 2.0.0

package/dist/chunks/withPlugins-DLoKg4AP.js

@@ -0,0 +1,559 @@
+import { jsxs as le, Fragment as ce, jsx as q } from "react/jsx-runtime";
+import ue, { useRef as M, useState as A, useCallback as C, useMemo as z, useLayoutEffect as X, createContext as fe, forwardRef as ge, useEffect as J } from "react";
+function me() {
+  const i = /* @__PURE__ */ new Map(), t = /* @__PURE__ */ new Map(), c = (e, o) => {
+    const s = i.get(e);
+    if (s)
+      for (const r of [...s])
+        try {
+          r(o);
+        } catch (a) {
+          console.warn(`[PluginBus] handler error for event "${e}"`, a);
+        }
+  }, g = (e, o) => {
+    let s = i.get(e);
+    return s || (s = /* @__PURE__ */ new Set(), i.set(e, s)), s.add(o), () => {
+      s?.delete(o);
+    };
+  }, m = (e, o) => {
+    const s = (r) => {
+      o(r), l(e, s);
+    };
+    return g(e, s);
+  }, l = (e, o) => {
+    if (!o) {
+      i.delete(e);
+      return;
+    }
+    i.get(e)?.delete(o);
+  };
+  return { emit: c, on: g, once: m, off: l, getData: (e) => t.get(e), setData: (e, o) => {
+    const s = t.get(e);
+    t.set(e, o), s !== o && c(e, o);
+  }, deleteData: (e) => {
+    const o = t.has(e);
+    t.delete(e), o && c(e, void 0);
+  }, hasData: (e) => t.has(e), getAll: () => {
+    const e = {};
+    return t.forEach((o, s) => {
+      e[s] = o;
+    }), e;
+  }, clear: () => {
+    i.clear(), t.clear();
+  } };
+}
+function ee(i) {
+  const t = new Map(i.map((o) => [o.name, o])), c = [];
+  for (const o of i)
+    for (const s of o.dependencies ?? [])
+      t.has(s) || c.push(`${o.name} -> ${s}`);
+  const g = [], m = /* @__PURE__ */ new Set(), l = [...i], e = (o) => (o.dependencies ?? []).every((s) => m.has(s) || !t.has(s));
+  for (; l.length > 0; ) {
+    const o = l.filter(e);
+    if (o.length === 0)
+      throw new Error(
+        `[vane/plugin-core] 插件循环依赖: ${l.map((r) => r.name).join(" <-> ")}`
+      );
+    let s = o[0];
+    for (const r of o)
+      (r.priority ?? 0) > (s.priority ?? 0) && (s = r);
+    g.push(s), m.add(s.name), l.splice(l.indexOf(s), 1);
+  }
+  return c.length > 0 && console.warn(
+    `[vane/plugin-core] 以下插件依赖未注册，将被忽略:
+  ${c.join(`
+  `)}`
+  ), g;
+}
+async function de(i, t = {}) {
+  const { timeout: c = 3e3, name: g = "anonymous", hook: m = "unknown" } = t;
+  if (!c || c <= 0)
+    return await i();
+  let l;
+  const e = new Promise((o, s) => {
+    l = setTimeout(() => {
+      s(new Error(`[vane/plugin-core] 插件 ${g} 的钩子 ${m} 超时(${c}ms)`));
+    }, c);
+  });
+  try {
+    return await Promise.race([Promise.resolve().then(i), e]);
+  } finally {
+    l && clearTimeout(l);
+  }
+}
+const he = /* @__PURE__ */ new Set(["onMount", "onUnmount", "onPropsChange", "onError"]);
+function pe(i = {}) {
+  const t = i.logger ?? console, c = i.sandbox ?? !0, g = i.timeout ?? 3e3, m = [], l = [], e = /* @__PURE__ */ new Map(), o = () => ee([...e.values()].filter((r) => r.enabled !== !1)), s = (r) => {
+    e.set(r.name, { ...r, enabled: r.enabled ?? !0 }), r.init && Promise.resolve(r.init()).catch((a) => {
+      t.warn(`[PluginManager] init failed for ${r.name}`, a);
+    });
+  };
+  return {
+    register: s,
+    registerAll: (r) => {
+      for (const a of r) s(a);
+    },
+    unregister: (r) => {
+      const a = e.get(r);
+      a && (a.destroy && Promise.resolve(a.destroy()).catch((b) => {
+        t.warn(`[PluginManager] destroy failed for ${a.name}`, b);
+      }), e.delete(r));
+    },
+    getPlugin: (r) => e.get(r),
+    getAllPlugins: () => [...e.values()],
+    getEnabledPlugins: () => [...e.values()].filter((r) => r.enabled !== !1),
+    getExecutionOrder: o,
+    enable: (r) => {
+      const a = e.get(r);
+      a && (a.enabled = !0);
+    },
+    disable: (r) => {
+      const a = e.get(r);
+      a && (a.enabled = !1);
+    },
+    has: (r) => e.has(r),
+    executeHook: async (r, a, ...b) => {
+      for (const p of o()) {
+        const R = p.hooks?.[r];
+        if (typeof R != "function") continue;
+        const $ = p.sandbox ?? c, N = p.timeout ?? g;
+        let k;
+        try {
+          k = $ ? await de(
+            () => R(a, ...b),
+            { timeout: N, name: p.name, hook: String(r) }
+          ) : await R(a, ...b);
+        } catch (W) {
+          if (m.push({ plugin: p.name, hook: String(r), error: W }), t.warn(
+            `[PluginManager] hook ${String(r)} failed in ${p.name}`,
+            W
+          ), i.onError?.(p.name, String(r), W), r === "onError") break;
+          continue;
+        }
+        if (he.has(String(r)) && typeof k == "function") {
+          l.push(k);
+          continue;
+        }
+        if (k === !1) return !1;
+        if (k !== void 0 && k !== !0) return k;
+      }
+    },
+    clear: () => {
+      const r = l.splice(0);
+      for (const a of r.reverse())
+        try {
+          a();
+        } catch (b) {
+          t.warn("[PluginManager] cleanup failed", b);
+        }
+      for (const a of e.values())
+        a.destroy && Promise.resolve(a.destroy()).catch((b) => {
+          t.warn(`[PluginManager] destroy failed for ${a.name}`, b);
+        });
+      e.clear();
+    },
+    getErrors: () => [...m]
+  };
+}
+var we = Object.defineProperty, ye = (i, t, c) => t in i ? we(i, t, { enumerable: !0, configurable: !0, writable: !0, value: c }) : i[t] = c, ve = (i, t, c) => ye(i, t + "", c);
+class te extends ue.Component {
+  constructor() {
+    super(...arguments), ve(this, "state", { error: null });
+  }
+  static getDerivedStateFromError(t) {
+    return { error: t };
+  }
+  componentDidCatch(t, c) {
+    console.warn("[vane/plugin-core] 插件渲染错误已被隔离", t, c), this.props.onError?.(t, c);
+  }
+  render() {
+    const { error: t } = this.state;
+    return t ? this.props.fallback ? this.props.fallback(t) : null : this.props.children;
+  }
+}
+let Y = null;
+function Pe(i = !1) {
+  if (Y && !i) return Y;
+  const t = typeof window < "u" ? window.innerWidth : 1024, c = typeof window < "u" ? window.innerHeight : 768, g = typeof window < "u" && window.devicePixelRatio || 1, m = typeof navigator < "u" && navigator.userAgent || "", l = /iPad|Tablet/i.test(m), e = /Mobile|Android|iPhone/i.test(m), o = typeof window < "u" && ("ontouchstart" in window || (navigator.maxTouchPoints ?? 0) > 0);
+  return Y = {
+    type: l ? "tablet" : e ? "mobile" : "desktop",
+    os: m,
+    browser: m,
+    devicePixelRatio: g,
+    viewportWidth: t,
+    viewportHeight: c,
+    isTouchDevice: o,
+    isRetina: g >= 2
+  }, Y;
+}
+function Ie(i) {
+  const {
+    plugins: t,
+    props: c,
+    data: g,
+    initialState: m,
+    containerRef: l,
+    enableDebug: e = !1,
+    managerOptions: o,
+    extendContext: s
+  } = i, r = M(null), a = l ?? r, b = M(null);
+  b.current || (b.current = pe(o));
+  const p = b.current, R = M(null);
+  R.current || (R.current = me());
+  const $ = R.current, N = M(/* @__PURE__ */ new Map()), [k, W] = A(m ?? {}), [, K] = A(0), U = C(() => K((I) => I + 1), []), O = z(() => Pe(), []), D = t.map((I) => I.name).join("|");
+  X(() => {
+    p.clear(), p.registerAll(t), e && console.debug("[vane/plugin-core] plugins registered:", D);
+  }, [D]), X(
+    () => () => {
+      p.executeHook("onUnmount", j.current), p.clear();
+    },
+    [p]
+  );
+  const B = z(
+    () => ee(t),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [D]
+  ), j = M(null), F = z(() => {
+    const I = {
+      props: c,
+      data: g,
+      bus: $,
+      refs: { container: a, getContainer: () => a.current },
+      state: k,
+      setState: (v) => W((V) => ({ ...V, ...v })),
+      shared: N.current,
+      deviceInfo: O,
+      forceUpdate: U,
+      getSize: () => {
+        const v = a.current;
+        return v ? { width: v.offsetWidth, height: v.offsetHeight } : { width: 0, height: 0 };
+      },
+      logger: console
+    };
+    return s ? s(I) : I;
+  }, [c, g, k, O, $, s]);
+  j.current = F;
+  const L = C(
+    (I) => {
+      let v = I;
+      for (const V of B) {
+        const E = V.hooks?.transformProps;
+        typeof E == "function" && (v = E(v));
+      }
+      return v;
+    },
+    [B]
+  ), T = C(
+    (I) => {
+      let v = I;
+      for (const V of B) {
+        const E = V.hooks?.transformData;
+        typeof E == "function" && (v = E(j.current, v));
+      }
+      return v;
+    },
+    [B]
+  ), h = C(
+    (I, ...v) => p.executeHook(I, j.current, ...v),
+    [p]
+  );
+  return {
+    manager: p,
+    bus: $,
+    context: F,
+    state: k,
+    setState: F.setState,
+    execute: h,
+    transformProps: L,
+    transformData: T,
+    orderedPlugins: B
+  };
+}
+fe(null);
+function _(i, t, c) {
+  const { hook: g, position: m = "after" } = c;
+  return i.filter((l) => l.enabled !== !1).filter((l) => typeof l.hooks?.[g] == "function").filter((l) => (l.config?.slotPosition ?? "after") === m).sort(
+    (l, e) => (l.config?.order ?? 0) - (e.config?.order ?? 0) || (e.priority ?? 0) - (l.priority ?? 0)
+  ).map((l, e) => {
+    try {
+      const o = l.hooks[g](t);
+      return o == null ? null : /* @__PURE__ */ q(te, { children: o }, `vane-slot-${l.name}-${e}`);
+    } catch (o) {
+      return console.warn(`[vane/plugin-core] 插件 ${l.name} 的 ${g} 渲染失败`, o), null;
+    }
+  });
+}
+function be(i, t, c) {
+  return /* @__PURE__ */ le(ce, { children: [
+    _(i, t, { hook: "renderHeader", position: "before" }),
+    c,
+    _(i, t, { hook: "renderOverlay" }),
+    _(i, t, { hook: "renderHeader", position: "after" }),
+    _(i, t, { hook: "renderFooter" })
+  ] });
+}
+const ke = {
+  columns: 0,
+  columnWidth: 0,
+  gap: 0,
+  columnHeights: [],
+  totalHeight: 0,
+  containerWidth: 0,
+  containerHeight: 0
+}, xe = {
+  scrollTop: 0,
+  scrollLeft: 0,
+  scrollHeight: 0,
+  scrollWidth: 0,
+  clientHeight: 0,
+  clientWidth: 0,
+  isScrolling: !1,
+  direction: null
+};
+function Ce() {
+  const i = typeof navigator < "u" ? navigator : void 0, t = i?.connection || i?.mozConnection || i?.webkitConnection;
+  if (t)
+    return {
+      effectiveType: t.effectiveType || "4g",
+      downlink: Number(t.downlink || 10),
+      rtt: Number(t.rtt || 50),
+      saveData: !!t.saveData,
+      online: i?.onLine !== !1
+    };
+}
+function Z(i, t, c) {
+  let g = Number.POSITIVE_INFINITY, m = -1;
+  return i.forEach((l, e) => {
+    Math.max(
+      0,
+      Math.min(t + c, l.y + l.height) - Math.max(t, l.y)
+    ) > 0 && (e < g && (g = e), e > m && (m = e));
+  }), m < 0 ? { start: 0, end: 0 } : { start: g, end: m };
+}
+function Le(i, t) {
+  const c = Array.isArray(t) ? { plugins: t } : t, { plugins: g, enableDebug: m = !1 } = c, l = ge(
+    (e, o) => {
+      const s = M(null), r = M(/* @__PURE__ */ new Map()), a = M(null), b = z(() => Ce(), []), p = M(null), [R, $] = A(ke), [N, k] = A(
+        () => /* @__PURE__ */ new Map()
+      ), [W, K] = A(xe), [U, O] = A(!1), [D, B] = A(e.items ?? []), j = C(
+        (n) => {
+          const u = () => a.current?.getLayoutInfo() ?? R, y = () => a.current?.getAllItemPositions() ?? N, P = () => a.current?.getViewportInfo() ?? W, f = {
+            ...n,
+            items: D,
+            itemCount: D.length,
+            containerRef: s,
+            itemRefs: r.current,
+            getItemRef: (d) => r.current.get(d) ?? null,
+            layout: u(),
+            itemPositions: y(),
+            getItemPosition: (d) => y().get(d) ?? null,
+            viewport: P(),
+            visibleItems: /* @__PURE__ */ new Set(),
+            visibleRange: Z(
+              y(),
+              P().scrollTop,
+              P().clientHeight
+            ),
+            isLayouting: U,
+            isScrolling: W.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: b,
+            dragInfo: n.state?.dragInfo,
+            relayout: () => a.current?.relayout(),
+            scrollToItem: (d, S) => a.current?.scrollToItem(d, S),
+            scrollToTop: (d) => a.current?.scrollToTop(d),
+            scrollToBottom: (d) => a.current?.scrollToBottom(d),
+            measureItem: (d) => a.current?.measureItem(d) ?? Promise.resolve({ width: 0, height: 0 })
+          };
+          return Object.defineProperties(f, {
+            layout: { get: u, enumerable: !0, configurable: !0 },
+            itemPositions: { get: y, enumerable: !0, configurable: !0 },
+            viewport: { get: P, enumerable: !0, configurable: !0 },
+            props: {
+              get: () => p.current ?? n.props,
+              enumerable: !0,
+              configurable: !0
+            },
+            visibleRange: {
+              get: () => {
+                const d = P();
+                return Z(y(), d.scrollTop, d.clientHeight);
+              },
+              enumerable: !0,
+              configurable: !0
+            }
+          }), f;
+        },
+        [D, R, N, W, U, b]
+      ), L = Ie({
+        plugins: g,
+        props: e,
+        enableDebug: m,
+        containerRef: s,
+        extendContext: j
+      }), T = M(L.context);
+      T.current = L.context;
+      const h = C(
+        (n, ...u) => L.execute(n, ...u),
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+        [L.manager]
+      ), I = L.orderedPlugins, v = g.map((n) => n.name).join("|"), V = z(() => {
+        const n = I.filter(
+          (f) => typeof f.hooks?.calculateColumns == "function"
+        ), u = I.filter(
+          (f) => typeof f.hooks?.calculateColumnWidth == "function"
+        ), y = I.filter(
+          (f) => typeof f.hooks?.calculateItemPosition == "function"
+        );
+        if (!n.length && !u.length && !y.length)
+          return;
+        const P = (f, d, S) => console.warn(`[vane-waterfall] ${f} 的 ${d} 执行失败`, S);
+        return {
+          calculateColumns: n.length ? (f) => {
+            const d = T.current?.containerRef?.current?.clientWidth ?? 0;
+            for (const S of n)
+              try {
+                const x = S.hooks.calculateColumns(T.current, d);
+                if (typeof x == "number" && Number.isFinite(x)) return x;
+              } catch (x) {
+                P(S.name, "calculateColumns", x);
+              }
+          } : void 0,
+          calculateColumnWidth: u.length ? (f, d, S) => {
+            for (const x of u)
+              try {
+                const H = x.hooks.calculateColumnWidth(
+                  T.current,
+                  S,
+                  d
+                );
+                if (typeof H == "number" && Number.isFinite(H)) return H;
+              } catch (H) {
+                P(x.name, "calculateColumnWidth", H);
+              }
+          } : void 0,
+          calculateItemPosition: y.length ? (f, d, S) => {
+            for (const x of y)
+              try {
+                const H = x.hooks.calculateItemPosition(
+                  T.current,
+                  f,
+                  d,
+                  S
+                );
+                if (H) return H;
+              } catch (H) {
+                P(x.name, "calculateItemPosition", H);
+              }
+          } : void 0
+        };
+      }, [v]), E = C(() => {
+        const n = a.current;
+        if (!n) return;
+        const u = n.getLayoutInfo(), y = n.getAllItemPositions(), P = n.getViewportInfo();
+        $(
+          (f) => f.totalHeight === u.totalHeight && f.columns === u.columns && f.columnWidth === u.columnWidth && f.containerWidth === u.containerWidth ? f : u
+        ), k(
+          (f) => f.size === y.size ? f : y
+        ), K(
+          (f) => f.scrollTop === P.scrollTop && f.clientHeight === P.clientHeight && f.scrollHeight === P.scrollHeight && f.isScrolling === P.isScrolling ? f : P
+        );
+      }, []);
+      J(() => {
+        B(e.items ?? []);
+      }, [e.items]), J(() => {
+        h("onMount");
+      }, [h]);
+      const G = M(e);
+      J(() => {
+        const n = G.current;
+        n !== e && (G.current = e, h("onPropsChange", n, e));
+      }, [e, h]);
+      const w = L.transformProps(e);
+      p.current = w;
+      const ne = C(async () => (O(!0), await h("onBeforeLayout") === !1 ? (O(!1), !1) : !0), [h]), oe = C(() => {
+        h("onLayout");
+      }, [h]), re = C(() => {
+        O(!1), h("onLayoutComplete"), Promise.resolve().then(E);
+      }, [h, E]), ie = I.filter(
+        (n) => typeof n.hooks?.renderItemWrapper == "function"
+      ), Q = w.renderItem, se = C(
+        (n, u) => {
+          let y = Q?.(n, u) ?? null;
+          for (const P of ie)
+            try {
+              const f = P.hooks.renderItemWrapper(T.current, y, u);
+              f != null && (y = f);
+            } catch (f) {
+              console.warn(`[vane-waterfall] ${P.name} 的 renderItemWrapper 失败`, f);
+            }
+          return y;
+        },
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+        [Q, v]
+      ), ae = {
+        ...w,
+        containerRefExternal: s,
+        itemRefsExternal: r,
+        debug: w.debug ?? m,
+        layoutHooks: V ?? w.layoutHooks,
+        renderItem: se,
+        children: /* @__PURE__ */ q(te, { children: be(L.orderedPlugins, L.context, w.children) }),
+        onMount: () => {
+          w.onMount?.();
+        },
+        onUnmount: () => {
+          w.onUnmount?.();
+        },
+        onBeforeLayout: async () => await ne() === !1 ? !1 : w.onBeforeLayout?.() ?? !0,
+        onLayout: () => {
+          w.onLayout?.(), oe();
+        },
+        onLayoutComplete: () => {
+          w.onLayoutComplete?.(), re();
+        },
+        onItemMount: (n, u) => {
+          w.onItemMount?.(n, u), h("onItemMount", n, u);
+        },
+        onItemUnmount: (n) => {
+          w.onItemUnmount?.(n), h("onItemUnmount", n);
+        },
+        onItemEnterViewport: (n, u) => {
+          w.onItemEnterViewport?.(n, u), h("onItemEnterViewport", n, u);
+        },
+        onItemLeaveViewport: (n, u) => {
+          w.onItemLeaveViewport?.(n, u), h("onItemLeaveViewport", n, u);
+        },
+        onScroll: (n, u) => {
+          w.onScroll?.(n, u), h("onScroll", n, u), E();
+        },
+        onResize: (n, u) => {
+          w.onResize?.(n, u), h("onResize", n, u);
+        },
+        onReachBottom: async (n) => {
+          await w.onReachBottom?.(n), await h("onReachBottom", n);
+        },
+        onItemClick: (n, u, y) => {
+          w.onItemClick?.(n, u, y), h("onItemClick", n, u, y);
+        }
+      };
+      return /* @__PURE__ */ q(
+        i,
+        {
+          ref: (n) => {
+            a.current = n, typeof o == "function" ? o(n) : o && (o.current = n);
+          },
+          ...ae
+        }
+      );
+    }
+  );
+  return l.displayName = "WithPlugins(WaterfallCore)", l;
+}
+export {
+  Le as w
+};

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

@@ -0,0 +1,124 @@
+import { default as React } from 'react';
+import { ItemPosition, ItemVisibility, LayoutInfo, ViewportInfo } from './plugins/types';
+import { AlignmentMode, LayoutHooks } from './layout';
+import { VirtualizeOptions } from './virtualize';
+export interface WaterfallCoreProps<T = any> {
+    items: T[];
+    renderItem: (item: T, index: number) => React.ReactNode;
+    keyExtractor?: (item: T, index: number) => React.Key;
+    /** 列数，默认 3；插件可通过 `calculateColumns` 覆盖 */
+    columns?: number;
+    /** 行/列间距的简写，默认 16 */
+    gap?: number;
+    rowGap?: number;
+    columnGap?: number;
+    /**
+     * 列分配策略，默认 shortest
+     * - shortest：放进当前最矮的列
+     * - balanced：放进项数最少的列
+     * - sequential：按 index 轮转
+     */
+    alignmentMode?: AlignmentMode;
+    /** 容器内边距 */
+    padding?: number | {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    };
+    containerStyle?: React.CSSProperties;
+    containerClassName?: string;
+    itemStyle?: React.CSSProperties;
+    itemClassName?: string;
+    /** 用 transform 定位（默认 true）；需要读 offsetLeft / 打印时传 false */
+    useTransform?: boolean;
+    throttleDelay?: number;
+    debounceDelay?: number;
+    /**
+     * 距底部多少像素内触发 `onReachBottom`，默认 100。
+     * 无限滚动类插件靠它提前预加载（旧版写死 100，插件配多大都没用）。
+     */
+    reachBottomOffset?: number;
+    /**
+     * 虚拟化：只渲染视口附近的项。
+     * 千项以上、项高度可估（图片卡、商品卡）时开；与 `RecyclePlugin` 不要同开。
+     */
+    virtualize?: boolean | VirtualizeOptions;
+    /** FilterPlugin 读取；优先级高于工厂里的 predicate */
+    filterFn?: (item: T, index: number) => boolean;
+    /** SortPlugin 读取；优先级高于工厂里的 comparator */
+    sortComparator?: (a: T, b: T) => number;
+    /** SearchPlugin 读取 */
+    searchQuery?: string;
+    /** PaginationPlugin 读取，1 基 */
+    pageIndex?: number;
+    /** PaginationPlugin 读取 */
+    pageSize?: number;
+    /** InfiniteScrollPlugin 读取 */
+    onLoadMore?: () => void | Promise<void>;
+    /** 数据条件变化后是否回顶（各插件分别读自己那个键） */
+    scrollToTopOnFilterChange?: boolean;
+    scrollToTopOnSortChange?: boolean;
+    scrollToTopOnSearchChange?: boolean;
+    scrollToTopOnPageChange?: boolean;
+    /** 回顶行为，默认 auto */
+    scrollToTopBehavior?: "auto" | "smooth";
+    /** D1-A 布局钩子（HOC 从插件装配结果里汇总） */
+    layoutHooks?: LayoutHooks;
+    onMount?: () => void;
+    onUnmount?: () => void;
+    onBeforeLayout?: () => boolean | void | Promise<boolean | void>;
+    onLayout?: () => void;
+    onLayoutComplete?: () => void;
+    onItemMount?: (index: number, element: HTMLElement) => void;
+    onItemUnmount?: (index: number) => void;
+    onItemEnterViewport?: (index: number, visibility: ItemVisibility) => void;
+    onItemLeaveViewport?: (index: number, visibility: ItemVisibility) => void;
+    onScroll?: (scrollTop: number, scrollLeft: number) => void;
+    onResize?: (width: number, height: number) => void;
+    onReachBottom?: (distance: number) => void;
+    onItemClick?: (index: number, item: T, event: React.MouseEvent) => void;
+    /** 插件覆盖层等（由 composeSlots 组装，渲染在滚动容器内部） */
+    children?: React.ReactNode;
+    /** HOC 注入：插件拿容器 DOM 用 */
+    containerRefExternal?: React.RefObject<HTMLDivElement | null>;
+    /** HOC 注入：插件拿项 DOM 用 */
+    itemRefsExternal?: React.MutableRefObject<Map<number, HTMLElement>>;
+    debug?: boolean;
+}
+export interface WaterfallCoreRef {
+    relayout: () => void;
+    scrollToItem: (index: number, options?: ScrollToItemOptions) => void;
+    scrollToTop: (options?: ScrollToOptions) => void;
+    scrollToBottom: (options?: ScrollToOptions) => void;
+    getItemPosition: (index: number) => ItemPosition | null;
+    getAllItemPositions: () => Map<number, ItemPosition>;
+    getColumnHeights: () => number[];
+    getLayoutInfo: () => LayoutInfo;
+    getViewportInfo: () => ViewportInfo;
+    /** 当前渲染出来的索引区间（虚拟化关闭时是 0..n-1） */
+    getVisibleRange: () => {
+        start: number;
+        end: number;
+    };
+    forceUpdate: () => void;
+    getContainer: () => HTMLDivElement | null;
+    getItemElement: (index: number) => HTMLElement | null;
+    measureItem: (index: number) => Promise<{
+        width: number;
+        height: number;
+    }>;
+}
+export interface ScrollToItemOptions {
+    behavior?: "auto" | "smooth";
+    block?: "start" | "center" | "end" | "nearest";
+    inline?: "start" | "center" | "end" | "nearest";
+    offset?: number;
+}
+export interface ScrollToOptions {
+    behavior?: "auto" | "smooth";
+    offset?: number;
+}
+declare const WaterfallCore: React.ForwardRefExoticComponent<WaterfallCoreProps<any> & React.RefAttributes<WaterfallCoreRef>>;
+export default WaterfallCore;
+//# sourceMappingURL=WaterfallCore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WaterfallCore.d.ts","sourceRoot":"","sources":["../../../src/components/WaterfallPlugin/WaterfallCore.tsx"],"names":[],"mappings":"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"}