vane-waterfall 2.0.0 → 2.0.2

package/dist/chunks/{doc-78xF08vt.js → doc-BmoijI6q.js}

@@ -1,37 +1,37 @@
-function g(n = {}) {
-  const t = Math.max(1, n.threshold ?? 300);
-  let e = !1;
+function y(t = {}) {
+  const s = Math.max(1, t.threshold ?? 300), n = /* @__PURE__ */ new WeakMap(), r = (e) => e.containerRef?.current ?? e.bus;
   return {
     name: "InfiniteScrollPlugin",
     priority: 35,
     enabled: !0,
     hooks: {
-      transformProps: (o) => ({
-        ...o,
-        reachBottomOffset: t
+      transformProps: (e) => ({
+        ...e,
+        reachBottomOffset: s
       }),
-      onReachBottom: async (o, a) => {
-        if (e || o.hasMore === !1 || a > t) return;
-        const s = n.onLoadMore ?? o.props.onLoadMore;
-        if (typeof s == "function") {
-          e = !0;
+      onReachBottom: async (e, i) => {
+        const o = r(e);
+        if (n.get(o) || e.hasMore === !1 || i > s) return;
+        const a = t.onLoadMore ?? e.props.onLoadMore;
+        if (typeof a == "function") {
+          n.set(o, !0);
           try {
-            await Promise.resolve(s());
+            await Promise.resolve(a());
           } finally {
-            e = !1;
+            n.delete(o);
           }
         }
       },
-      onUnmount: () => {
-        e = !1;
+      onUnmount: (e) => {
+        n.delete(r(e));
       }
     }
   };
 }
-const r = "InfiniteScrollPlugin", i = "监听 Core 的 onReachBottom，在距底部 `threshold` 像素内触发 onLoadMore。自带并发锁：上一次还没结束不会重复触发。", l = "2.0.0", c = [
+const c = "InfiniteScrollPlugin", l = "监听 Core 的 onReachBottom，在距底部 `threshold` 像素内触发 onLoadMore。自带并发锁：上一次还没结束不会重复触发。", d = "2.0.0", f = [
   "data",
   "加载更多"
-], f = [
+], u = [
   {
     name: "threshold",
     type: "number",
@@ -44,39 +44,39 @@ const r = "InfiniteScrollPlugin", i = "监听 Core 的 onReachBottom，在距底
     default: "props.onLoadMore",
     description: "加载回调"
   }
-], d = `// 滚动到距底部阈值内触发加载更多，带并发锁防重复请求。
+], m = `// 滚动到距底部阈值内触发加载更多，带并发锁防重复请求。
 const Waterfall = withPlugins(WaterfallCore, [
   createInfiniteScrollPlugin({
     threshold: 300,
   }),
 ]);
 
-<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, u = [
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, p = [
   "PaginationPlugin"
-], m = [
+], h = [
   "距底 300px 预加载，滚到底时数据已就位",
   "并发锁：加载中不重复触发",
   "context.hasMore 为 false 时自动停"
-], p = [
+], g = [
   "信息流无限滚动",
   "画廊继续加载",
   "搜索结果瀑布流"
-], h = [
+], P = [
   "阈值不要小于一屏（约 600px），否则用户滚到底会看到空白等待。",
   "翻页类场景请用 PaginationPlugin，两者不要同装。"
-], P = {
-  name: r,
-  description: i,
-  since: l,
-  tags: c,
-  config: f,
-  example: d,
-  conflicts: u,
-  features: m,
-  useCases: p,
-  notes: h
+], M = {
+  name: c,
+  description: l,
+  since: d,
+  tags: f,
+  config: u,
+  example: m,
+  conflicts: p,
+  features: h,
+  useCases: g,
+  notes: P
 };
 export {
-  g as c,
-  P as d
+  y as c,
+  M as d
 };

package/dist/chunks/{doc-BtzhgTYj.js → doc-CN4edvn_.js}

@@ -1,13 +1,13 @@
-import { jsxs as a, jsx as r } from "react/jsx-runtime";
-function h(t = {}) {
-  const s = t.title || "分组标题", i = t.showHint ?? !1;
+import { jsxs as c, jsx as l } from "react/jsx-runtime";
+function b(e = {}) {
+  const i = e.title || "分组标题", o = e.showHint ?? !1;
   return {
     name: "StickyHeaderPlugin",
     enabled: !0,
     hooks: {
-      renderOverlay: (o) => {
-        const e = o.sharedData?.get("GROUPS") || /* @__PURE__ */ new Map(), n = e.size > 0 ? Array.from(e.keys())[0] : void 0;
-        return /* @__PURE__ */ a(
+      renderOverlay: (t) => {
+        const n = t.sharedData?.get("GROUPS") || /* @__PURE__ */ new Map(), a = t.sharedData?.get("GROUP_INDEX"), r = t.visibleRange?.start ?? 0, s = a?.get(r) ?? (n.size > 0 ? Array.from(n.keys())[0] : void 0);
+        return /* @__PURE__ */ c(
           "div",
           {
             style: {
@@ -23,10 +23,10 @@ function h(t = {}) {
               fontWeight: 600
             },
             children: [
-              s,
+              i,
               " ",
-              n !== void 0 ? `：${String(n)}` : "",
-              i ? /* @__PURE__ */ r("span", { style: { marginLeft: 8, fontSize: 12, opacity: 0.8 }, children: "向下滚动观察吸顶" }) : null
+              s !== void 0 ? `：${String(s)}` : "",
+              o ? /* @__PURE__ */ l("span", { style: { marginLeft: 8, fontSize: 12, opacity: 0.8 }, children: "向下滚动观察吸顶" }) : null
             ]
           }
         );
@@ -34,10 +34,10 @@ function h(t = {}) {
     }
   };
 }
-const c = "StickyHeaderPlugin", l = "在滚动容器内渲染一条 `position: sticky` 的标题条，始终贴住容器顶部。装了 GroupingPlugin 时自动显示第一个分组名，也可用 title 写死。", d = "2.0.0", p = [
+const d = "StickyHeaderPlugin", p = "在滚动容器内渲染一条 `position: sticky` 的标题条，始终贴住容器顶部。装了 GroupingPlugin 时自动显示第一个分组名，也可用 title 写死。", g = "2.0.0", f = [
   "ui",
   "吸顶"
-], f = [
+], u = [
   {
     name: "title",
     type: "string",
@@ -50,7 +50,7 @@ const c = "StickyHeaderPlugin", l = "在滚动容器内渲染一条 `position: s
     default: "false",
     description: "是否显示「向下滚动观察」提示"
   }
-], u = `// 滚动容器内的吸顶标题条，可与分组联动显示当前组。
+], y = `// 滚动容器内的吸顶标题条，可与分组联动显示当前组。
 const Waterfall = withPlugins(WaterfallCore, [
   createStickyHeaderPlugin({
     title: "分组标题",
@@ -58,28 +58,28 @@ const Waterfall = withPlugins(WaterfallCore, [
   }),
 ]);
 
-<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, g = [
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, m = [
   "sticky 吸顶，不依赖额外容器",
   "与 Grouping 联动显示当前组",
   "提示文案默认关闭"
-], m = [
+], h = [
   "分组信息流",
   "按日期分组的时间线",
   "长列表的上下文提示"
-], y = [
+], k = [
   "sticky 生效要求它作为滚动容器的直接子元素——由 composeSlots 保证，单测已锁。"
-], k = {
-  name: c,
-  description: l,
-  since: d,
-  tags: p,
-  config: f,
-  example: u,
-  features: g,
-  useCases: m,
-  notes: y
+], H = {
+  name: d,
+  description: p,
+  since: g,
+  tags: f,
+  config: u,
+  example: y,
+  features: m,
+  useCases: h,
+  notes: k
 };
 export {
-  h as c,
-  k as d
+  b as c,
+  H as d
 };

package/dist/chunks/{doc-NhL4Ux8q.js → doc-CkU5GtLw.js}

@@ -1,17 +1,20 @@
-function K(o = {}) {
-  const i = o.storageKey || "waterfall-state", l = o.persistScroll ?? !0, a = o.persistKeys || ["pageIndex", "pageSize", "searchQuery"];
-  let u = !1;
-  function c() {
+function x(c = {}) {
+  const l = c.storageKey || "waterfall-state", u = c.persistScroll ?? !0, a = c.persistKeys || ["pageIndex", "pageSize", "searchQuery"];
+  let p = !1;
+  const f = 1, i = /* @__PURE__ */ new WeakSet(), S = (t) => t.containerRef?.current ?? t.bus;
+  function o() {
     try {
-      const e = localStorage.getItem(i);
-      return e ? JSON.parse(e) : null;
+      const t = localStorage.getItem(l);
+      if (!t) return null;
+      const e = JSON.parse(t);
+      return !e || e.version !== f || typeof e.state != "object" ? null : e.state;
     } catch {
       return null;
     }
   }
-  function p(e) {
+  function d(t) {
     try {
-      localStorage.setItem(i, JSON.stringify(e));
+      localStorage.setItem(l, JSON.stringify({ version: f, state: t }));
     } catch {
     }
   }
@@ -20,56 +23,64 @@ function K(o = {}) {
     enabled: !0,
     hooks: {
       // 首次渲染时，尽量将本地快照中的分页/查询键注入到 props，便于核心按恢复后的状态渲染
-      transformProps: (e) => {
-        if (u) return e;
-        const t = c();
-        if (!t) return e;
-        const n = { ...e };
+      transformProps: (t) => {
+        if (p) return t;
+        const e = o();
+        if (!e) return t;
+        const n = { ...t };
         let s = !1;
         return a.forEach((r) => {
-          t[r] !== void 0 && (n[r] = t[r], s = !0);
-        }), s && (u = !0), n;
+          e[r] !== void 0 && (n[r] = e[r], s = !0);
+        }), s && (p = !0), n;
       },
-      onMount: (e) => {
-        const t = c();
-        if (!t) return;
-        if (l) {
-          const s = Number(t.scrollTop ?? 0), r = e.containerRef.current;
-          r ? r.scrollTo({ top: s, behavior: "auto" }) : e.scrollToTop?.({ behavior: "auto" });
-        }
+      onMount: (t) => {
+        const e = o();
+        if (!e) return;
         const n = {};
         if (a.forEach((s) => {
-          t[s] !== void 0 && (n[s] = t[s]);
-        }), Object.keys(n).length > 0 && (e.bus?.emit("state:restored", n), typeof window < "u"))
+          e[s] !== void 0 && (n[s] = e[s]);
+        }), Object.keys(n).length > 0 && (t.bus?.emit("state:restored", n), typeof window < "u"))
           try {
             window.dispatchEvent(new CustomEvent("waterfall:state-restored", { detail: n }));
           } catch {
           }
       },
+      onLayoutComplete: (t) => {
+        if (!u) return;
+        const e = S(t);
+        if (i.has(e)) return;
+        const n = o(), s = Number(n?.scrollTop ?? 0);
+        if (!Number.isFinite(s) || s <= 0) {
+          i.add(e);
+          return;
+        }
+        const r = t.containerRef.current;
+        r && (r.scrollTo({ top: s, behavior: "auto" }), i.add(e));
+      },
       // props 变化时，增量更新快照（立即持久化分页/查询键）
-      onPropsChange: (e, t, n) => {
-        const r = { ...c() || {} }, g = n ?? {};
-        a.forEach((f) => {
-          const d = g[f];
-          d !== void 0 && (r[f] = d);
-        }), p(r);
+      onPropsChange: (t, e, n) => {
+        const r = { ...o() || {} }, m = n ?? {};
+        a.forEach((g) => {
+          const y = m[g];
+          y !== void 0 && (r[g] = y);
+        }), d(r);
       },
-      onUnmount: (e) => {
-        const t = {};
-        l && (t.scrollTop = e.containerRef.current?.scrollTop || 0);
-        const n = e.props ?? {};
+      onUnmount: (t) => {
+        const e = {};
+        u && (e.scrollTop = t.containerRef.current?.scrollTop || 0);
+        const n = t.props ?? {};
         a.forEach((s) => {
           const r = n[s];
-          r !== void 0 && (t[s] = r);
-        }), p(t);
+          r !== void 0 && (e[s] = r);
+        }), d(e);
       }
     }
   };
 }
-const y = "StatePersistencePlugin", m = "三个时机各做一件事：首次渲染把快照里的 pageIndex / searchQuery 注入 props；挂载后恢复 scrollTop；props 变化与卸载时写回快照。刷新页面不丢进度。", S = "2.0.0", h = [
+const h = "StatePersistencePlugin", w = "三个时机各做一件事：首次渲染把快照里的 pageIndex / searchQuery 注入 props；挂载后恢复 scrollTop；props 变化与卸载时写回快照。刷新页面不丢进度。", v = "2.0.0", P = [
   "ui",
   "持久化"
-], w = [
+], b = [
   {
     name: "storageKey",
     type: "string",
@@ -88,7 +99,7 @@ const y = "StatePersistencePlugin", m = "三个时机各做一件事：首次渲
     default: '["pageIndex","pageSize","searchQuery"]',
     description: "要持久化的 props 键"
   }
-], v = `// 把滚动位置与分页/查询状态存 localStorage，回来时恢复。
+], I = `// 把滚动位置与分页/查询状态存 localStorage，回来时恢复。
 const Waterfall = withPlugins(WaterfallCore, [
   createStatePersistencePlugin({
     storageKey: "waterfall-state",
@@ -97,29 +108,29 @@ const Waterfall = withPlugins(WaterfallCore, [
   }),
 ]);
 
-<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, P = [
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, C = [
   "滚动位置 + 分页/查询一起存",
   "首帧注入只做一次，不会覆盖用户操作",
   "SSR / 隐私模式下降级为不持久化"
-], b = [
+], E = [
   "后台列表刷新不丢页",
   "搜索结果返回定位",
   "移动端来回切换页面"
-], I = [
+], K = [
   "只能恢复「值」，不能替你把它写回 React state——页面应订阅 `state:restored` 事件或读 bus。",
   "localStorage 不可用（隐私模式/配额满）时静默跳过，不会抛错。"
-], T = {
-  name: y,
-  description: m,
-  since: S,
-  tags: h,
-  config: w,
-  example: v,
-  features: P,
-  useCases: b,
-  notes: I
+], R = {
+  name: h,
+  description: w,
+  since: v,
+  tags: P,
+  config: b,
+  example: I,
+  features: C,
+  useCases: E,
+  notes: K
 };
 export {
-  K as c,
-  T as d
+  x as c,
+  R as d
 };

package/dist/chunks/doc-DAieSXLy.js

@@ -0,0 +1,86 @@
+function T(r = {}) {
+  return {
+    name: "PaginationPlugin",
+    priority: 10,
+    enabled: !0,
+    hooks: {
+      transformProps: (n) => {
+        const a = Number(n.pageIndex ?? 1), e = Math.max(
+          1,
+          Math.floor(Number.isFinite(a) ? a : 1)
+        ), t = Number(n.pageSize ?? r.pageSize ?? 20), o = Math.max(1, Math.floor(Number.isFinite(t) ? t : 20)), l = Array.isArray(n.items) ? n.items : [], s = Math.max(1, Math.ceil(l.length / o)), i = Math.min(e, s);
+        e > s && console.warn(
+          `[vane-waterfall] PaginationPlugin：pageIndex=${e} 超出总页数 ${s}，已钳制到第 ${i} 页`
+        );
+        const c = (i - 1) * o, p = l.slice(c, c + o);
+        return { ...n, items: p };
+      },
+      onPropsChange: (n, a, e) => {
+        const t = Math.max(1, Number(a?.pageIndex ?? 1)), o = Math.max(1, Number(e?.pageIndex ?? 1));
+        if (((typeof e?.scrollToTopOnPageChange == "boolean" ? e.scrollToTopOnPageChange : void 0) ?? !!r.scrollToTop) && t !== o) {
+          const i = e?.scrollToTopBehavior ?? r.scrollBehavior ?? "auto";
+          n.scrollToTop?.({ behavior: i });
+        }
+      }
+    }
+  };
+}
+const g = "PaginationPlugin", m = "读 `props.pageIndex`（1 基）与 `props.pageSize` 切片。放在数据管线最末端，保证切的是「过滤 + 排序 + 搜索」之后的结果。", u = "2.0.0", d = [
+  "data",
+  "数据管线",
+  "分页"
+], h = [
+  {
+    name: "pageSize",
+    type: "number",
+    default: "props.pageSize ?? 20",
+    description: "每页条数"
+  },
+  {
+    name: "scrollToTop",
+    type: "boolean",
+    default: "false",
+    description: "翻页后回顶"
+  },
+  {
+    name: "scrollBehavior",
+    type: '"auto" | "smooth"',
+    default: '"auto"',
+    description: "回顶行为"
+  }
+], f = `// 按 props.pageIndex / pageSize 切片，页码从 1 开始。
+const Waterfall = withPlugins(WaterfallCore, [
+  createPaginationPlugin({
+    scrollToTop: false,
+    scrollBehavior: "auto",
+  }),
+]);
+
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, x = [
+  "InfiniteScrollPlugin"
+], P = [
+  "1 基页码（与 UI 分页器一致）",
+  "pageIndex 非法值自动夹到 1",
+  "翻页自动回顶可选"
+], S = [
+  "后台列表分页",
+  "搜索结果分页",
+  "与 URLSyncPlugin 配合做可分享链接"
+], I = [
+  "pageSize 优先级：props.pageSize > 工厂 config.pageSize > 20。"
+], b = {
+  name: g,
+  description: m,
+  since: u,
+  tags: d,
+  config: h,
+  example: f,
+  conflicts: x,
+  features: P,
+  useCases: S,
+  notes: I
+};
+export {
+  T as c,
+  b as d
+};

package/dist/chunks/{doc-BP0DmB7-.js → doc-D_ozEn0Q.js}

@@ -1,8 +1,8 @@
-function v(s = {}) {
+function B(s = {}) {
   const c = s.storageKey || "waterfall-bookmark", l = s.scrollBehavior || "smooth", u = (r) => {
-    const e = r;
-    if (!e) return !1;
-    const n = e.tagName?.toLowerCase(), a = (e.getAttribute && e.getAttribute("contenteditable")) === "true";
+    const o = r;
+    if (!o) return !1;
+    const n = o.tagName?.toLowerCase(), a = (o.getAttribute && o.getAttribute("contenteditable")) === "true";
     return n === "input" || n === "textarea" || a;
   };
   return {
@@ -10,40 +10,40 @@ function v(s = {}) {
     enabled: !0,
     hooks: {
       onMount: (r) => {
-        const e = (n) => {
+        const o = (n) => {
           if (u(n.target)) return;
           const a = (n.key || "").toLowerCase(), i = n.code || "";
           if (a === "b" || i === "KeyB") {
-            const t = r.containerRef?.current || null;
-            let o = 0;
-            t && t.scrollHeight > t.clientHeight ? o = t.scrollTop : o = window.pageYOffset || document.documentElement.scrollTop || document.body.scrollTop || 0;
+            const e = r.containerRef?.current || null;
+            let t = 0;
+            e && e.scrollHeight > e.clientHeight ? t = e.scrollTop : t = window.pageYOffset || document.documentElement.scrollTop || document.body.scrollTop || 0;
             try {
-              localStorage.setItem(c, String(Math.max(0, o)));
+              localStorage.setItem(c, String(Math.max(0, t)));
             } catch {
             }
           } else if (a === "r" || i === "KeyR") {
-            let t = 0;
+            let e = 0;
             try {
-              const d = localStorage.getItem(c) || "0";
-              t = Math.max(0, Number(d) || 0);
+              const m = localStorage.getItem(c) || "0";
+              e = Math.max(0, Number(m) || 0);
             } catch {
             }
-            const o = r.containerRef?.current || null;
-            o && o.scrollHeight > o.clientHeight ? o.scrollTo({ top: t, behavior: l }) : window.scrollTo({ top: t, behavior: l });
+            const t = r.containerRef?.current || null;
+            t && t.scrollHeight > t.clientHeight ? t.scrollTo({ top: e, behavior: l }) : window.scrollTo({ top: e, behavior: l });
           }
         };
-        return window.addEventListener("keydown", e, { capture: !0 }), document.addEventListener("keydown", e, { capture: !0 }), () => {
-          window.removeEventListener("keydown", e, { capture: !0 }), document.removeEventListener("keydown", e, { capture: !0 });
+        return window.addEventListener("keydown", o, { capture: !0 }), () => {
+          window.removeEventListener("keydown", o, { capture: !0 });
         };
       }
     }
   };
 }
-const m = "BookmarkPlugin", g = "长列表读到一半要跳走时按 **B** 存位置，回来按 **R** 复原。焦点在输入框/可编辑区域时不拦截按键。", f = "2.0.0", k = [
+const g = "BookmarkPlugin", d = "长列表读到一半要跳走时按 **B** 存位置，回来按 **R** 复原。焦点在输入框/可编辑区域时不拦截按键。", f = "2.0.0", h = [
   "ui",
   "滚动",
   "快捷键"
-], p = [
+], k = [
   {
     name: "storageKey",
     type: "string",
@@ -56,7 +56,7 @@ const m = "BookmarkPlugin", g = "长列表读到一半要跳走时按 **B** 存
     default: '"smooth"',
     description: "恢复时的滚动行为"
   }
-], h = `// 按 B 记录滚动位置、按 R 跳回（localStorage），忽略输入框按键。
+], p = `// 按 B 记录滚动位置、按 R 跳回（localStorage），忽略输入框按键。
 const Waterfall = withPlugins(WaterfallCore, [
   createBookmarkPlugin({
     storageKey: "waterfall-bookmark",
@@ -74,18 +74,18 @@ const Waterfall = withPlugins(WaterfallCore, [
   "演示时快速复位"
 ], b = [
   "键名全局共用，一个页面里多处瀑布流请各自传不同的 storageKey。"
-], B = {
-  name: m,
-  description: g,
+], v = {
+  name: g,
+  description: d,
   since: f,
-  tags: k,
-  config: p,
-  example: h,
+  tags: h,
+  config: k,
+  example: p,
   features: w,
   useCases: y,
   notes: b
 };
 export {
-  v as c,
-  B as d
+  B as c,
+  v as d
 };