vane-waterfall 1.0.5 → 2.0.0

package/dist/chunks/doc-78xF08vt.js

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

package/dist/chunks/doc-B-7dugGv.js

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

package/dist/chunks/doc-B6kLfMPv.js

@@ -0,0 +1,121 @@
+import { jsxs as r } from "react/jsx-runtime";
+function k(l = {}) {
+  const m = l.showOverlay ?? l.showOverlaySummary ?? !1, a = /* @__PURE__ */ new Map(), o = /* @__PURE__ */ new Map();
+  let i = !1;
+  const c = (t) => Array.from(t.values()).reduce((e, s) => e + s, 0);
+  return {
+    name: "HeatmapAnalyticsPlugin",
+    enabled: !0,
+    getStats: () => {
+      const t = /* @__PURE__ */ new Set([...a.keys(), ...o.keys()]);
+      return {
+        totalViews: c(a),
+        totalClicks: c(o),
+        items: Array.from(t).sort((e, s) => e - s).map((e) => ({
+          index: e,
+          views: a.get(e) ?? 0,
+          clicks: o.get(e) ?? 0
+        }))
+      };
+    },
+    hooks: {
+      onLayoutComplete: (t) => {
+        if (i) return;
+        const { start: e, end: s } = t.visibleRange;
+        for (let n = e; n <= s; n++)
+          a.set(n, (a.get(n) || 0) + 1);
+        i = !0;
+      },
+      onItemEnterViewport: (t, e) => {
+        a.set(e, (a.get(e) || 0) + 1);
+      },
+      onItemClick: (t, e) => {
+        o.set(e, (o.get(e) || 0) + 1), t.forceUpdate?.();
+      },
+      renderOverlay: () => {
+        if (!m) return null;
+        const t = Array.from(a.values()).reduce((s, n) => s + n, 0), e = Array.from(o.values()).reduce((s, n) => s + n, 0);
+        return /* @__PURE__ */ r(
+          "div",
+          {
+            style: {
+              position: "sticky",
+              top: 0,
+              zIndex: 100,
+              display: "flex",
+              gap: 12,
+              alignItems: "center",
+              padding: "6px 10px",
+              background: "rgba(0,0,0,0.6)",
+              color: "white",
+              borderRadius: 8,
+              fontSize: 12,
+              marginBottom: 8
+            },
+            children: [
+              /* @__PURE__ */ r("span", { children: [
+                "曝光总计: ",
+                t
+              ] }),
+              /* @__PURE__ */ r("span", { children: [
+                "点击总计: ",
+                e
+              ] })
+            ]
+          }
+        );
+      }
+    }
+  };
+}
+const u = "HeatmapAnalyticsPlugin", p = "统计每项进入视口次数与点击次数，可选顶部汇总条，`getStats()` 取出每项明细。曝光是瀑布流里最容易统计错的东西（滚动时反复进出视口），交给插件比自己写 IntersectionObserver 少踩坑。", y = "2.0.0", d = [
+  "interaction",
+  "埋点",
+  "曝光"
+], f = [
+  {
+    name: "showOverlay",
+    type: "boolean",
+    default: "false",
+    description: "是否显示顶部汇总条"
+  },
+  {
+    name: "showOverlaySummary",
+    type: "boolean",
+    default: "—",
+    description: "showOverlay 的旧别名"
+  }
+], g = `// 统计每项曝光次数与点击次数，可显示汇总条。
+const Waterfall = withPlugins(WaterfallCore, [
+  createHeatmapAnalyticsPlugin({
+    showOverlay: false,
+  }),
+]);
+
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, w = [
+  "按项的曝光 / 点击双计数",
+  "首屏曝光在 onLayoutComplete 补一次",
+  "getStats() 输出可上报的扁平结构"
+], v = [
+  "信息流曝光分析",
+  "广告位可见性验证",
+  "调试曝光策略"
+], h = [
+  "首屏曝光靠 onLayoutComplete 补一次，否则第一帧显示 0。",
+  "真实上报要自己做去重与批次（插件只负责计数，不区分「同一项第几次进入」）。",
+  "计数只在内存里，刷新即清零 —— 定时取 getStats() 上报。"
+], O = {
+  name: u,
+  description: p,
+  since: y,
+  tags: d,
+  config: f,
+  example: g,
+  features: w,
+  useCases: v,
+  notes: h
+};
+export {
+  k as c,
+  O as d
+};

package/dist/chunks/doc-BCGQ8Cp5.js

@@ -0,0 +1,114 @@
+import { jsxs as a } from "react/jsx-runtime";
+const p = "GROUPS";
+function x(i = {}) {
+  const u = i.groupBy ?? ((e) => e?.category ?? "default"), l = i.showOverlay ?? !1, r = (e) => {
+    const t = /* @__PURE__ */ new Map();
+    return (e.props.items ?? []).forEach((s, n) => {
+      const o = u(s, n);
+      t.has(o) || t.set(o, []), t.get(o).push(n);
+    }), e.sharedData.set(p, t), t.size > 0 && e.bus.emit("grouping:change", { groups: t }), t;
+  };
+  return {
+    name: "GroupingPlugin",
+    enabled: !0,
+    hooks: {
+      onMount: (e) => {
+        r(e);
+      },
+      onLayoutComplete: (e) => {
+        r(e);
+      },
+      onPropsChange: (e) => {
+        r(e);
+      },
+      renderOverlay: (e) => {
+        if (!l) return null;
+        const t = e.sharedData.get(p) ?? /* @__PURE__ */ new Map();
+        if (t.size === 0) return null;
+        const s = Array.from(t.entries()).slice(0, 3);
+        return /* @__PURE__ */ a(
+          "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__ */ a("div", { style: { opacity: 0.85, marginBottom: 6 }, children: [
+                "分组：",
+                t.size,
+                " 组"
+              ] }),
+              s.map(([n, o]) => /* @__PURE__ */ a("div", { children: [
+                String(n),
+                " · ",
+                o.length,
+                " 项"
+              ] }, String(n)))
+            ]
+          }
+        );
+      }
+    }
+  };
+}
+const c = "GroupingPlugin", d = "用 groupBy 把项按业务字段分组，结果放进 sharedData 的 `GROUPS`（Map<组键, 索引数组>），供 StickyHeaderPlugin、分组统计条等消费。挂载即算一次，之后 props 变化重算。", g = "2.0.0", f = [
+  "ui",
+  "分组"
+], m = [
+  {
+    name: "groupBy",
+    type: "(item, index) => string | number",
+    default: 'item.category ?? "default"',
+    description: "分组函数"
+  },
+  {
+    name: "showOverlay",
+    type: "boolean",
+    default: "false",
+    description: "是否显示分组统计角标"
+  }
+], h = `// 按字段把项分组，结果写进 sharedData(GROUPS) 供吸顶条 / 统计用。
+const Waterfall = withPlugins(WaterfallCore, [
+  createGroupingPlugin({
+    groupBy: "item.category ?? \\"default\\"",
+    showOverlay: false,
+  }),
+]);
+
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, y = [
+  "挂载即计算（旧版只在 props 变化时算，首屏永远拿不到分组）",
+  "结果写 sharedData，跨插件可读",
+  "统计角标默认关闭"
+], b = [
+  "按分类分组的信息流",
+  "按日期分组的时间线",
+  "吸顶条显示当前分组"
+], P = [
+  "分组只产出索引映射，不改变渲染顺序；要视觉分组请自己按分组建行。"
+], w = {
+  name: c,
+  description: d,
+  since: g,
+  tags: f,
+  config: m,
+  example: h,
+  features: y,
+  useCases: b,
+  notes: P
+};
+export {
+  x as c,
+  w as d
+};

package/dist/chunks/doc-BIzjYAZW.js

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

package/dist/chunks/doc-BP0DmB7-.js

@@ -0,0 +1,91 @@
+function v(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";
+    return n === "input" || n === "textarea" || a;
+  };
+  return {
+    name: "BookmarkPlugin",
+    enabled: !0,
+    hooks: {
+      onMount: (r) => {
+        const e = (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;
+            try {
+              localStorage.setItem(c, String(Math.max(0, o)));
+            } catch {
+            }
+          } else if (a === "r" || i === "KeyR") {
+            let t = 0;
+            try {
+              const d = localStorage.getItem(c) || "0";
+              t = Math.max(0, Number(d) || 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 });
+          }
+        };
+        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 });
+        };
+      }
+    }
+  };
+}
+const m = "BookmarkPlugin", g = "长列表读到一半要跳走时按 **B** 存位置，回来按 **R** 复原。焦点在输入框/可编辑区域时不拦截按键。", f = "2.0.0", k = [
+  "ui",
+  "滚动",
+  "快捷键"
+], p = [
+  {
+    name: "storageKey",
+    type: "string",
+    default: '"waterfall-bookmark"',
+    description: "localStorage 键名"
+  },
+  {
+    name: "scrollBehavior",
+    type: '"auto" | "smooth"',
+    default: '"smooth"',
+    description: "恢复时的滚动行为"
+  }
+], h = `// 按 B 记录滚动位置、按 R 跳回（localStorage），忽略输入框按键。
+const Waterfall = withPlugins(WaterfallCore, [
+  createBookmarkPlugin({
+    storageKey: "waterfall-bookmark",
+    scrollBehavior: "smooth",
+  }),
+]);
+
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, w = [
+  "B 存 / R 取，零 UI 侵入",
+  "自动区分容器滚动与页面滚动",
+  "输入框内不误触"
+], y = [
+  "长文列表阅读",
+  "后台大表格浏览",
+  "演示时快速复位"
+], b = [
+  "键名全局共用，一个页面里多处瀑布流请各自传不同的 storageKey。"
+], B = {
+  name: m,
+  description: g,
+  since: f,
+  tags: k,
+  config: p,
+  example: h,
+  features: w,
+  useCases: y,
+  notes: b
+};
+export {
+  v as c,
+  B as d
+};

package/dist/chunks/doc-BXElhF2h.js

@@ -0,0 +1,138 @@
+import { jsx as E } from "react/jsx-runtime";
+const i = "data-drag-over";
+function y(s, l) {
+  if (typeof document > "u") return null;
+  const c = document.elementFromPoint(s, l)?.closest?.("[data-index]");
+  if (!c) return null;
+  const d = Number(c.getAttribute("data-index"));
+  return Number.isFinite(d) ? d : null;
+}
+function C(s = {}) {
+  const l = s.enabled ?? !0, g = s.showHandle ?? !1, c = s.touchHoldMs ?? 180, d = (t, n, r) => {
+    const e = Number(r);
+    if (!Number.isFinite(e) || e === n) return;
+    t.sharedData.set("drag-from", e), t.sharedData.set("drag-to", n), t.bus.emit("drag:reorder", { from: e, to: n });
+    const f = t.props.items;
+    s.onReorder?.(e, n, f?.[e]);
+  }, b = () => {
+    document.querySelectorAll(`[${i}]`).forEach((t) => t.removeAttribute(i));
+  }, m = () => {
+    typeof document > "u" || (b(), document.body.style.userSelect = "", document.body.style.cursor = "");
+  }, w = (t, n, r) => {
+    if (t.pointerType === "mouse") return;
+    const e = t.clientX, f = t.clientY, R = Date.now();
+    let p = !1, h = null;
+    const v = (o) => {
+      if (!p) {
+        const D = Date.now() - R >= c, H = Math.hypot(o.clientX - e, o.clientY - f) >= 6;
+        if (!D || !H) return;
+        p = !0, document.body.style.userSelect = "none", document.body.style.cursor = "grabbing";
+      }
+      o.preventDefault();
+      const a = y(o.clientX, o.clientY);
+      a !== h && (b(), h = a, a != null && document.querySelector(`[data-index="${a}"]`)?.setAttribute(i, ""));
+    }, u = (o) => {
+      if (window.removeEventListener("pointermove", v), window.removeEventListener("pointerup", u), window.removeEventListener("pointercancel", u), m(), !p) return;
+      const a = y(o.clientX, o.clientY);
+      a != null && d(r, a, String(n));
+    };
+    window.addEventListener("pointermove", v, { passive: !1 }), window.addEventListener("pointerup", u), window.addEventListener("pointercancel", u);
+  };
+  return {
+    name: "DragReorderPlugin",
+    enabled: l,
+    hooks: {
+      renderItemWrapper: (t, n, r) => l ? /* @__PURE__ */ E(
+        "div",
+        {
+          draggable: !0,
+          onDragStart: (e) => {
+            e.dataTransfer?.setData("text/plain", String(r)), t.sharedData.set("drag-from", r);
+          },
+          onDragOver: (e) => {
+            e.preventDefault();
+          },
+          onDragEnter: () => {
+            document.querySelector(`[data-index="${r}"]`)?.setAttribute(i, "");
+          },
+          onDragLeave: () => {
+            document.querySelector(`[data-index="${r}"]`)?.removeAttribute(i);
+          },
+          onDrop: (e) => {
+            e.preventDefault(), m(), d(t, r, e.dataTransfer?.getData("text/plain") ?? "");
+          },
+          onDragEnd: m,
+          onPointerDown: (e) => w(e, r, t),
+          style: {
+            cursor: "grab",
+            ...g ? { border: "1px dashed #bdbdbd", borderRadius: 6 } : null
+          },
+          children: n
+        }
+      ) : n
+    }
+  };
+}
+const L = "DragReorderPlugin", M = "给每个项加拖拽能力，松手时回调 `onReorder(from, to)`，同时向 bus 发 `drag:reorder`。鼠标走原生 HTML5 拖拽，触屏走「长按 + pointer」——触摸设备上 `draggable` 根本不触发，旧版因此在手机上完全失效。", A = "2.0.0", P = [
+  "interaction",
+  "拖拽"
+], S = [
+  {
+    name: "enabled",
+    type: "boolean",
+    default: "true",
+    description: "是否启用拖拽"
+  },
+  {
+    name: "onReorder",
+    type: "(from, to, item) => void",
+    default: "—",
+    description: "重排回调"
+  },
+  {
+    name: "showHandle",
+    type: "boolean",
+    default: "false",
+    description: "是否显示虚线边框提示可拖"
+  },
+  {
+    name: "touchHoldMs",
+    type: "number",
+    default: "180",
+    description: "触屏长按多久进入拖拽（ms），0 表示不需要长按"
+  }
+], T = `// 鼠标走 HTML5 draggable，触屏走长按 + pointer，松手时回调 onReorder(from, to)。
+const Waterfall = withPlugins(WaterfallCore, [
+  createDragReorderPlugin({
+    enabled: true,
+    showHandle: false,
+    touchHoldMs: 180,
+  }),
+]);
+
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, X = [
+  "鼠标：原生 HTML5 拖拽，无额外依赖",
+  "触屏：长按 180ms 后 pointer 拖拽（可配 touchHoldMs）",
+  "onReorder 回调真正可用，bus 发 `drag:reorder`"
+], Y = [
+  "后台卡片排序",
+  "收藏夹手动排序",
+  "仪表盘组件排列"
+], q = [
+  "插件只负责「拖」和「告诉你从哪到哪」，数组重排由调用方在 onReorder 里做。",
+  "触屏用长按区分「想滚」和「想拖」：不这样做，手指一滑就变成拖拽，页面滚不动。"
+], N = {
+  name: L,
+  description: M,
+  since: A,
+  tags: P,
+  config: S,
+  example: T,
+  features: X,
+  useCases: Y,
+  notes: q
+};
+export {
+  C as c,
+  N as d
+};