vane-waterfall 1.0.4 → 2.0.0

package/dist/chunks/doc-DJjxOYzW.js

@@ -0,0 +1,111 @@
+function L(i = {}) {
+  const h = i.mode || "hash", r = i.keys || ["pageIndex", "pageSize", "searchQuery"];
+  function l() {
+    try {
+      if (h === "hash") {
+        const s = window.location.hash || "", t = s.indexOf("?"), a = t >= 0 ? s.slice(t + 1) : s.replace(/^#/, ""), e = new URLSearchParams(a), n = {};
+        return r.forEach((c) => {
+          const o = e.get(c);
+          o !== null && (n[c] = o);
+        }), n;
+      } else {
+        const s = new URLSearchParams(window.location.search), t = {};
+        return r.forEach((a) => {
+          const e = s.get(a);
+          e !== null && (t[a] = e);
+        }), t;
+      }
+    } catch {
+      return {};
+    }
+  }
+  function p(s) {
+    try {
+      const t = new URLSearchParams();
+      r.forEach((e) => {
+        const n = s[e];
+        n != null && String(n).length > 0 && t.set(e, String(n));
+      });
+      const a = t.toString();
+      if (h === "hash") {
+        const e = window.location.hash || "", o = `#${e.replace(/^#/, "").split("?")[0] || ""}${a ? `?${a}` : ""}`;
+        e !== o && history.replaceState(
+          null,
+          "",
+          `${window.location.pathname}${window.location.search}${o}`
+        );
+      } else {
+        const n = window.location.pathname + (a ? `?${a}` : "") + (window.location.hash || "");
+        history.replaceState(null, "", n);
+      }
+    } catch {
+    }
+  }
+  return {
+    name: "URLSyncPlugin",
+    enabled: !0,
+    hooks: {
+      onMount: (s) => {
+        const t = l();
+        s.bus?.emit("urlsync:init", t);
+      },
+      onPropsChange: (s, t, a) => {
+        const e = {}, n = a ?? {};
+        r.forEach((c) => {
+          const o = n[c];
+          o !== void 0 && (e[c] = o);
+        }), p(e);
+      }
+    }
+  };
+}
+const u = "URLSyncPlugin", d = "props 变化时把指定键写进 URL（hash 或 search），挂载时读出来广播 `urlsync:init`。刷新与分享都能还原筛选状态。", m = "2.0.0", w = [
+  "ui",
+  "URL",
+  "可分享"
+], f = [
+  {
+    name: "mode",
+    type: '"hash" | "search"',
+    default: '"hash"',
+    description: "写 hash 还是 search"
+  },
+  {
+    name: "keys",
+    type: "string[]",
+    default: '["pageIndex","pageSize","searchQuery"]',
+    description: "要同步的 props 键"
+  }
+], g = `// 把分页/搜索/排序同步进 URL（hash 或 search），链接可分享。
+const Waterfall = withPlugins(WaterfallCore, [
+  createURLSyncPlugin({
+    mode: "hash",
+    keys: ["pageIndex","pageSize","searchQuery"],
+  }),
+]);
+
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, S = [
+  "hash 模式会保留已有路由路径",
+  "用 replaceState，不污染后退栈",
+  "SSR 安全：无 window 时直接跳过"
+], y = [
+  "搜索结果可分享",
+  "后台筛选状态可刷新",
+  "带参数的深链"
+], R = [
+  "只做单向同步（props → URL）与初始读取；URL 前进后退的监听请页面自己做。"
+], U = {
+  name: u,
+  description: d,
+  since: m,
+  tags: w,
+  config: f,
+  example: g,
+  features: S,
+  useCases: y,
+  notes: R
+};
+export {
+  L as c,
+  U as d
+};

package/dist/chunks/doc-DukOmDCo.js

@@ -0,0 +1,95 @@
+const l = "(prefers-reduced-motion: reduce)";
+function R(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))
+      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");
+      } else {
+        const n = t.get(e);
+        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) => {
+    e.matches !== s && (s = e.matches, f());
+  };
+  return i?.addEventListener?.("change", d), {
+    name: "ReducedMotionPlugin",
+    priority: 70,
+    enabled: !0,
+    hooks: {
+      transformProps: (e) => {
+        if (!s) return e;
+        const n = { ...e };
+        return m && (n.useTransform = !1), u && (n.itemStyle = { ...e.itemStyle ?? {}, transitionDuration: "0s" }), n;
+      },
+      onItemMount: (e, n, r) => {
+        o.set(n, r), a(r);
+      },
+      onItemUnmount: (e, n) => {
+        o.delete(n);
+      },
+      onLayoutComplete: (e) => {
+        e.itemRefs.forEach((n, r) => {
+          n && o.set(r, n), a(n);
+        });
+      },
+      onUnmount: () => {
+        i?.removeEventListener?.("change", d), o.clear(), t.clear();
+      }
+    }
+  };
+}
+const p = "ReducedMotionPlugin", y = "检测 `prefers-reduced-motion: reduce`，命中后把 useTransform 关掉并清掉项上的 transition。前庭功能敏感用户不会因为滚动时的位置微动而不适。", g = "2.0.0", h = [
+  "perf",
+  "a11y"
+], T = [
+  {
+    name: "disableTransform",
+    type: "boolean",
+    default: "true",
+    description: "命中偏好时改用 left/top 定位"
+  },
+  {
+    name: "removeTransitions",
+    type: "boolean",
+    default: "true",
+    description: "命中偏好时清掉项过渡"
+  }
+], P = `// 尊重系统「减少动画」偏好：关掉 transform 定位与项过渡。
+const Waterfall = withPlugins(WaterfallCore, [
+  createReducedMotionPlugin({
+    disableTransform: true,
+    removeTransitions: true,
+  }),
+]);
+
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, M = [
+  "系统偏好驱动，零配置生效",
+  "两项能力可分别关闭",
+  "与 TransitionPlugin 同装时优先生效"
+], v = [
+  "政务 / 医疗类站点",
+  "无障碍合规要求",
+  "低性能设备"
+], w = [
+  "偏好由 matchMedia 驱动，并监听 change：运行中改系统设置即时生效（定位方式要等下一次重渲染才切过来）。",
+  "只压 `transition-duration`，不写 `transition: none` —— 写简写会把 TransitionPlugin 的过渡整条覆盖，撤销偏好后无从还原。",
+  "与 TransitionPlugin 同装不是冲突：ReducedMotion 优先级更高，会先执行并压住过渡。"
+], b = {
+  name: p,
+  description: y,
+  since: g,
+  tags: h,
+  config: T,
+  example: P,
+  features: M,
+  useCases: v,
+  notes: w
+};
+export {
+  R as c,
+  b as d
+};

package/dist/chunks/doc-DzvTrZ13.js

@@ -0,0 +1,60 @@
+function m(e) {
+  return {
+    name: "ThrottlePlugin",
+    priority: 80,
+    enabled: !0,
+    hooks: {
+      transformProps: (t) => ({
+        ...t,
+        throttleDelay: e.scroll,
+        debounceDelay: e.resize ?? t.debounceDelay
+      })
+    }
+  };
+}
+const n = "ThrottlePlugin", s = "接管 Core 的 throttleDelay（滚动回调节流）与 debounceDelay（尺寸变化后多久重排）。默认 16ms / 150ms，长列表滚动卡顿时可以放宽到 32 / 300。", o = "2.0.0", r = [
+  "perf",
+  "性能"
+], a = [
+  {
+    name: "scroll",
+    type: "number",
+    default: "—",
+    description: "滚动节流 ms（必填）"
+  },
+  {
+    name: "resize",
+    type: "number",
+    default: "props.debounceDelay",
+    description: "布局防抖 ms"
+  }
+], l = `// 调整滚动节流与尺寸防抖，弱网/低端机可放宽。
+const Waterfall = withPlugins(WaterfallCore, [
+  createThrottlePlugin(),
+]);
+
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, c = [
+  "滚动节流与布局防抖分开调",
+  "只改 props，不改算法",
+  "与 DebounceLayoutPlugin 叠加时后者优先"
+], i = [
+  "低端安卓机长列表",
+  "滚动时 CPU 占用过高",
+  "拖拽侧栏时减少重排"
+], u = [
+  "scroll 低于 16ms 没有意义（浏览器帧率上限）。"
+], d = {
+  name: n,
+  description: s,
+  since: o,
+  tags: r,
+  config: a,
+  example: l,
+  features: c,
+  useCases: i,
+  notes: u
+};
+export {
+  m as c,
+  d
+};

package/dist/chunks/doc-NhL4Ux8q.js

@@ -0,0 +1,125 @@
+function K(o = {}) {
+  const i = o.storageKey || "waterfall-state", l = o.persistScroll ?? !0, a = o.persistKeys || ["pageIndex", "pageSize", "searchQuery"];
+  let u = !1;
+  function c() {
+    try {
+      const e = localStorage.getItem(i);
+      return e ? JSON.parse(e) : null;
+    } catch {
+      return null;
+    }
+  }
+  function p(e) {
+    try {
+      localStorage.setItem(i, JSON.stringify(e));
+    } catch {
+    }
+  }
+  return {
+    name: "StatePersistencePlugin",
+    enabled: !0,
+    hooks: {
+      // 首次渲染时，尽量将本地快照中的分页/查询键注入到 props，便于核心按恢复后的状态渲染
+      transformProps: (e) => {
+        if (u) return e;
+        const t = c();
+        if (!t) return e;
+        const n = { ...e };
+        let s = !1;
+        return a.forEach((r) => {
+          t[r] !== void 0 && (n[r] = t[r], s = !0);
+        }), s && (u = !0), n;
+      },
+      onMount: (e) => {
+        const t = c();
+        if (!t) return;
+        if (l) {
+          const s = Number(t.scrollTop ?? 0), r = e.containerRef.current;
+          r ? r.scrollTo({ top: s, behavior: "auto" }) : e.scrollToTop?.({ behavior: "auto" });
+        }
+        const n = {};
+        if (a.forEach((s) => {
+          t[s] !== void 0 && (n[s] = t[s]);
+        }), Object.keys(n).length > 0 && (e.bus?.emit("state:restored", n), typeof window < "u"))
+          try {
+            window.dispatchEvent(new CustomEvent("waterfall:state-restored", { detail: n }));
+          } catch {
+          }
+      },
+      // props 变化时，增量更新快照（立即持久化分页/查询键）
+      onPropsChange: (e, t, n) => {
+        const r = { ...c() || {} }, g = n ?? {};
+        a.forEach((f) => {
+          const d = g[f];
+          d !== void 0 && (r[f] = d);
+        }), p(r);
+      },
+      onUnmount: (e) => {
+        const t = {};
+        l && (t.scrollTop = e.containerRef.current?.scrollTop || 0);
+        const n = e.props ?? {};
+        a.forEach((s) => {
+          const r = n[s];
+          r !== void 0 && (t[s] = r);
+        }), p(t);
+      }
+    }
+  };
+}
+const y = "StatePersistencePlugin", m = "三个时机各做一件事：首次渲染把快照里的 pageIndex / searchQuery 注入 props；挂载后恢复 scrollTop；props 变化与卸载时写回快照。刷新页面不丢进度。", S = "2.0.0", h = [
+  "ui",
+  "持久化"
+], w = [
+  {
+    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 键"
+  }
+], v = `// 把滚动位置与分页/查询状态存 localStorage，回来时恢复。
+const Waterfall = withPlugins(WaterfallCore, [
+  createStatePersistencePlugin({
+    storageKey: "waterfall-state",
+    persistScroll: true,
+    persistKeys: ["pageIndex","pageSize","searchQuery"],
+  }),
+]);
+
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, P = [
+  "滚动位置 + 分页/查询一起存",
+  "首帧注入只做一次，不会覆盖用户操作",
+  "SSR / 隐私模式下降级为不持久化"
+], b = [
+  "后台列表刷新不丢页",
+  "搜索结果返回定位",
+  "移动端来回切换页面"
+], I = [
+  "只能恢复「值」，不能替你把它写回 React state——页面应订阅 `state:restored` 事件或读 bus。",
+  "localStorage 不可用（隐私模式/配额满）时静默跳过，不会抛错。"
+], T = {
+  name: y,
+  description: m,
+  since: S,
+  tags: h,
+  config: w,
+  example: v,
+  features: P,
+  useCases: b,
+  notes: I
+};
+export {
+  K as c,
+  T as d
+};

package/dist/chunks/doc-bTHwfIVb.js

@@ -0,0 +1,78 @@
+function w(s) {
+  const r = new Set(s.pinnedIndices), e = Math.max(0, s.column ?? 0), n = /* @__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);
+          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,
+          y: a,
+          width: t.width,
+          height: c,
+          row: 0
+        };
+      }
+    }
+  };
+}
+const m = "PinItemPlugin", d = "把若干索引的项钉在顶部指定列，其余项从它们下方继续排。走 D1-A 布局钩子（calculateItemPosition），是旧版宣称但从未生效的能力。", p = "2.0.0", f = [
+  "layout",
+  "layout-hook",
+  "置顶"
+], g = [
+  {
+    name: "pinnedIndices",
+    type: "number[]",
+    default: "[]",
+    description: "要钉住的项索引"
+  },
+  {
+    name: "column",
+    type: "number",
+    default: "0",
+    description: "钉到第几列"
+  }
+], I = `// 把指定索引的项钉在顶部同一列，不参与常规列高推进（广告位 / 公告卡）。
+const Waterfall = withPlugins(WaterfallCore, [
+  createPinItemPlugin({
+    pinnedIndices: [],
+    column: 0,
+  }),
+]);
+
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, P = [
+  "置顶项不占常规列高：后续项从置顶块下方开始",
+  "支持多列分别置顶（column 可不同）",
+  "每次布局前重置偏移，items 变化后不会累加错位"
+], y = [
+  "信息流首位的推广卡",
+  "公告 / 置顶帖",
+  "需要固定在左上角的活动位"
+], h = [
+  "置顶项之间按 pinnedIndices 顺序纵向堆叠，同一列多条会依次往下排。",
+  "置顶会挤掉该列的正常网格位置，pinnedIndices 建议控制在 1~2 条。",
+  "换列后的 x 由布局引擎按本轮列宽补齐，插件只返回 column 即可 —— 自己用「列宽 + 间距」反推 x 会在间距由其它插件（GapPlugin）注入时算错。"
+], C = {
+  name: m,
+  description: d,
+  since: p,
+  tags: f,
+  config: g,
+  example: I,
+  features: P,
+  useCases: y,
+  notes: h
+};
+export {
+  w as c,
+  C as d
+};

package/dist/chunks/doc-f4Uijujv.js

@@ -0,0 +1,102 @@
+import { jsxs as u, jsx as f } from "react/jsx-runtime";
+function v(o = {}) {
+  const { log: i = !1, showOverlay: l = !1 } = o, n = /* @__PURE__ */ new Map(), s = () => Array.from(n.values()).reduce((t, e) => t + e, 0);
+  return {
+    name: "ClickAnalyticsPlugin",
+    enabled: !0,
+    getStats: () => ({
+      total: s(),
+      byIndex: Array.from(n.entries()).map(([t, e]) => ({ index: t, clicks: e })).sort((t, e) => t.index - e.index)
+    }),
+    hooks: {
+      onMount: (t) => {
+        t.sharedData?.set("click-count", s());
+      },
+      onItemClick: (t, e, c, r) => {
+        const d = (n.get(e) ?? 0) + 1;
+        n.set(e, d);
+        const a = s();
+        t.sharedData?.set("click-count", a), t.bus?.emit("analytics:click", { index: e, item: c, event: r, total: a }), t.forceUpdate?.(), i && console.log(`[ClickAnalytics] item=${e} total=${a}`);
+      },
+      renderOverlay: (t) => {
+        if (!l) return null;
+        const e = t.sharedData?.get("click-count") || 0;
+        return /* @__PURE__ */ u(
+          "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: [
+              "点击次数：",
+              e,
+              /* @__PURE__ */ f("div", { style: { fontSize: 12, fontWeight: 400, opacity: 0.85, marginTop: 4 }, children: "提示：点击任意卡片观察计数变化" })
+            ]
+          }
+        );
+      }
+    }
+  };
+}
+const g = "ClickAnalyticsPlugin", p = "统计每次项点击并累计总数，向 bus 发 `analytics:click`（带 index / item / total），`getStats()` 可随时取出按 index 的计数。默认只上报不显示角标，接入真实版式时不会被调试面板盖住内容。", m = "2.0.0", y = [
+  "interaction",
+  "埋点"
+], k = [
+  {
+    name: "log",
+    type: "boolean",
+    default: "false",
+    description: "是否在控制台打印每次点击"
+  },
+  {
+    name: "showOverlay",
+    type: "boolean",
+    default: "false",
+    description: "是否显示右上角计数角标"
+  }
+], b = `// 统计项点击次数，发 \`analytics:click\` 事件，可选角标与日志。
+const Waterfall = withPlugins(WaterfallCore, [
+  createClickAnalyticsPlugin({
+    log: false,
+    showOverlay: false,
+  }),
+]);
+
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, h = [
+  "点击总量 + 按 index 明细（getStats）",
+  "bus 事件可被外部订阅上报",
+  "角标默认关闭"
+], x = [
+  "内容流点击率统计",
+  "AB 实验埋点",
+  "调试点击行为"
+], C = [
+  "生产环境请把数据从 bus 事件或 getStats() 接到自己的埋点 SDK，不要让插件直接打日志。",
+  "计数只在内存里，刷新即清零 —— 想持久化要自己定时取 getStats() 上报。"
+], A = {
+  name: g,
+  description: p,
+  since: m,
+  tags: y,
+  config: k,
+  example: b,
+  features: h,
+  useCases: x,
+  notes: C
+};
+export {
+  v as c,
+  A as d
+};

package/dist/chunks/doc-gTAsLjVx.js

@@ -0,0 +1,55 @@
+function u(n) {
+  return {
+    name: "AlignmentPlugin",
+    priority: 60,
+    enabled: !0,
+    hooks: {
+      transformProps: (e) => ({ ...e, alignmentMode: n.mode }),
+      onResize: (e) => {
+        e.relayout?.();
+      }
+    }
+  };
+}
+const t = "AlignmentPlugin", s = "设置瀑布流的列分配策略。shortest 让每列尽量等高（视觉最自然），balanced 让每列项数接近，sequential 按 index 轮转（可预测位置，适合需要与外部索引对齐的场景）。", o = "2.0.0", a = [
+  "layout",
+  "布局"
+], i = [
+  {
+    name: "mode",
+    type: '"shortest" | "balanced" | "sequential"',
+    default: "shortest",
+    description: "列分配策略"
+  }
+], l = `// 指定列分配策略：最矮列优先（shortest）/ 项数均衡（balanced）/ 顺序轮转（sequential）。
+const Waterfall = withPlugins(WaterfallCore, [
+  createAlignmentPlugin({
+    mode: "shortest",
+  }),
+]);
+
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, r = [
+  "三种列分配策略",
+  "只改 props.alignmentMode，不影响其他配置",
+  "与 ResponsiveColumns / AutoColumn 正交"
+], c = [
+  "内容流：默认 shortest",
+  "等长卡片：balanced 更整齐",
+  "需要与后端顺序对齐：sequential"
+], m = [
+  "balanced 与 shortest 在列高相同时都取最左列，视觉上左偏是预期行为。"
+], d = {
+  name: t,
+  description: s,
+  since: o,
+  tags: a,
+  config: i,
+  example: l,
+  features: r,
+  useCases: c,
+  notes: m
+};
+export {
+  u as c,
+  d
+};