vane-waterfall 2.0.1 → 2.0.3

package/dist/chunks/{doc-C5xrHNoC.js → doc-DhICh9S2.js}

@@ -1,25 +1,36 @@
-function y(s = {}) {
-  const n = s.duration ?? 300, t = s.easing ?? "ease";
+function P(s = {}) {
+  const t = s.duration ?? 300, n = s.easing ?? "ease";
   return {
     name: "TransitionPlugin",
     priority: 65,
     enabled: !0,
     hooks: {
-      onItemMount: (o, e, i) => {
-        i.style.transition = `transform ${n}ms ${t}, opacity ${n}ms ${t}`;
+      onItemMount: (o, e, a) => {
+        a.style.transition = `transform ${t}ms ${n}, opacity ${t}ms ${n}`;
       },
       onLayout: (o) => {
         o.itemRefs.forEach((e) => {
-          e && (e.style.transition = `transform ${n}ms ${t}, opacity ${n}ms ${t}`);
+          e && (e.style.transition = `transform ${t}ms ${n}, opacity ${t}ms ${n}`);
         });
       }
     }
   };
 }
-const a = "TransitionPlugin", r = "给每个项挂上 transform + opacity 的 CSS 过渡，布局重排、分页切换、筛选后重新排列时位置变化是滑过去的，不是瞬移。", c = "2.0.0", u = [
+const i = "TransitionPlugin", r = "给每个项挂上 transform + opacity 的 CSS 过渡，布局重排、分页切换、筛选后重新排列时位置变化是滑过去的，不是瞬移。", c = "2.0.0", m = [
   "perf",
   "动效"
-], m = [
+], d = [
+  {
+    name: "onItemMount",
+    when: "单个卡片挂载并拿到 DOM 元素时",
+    description: "按卡片绑定监听、观察器、埋点"
+  },
+  {
+    name: "onLayout",
+    when: "布局计算完成、结果已确定",
+    description: "读取每列高度、做二次修正或上报"
+  }
+], u = [], l = "只读取 context 字段（props / state / data），不调用上下文方法", f = [
   {
     name: "duration",
     type: "number",
@@ -32,7 +43,7 @@ const a = "TransitionPlugin", r = "给每个项挂上 transform + opacity 的 CS
     default: "ease",
     description: "缓动函数"
   }
-], d = `// 布局变化时给项加 transform/opacity 过渡，插入新数据不「闪现」。
+], p = `// 布局变化时给项加 transform/opacity 过渡，插入新数据不「闪现」。
 const Waterfall = withPlugins(WaterfallCore, [
   createTransitionPlugin({
     duration: 300,
@@ -40,31 +51,34 @@ const Waterfall = withPlugins(WaterfallCore, [
   }),
 ]);
 
-<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, l = [
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, g = [
   "ReducedMotionPlugin"
-], f = [
+], y = [
   "项位置变化平滑过渡",
   "挂载时即生效（onItemMount）",
   "与 ReducedMotionPlugin 互斥"
-], g = [
+], h = [
   "筛选 / 排序后重排",
   "分页切换",
   "动态插入卡片"
-], p = [
+], $ = [
   "首屏大量项同时过渡会有一次「整体滑入」，想要更克制可以把 duration 降到 150ms。"
-], $ = {
-  name: a,
+], x = {
+  name: i,
   description: r,
   since: c,
-  tags: u,
-  config: m,
-  example: d,
-  conflicts: l,
-  features: f,
-  useCases: g,
-  notes: p
+  tags: m,
+  events: d,
+  methods: u,
+  methodsNote: l,
+  config: f,
+  example: p,
+  conflicts: g,
+  features: y,
+  useCases: h,
+  notes: $
 };
 export {
-  y as c,
-  $ as d
+  P as c,
+  x as d
 };

package/dist/chunks/doc-DlJICsyN.js

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

package/dist/chunks/{doc-BtzhgTYj.js → doc-DtxS1-P0.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 d } from "react/jsx-runtime";
+function H(t = {}) {
+  const o = t.title || "分组标题", i = t.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: (e) => {
+        const n = e.sharedData?.get("GROUPS") || /* @__PURE__ */ new Map(), a = e.sharedData?.get("GROUP_INDEX"), r = e.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,
+              o,
               " ",
-              n !== void 0 ? `：${String(n)}` : "",
-              i ? /* @__PURE__ */ r("span", { style: { marginLeft: 8, fontSize: 12, opacity: 0.8 }, children: "向下滚动观察吸顶" }) : null
+              s !== void 0 ? `：${String(s)}` : "",
+              i ? /* @__PURE__ */ d("span", { style: { marginLeft: 8, fontSize: 12, opacity: 0.8 }, children: "向下滚动观察吸顶" }) : null
             ]
           }
         );
@@ -34,10 +34,16 @@ function h(t = {}) {
     }
   };
 }
-const c = "StickyHeaderPlugin", l = "在滚动容器内渲染一条 `position: sticky` 的标题条，始终贴住容器顶部。装了 GroupingPlugin 时自动显示第一个分组名，也可用 title 写死。", d = "2.0.0", p = [
+const l = "StickyHeaderPlugin", p = "在滚动容器内渲染一条 `position: sticky` 的标题条，始终贴住容器顶部。装了 GroupingPlugin 时自动显示第一个分组名，也可用 title 写死。", g = "2.0.0", m = [
   "ui",
   "吸顶"
 ], f = [
+  {
+    name: "renderOverlay",
+    when: "每次渲染，滚动容器内的内容层之上",
+    description: "回到顶部、加载提示、浮层工具"
+  }
+], u = [], y = "只读取 context 字段（props / state / data），不调用上下文方法", h = [
   {
     name: "title",
     type: "string",
@@ -50,7 +56,7 @@ const c = "StickyHeaderPlugin", l = "在滚动容器内渲染一条 `position: s
     default: "false",
     description: "是否显示「向下滚动观察」提示"
   }
-], u = `// 滚动容器内的吸顶标题条，可与分组联动显示当前组。
+], x = `// 滚动容器内的吸顶标题条，可与分组联动显示当前组。
 const Waterfall = withPlugins(WaterfallCore, [
   createStickyHeaderPlugin({
     title: "分组标题",
@@ -58,28 +64,31 @@ const Waterfall = withPlugins(WaterfallCore, [
   }),
 ]);
 
-<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, g = [
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, k = [
   "sticky 吸顶，不依赖额外容器",
   "与 Grouping 联动显示当前组",
   "提示文案默认关闭"
-], m = [
+], v = [
   "分组信息流",
   "按日期分组的时间线",
   "长列表的上下文提示"
-], y = [
+], S = [
   "sticky 生效要求它作为滚动容器的直接子元素——由 composeSlots 保证，单测已锁。"
-], k = {
-  name: c,
-  description: l,
-  since: d,
-  tags: p,
-  config: f,
-  example: u,
-  features: g,
-  useCases: m,
-  notes: y
+], P = {
+  name: l,
+  description: p,
+  since: g,
+  tags: m,
+  events: f,
+  methods: u,
+  methodsNote: y,
+  config: h,
+  example: x,
+  features: k,
+  useCases: v,
+  notes: S
 };
 export {
-  h as c,
-  k as d
+  H as c,
+  P as d
 };

package/dist/chunks/{doc-BIzjYAZW.js → doc-DudYCn_-.js}

@@ -1,50 +1,59 @@
-function d(e) {
+function f(e) {
   return {
     name: "DebounceLayoutPlugin",
     priority: 75,
     enabled: !0,
     hooks: {
-      transformProps: (n) => ({ ...n, debounceDelay: e.delay })
+      transformProps: (t) => ({ ...t, debounceDelay: e.delay })
     }
   };
 }
-const t = "DebounceLayoutPlugin", o = "只调 debounceDelay：容器宽度连续变化（抽屉展开、分栏拖拽）时，等变化停下来再算一次布局，避免每帧重排。", s = "2.0.0", a = [
+const n = "DebounceLayoutPlugin", o = "只调 debounceDelay：容器宽度连续变化（抽屉展开、分栏拖拽）时，等变化停下来再算一次布局，避免每帧重排。", s = "2.0.0", a = [
   "perf",
   "性能"
 ], c = [
+  {
+    name: "transformProps",
+    when: "渲染前链式改写瀑布流 props",
+    description: "补 gap / columns 默认值、按断点覆盖配置"
+  }
+], r = [], u = "只读取 context 字段（props / state / data），不调用上下文方法", i = [
   {
     name: "delay",
     type: "number",
     default: "—",
     description: "布局防抖 ms（必填）"
   }
-], r = `// 单独放大布局防抖，容器频繁变宽时（抽屉/侧栏动画）不抖。
+], l = `// 单独放大布局防抖，容器频繁变宽时（抽屉/侧栏动画）不抖。
 const Waterfall = withPlugins(WaterfallCore, [
   createDebounceLayoutPlugin(),
 ]);
 
-<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, u = [
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, m = [
   "只影响布局时机，不影响渲染",
   "可被 ThrottlePlugin 覆盖",
   "对移动端软键盘弹出也有效"
-], i = [
+], d = [
   "可折叠侧栏",
   "分栏宽度拖拽",
   "横竖屏切换"
-], l = [
+], p = [
   "delay 过大会让「展开后布局」明显滞后，建议 120–250ms。"
-], m = {
-  name: t,
+], g = {
+  name: n,
   description: o,
   since: s,
   tags: a,
-  config: c,
-  example: r,
-  features: u,
-  useCases: i,
-  notes: l
+  events: c,
+  methods: r,
+  methodsNote: u,
+  config: i,
+  example: l,
+  features: m,
+  useCases: d,
+  notes: p
 };
 export {
-  d as c,
-  m as d
+  f as c,
+  g as d
 };

package/dist/chunks/doc-HoyAFR_m.js

@@ -0,0 +1,101 @@
+function x(t = {}) {
+  const s = Math.max(1, t.threshold ?? 300), n = /* @__PURE__ */ new WeakMap(), a = (e) => e.containerRef?.current ?? e.bus;
+  return {
+    name: "InfiniteScrollPlugin",
+    priority: 35,
+    enabled: !0,
+    hooks: {
+      transformProps: (e) => ({
+        ...e,
+        reachBottomOffset: s
+      }),
+      onReachBottom: async (e, i) => {
+        const o = a(e);
+        if (n.get(o) || e.hasMore === !1 || i > s) return;
+        const r = t.onLoadMore ?? e.props.onLoadMore;
+        if (typeof r == "function") {
+          n.set(o, !0);
+          try {
+            await Promise.resolve(r());
+          } finally {
+            n.delete(o);
+          }
+        }
+      },
+      onUnmount: (e) => {
+        n.delete(a(e));
+      }
+    }
+  };
+}
+const c = "InfiniteScrollPlugin", l = "监听 Core 的 onReachBottom，在距底部 `threshold` 像素内触发 onLoadMore。自带并发锁：上一次还没结束不会重复触发。", d = "2.0.0", m = [
+  "data",
+  "加载更多"
+], f = [
+  {
+    name: "onUnmount",
+    when: "瀑布流卸载前",
+    description: "断开观察器、移除滚动监听"
+  },
+  {
+    name: "onReachBottom",
+    when: "滚动触底（distance 为距底像素）",
+    description: "加载更多、预取下一页"
+  },
+  {
+    name: "transformProps",
+    when: "渲染前链式改写瀑布流 props",
+    description: "补 gap / columns 默认值、按断点覆盖配置"
+  }
+], p = [], u = "只读取 context 字段（props / state / data），不调用上下文方法", h = [
+  {
+    name: "threshold",
+    type: "number",
+    default: "300",
+    description: "触发距离 px"
+  },
+  {
+    name: "onLoadMore",
+    type: "() => void | Promise<void>",
+    default: "props.onLoadMore",
+    description: "加载回调"
+  }
+], g = `// 滚动到距底部阈值内触发加载更多，带并发锁防重复请求。
+const Waterfall = withPlugins(WaterfallCore, [
+  createInfiniteScrollPlugin({
+    threshold: 300,
+  }),
+]);
+
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, P = [
+  "PaginationPlugin"
+], y = [
+  "距底 300px 预加载，滚到底时数据已就位",
+  "并发锁：加载中不重复触发",
+  "context.hasMore 为 false 时自动停"
+], M = [
+  "信息流无限滚动",
+  "画廊继续加载",
+  "搜索结果瀑布流"
+], w = [
+  "阈值不要小于一屏（约 600px），否则用户滚到底会看到空白等待。",
+  "翻页类场景请用 PaginationPlugin，两者不要同装。"
+], I = {
+  name: c,
+  description: l,
+  since: d,
+  tags: m,
+  events: f,
+  methods: p,
+  methodsNote: u,
+  config: h,
+  example: g,
+  conflicts: P,
+  features: y,
+  useCases: M,
+  notes: w
+};
+export {
+  x as c,
+  I as d
+};

package/dist/chunks/doc-RlBMCMNs.js

@@ -0,0 +1,170 @@
+function O(c = {}) {
+  const l = c.storageKey || "waterfall-state", p = c.persistScroll ?? !0, o = c.persistKeys || ["pageIndex", "pageSize", "searchQuery"];
+  let u = !1;
+  const d = 1, i = /* @__PURE__ */ new WeakSet(), h = (t) => t.containerRef?.current ?? t.bus;
+  function a() {
+    try {
+      const t = localStorage.getItem(l);
+      if (!t) return null;
+      const e = JSON.parse(t);
+      return !e || e.version !== d || typeof e.state != "object" ? null : e.state;
+    } catch {
+      return null;
+    }
+  }
+  function f(t) {
+    try {
+      localStorage.setItem(l, JSON.stringify({ version: d, state: t }));
+    } catch {
+    }
+  }
+  return {
+    name: "StatePersistencePlugin",
+    enabled: !0,
+    hooks: {
+      // 首次渲染时，尽量将本地快照中的分页/查询键注入到 props，便于核心按恢复后的状态渲染
+      transformProps: (t) => {
+        if (u) return t;
+        const e = a();
+        if (!e) return t;
+        const s = { ...t };
+        let n = !1;
+        return o.forEach((r) => {
+          e[r] !== void 0 && (s[r] = e[r], n = !0);
+        }), n && (u = !0), s;
+      },
+      onMount: (t) => {
+        const e = a();
+        if (!e) return;
+        const s = {};
+        if (o.forEach((n) => {
+          e[n] !== void 0 && (s[n] = e[n]);
+        }), Object.keys(s).length > 0 && (t.bus?.emit("state:restored", s), typeof window < "u"))
+          try {
+            window.dispatchEvent(new CustomEvent("waterfall:state-restored", { detail: s }));
+          } catch {
+          }
+      },
+      onLayoutComplete: (t) => {
+        if (!p) return;
+        const e = h(t);
+        if (i.has(e)) return;
+        const s = a(), n = Number(s?.scrollTop ?? 0);
+        if (!Number.isFinite(n) || n <= 0) {
+          i.add(e);
+          return;
+        }
+        const r = t.containerRef.current;
+        r && (r.scrollTo({ top: n, behavior: "auto" }), i.add(e));
+      },
+      // props 变化时，增量更新快照（立即持久化分页/查询键）
+      onPropsChange: (t, e, s) => {
+        const r = { ...a() || {} }, y = s ?? {};
+        o.forEach((m) => {
+          const g = y[m];
+          g !== void 0 && (r[m] = g);
+        }), f(r);
+      },
+      onUnmount: (t) => {
+        const e = {};
+        p && (e.scrollTop = t.containerRef.current?.scrollTop || 0);
+        const s = t.props ?? {};
+        o.forEach((n) => {
+          const r = s[n];
+          r !== void 0 && (e[n] = r);
+        }), f(e);
+      }
+    }
+  };
+}
+const S = "StatePersistencePlugin", w = "三个时机各做一件事：首次渲染把快照里的 pageIndex / searchQuery 注入 props；挂载后恢复 scrollTop；props 变化与卸载时写回快照。刷新页面不丢进度。", v = "2.0.0", P = [
+  "ui",
+  "持久化"
+], b = [
+  {
+    name: "onMount",
+    when: "瀑布流挂载完成",
+    description: "初始化观察器与滚动监听，返回清理函数"
+  },
+  {
+    name: "onUnmount",
+    when: "瀑布流卸载前",
+    description: "断开观察器、移除滚动监听"
+  },
+  {
+    name: "onPropsChange",
+    when: "props 变化后",
+    description: "数据或配置变化时请求重排"
+  },
+  {
+    name: "onLayoutComplete",
+    when: "DOM 落位完成（可安全测量）",
+    description: "测量真实高度、懒加载判定、曝光上报"
+  },
+  {
+    name: "transformProps",
+    when: "渲染前链式改写瀑布流 props",
+    description: "补 gap / columns 默认值、按断点覆盖配置"
+  },
+  {
+    name: "state:restored",
+    when: "从持久化恢复滚动位置 / 顺序后",
+    description: "广播恢复后的状态快照"
+  }
+], C = [], I = "只读取 context 字段（props / state / data），不调用上下文方法", E = [
+  {
+    name: "storageKey",
+    type: "string",
+    default: '"waterfall-state"',
+    description: "localStorage 键名"
+  },
+  {
+    name: "persistScroll",
+    type: "boolean",
+    default: "true",
+    description: "是否持久化滚动位置"
+  },
+  {
+    name: "persistKeys",
+    type: "string[]",
+    default: '["pageIndex","pageSize","searchQuery"]',
+    description: "要持久化的 props 键"
+  }
+], K = `// 把滚动位置与分页/查询状态存 localStorage，回来时恢复。
+const Waterfall = withPlugins(WaterfallCore, [
+  createStatePersistencePlugin({
+    storageKey: "waterfall-state",
+    persistScroll: true,
+    persistKeys: ["pageIndex","pageSize","searchQuery"],
+  }),
+]);
+
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, x = [
+  "滚动位置 + 分页/查询一起存",
+  "首帧注入只做一次，不会覆盖用户操作",
+  "SSR / 隐私模式下降级为不持久化"
+], N = [
+  "后台列表刷新不丢页",
+  "搜索结果返回定位",
+  "移动端来回切换页面"
+], R = [
+  "只能恢复「值」，不能替你把它写回 React state——页面应订阅 `state:restored` 事件或读 bus。",
+  "localStorage 不可用（隐私模式/配额满）时静默跳过，不会抛错。"
+], T = {
+  name: S,
+  description: w,
+  since: v,
+  tags: P,
+  events: b,
+  methods: C,
+  methodsNote: I,
+  config: E,
+  example: K,
+  features: x,
+  useCases: N,
+  notes: R
+};
+export {
+  O as c,
+  T as d
+};