vane-waterfall 2.0.1 → 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-BU0CKW63.js

@@ -0,0 +1,156 @@
+import { jsxs as p } from "react/jsx-runtime";
+const d = "GROUPS", y = "GROUP_INDEX";
+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 o = n.get(t);
+      if (!o || o.length !== s.length) return !1;
+    }
+    return !0;
+  }, i = (e) => {
+    const n = e.items ?? [];
+    if (r && l === n) return r;
+    const t = /* @__PURE__ */ new Map(), s = /* @__PURE__ */ new Map();
+    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 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",
+    enabled: !0,
+    hooks: {
+      onMount: (e) => {
+        i(e);
+      },
+      onLayoutComplete: (e) => {
+        i(e);
+      },
+      onPropsChange: (e) => {
+        i(e);
+      },
+      renderOverlay: (e) => {
+        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__ */ p(
+          "div",
+          {
+            style: {
+              position: "absolute",
+              top: 12,
+              left: 12,
+              zIndex: 99,
+              background: "#111827",
+              color: "#fff",
+              padding: "10px 12px",
+              borderRadius: 8,
+              boxShadow: "0 4px 12px rgba(0,0,0,0.25)",
+              border: "1px solid rgba(255,255,255,0.15)",
+              minWidth: 150,
+              fontSize: 12,
+              pointerEvents: "none"
+            },
+            children: [
+              /* @__PURE__ */ p("div", { style: { opacity: 0.85, marginBottom: 6 }, children: [
+                "分组：",
+                n.size,
+                " 组"
+              ] }),
+              t.map(([s, o]) => /* @__PURE__ */ p("div", { children: [
+                String(s),
+                " · ",
+                o.length,
+                " 项"
+              ] }, String(s)))
+            ]
+          }
+        );
+      }
+    }
+  };
+}
+const w = "GroupingPlugin", v = "用 groupBy 把项按业务字段分组，结果放进 sharedData 的 `GROUPS`（Map<组键, 索引数组>），供 StickyHeaderPlugin、分组统计条等消费。挂载即算一次，之后 props 变化重算。", P = "2.0.0", O = [
+  "ui",
+  "分组"
+], 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",
+    default: 'item.category ?? "default"',
+    description: "分组函数"
+  },
+  {
+    name: "showOverlay",
+    type: "boolean",
+    default: "false",
+    description: "是否显示分组统计角标"
+  }
+], C = `// 按字段把项分组，结果写进 sharedData(GROUPS) 供吸顶条 / 统计用。
+const Waterfall = withPlugins(WaterfallCore, [
+  createGroupingPlugin({
+    groupBy: "item.category ?? \\"default\\"",
+    showOverlay: false,
+  }),
+]);
+
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, M = [
+  "挂载即计算（旧版只在 props 变化时算，首屏永远拿不到分组）",
+  "结果写 sharedData，跨插件可读",
+  "统计角标默认关闭"
+], S = [
+  "按分类分组的信息流",
+  "按日期分组的时间线",
+  "吸顶条显示当前分组"
+], z = [
+  "分组只产出索引映射，不改变渲染顺序；要视觉分组请自己按分组建行。"
+], 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 {
+  E as c,
+  I as d
+};

package/dist/chunks/doc-BrEd0oZB.js

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

package/dist/chunks/{doc-DukOmDCo.js → doc-C-B3zK2o.js}

@@ -1,9 +1,9 @@
 const l = "(prefers-reduced-motion: reduce)";
-function R(c = {}) {
+function C(c = {}) {
   const i = typeof window < "u" && typeof window.matchMedia == "function" ? window.matchMedia(l) : null;
   let s = i?.matches ?? !1;
-  const m = c.disableTransform ?? !0, u = c.removeTransitions ?? !0, o = /* @__PURE__ */ new Map(), t = /* @__PURE__ */ new Map(), a = (e) => {
-    if (!(!e || !u))
+  const m = c.disableTransform ?? !0, d = c.removeTransitions ?? !0, o = /* @__PURE__ */ new Map(), t = /* @__PURE__ */ new Map(), a = (e) => {
+    if (!(!e || !d))
       if (s) {
         const n = e.style.transitionDuration;
         n && n !== "0s" ? t.set(e, n) : t.has(e) || t.set(e, n), e.style.setProperty("transition-duration", "0s");
@@ -12,10 +12,10 @@ function R(c = {}) {
         if (n === void 0) return;
         n ? e.style.setProperty("transition-duration", n) : e.style.removeProperty("transition-duration"), t.delete(e);
       }
-  }, f = () => o.forEach((e) => a(e)), d = (e) => {
+  }, f = () => o.forEach((e) => a(e)), u = (e) => {
     e.matches !== s && (s = e.matches, f());
   };
-  return i?.addEventListener?.("change", d), {
+  return i?.addEventListener?.("change", u), {
     name: "ReducedMotionPlugin",
     priority: 70,
     enabled: !0,
@@ -23,7 +23,7 @@ function R(c = {}) {
       transformProps: (e) => {
         if (!s) return e;
         const n = { ...e };
-        return m && (n.useTransform = !1), u && (n.itemStyle = { ...e.itemStyle ?? {}, transitionDuration: "0s" }), n;
+        return m && (n.useTransform = !1), d && (n.itemStyle = { ...e.itemStyle ?? {}, transitionDuration: "0s" }), n;
       },
       onItemMount: (e, n, r) => {
         o.set(n, r), a(r);
@@ -37,15 +37,41 @@ function R(c = {}) {
         });
       },
       onUnmount: () => {
-        i?.removeEventListener?.("change", d), o.clear(), t.clear();
+        i?.removeEventListener?.("change", u), o.clear(), t.clear();
       }
     }
   };
 }
-const p = "ReducedMotionPlugin", y = "检测 `prefers-reduced-motion: reduce`，命中后把 useTransform 关掉并清掉项上的 transition。前庭功能敏感用户不会因为滚动时的位置微动而不适。", g = "2.0.0", h = [
+const p = "ReducedMotionPlugin", h = "检测 `prefers-reduced-motion: reduce`，命中后把 useTransform 关掉并清掉项上的 transition。前庭功能敏感用户不会因为滚动时的位置微动而不适。", y = "2.0.0", g = [
   "perf",
   "a11y"
-], T = [
+], w = [
+  {
+    name: "onUnmount",
+    when: "瀑布流卸载前",
+    description: "断开观察器、移除滚动监听"
+  },
+  {
+    name: "onItemMount",
+    when: "单个卡片挂载并拿到 DOM 元素时",
+    description: "按卡片绑定监听、观察器、埋点"
+  },
+  {
+    name: "onItemUnmount",
+    when: "单个卡片卸载时",
+    description: "解绑该卡片的监听与观察器"
+  },
+  {
+    name: "onLayoutComplete",
+    when: "DOM 落位完成（可安全测量）",
+    description: "测量真实高度、懒加载判定、曝光上报"
+  },
+  {
+    name: "transformProps",
+    when: "渲染前链式改写瀑布流 props",
+    description: "补 gap / columns 默认值、按断点覆盖配置"
+  }
+], M = [], P = "只读取 context 字段（props / state / data），不调用上下文方法", T = [
   {
     name: "disableTransform",
     type: "boolean",
@@ -58,7 +84,7 @@ const p = "ReducedMotionPlugin", y = "检测 `prefers-reduced-motion: reduce`，
     default: "true",
     description: "命中偏好时清掉项过渡"
   }
-], P = `// 尊重系统「减少动画」偏好：关掉 transform 定位与项过渡。
+], v = `// 尊重系统「减少动画」偏好：关掉 transform 定位与项过渡。
 const Waterfall = withPlugins(WaterfallCore, [
   createReducedMotionPlugin({
     disableTransform: true,
@@ -66,30 +92,33 @@ const Waterfall = withPlugins(WaterfallCore, [
   }),
 ]);
 
-<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, M = [
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, R = [
   "系统偏好驱动，零配置生效",
   "两项能力可分别关闭",
   "与 TransitionPlugin 同装时优先生效"
-], v = [
+], b = [
   "政务 / 医疗类站点",
   "无障碍合规要求",
   "低性能设备"
-], w = [
+], x = [
   "偏好由 matchMedia 驱动，并监听 change：运行中改系统设置即时生效（定位方式要等下一次重渲染才切过来）。",
   "只压 `transition-duration`，不写 `transition: none` —— 写简写会把 TransitionPlugin 的过渡整条覆盖，撤销偏好后无从还原。",
   "与 TransitionPlugin 同装不是冲突：ReducedMotion 优先级更高，会先执行并压住过渡。"
-], b = {
+], D = {
   name: p,
-  description: y,
-  since: g,
-  tags: h,
+  description: h,
+  since: y,
+  tags: g,
+  events: w,
+  methods: M,
+  methodsNote: P,
   config: T,
-  example: P,
-  features: M,
-  useCases: v,
-  notes: w
+  example: v,
+  features: R,
+  useCases: b,
+  notes: x
 };
 export {
-  R as c,
-  b as d
+  C as c,
+  D as d
 };