vane-waterfall 2.0.2 → 2.0.3

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
+};

package/dist/chunks/doc-RwKQqySd.js

@@ -0,0 +1,102 @@
+function b(n = {}) {
+  const l = n.fields ?? [];
+  return {
+    name: "SearchPlugin",
+    priority: 20,
+    enabled: !0,
+    hooks: {
+      transformProps: (e) => {
+        const t = String(e.searchQuery ?? "").trim(), o = Array.isArray(e.items) ? e.items : [];
+        if (!t) return e;
+        const r = t.toLowerCase(), a = o.filter((s) => {
+          if (typeof s != "object" || s === null) return !1;
+          const i = l.length > 0 ? l : Object.keys(s);
+          for (const c of i) {
+            const u = s[c];
+            if (u != null && String(u).toLowerCase().includes(r)) return !0;
+          }
+          return !1;
+        });
+        return { ...e, items: a };
+      },
+      onPropsChange: (e, t, o) => {
+        const r = String(t?.searchQuery ?? ""), a = String(o?.searchQuery ?? "");
+        if (((typeof o?.scrollToTopOnSearchChange == "boolean" ? o.scrollToTopOnSearchChange : void 0) ?? !!n.scrollToTop) && r !== a) {
+          const c = o?.scrollToTopBehavior ?? n.scrollBehavior ?? "auto";
+          e.scrollToTop?.({ behavior: c });
+        }
+      }
+    }
+  };
+}
+const d = "SearchPlugin", h = "读取 `props.searchQuery`，在指定字段上做大小写不敏感的 `includes` 匹配。没指定字段就对对象的全部自有字段匹配。", f = "2.0.0", p = [
+  "data",
+  "数据管线",
+  "搜索"
+], m = [
+  {
+    name: "onPropsChange",
+    when: "props 变化后",
+    description: "数据或配置变化时请求重排"
+  },
+  {
+    name: "transformProps",
+    when: "渲染前链式改写瀑布流 props",
+    description: "补 gap / columns 默认值、按断点覆盖配置"
+  }
+], y = [], g = "只读取 context 字段（props / state / data），不调用上下文方法", T = [
+  {
+    name: "fields",
+    type: "(keyof T)[]",
+    default: "[]",
+    description: "参与匹配的字段；空则匹配全部自有字段"
+  },
+  {
+    name: "scrollToTop",
+    type: "boolean",
+    default: "false",
+    description: "关键词变化后回顶"
+  },
+  {
+    name: "scrollBehavior",
+    type: '"auto" | "smooth"',
+    default: '"auto"',
+    description: "回顶行为"
+  }
+], S = `// 按 props.searchQuery 做大小写不敏感的多字段包含匹配。
+const Waterfall = withPlugins(WaterfallCore, [
+  createSearchPlugin({
+    fields: [],
+    scrollToTop: false,
+    scrollBehavior: "auto",
+  }),
+]);
+
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, v = [
+  "大小写不敏感",
+  "多字段 OR 匹配",
+  "空关键词直接放行（不触发过滤）"
+], C = [
+  "站内搜索结果页",
+  "后台列表即时搜索",
+  "商品名 / 店铺名联合搜索"
+], P = [
+  "纯前端 `includes`，不排序也不做拼音；要相关性排序请在 Search 之后接 SortPlugin。"
+], Q = {
+  name: d,
+  description: h,
+  since: f,
+  tags: p,
+  events: m,
+  methods: y,
+  methodsNote: g,
+  config: T,
+  example: S,
+  features: v,
+  useCases: C,
+  notes: P
+};
+export {
+  b as c,
+  Q as d
+};

package/dist/chunks/{doc-CTUoMe7o.js → doc-eYhNJy97.js}

@@ -1,4 +1,4 @@
-function b(n) {
+function w(n) {
   if (!(n.minColumnWidth > 0))
     throw new Error("[vane-waterfall] AutoColumnPlugin 需要正数的 minColumnWidth");
   return {
@@ -6,14 +6,14 @@ function b(n) {
     priority: 55,
     enabled: !0,
     hooks: {
-      calculateColumns: (s, i) => {
-        const t = s.props, e = t.columnGap ?? t.gap ?? 0, o = t.padding, l = typeof o == "number" ? o * 2 : (o?.left ?? 0) + (o?.right ?? 0), a = Math.max(0, i - l);
-        if (!a) return t.columns ?? 1;
-        const m = Math.max(
+      calculateColumns: (a, m) => {
+        const t = a.props, e = t.columnGap ?? t.gap ?? 0, o = t.padding, i = typeof o == "number" ? o * 2 : (o?.left ?? 0) + (o?.right ?? 0), s = Math.max(0, m - i);
+        if (!s) return t.columns ?? 1;
+        const l = Math.max(
           1,
-          Math.floor((a + e) / (n.minColumnWidth + e))
+          Math.floor((s + e) / (n.minColumnWidth + e))
         ), u = Math.max(1, n.minColumns ?? 1), c = n.maxColumns ?? Number.POSITIVE_INFINITY;
-        return Math.min(Math.max(m, u), c);
+        return Math.min(Math.max(l, u), c);
       }
     }
   };
@@ -22,7 +22,13 @@ const r = "AutoColumnPlugin", d = "按「容器可用宽度 ÷ 最小列宽」
   "layout",
   "layout-hook",
   "响应式"
-], f = [
+], h = [
+  {
+    name: "calculateColumns",
+    when: "每次布局前，询问列数",
+    description: "返回列数则覆盖 props.columns；返回 undefined 沿用配置"
+  }
+], f = [], g = "只读取 context 字段（props / state / data），不调用上下文方法", x = [
   {
     name: "minColumnWidth",
     type: "number",
@@ -41,7 +47,7 @@ const r = "AutoColumnPlugin", d = "按「容器可用宽度 ÷ 最小列宽」
     default: "1",
     description: "列数下限"
   }
-], h = `// 按容器宽与最小列宽自动算列数，窄屏自动降列。
+], P = `// 按容器宽与最小列宽自动算列数，窄屏自动降列。
 const Waterfall = withPlugins(WaterfallCore, [
   createAutoColumnPlugin({
     maxColumns: "Infinity",
@@ -49,31 +55,34 @@ const Waterfall = withPlugins(WaterfallCore, [
   }),
 ]);
 
-<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, g = [
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, y = [
   "ResponsiveColumnsPlugin"
-], x = [
+], b = [
   "按容器宽度（不是视口宽度）算列数",
   "列数上下限可夹",
   "与 Gap / Padding 一起算，留白不吞列宽"
-], P = [
+], I = [
   "响应式信息流",
   "侧边栏宽度可拖动的后台看板",
   "移动端 → 桌面端同一套代码"
-], y = [
+], W = [
   "与 ResponsiveColumnsPlugin 同时装会互相覆盖列数，只选一个。"
-], I = {
+], v = {
   name: r,
   description: d,
   since: p,
   tags: C,
-  config: f,
-  example: h,
-  conflicts: g,
-  features: x,
-  useCases: P,
-  notes: y
+  events: h,
+  methods: f,
+  methodsNote: g,
+  config: x,
+  example: P,
+  conflicts: y,
+  features: b,
+  useCases: I,
+  notes: W
 };
 export {
-  b as c,
-  I as d
+  w as c,
+  v as d
 };

package/dist/chunks/{doc-CcPFavOs.js → doc-i6FY1We1.js}

@@ -1,12 +1,12 @@
-function d(n) {
+function x(n) {
   return {
     name: "FixedHeightPlugin",
     priority: 45,
     enabled: !0,
     hooks: {
       transformProps: (t) => {
-        const { itemHeight: i } = n, s = (t.items || []).map((e) => typeof e == "object" && e !== null && "height" in e ? { ...e, height: i } : e);
-        return { ...t, items: s };
+        const { itemHeight: s } = n, o = (t.items || []).map((e) => typeof e == "object" && e !== null && "height" in e ? { ...e, height: s } : e);
+        return { ...t, items: o };
       },
       onResize: (t) => {
         t.relayout?.();
@@ -14,10 +14,21 @@ function d(n) {
     }
   };
 }
-const o = "FixedHeightPlugin", a = "把数据里带 height 字段的项统一改写为固定高度，瀑布流变成等高网格。适合「图少字多」的卡片流——等高反而更好扫读。", r = "2.0.0", c = [
+const i = "FixedHeightPlugin", a = "把数据里带 height 字段的项统一改写为固定高度，瀑布流变成等高网格。适合「图少字多」的卡片流——等高反而更好扫读。", r = "2.0.0", c = [
   "layout",
   "网格"
-], g = [
+], h = [
+  {
+    name: "onResize",
+    when: "容器宽度变化触发重排前",
+    description: "按新宽度调整列数或卡片密度"
+  },
+  {
+    name: "transformProps",
+    when: "渲染前链式改写瀑布流 props",
+    description: "补 gap / columns 默认值、按断点覆盖配置"
+  }
+], m = [], d = "只读取 context 字段（props / state / data），不调用上下文方法", g = [
   {
     name: "itemHeight",
     type: "number",
@@ -33,24 +44,27 @@ const Waterfall = withPlugins(WaterfallCore, [
   "等高网格（严格对齐）",
   "只改数据里已有的 height 字段",
   "与 Pagination / Filter 组合仍然成立"
-], h = [
+], p = [
   "商品列表（图固定比例）",
   "后台看板卡片",
   "需要严格栅格对齐的页面"
-], m = [
+], f = [
   "数据里没有 height 字段时不会生效——高度由 renderItem 自己的内容决定。"
-], f = {
-  name: o,
+], P = {
+  name: i,
   description: a,
   since: r,
   tags: c,
+  events: h,
+  methods: m,
+  methodsNote: d,
   config: g,
   example: l,
   features: u,
-  useCases: h,
-  notes: m
+  useCases: p,
+  notes: f
 };
 export {
-  d as c,
-  f as d
+  x as c,
+  P as d
 };

package/dist/chunks/doc-skPl6ZMP.js

@@ -0,0 +1,101 @@
+function y(s) {
+  const n = /* @__PURE__ */ new Set(), o = (i) => {
+    if (n.size <= s.poolSize) return;
+    const e = n.values().next().value;
+    if (typeof e == "number") {
+      n.delete(e);
+      const t = i.getItemRef(e);
+      t && (t.style.visibility = "hidden");
+    }
+  };
+  return {
+    name: "RecyclePlugin",
+    enabled: !0,
+    hooks: {
+      onItemEnterViewport: (i, e) => {
+        const t = i.getItemRef(e);
+        t && (t.style.visibility = "visible"), n.add(e), o(i);
+      },
+      onItemLeaveViewport: (i, e) => {
+        const t = i.getItemRef(e);
+        t && (t.style.visibility = "hidden"), n.delete(e);
+      },
+      onItemUnmount: (i, e) => {
+        n.delete(e);
+      },
+      onUnmount: () => {
+        n.clear();
+      }
+    }
+  };
+}
+const c = "RecyclePlugin", l = "纯绘制层优化：项离开视口就 `visibility: hidden`，回来再显示。DOM 节点不销毁，滚动位置与已加载的图片都保留，适合「项里有视频/Canvas，重建代价高」的场景。", a = "2.0.0", r = [
+  "interaction",
+  "性能"
+], m = [
+  {
+    name: "onUnmount",
+    when: "瀑布流卸载前",
+    description: "断开观察器、移除滚动监听"
+  },
+  {
+    name: "onItemUnmount",
+    when: "单个卡片卸载时",
+    description: "解绑该卡片的监听与观察器"
+  },
+  {
+    name: "onItemEnterViewport",
+    when: "单个卡片进入视口",
+    description: "卡片级曝光、视频自动播放等"
+  },
+  {
+    name: "onItemLeaveViewport",
+    when: "单个卡片离开视口",
+    description: "暂停播放、回收资源"
+  }
+], d = [
+  {
+    name: "getItemRef",
+    signature: "ctx.getItemRef(index: number): HTMLElement | null",
+    description: "取第 index 张卡片的 DOM 引用，可能为 null（尚未挂载 / 已回收）"
+  }
+], u = [
+  {
+    name: "poolSize",
+    type: "number",
+    default: "—",
+    description: "同时保持可见的项数上限（超出则回收最早的）"
+  }
+], f = `// 视口外的项设 \`visibility: hidden\`，降低长列表的绘制压力。
+const Waterfall = withPlugins(WaterfallCore, [
+  createRecyclePlugin(),
+]);
+
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, p = [
+  "不销毁 DOM，只隐藏",
+  "项内媒体不重新加载",
+  "与虚拟化正交（一个省绘制、一个省节点）"
+], v = [
+  "项内含视频 / canvas",
+  "长列表滚动发虚",
+  "低端设备省电"
+], g = [
+  "与 Core 的 `virtualize` 同开会让项被卸载又隐藏，收益互相抵消，建议只选一个。",
+  "只改 visibility 不改布局，所以不会引起重排。"
+], b = {
+  name: c,
+  description: l,
+  since: a,
+  tags: r,
+  events: m,
+  methods: d,
+  config: u,
+  example: f,
+  features: p,
+  useCases: v,
+  notes: g
+};
+export {
+  y as c,
+  b as d
+};

package/dist/chunks/index-8gEIzUxi.js

@@ -0,0 +1,15 @@
+import { c as a, d as e } from "./doc-C206ZwYC.js";
+import { c as t, d as s } from "./doc-i6FY1We1.js";
+import { c, d as i } from "./doc-D7m1OFCW.js";
+import { c as n, d as o } from "./doc-CInpKZNU.js";
+import { c as r, d as g } from "./doc-DlJICsyN.js";
+import { c as l, d as m } from "./doc-DEN2WTDh.js";
+const f = Object.assign(a, { meta: e }), j = Object.assign(t, { meta: s }), O = Object.assign(c, { meta: i }), C = Object.assign(n, { meta: o }), F = Object.assign(r, { meta: g }), x = Object.assign(l, { meta: m });
+export {
+  O as a,
+  j as b,
+  x as c,
+  F as d,
+  f as e,
+  C as f
+};

package/dist/chunks/index-B96I5CKE.js

@@ -0,0 +1,21 @@
+import { c as a, d as e } from "./doc-CYxwSuG6.js";
+import { c, d as t } from "./doc-Bud0hbaz.js";
+import { c as s, d as r } from "./doc-RwKQqySd.js";
+import { c as n, d as i } from "./doc-CE1DGMBV.js";
+import { c as o, d as g } from "./doc-CiCso5Ti.js";
+import { c as m, d as l } from "./doc-CHbQXLwY.js";
+import { c as d, d as u } from "./doc-BU0CKW63.js";
+import { c as P, d as $ } from "./doc-DtxS1-P0.js";
+import { c as p, d as b } from "./doc-BAhVW3g8.js";
+const k = Object.assign(a, { meta: e }), D = Object.assign(c, { meta: t }), G = Object.assign(s, { meta: r }), I = Object.assign(n, { meta: i }), L = Object.assign(o, { meta: g }), U = Object.assign(m, { meta: l }), x = Object.assign(d, { meta: u }), q = Object.assign(P, { meta: $ }), v = Object.assign(p, { meta: b });
+export {
+  L as a,
+  x as b,
+  k as c,
+  I as d,
+  D as e,
+  U as f,
+  G as g,
+  q as h,
+  v as i
+};

package/dist/chunks/index-Bjmhy8jW.js

@@ -0,0 +1,11 @@
+import { c as a, d as e } from "./doc-eYhNJy97.js";
+import { c as t, d as c } from "./doc-C2L8kkeI.js";
+import { c as o, d as n } from "./doc-C-B3zK2o.js";
+import { c as s, d as i } from "./doc-HoyAFR_m.js";
+const d = Object.assign(a, { meta: e }), g = Object.assign(t, { meta: c }), P = Object.assign(o, { meta: n }), p = Object.assign(s, { meta: i });
+export {
+  g as a,
+  p as b,
+  d as c,
+  P as d
+};

package/dist/chunks/index-Cuq0ofv-.js

@@ -0,0 +1,13 @@
+import { c as e, d as t } from "./doc-CaJ02INP.js";
+import { c as a, d as c } from "./doc-DudYCn_-.js";
+import { c as s, d as o } from "./doc-skPl6ZMP.js";
+import { c as r, d as n } from "./doc-BrEd0oZB.js";
+import { c as i, d as m } from "./doc-RlBMCMNs.js";
+const $ = Object.assign(e, { meta: t }), b = Object.assign(a, { meta: c }), p = Object.assign(s, { meta: o }), f = Object.assign(r, { meta: n }), j = Object.assign(i, { meta: m });
+export {
+  b as a,
+  p as b,
+  f as c,
+  j as d,
+  $ as e
+};

package/dist/chunks/{index-BAWlVYr3.js → index-Cz4YEqRF.js}

@@ -1,4 +1,4 @@
-import { c as a, d as t } from "./doc-C5xrHNoC.js";
+import { c as a, d as t } from "./doc-DhICh9S2.js";
 const n = Object.assign(a, { meta: t });
 export {
   n as c

package/dist/chunks/{index-CF0tYRop.js → index-FBJVUYmH.js}

@@ -1,4 +1,4 @@
-import { c as a, d as c } from "./doc-BCmEnh39.js";
+import { c as a, d as c } from "./doc-CkuMr8Ca.js";
 const t = Object.assign(a, { meta: c });
 export {
   t as c