vane-waterfall 2.0.2 → 2.0.3

package/dist/chunks/doc-BAhVW3g8.js

@@ -0,0 +1,150 @@
+function E(p = {}) {
+  const u = p.mode || "hash", o = p.keys || ["pageIndex", "pageSize", "searchQuery"];
+  let h = null, d = !1;
+  const l = () => (h === null && (h = f()), h);
+  function f() {
+    try {
+      if (u === "hash") {
+        const s = window.location.hash || "", a = s.indexOf("?"), t = a >= 0 ? s.slice(a + 1) : s.replace(/^#/, ""), e = new URLSearchParams(t), n = {};
+        return o.forEach((c) => {
+          const r = e.get(c);
+          r !== null && (n[c] = r);
+        }), n;
+      } else {
+        const s = new URLSearchParams(window.location.search), a = {};
+        return o.forEach((t) => {
+          const e = s.get(t);
+          e !== null && (a[t] = e);
+        }), a;
+      }
+    } catch {
+      return {};
+    }
+  }
+  function w(s) {
+    try {
+      const a = new URLSearchParams();
+      o.forEach((e) => {
+        const n = s[e];
+        n != null && String(n).length > 0 && a.set(e, String(n));
+      });
+      const t = a.toString();
+      if (u === "hash") {
+        const e = window.location.hash || "", r = `#${e.replace(/^#/, "").split("?")[0] || ""}${t ? `?${t}` : ""}`;
+        e !== r && history.replaceState(
+          null,
+          "",
+          `${window.location.pathname}${window.location.search}${r}`
+        );
+      } else {
+        const n = window.location.pathname + (t ? `?${t}` : "") + (window.location.hash || "");
+        history.replaceState(null, "", n);
+      }
+    } catch {
+    }
+  }
+  return {
+    name: "URLSyncPlugin",
+    enabled: !0,
+    hooks: {
+      // 首次渲染就把 URL 里的值注入 props：旧实现只广播 `urlsync:init`，
+      // 页面不手动订阅时深链参数根本不会生效（「只写不读」，P2-6）
+      transformProps: (s) => {
+        if (d) return s;
+        const a = l(), t = { ...s };
+        let e = !1;
+        return o.forEach((n) => {
+          a[n] !== void 0 && (t[n] = a[n], e = !0);
+        }), e && (d = !0), t;
+      },
+      onMount: (s) => {
+        s.bus?.emit("urlsync:init", l());
+      },
+      onPropsChange: (s, a, t) => {
+        const e = {}, n = t ?? {};
+        o.forEach((i) => {
+          const m = n[i];
+          m !== void 0 && (e[i] = m);
+        });
+        const c = l();
+        o.some(
+          (i) => String(e[i] ?? "") !== String(c[i] ?? "")
+        ) && w(e);
+      }
+    }
+  };
+}
+const g = "URLSyncPlugin", S = "props 变化时把指定键写进 URL（hash 或 search），挂载时读出来广播 `urlsync:init`。刷新与分享都能还原筛选状态。", y = "2.0.0", P = [
+  "ui",
+  "URL",
+  "可分享"
+], R = [
+  {
+    name: "onMount",
+    when: "瀑布流挂载完成",
+    description: "初始化观察器与滚动监听，返回清理函数"
+  },
+  {
+    name: "onPropsChange",
+    when: "props 变化后",
+    description: "数据或配置变化时请求重排"
+  },
+  {
+    name: "transformProps",
+    when: "渲染前链式改写瀑布流 props",
+    description: "补 gap / columns 默认值、按断点覆盖配置"
+  },
+  {
+    name: "urlsync:init",
+    when: "从 URL 参数初始化完成后",
+    description: "广播初始参数快照"
+  }
+], L = [], U = "只读取 context 字段（props / state / data），不调用上下文方法", x = [
+  {
+    name: "mode",
+    type: '"hash" | "search"',
+    default: '"hash"',
+    description: "写 hash 还是 search"
+  },
+  {
+    name: "keys",
+    type: "string[]",
+    default: '["pageIndex","pageSize","searchQuery"]',
+    description: "要同步的 props 键"
+  }
+], v = `// 把分页/搜索/排序同步进 URL（hash 或 search），链接可分享。
+const Waterfall = withPlugins(WaterfallCore, [
+  createURLSyncPlugin({
+    mode: "hash",
+    keys: ["pageIndex","pageSize","searchQuery"],
+  }),
+]);
+
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, $ = [
+  "hash 模式会保留已有路由路径",
+  "用 replaceState，不污染后退栈",
+  "SSR 安全：无 window 时直接跳过"
+], C = [
+  "搜索结果可分享",
+  "后台筛选状态可刷新",
+  "带参数的深链"
+], I = [
+  "只做单向同步（props → URL）与初始读取；URL 前进后退的监听请页面自己做。"
+], b = {
+  name: g,
+  description: S,
+  since: y,
+  tags: P,
+  events: R,
+  methods: L,
+  methodsNote: U,
+  config: x,
+  example: v,
+  features: $,
+  useCases: C,
+  notes: I
+};
+export {
+  E as c,
+  b as d
+};

package/dist/chunks/{doc-BXaJl1By.js → doc-BU0CKW63.js}

@@ -1,25 +1,25 @@
-import { jsxs as u } from "react/jsx-runtime";
+import { jsxs as p } from "react/jsx-runtime";
 const d = "GROUPS", y = "GROUP_INDEX";
-function B(c = {}) {
-  const g = c.groupBy ?? ((e) => e?.category ?? "default"), f = c.showOverlay ?? !1;
-  let p = null, o = null;
+function E(u = {}) {
+  const g = u.groupBy ?? ((e) => e?.category ?? "default"), h = u.showOverlay ?? !1;
+  let l = null, r = null;
   const m = (e, n) => {
     if (e.size !== n.size) return !1;
     for (const [t, s] of e) {
-      const r = n.get(t);
-      if (!r || r.length !== s.length) return !1;
+      const o = n.get(t);
+      if (!o || o.length !== s.length) return !1;
     }
     return !0;
   }, i = (e) => {
     const n = e.items ?? [];
-    if (o && p === n) return o;
+    if (r && l === n) return r;
     const t = /* @__PURE__ */ new Map(), s = /* @__PURE__ */ new Map();
-    n.forEach((h, l) => {
-      const a = g(h, l);
-      s.set(l, a), t.has(a) || t.set(a, []), t.get(a).push(l);
+    n.forEach((f, c) => {
+      const a = g(f, c);
+      s.set(c, a), t.has(a) || t.set(a, []), t.get(a).push(c);
     });
-    const r = o ? !m(t, o) : !0;
-    return p = n, o = t, e.sharedData.set(d, t), e.sharedData.set(y, s), r && t.size > 0 && e.bus.emit("grouping:change", { groups: t }), t;
+    const o = r ? !m(t, r) : !0;
+    return l = n, r = t, e.sharedData.set(d, t), e.sharedData.set(y, s), o && t.size > 0 && e.bus.emit("grouping:change", { groups: t }), t;
   };
   return {
     name: "GroupingPlugin",
@@ -35,11 +35,11 @@ function B(c = {}) {
         i(e);
       },
       renderOverlay: (e) => {
-        if (!f) return null;
+        if (!h) return null;
         const n = e.sharedData.get(d) ?? /* @__PURE__ */ new Map();
         if (n.size === 0) return null;
         const t = Array.from(n.entries()).slice(0, 3);
-        return /* @__PURE__ */ u(
+        return /* @__PURE__ */ p(
           "div",
           {
             style: {
@@ -58,15 +58,15 @@ function B(c = {}) {
               pointerEvents: "none"
             },
             children: [
-              /* @__PURE__ */ u("div", { style: { opacity: 0.85, marginBottom: 6 }, children: [
+              /* @__PURE__ */ p("div", { style: { opacity: 0.85, marginBottom: 6 }, children: [
                 "分组：",
                 n.size,
                 " 组"
               ] }),
-              t.map(([s, r]) => /* @__PURE__ */ u("div", { children: [
+              t.map(([s, o]) => /* @__PURE__ */ p("div", { children: [
                 String(s),
                 " · ",
-                r.length,
+                o.length,
                 " 项"
               ] }, String(s)))
             ]
@@ -76,10 +76,36 @@ function B(c = {}) {
     }
   };
 }
-const P = "GroupingPlugin", b = "用 groupBy 把项按业务字段分组，结果放进 sharedData 的 `GROUPS`（Map<组键, 索引数组>），供 StickyHeaderPlugin、分组统计条等消费。挂载即算一次，之后 props 变化重算。", G = "2.0.0", v = [
+const w = "GroupingPlugin", v = "用 groupBy 把项按业务字段分组，结果放进 sharedData 的 `GROUPS`（Map<组键, 索引数组>），供 StickyHeaderPlugin、分组统计条等消费。挂载即算一次，之后 props 变化重算。", P = "2.0.0", O = [
   "ui",
   "分组"
-], w = [
+], b = [
+  {
+    name: "onMount",
+    when: "瀑布流挂载完成",
+    description: "初始化观察器与滚动监听，返回清理函数"
+  },
+  {
+    name: "onPropsChange",
+    when: "props 变化后",
+    description: "数据或配置变化时请求重排"
+  },
+  {
+    name: "onLayoutComplete",
+    when: "DOM 落位完成（可安全测量）",
+    description: "测量真实高度、懒加载判定、曝光上报"
+  },
+  {
+    name: "renderOverlay",
+    when: "每次渲染，滚动容器内的内容层之上",
+    description: "回到顶部、加载提示、浮层工具"
+  },
+  {
+    name: "grouping:change",
+    when: "分组结果变化时",
+    description: "广播 { groups } 分组结构"
+  }
+], G = [], x = "只读取 context 字段（props / state / data），不调用上下文方法", D = [
   {
     name: "groupBy",
     type: "(item, index) => string | number",
@@ -92,7 +118,7 @@ const P = "GroupingPlugin", b = "用 groupBy 把项按业务字段分组，结
     default: "false",
     description: "是否显示分组统计角标"
   }
-], O = `// 按字段把项分组，结果写进 sharedData(GROUPS) 供吸顶条 / 统计用。
+], C = `// 按字段把项分组，结果写进 sharedData(GROUPS) 供吸顶条 / 统计用。
 const Waterfall = withPlugins(WaterfallCore, [
   createGroupingPlugin({
     groupBy: "item.category ?? \\"default\\"",
@@ -100,28 +126,31 @@ const Waterfall = withPlugins(WaterfallCore, [
   }),
 ]);
 
-<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, x = [
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, M = [
   "挂载即计算（旧版只在 props 变化时算，首屏永远拿不到分组）",
   "结果写 sharedData，跨插件可读",
   "统计角标默认关闭"
-], D = [
+], S = [
   "按分类分组的信息流",
   "按日期分组的时间线",
   "吸顶条显示当前分组"
-], S = [
+], z = [
   "分组只产出索引映射，不改变渲染顺序；要视觉分组请自己按分组建行。"
-], C = {
-  name: P,
-  description: b,
-  since: G,
-  tags: v,
-  config: w,
-  example: O,
-  features: x,
-  useCases: D,
-  notes: S
+], I = {
+  name: w,
+  description: v,
+  since: P,
+  tags: O,
+  events: b,
+  methods: G,
+  methodsNote: x,
+  config: D,
+  example: C,
+  features: M,
+  useCases: S,
+  notes: z
 };
 export {
-  B as c,
-  C as d
+  E as c,
+  I as d
 };

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

@@ -1,34 +1,34 @@
-function B(s = {}) {
-  const c = s.storageKey || "waterfall-bookmark", l = s.scrollBehavior || "smooth", u = (r) => {
-    const o = r;
+function x(s = {}) {
+  const c = s.storageKey || "waterfall-bookmark", l = s.scrollBehavior || "smooth", m = (a) => {
+    const o = a;
     if (!o) return !1;
-    const n = o.tagName?.toLowerCase(), a = (o.getAttribute && o.getAttribute("contenteditable")) === "true";
-    return n === "input" || n === "textarea" || a;
+    const n = o.tagName?.toLowerCase(), r = (o.getAttribute && o.getAttribute("contenteditable")) === "true";
+    return n === "input" || n === "textarea" || r;
   };
   return {
     name: "BookmarkPlugin",
     enabled: !0,
     hooks: {
-      onMount: (r) => {
+      onMount: (a) => {
         const o = (n) => {
-          if (u(n.target)) return;
-          const a = (n.key || "").toLowerCase(), i = n.code || "";
-          if (a === "b" || i === "KeyB") {
-            const e = r.containerRef?.current || null;
+          if (m(n.target)) return;
+          const r = (n.key || "").toLowerCase(), i = n.code || "";
+          if (r === "b" || i === "KeyB") {
+            const e = a.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, t)));
             } catch {
             }
-          } else if (a === "r" || i === "KeyR") {
+          } else if (r === "r" || i === "KeyR") {
             let e = 0;
             try {
-              const m = localStorage.getItem(c) || "0";
-              e = Math.max(0, Number(m) || 0);
+              const u = localStorage.getItem(c) || "0";
+              e = Math.max(0, Number(u) || 0);
             } catch {
             }
-            const t = r.containerRef?.current || null;
+            const t = a.containerRef?.current || null;
             t && t.scrollHeight > t.clientHeight ? t.scrollTo({ top: e, behavior: l }) : window.scrollTo({ top: e, behavior: l });
           }
         };
@@ -39,11 +39,17 @@ function B(s = {}) {
     }
   };
 }
-const g = "BookmarkPlugin", d = "长列表读到一半要跳走时按 **B** 存位置，回来按 **R** 复原。焦点在输入框/可编辑区域时不拦截按键。", f = "2.0.0", h = [
+const d = "BookmarkPlugin", g = "长列表读到一半要跳走时按 **B** 存位置，回来按 **R** 复原。焦点在输入框/可编辑区域时不拦截按键。", h = "2.0.0", f = [
   "ui",
   "滚动",
   "快捷键"
-], k = [
+], p = [
+  {
+    name: "onMount",
+    when: "瀑布流挂载完成",
+    description: "初始化观察器与滚动监听，返回清理函数"
+  }
+], k = [], w = "只读取 context 字段（props / state / data），不调用上下文方法", y = [
   {
     name: "storageKey",
     type: "string",
@@ -56,7 +62,7 @@ const g = "BookmarkPlugin", d = "长列表读到一半要跳走时按 **B** 存
     default: '"smooth"',
     description: "恢复时的滚动行为"
   }
-], p = `// 按 B 记录滚动位置、按 R 跳回（localStorage），忽略输入框按键。
+], b = `// 按 B 记录滚动位置、按 R 跳回（localStorage），忽略输入框按键。
 const Waterfall = withPlugins(WaterfallCore, [
   createBookmarkPlugin({
     storageKey: "waterfall-bookmark",
@@ -64,28 +70,31 @@ const Waterfall = withPlugins(WaterfallCore, [
   }),
 ]);
 
-<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, w = [
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, B = [
   "B 存 / R 取，零 UI 侵入",
   "自动区分容器滚动与页面滚动",
   "输入框内不误触"
-], y = [
+], v = [
   "长文列表阅读",
   "后台大表格浏览",
   "演示时快速复位"
-], b = [
+], K = [
   "键名全局共用，一个页面里多处瀑布流请各自传不同的 storageKey。"
-], v = {
-  name: g,
-  description: d,
-  since: f,
-  tags: h,
-  config: k,
-  example: p,
-  features: w,
-  useCases: y,
-  notes: b
+], C = {
+  name: d,
+  description: g,
+  since: h,
+  tags: f,
+  events: p,
+  methods: k,
+  methodsNote: w,
+  config: y,
+  example: b,
+  features: B,
+  useCases: v,
+  notes: K
 };
 export {
-  B as c,
-  v as d
+  x as c,
+  C as d
 };

package/dist/chunks/{doc-bTHwfIVb.js → doc-Bud0hbaz.js}

@@ -1,20 +1,20 @@
-function w(s) {
-  const r = new Set(s.pinnedIndices), e = Math.max(0, s.column ?? 0), n = /* @__PURE__ */ new Map();
+function v(s) {
+  const r = new Set(s.pinnedIndices), n = Math.max(0, s.column ?? 0), e = /* @__PURE__ */ new Map();
   return {
     name: "PinItemPlugin",
     priority: 100,
     enabled: !0,
     hooks: {
-      onBeforeLayout: () => (n.clear(), !0),
-      calculateItemPosition: (i, u, c, t) => {
-        const l = i.props.rowGap ?? i.props.gap ?? 0;
-        if (!r.has(u)) {
-          const o = n.get(t.column);
+      onBeforeLayout: () => (e.clear(), !0),
+      calculateItemPosition: (i, l, c, t) => {
+        const m = i.props.rowGap ?? i.props.gap ?? 0;
+        if (!r.has(l)) {
+          const o = e.get(t.column);
           return o !== void 0 && t.y < o ? { y: o } : void 0;
         }
-        const a = n.get(e) ?? 0;
-        return n.set(e, a + c + l), {
-          column: e,
+        const a = e.get(n) ?? 0;
+        return e.set(n, a + c + m), {
+          column: n,
           y: a,
           width: t.width,
           height: c,
@@ -24,11 +24,22 @@ function w(s) {
     }
   };
 }
-const m = "PinItemPlugin", d = "把若干索引的项钉在顶部指定列，其余项从它们下方继续排。走 D1-A 布局钩子（calculateItemPosition），是旧版宣称但从未生效的能力。", p = "2.0.0", f = [
+const u = "PinItemPlugin", d = "把若干索引的项钉在顶部指定列，其余项从它们下方继续排。走 D1-A 布局钩子（calculateItemPosition），是旧版宣称但从未生效的能力。", p = "2.0.0", f = [
   "layout",
   "layout-hook",
   "置顶"
-], g = [
+], h = [
+  {
+    name: "onBeforeLayout",
+    when: "开始一次布局之前",
+    description: "返回 false 可阻止本次布局（如数据仍在加载）"
+  },
+  {
+    name: "calculateItemPosition",
+    when: "每个卡片参与布局时（拿到 index / item / columns）",
+    description: "返回坐标片段可覆盖列分配结果（置顶、跨列、错位）"
+  }
+], g = [], I = "只读取 context 字段（props / state / data），不调用上下文方法", P = [
   {
     name: "pinnedIndices",
     type: "number[]",
@@ -41,7 +52,7 @@ const m = "PinItemPlugin", d = "把若干索引的项钉在顶部指定列，其
     default: "0",
     description: "钉到第几列"
   }
-], I = `// 把指定索引的项钉在顶部同一列，不参与常规列高推进（广告位 / 公告卡）。
+], y = `// 把指定索引的项钉在顶部同一列，不参与常规列高推进（广告位 / 公告卡）。
 const Waterfall = withPlugins(WaterfallCore, [
   createPinItemPlugin({
     pinnedIndices: [],
@@ -49,30 +60,33 @@ const Waterfall = withPlugins(WaterfallCore, [
   }),
 ]);
 
-<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, P = [
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, w = [
   "置顶项不占常规列高：后续项从置顶块下方开始",
   "支持多列分别置顶（column 可不同）",
   "每次布局前重置偏移，items 变化后不会累加错位"
-], y = [
+], x = [
   "信息流首位的推广卡",
   "公告 / 置顶帖",
   "需要固定在左上角的活动位"
-], h = [
+], C = [
   "置顶项之间按 pinnedIndices 顺序纵向堆叠，同一列多条会依次往下排。",
   "置顶会挤掉该列的正常网格位置，pinnedIndices 建议控制在 1~2 条。",
   "换列后的 x 由布局引擎按本轮列宽补齐，插件只返回 column 即可 —— 自己用「列宽 + 间距」反推 x 会在间距由其它插件（GapPlugin）注入时算错。"
-], C = {
-  name: m,
+], B = {
+  name: u,
   description: d,
   since: p,
   tags: f,
-  config: g,
-  example: I,
-  features: P,
-  useCases: y,
-  notes: h
+  events: h,
+  methods: g,
+  methodsNote: I,
+  config: P,
+  example: y,
+  features: w,
+  useCases: x,
+  notes: C
 };
 export {
-  w as c,
-  C as d
+  v as c,
+  B as d
 };