vane-waterfall 2.0.1 → 2.0.3

package/dist/chunks/{doc-DzvTrZ13.js → doc-CaJ02INP.js}

@@ -1,4 +1,4 @@
-function m(e) {
+function h(e) {
   return {
     name: "ThrottlePlugin",
     priority: 80,
@@ -12,10 +12,16 @@ function m(e) {
     }
   };
 }
-const n = "ThrottlePlugin", s = "接管 Core 的 throttleDelay（滚动回调节流）与 debounceDelay（尺寸变化后多久重排）。默认 16ms / 150ms，长列表滚动卡顿时可以放宽到 32 / 300。", o = "2.0.0", r = [
+const s = "ThrottlePlugin", n = "接管 Core 的 throttleDelay（滚动回调节流）与 debounceDelay（尺寸变化后多久重排）。默认 16ms / 150ms，长列表滚动卡顿时可以放宽到 32 / 300。", o = "2.0.0", r = [
   "perf",
   "性能"
 ], a = [
+  {
+    name: "transformProps",
+    when: "渲染前链式改写瀑布流 props",
+    description: "补 gap / columns 默认值、按断点覆盖配置"
+  }
+], c = [], l = "只读取 context 字段（props / state / data），不调用上下文方法", i = [
   {
     name: "scroll",
     type: "number",
@@ -28,33 +34,36 @@ const n = "ThrottlePlugin", s = "接管 Core 的 throttleDelay（滚动回调节
     default: "props.debounceDelay",
     description: "布局防抖 ms"
   }
-], l = `// 调整滚动节流与尺寸防抖，弱网/低端机可放宽。
+], m = `// 调整滚动节流与尺寸防抖，弱网/低端机可放宽。
 const Waterfall = withPlugins(WaterfallCore, [
   createThrottlePlugin(),
 ]);
 
-<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, c = [
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, u = [
   "滚动节流与布局防抖分开调",
   "只改 props，不改算法",
   "与 DebounceLayoutPlugin 叠加时后者优先"
-], i = [
+], d = [
   "低端安卓机长列表",
   "滚动时 CPU 占用过高",
   "拖拽侧栏时减少重排"
-], u = [
+], p = [
   "scroll 低于 16ms 没有意义（浏览器帧率上限）。"
-], d = {
-  name: n,
-  description: s,
+], f = {
+  name: s,
+  description: n,
   since: o,
   tags: r,
-  config: a,
-  example: l,
-  features: c,
-  useCases: i,
-  notes: u
+  events: a,
+  methods: c,
+  methodsNote: l,
+  config: i,
+  example: m,
+  features: u,
+  useCases: d,
+  notes: p
 };
 export {
-  m as c,
-  d
+  h as c,
+  f as d
 };

package/dist/chunks/{doc-BXElhF2h.js → doc-CiCso5Ti.js}

@@ -1,48 +1,48 @@
 import { jsx as E } from "react/jsx-runtime";
 const i = "data-drag-over";
-function y(s, l) {
+function w(a, c) {
   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"));
+  const l = document.elementFromPoint(a, c)?.closest?.("[data-index]");
+  if (!l) return null;
+  const d = Number(l.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) => {
+function O(a = {}) {
+  const c = a.enabled ?? !0, g = a.showHandle ?? !1, l = a.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 = () => {
+    const p = t.props.items;
+    a.onReorder?.(e, n, p?.[e]);
+  }, h = () => {
     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) => {
+    typeof document > "u" || (h(), document.body.style.userSelect = "", document.body.style.cursor = "");
+  }, y = (t, n, r) => {
     if (t.pointerType === "mouse") return;
-    const e = t.clientX, f = t.clientY, R = Date.now();
-    let p = !1, h = null;
+    const e = t.clientX, p = t.clientY, R = Date.now();
+    let f = !1, b = null;
     const v = (o) => {
-      if (!p) {
-        const D = Date.now() - R >= c, H = Math.hypot(o.clientX - e, o.clientY - f) >= 6;
+      if (!f) {
+        const D = Date.now() - R >= l, H = Math.hypot(o.clientX - e, o.clientY - p) >= 6;
         if (!D || !H) return;
-        p = !0, document.body.style.userSelect = "none", document.body.style.cursor = "grabbing";
+        f = !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, ""));
+      const s = w(o.clientX, o.clientY);
+      s !== b && (h(), b = s, s != null && document.querySelector(`[data-index="${s}"]`)?.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));
+      if (window.removeEventListener("pointermove", v), window.removeEventListener("pointerup", u), window.removeEventListener("pointercancel", u), m(), !f) return;
+      const s = w(o.clientX, o.clientY);
+      s != null && d(r, s, String(n));
     };
     window.addEventListener("pointermove", v, { passive: !1 }), window.addEventListener("pointerup", u), window.addEventListener("pointercancel", u);
   };
   return {
     name: "DragReorderPlugin",
-    enabled: l,
+    enabled: c,
     hooks: {
-      renderItemWrapper: (t, n, r) => l ? /* @__PURE__ */ E(
+      renderItemWrapper: (t, n, r) => c ? /* @__PURE__ */ E(
         "div",
         {
           draggable: !0,
@@ -62,7 +62,7 @@ function C(s = {}) {
             e.preventDefault(), m(), d(t, r, e.dataTransfer?.getData("text/plain") ?? "");
           },
           onDragEnd: m,
-          onPointerDown: (e) => w(e, r, t),
+          onPointerDown: (e) => y(e, r, t),
           style: {
             cursor: "grab",
             ...g ? { border: "1px dashed #bdbdbd", borderRadius: 6 } : null
@@ -77,6 +77,17 @@ const L = "DragReorderPlugin", M = "给每个项加拖拽能力，松手时回
   "interaction",
   "拖拽"
 ], S = [
+  {
+    name: "renderItemWrapper",
+    when: "渲染每个卡片时包裹其内容",
+    description: "给单卡加包裹层（拖拽、无障碍语义、占位骨架）"
+  },
+  {
+    name: "drag:reorder",
+    when: "拖拽排序完成后",
+    description: "广播 { from, to }，供业务层同步顺序"
+  }
+], T = [], N = "只读取 context 字段（props / state / data），不调用上下文方法", x = [
   {
     name: "enabled",
     type: "boolean",
@@ -101,7 +112,7 @@ const L = "DragReorderPlugin", M = "给每个项加拖拽能力，松手时回
     default: "180",
     description: "触屏长按多久进入拖拽（ms），0 表示不需要长按"
   }
-], T = `// 鼠标走 HTML5 draggable，触屏走长按 + pointer，松手时回调 onReorder(from, to)。
+], W = `// 鼠标走 HTML5 draggable，触屏走长按 + pointer，松手时回调 onReorder(from, to)。
 const Waterfall = withPlugins(WaterfallCore, [
   createDragReorderPlugin({
     enabled: true,
@@ -121,18 +132,21 @@ const Waterfall = withPlugins(WaterfallCore, [
 ], q = [
   "插件只负责「拖」和「告诉你从哪到哪」，数组重排由调用方在 onReorder 里做。",
   "触屏用长按区分「想滚」和「想拖」：不这样做，手指一滑就变成拖拽，页面滚不动。"
-], N = {
+], $ = {
   name: L,
   description: M,
   since: A,
   tags: P,
-  config: S,
-  example: T,
+  events: S,
+  methods: T,
+  methodsNote: N,
+  config: x,
+  example: W,
   features: X,
   useCases: Y,
   notes: q
 };
 export {
-  C as c,
-  N as d
+  O as c,
+  $ as d
 };

package/dist/chunks/doc-CkuMr8Ca.js

@@ -0,0 +1,118 @@
+import { jsx as u } from "react/jsx-runtime";
+function w(n = {}) {
+  const l = n.containerRole ?? "list", c = n.itemRole ?? "listitem", m = n.enableTabIndex ?? !0, d = n.containerLabel ?? "Waterfall list", a = /* @__PURE__ */ new WeakMap(), s = (e) => e.containerRef?.current ?? e.bus, i = (e) => a.get(s(e)) ?? 0, o = (e) => {
+    const t = e.containerRef.current;
+    t && (t.setAttribute("role", l), t.setAttribute("aria-label", d), t.setAttribute("aria-busy", e.isLayouting ? "true" : "false"));
+  };
+  return {
+    name: "A11yPlugin",
+    enabled: !0,
+    hooks: {
+      onMount: (e) => {
+        o(e);
+      },
+      onLayoutComplete: (e) => {
+        o(e);
+      },
+      onItemClick: (e, t) => {
+        i(e) !== t && (a.set(s(e), t), e.forceUpdate?.());
+      },
+      renderItemWrapper: (e, t, r) => /* @__PURE__ */ u(
+        "div",
+        {
+          role: c,
+          "aria-posinset": r + 1,
+          "aria-setsize": e.itemCount,
+          tabIndex: m ? r === i(e) ? 0 : -1 : void 0,
+          children: t
+        }
+      )
+    }
+  };
+}
+const p = "A11yPlugin", b = "把瀑布流补成读屏可理解的列表：容器 `role=list` + `aria-label`，每项 `role=listitem` + `aria-posinset` / `aria-setsize`，并可选加 `tabIndex` 让键盘能逐项聚焦。", f = "2.0.0", y = [
+  "ui",
+  "a11y"
+], I = [
+  {
+    name: "onMount",
+    when: "瀑布流挂载完成",
+    description: "初始化观察器与滚动监听，返回清理函数"
+  },
+  {
+    name: "onItemClick",
+    when: "单个卡片被点击",
+    description: "卡片级跳转与点击埋点"
+  },
+  {
+    name: "onLayoutComplete",
+    when: "DOM 落位完成（可安全测量）",
+    description: "测量真实高度、懒加载判定、曝光上报"
+  },
+  {
+    name: "renderItemWrapper",
+    when: "渲染每个卡片时包裹其内容",
+    description: "给单卡加包裹层（拖拽、无障碍语义、占位骨架）"
+  }
+], g = [], R = "只读取 context 字段（props / state / data），不调用上下文方法", h = [
+  {
+    name: "containerRole",
+    type: "string",
+    default: '"list"',
+    description: "容器 role"
+  },
+  {
+    name: "itemRole",
+    type: "string",
+    default: '"listitem"',
+    description: "项 role"
+  },
+  {
+    name: "enableTabIndex",
+    type: "boolean",
+    default: "true",
+    description: "项是否可 Tab 聚焦"
+  },
+  {
+    name: "containerLabel",
+    type: "string",
+    default: '"Waterfall list"',
+    description: "容器 aria-label"
+  }
+], C = `// 给容器与项补 ARIA role / label / posinset，支持键盘 Tab 遍历。
+const Waterfall = withPlugins(WaterfallCore, [
+  createA11yPlugin({
+    containerRole: "list",
+    itemRole: "listitem",
+    enableTabIndex: true,
+  }),
+]);
+
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, A = [
+  "容器 / 项 role 成对补齐",
+  "aria-posinset + aria-setsize 正确标注序号",
+  "键盘可逐项聚焦"
+], W = [
+  "政务 / 金融等合规站点",
+  "读屏用户可用的信息流",
+  "键盘操作优先的桌面端"
+], T = [
+  "项数很多时 `tabIndex=0` 会让 Tab 变长，建议配合「跳转主内容」链接使用。"
+], x = {
+  name: p,
+  description: b,
+  since: f,
+  tags: y,
+  events: I,
+  methods: g,
+  methodsNote: R,
+  config: h,
+  example: C,
+  features: A,
+  useCases: W,
+  notes: T
+};
+export {
+  w as c,
+  x as d
+};

package/dist/chunks/{doc-3Fpag2G8.js → doc-D7m1OFCW.js}

@@ -1,4 +1,4 @@
-function g(o = {}) {
+function v(o = {}) {
   return {
     name: "FilterPlugin",
     priority: 40,
@@ -7,9 +7,9 @@ function g(o = {}) {
       transformProps: (e) => {
         const n = Array.isArray(e.items) ? e.items : [], t = e.filterFn || o.predicate;
         if (typeof t != "function") return e;
-        const r = n.filter((a, i) => {
+        const r = n.filter((s, a) => {
           try {
-            return !!t(a, i);
+            return !!t(s, a);
           } catch {
             return !0;
           }
@@ -17,19 +17,30 @@ function g(o = {}) {
         return { ...e, items: r };
       },
       onPropsChange: (e, n, t) => {
-        const r = n?.filterFn, a = t?.filterFn;
-        if (((typeof t?.scrollToTopOnFilterChange == "boolean" ? t.scrollToTopOnFilterChange : void 0) ?? !!o.scrollToTop) && r !== a) {
-          const l = t?.scrollToTopBehavior ?? o.scrollBehavior ?? "auto";
-          e.scrollToTop?.({ behavior: l });
+        const r = n?.filterFn, s = t?.filterFn;
+        if (((typeof t?.scrollToTopOnFilterChange == "boolean" ? t.scrollToTopOnFilterChange : void 0) ?? !!o.scrollToTop) && r !== s) {
+          const i = t?.scrollToTopBehavior ?? o.scrollBehavior ?? "auto";
+          e.scrollToTop?.({ behavior: i });
         }
       }
     }
   };
 }
-const s = "FilterPlugin", c = "用谓词函数过滤数据，优先读 `props.filterFn`，没有就用工厂里传入的 predicate。过滤条件变了可以自动滚回顶部（默认不开）。", u = "2.0.0", f = [
+const l = "FilterPlugin", c = "用谓词函数过滤数据，优先读 `props.filterFn`，没有就用工厂里传入的 predicate。过滤条件变了可以自动滚回顶部（默认不开）。", p = "2.0.0", d = [
   "data",
   "数据管线"
-], d = [
+], m = [
+  {
+    name: "onPropsChange",
+    when: "props 变化后",
+    description: "数据或配置变化时请求重排"
+  },
+  {
+    name: "transformProps",
+    when: "渲染前链式改写瀑布流 props",
+    description: "补 gap / columns 默认值、按断点覆盖配置"
+  }
+], u = [], f = "只读取 context 字段（props / state / data），不调用上下文方法", h = [
   {
     name: "predicate",
     type: "(item, index) => boolean",
@@ -48,7 +59,7 @@ const s = "FilterPlugin", c = "用谓词函数过滤数据，优先读 `props.fi
     default: '"auto"',
     description: "回顶行为"
   }
-], p = `// 按谓词过滤 items，参数变化可自动回顶。
+], F = `// 按谓词过滤 items，参数变化可自动回顶。
 const Waterfall = withPlugins(WaterfallCore, [
   createFilterPlugin({
     scrollToTop: false,
@@ -56,29 +67,32 @@ const Waterfall = withPlugins(WaterfallCore, [
   }),
 ]);
 
-<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, m = [
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, T = [
   "谓词抛错时按「保留」处理，不会整表消失",
   "props.filterFn 优先，便于页面动态换过滤条件",
   "可与 Sort / Search / Pagination 串联"
-], F = [
+], g = [
   "分类 Tab 切换",
   "只看有货 / 只看促销",
   "价格区间筛选"
-], h = [
+], y = [
   "数据管线的执行顺序由 priority 决定：Filter(40) → Sort(30) → Search(20) → Pagination(10)。",
   "先过滤再分页，页码总数才是过滤后的总数——顺序反了会出现「第 2 页空」。"
-], y = {
-  name: s,
+], b = {
+  name: l,
   description: c,
-  since: u,
-  tags: f,
-  config: d,
-  example: p,
-  features: m,
-  useCases: F,
-  notes: h
+  since: p,
+  tags: d,
+  events: m,
+  methods: u,
+  methodsNote: f,
+  config: h,
+  example: F,
+  features: T,
+  useCases: g,
+  notes: y
 };
 export {
-  g as c,
-  y as d
+  v as c,
+  b as d
 };

package/dist/chunks/doc-DEN2WTDh.js

@@ -0,0 +1,153 @@
+import { jsxs as g, jsx as h } from "react/jsx-runtime";
+function W(u = {}) {
+  const { log: m = !1, showOverlay: p = !1 } = u, n = /* @__PURE__ */ new Map(), c = /* @__PURE__ */ new Map();
+  let i = null;
+  const l = () => Array.from(n.values()).reduce((e, t) => e + t, 0), y = (e, t, s) => {
+    try {
+      const o = e.props?.keyExtractor?.(t, s);
+      if (o != null) return String(o);
+    } catch {
+    }
+    return `#${s}`;
+  }, d = (e) => {
+    const t = e.items;
+    (i === null || t !== i) && (i = t, n.clear(), c.clear(), e.sharedData?.set("click-count", 0));
+  };
+  return {
+    name: "ClickAnalyticsPlugin",
+    enabled: !0,
+    getStats: () => ({
+      total: l(),
+      byIndex: Array.from(n.entries()).map(([e, t]) => ({
+        index: c.get(e) ?? 0,
+        key: e,
+        clicks: t
+      })).sort((e, t) => e.index - t.index || e.key.localeCompare(t.key))
+    }),
+    hooks: {
+      onMount: (e) => {
+        e.sharedData?.set("click-count", l());
+      },
+      onLayoutComplete: (e) => {
+        d(e);
+      },
+      onItemClick: (e, t, s, o) => {
+        d(e);
+        const a = y(e, s, t);
+        c.set(a, t);
+        const f = (n.get(a) ?? 0) + 1;
+        n.set(a, f);
+        const r = l();
+        e.sharedData?.set("click-count", r), e.bus?.emit("analytics:click", { index: t, key: a, item: s, event: o, total: r }), e.forceUpdate?.(), m && console.log(`[ClickAnalytics] item=${t} total=${r}`);
+      },
+      renderOverlay: (e) => {
+        if (!p) return null;
+        const t = e.sharedData?.get("click-count") || 0;
+        return /* @__PURE__ */ g(
+          "div",
+          {
+            style: {
+              position: "absolute",
+              top: 12,
+              right: 12,
+              padding: "10px 12px",
+              background: "#222",
+              color: "#fff",
+              borderRadius: 8,
+              fontSize: 14,
+              fontWeight: 600,
+              boxShadow: "0 4px 12px rgba(0,0,0,0.25)",
+              border: "1px solid rgba(255,255,255,0.15)",
+              pointerEvents: "none",
+              zIndex: 99
+            },
+            children: [
+              "点击次数：",
+              t,
+              /* @__PURE__ */ h("div", { style: { fontSize: 12, fontWeight: 400, opacity: 0.85, marginTop: 4 }, children: "提示：点击任意卡片观察计数变化" })
+            ]
+          }
+        );
+      }
+    }
+  };
+}
+const k = "ClickAnalyticsPlugin", x = "统计每次项点击并累计总数，向 bus 发 `analytics:click`（带 index / item / total），`getStats()` 可随时取出按 index 的计数。默认只上报不显示角标，接入真实版式时不会被调试面板盖住内容。", b = "2.0.0", C = [
+  "interaction",
+  "埋点"
+], v = [
+  {
+    name: "onMount",
+    when: "瀑布流挂载完成",
+    description: "初始化观察器与滚动监听，返回清理函数"
+  },
+  {
+    name: "onItemClick",
+    when: "单个卡片被点击",
+    description: "卡片级跳转与点击埋点"
+  },
+  {
+    name: "onLayoutComplete",
+    when: "DOM 落位完成（可安全测量）",
+    description: "测量真实高度、懒加载判定、曝光上报"
+  },
+  {
+    name: "renderOverlay",
+    when: "每次渲染，滚动容器内的内容层之上",
+    description: "回到顶部、加载提示、浮层工具"
+  },
+  {
+    name: "analytics:click",
+    when: "卡片点击后",
+    description: "广播 { index, key, item, event, total } 点击埋点"
+  }
+], w = [], S = "只读取 context 字段（props / state / data），不调用上下文方法", A = [
+  {
+    name: "log",
+    type: "boolean",
+    default: "false",
+    description: "是否在控制台打印每次点击"
+  },
+  {
+    name: "showOverlay",
+    type: "boolean",
+    default: "false",
+    description: "是否显示右上角计数角标"
+  }
+], D = `// 统计项点击次数，发 \`analytics:click\` 事件，可选角标与日志。
+const Waterfall = withPlugins(WaterfallCore, [
+  createClickAnalyticsPlugin({
+    log: false,
+    showOverlay: false,
+  }),
+]);
+
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, O = [
+  "点击总量 + 按 index 明细（getStats）",
+  "bus 事件可被外部订阅上报",
+  "角标默认关闭"
+], I = [
+  "内容流点击率统计",
+  "AB 实验埋点",
+  "调试点击行为"
+], M = [
+  "生产环境请把数据从 bus 事件或 getStats() 接到自己的埋点 SDK，不要让插件直接打日志。",
+  "计数只在内存里，刷新即清零 —— 想持久化要自己定时取 getStats() 上报。"
+], z = {
+  name: k,
+  description: x,
+  since: b,
+  tags: C,
+  events: v,
+  methods: w,
+  methodsNote: S,
+  config: A,
+  example: D,
+  features: O,
+  useCases: I,
+  notes: M
+};
+export {
+  W as c,
+  z as d
+};