vane-waterfall 1.0.5 → 2.0.0

package/dist/chunks/doc-BXSy2aPP.js

@@ -0,0 +1,59 @@
+function A(t = {}) {
+  const s = t.getAnchorId || ((n) => n?.id);
+  let e;
+  return {
+    name: "ScrollAnchorPlugin",
+    enabled: !0,
+    hooks: {
+      onMount: (n) => {
+        e = n.bus?.on("anchor:scrollToId", (c) => {
+          const o = (n.props?.items || []).findIndex((i, r) => s(i, r) === c.id);
+          o >= 0 && n.scrollToItem?.(o, { behavior: "smooth", block: "start" });
+        });
+      },
+      onUnmount: () => e?.()
+    }
+  };
+}
+const a = "ScrollAnchorPlugin", l = '不需要自己算索引：外部只管 `bus.emit("anchor:scrollToId", { id })`，插件用 getAnchorId 找到对应项并滚过去。适合「从消息跳到某条内容」。', d = "2.0.0", m = [
+  "interaction",
+  "滚动"
+], u = [
+  {
+    name: "getAnchorId",
+    type: "(item, index) => string | number | undefined",
+    default: "item.id",
+    description: "从项里取锚点 id"
+  }
+], g = `// 监听 \`anchor:scrollToId\` 事件，按业务 id 滚动到对应项。
+const Waterfall = withPlugins(WaterfallCore, [
+  createScrollAnchorPlugin({
+    getAnchorId: "item.id",
+  }),
+]);
+
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, h = [
+  "按业务 id 定位，不用算下标",
+  "onMount 订阅 / onUnmount 退订（不泄漏）",
+  "平滑滚动"
+], f = [
+  "从通知跳转到具体卡片",
+  "目录点击定位",
+  "外链深链定位"
+], I = [
+  "目标项必须已在 items 里；分页场景请先切到对应页再发事件。"
+], b = {
+  name: a,
+  description: l,
+  since: d,
+  tags: m,
+  config: u,
+  example: g,
+  features: h,
+  useCases: f,
+  notes: I
+};
+export {
+  A as c,
+  b as d
+};

package/dist/chunks/doc-BfWnfTst.js

@@ -0,0 +1,83 @@
+function g(r = {}) {
+  return {
+    name: "SortPlugin",
+    priority: 30,
+    enabled: !0,
+    hooks: {
+      transformProps: (o) => {
+        const e = Array.isArray(o.items) ? o.items : [], t = o.sortComparator || r.comparator;
+        if (typeof t != "function") return o;
+        const s = [...e].sort((a, n) => {
+          try {
+            return t(a, n);
+          } catch {
+            return 0;
+          }
+        });
+        return { ...o, items: s };
+      },
+      onPropsChange: (o, e, t) => {
+        const s = e?.sortComparator, a = t?.sortComparator;
+        if (((typeof t?.scrollToTopOnSortChange == "boolean" ? t.scrollToTopOnSortChange : void 0) ?? !!r.scrollToTop) && s !== a) {
+          const l = t?.scrollToTopBehavior ?? r.scrollBehavior ?? "auto";
+          o.scrollToTop?.({ behavior: l });
+        }
+      }
+    }
+  };
+}
+const c = "SortPlugin", i = "用比较函数排序，优先读 `props.sortComparator`。排序总是在过滤之后、分页之前执行，保证「第 N 页」是排序后的第 N 页。", m = "2.0.0", p = [
+  "data",
+  "数据管线"
+], u = [
+  {
+    name: "comparator",
+    type: "(a, b) => number",
+    default: "—",
+    description: "默认比较函数，可被 props.sortComparator 覆盖"
+  },
+  {
+    name: "scrollToTop",
+    type: "boolean",
+    default: "false",
+    description: "排序变化后回顶"
+  },
+  {
+    name: "scrollBehavior",
+    type: '"auto" | "smooth"',
+    default: '"auto"',
+    description: "回顶行为"
+  }
+], d = `// 按比较函数排序 items，比较函数变化可自动回顶。
+const Waterfall = withPlugins(WaterfallCore, [
+  createSortPlugin({
+    scrollToTop: false,
+    scrollBehavior: "auto",
+  }),
+]);
+
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, f = [
+  "稳定排序（不改原数组）",
+  "比较函数抛错按相等处理",
+  "与 Filter / Search 顺序固定"
+], h = [
+  "价格 / 时间排序",
+  "热度排序",
+  "手动置顶项优先"
+], C = [
+  "排序会复制数组（`[...items].sort`），不会改调用方传入的 items。"
+], y = {
+  name: c,
+  description: i,
+  since: m,
+  tags: p,
+  config: u,
+  example: d,
+  features: f,
+  useCases: h,
+  notes: C
+};
+export {
+  g as c,
+  y as d
+};

package/dist/chunks/doc-BtzhgTYj.js

@@ -0,0 +1,85 @@
+import { jsxs as a, jsx as r } from "react/jsx-runtime";
+function h(t = {}) {
+  const s = t.title || "分组标题", i = t.showHint ?? !1;
+  return {
+    name: "StickyHeaderPlugin",
+    enabled: !0,
+    hooks: {
+      renderOverlay: (o) => {
+        const e = o.sharedData?.get("GROUPS") || /* @__PURE__ */ new Map(), n = e.size > 0 ? Array.from(e.keys())[0] : void 0;
+        return /* @__PURE__ */ a(
+          "div",
+          {
+            style: {
+              position: "sticky",
+              top: 0,
+              zIndex: 20,
+              background: "#111827",
+              color: "#fff",
+              borderBottom: "1px solid rgba(255,255,255,0.15)",
+              boxShadow: "0 4px 12px rgba(0,0,0,0.15)",
+              padding: "10px 14px",
+              fontSize: 15,
+              fontWeight: 600
+            },
+            children: [
+              s,
+              " ",
+              n !== void 0 ? `：${String(n)}` : "",
+              i ? /* @__PURE__ */ r("span", { style: { marginLeft: 8, fontSize: 12, opacity: 0.8 }, children: "向下滚动观察吸顶" }) : null
+            ]
+          }
+        );
+      }
+    }
+  };
+}
+const c = "StickyHeaderPlugin", l = "在滚动容器内渲染一条 `position: sticky` 的标题条，始终贴住容器顶部。装了 GroupingPlugin 时自动显示第一个分组名，也可用 title 写死。", d = "2.0.0", p = [
+  "ui",
+  "吸顶"
+], f = [
+  {
+    name: "title",
+    type: "string",
+    default: '"分组标题"',
+    description: "标题文案"
+  },
+  {
+    name: "showHint",
+    type: "boolean",
+    default: "false",
+    description: "是否显示「向下滚动观察」提示"
+  }
+], u = `// 滚动容器内的吸顶标题条，可与分组联动显示当前组。
+const Waterfall = withPlugins(WaterfallCore, [
+  createStickyHeaderPlugin({
+    title: "分组标题",
+    showHint: false,
+  }),
+]);
+
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, g = [
+  "sticky 吸顶，不依赖额外容器",
+  "与 Grouping 联动显示当前组",
+  "提示文案默认关闭"
+], m = [
+  "分组信息流",
+  "按日期分组的时间线",
+  "长列表的上下文提示"
+], y = [
+  "sticky 生效要求它作为滚动容器的直接子元素——由 composeSlots 保证，单测已锁。"
+], k = {
+  name: c,
+  description: l,
+  since: d,
+  tags: p,
+  config: f,
+  example: u,
+  features: g,
+  useCases: m,
+  notes: y
+};
+export {
+  h as c,
+  k as d
+};

package/dist/chunks/doc-C5xrHNoC.js

@@ -0,0 +1,70 @@
+function y(s = {}) {
+  const n = s.duration ?? 300, t = s.easing ?? "ease";
+  return {
+    name: "TransitionPlugin",
+    priority: 65,
+    enabled: !0,
+    hooks: {
+      onItemMount: (o, e, i) => {
+        i.style.transition = `transform ${n}ms ${t}, opacity ${n}ms ${t}`;
+      },
+      onLayout: (o) => {
+        o.itemRefs.forEach((e) => {
+          e && (e.style.transition = `transform ${n}ms ${t}, opacity ${n}ms ${t}`);
+        });
+      }
+    }
+  };
+}
+const a = "TransitionPlugin", r = "给每个项挂上 transform + opacity 的 CSS 过渡，布局重排、分页切换、筛选后重新排列时位置变化是滑过去的，不是瞬移。", c = "2.0.0", u = [
+  "perf",
+  "动效"
+], m = [
+  {
+    name: "duration",
+    type: "number",
+    default: "300",
+    description: "过渡时长 ms"
+  },
+  {
+    name: "easing",
+    type: "string",
+    default: "ease",
+    description: "缓动函数"
+  }
+], d = `// 布局变化时给项加 transform/opacity 过渡，插入新数据不「闪现」。
+const Waterfall = withPlugins(WaterfallCore, [
+  createTransitionPlugin({
+    duration: 300,
+    easing: "ease",
+  }),
+]);
+
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, l = [
+  "ReducedMotionPlugin"
+], f = [
+  "项位置变化平滑过渡",
+  "挂载时即生效（onItemMount）",
+  "与 ReducedMotionPlugin 互斥"
+], g = [
+  "筛选 / 排序后重排",
+  "分页切换",
+  "动态插入卡片"
+], p = [
+  "首屏大量项同时过渡会有一次「整体滑入」，想要更克制可以把 duration 降到 150ms。"
+], $ = {
+  name: a,
+  description: r,
+  since: c,
+  tags: u,
+  config: m,
+  example: d,
+  conflicts: l,
+  features: f,
+  useCases: g,
+  notes: p
+};
+export {
+  y as c,
+  $ as d
+};

package/dist/chunks/doc-CBHjiDG7.js

@@ -0,0 +1,88 @@
+function C(t = {}) {
+  const c = t.fields ?? [];
+  return {
+    name: "SearchPlugin",
+    priority: 20,
+    enabled: !0,
+    hooks: {
+      transformProps: (e) => {
+        const s = String(e.searchQuery ?? "").trim(), o = Array.isArray(e.items) ? e.items : [];
+        if (!s) return e;
+        const n = s.toLowerCase(), a = o.filter((r) => {
+          if (typeof r != "object" || r === null) return !1;
+          const i = c.length > 0 ? c : Object.keys(r);
+          for (const l of i) {
+            const u = r[l];
+            if (u != null && String(u).toLowerCase().includes(n)) return !0;
+          }
+          return !1;
+        });
+        return { ...e, items: a };
+      },
+      onPropsChange: (e, s, o) => {
+        const n = String(s?.searchQuery ?? ""), a = String(o?.searchQuery ?? "");
+        if (((typeof o?.scrollToTopOnSearchChange == "boolean" ? o.scrollToTopOnSearchChange : void 0) ?? !!t.scrollToTop) && n !== a) {
+          const l = o?.scrollToTopBehavior ?? t.scrollBehavior ?? "auto";
+          e.scrollToTop?.({ behavior: l });
+        }
+      }
+    }
+  };
+}
+const f = "SearchPlugin", d = "读取 `props.searchQuery`，在指定字段上做大小写不敏感的 `includes` 匹配。没指定字段就对对象的全部自有字段匹配。", h = "2.0.0", m = [
+  "data",
+  "数据管线",
+  "搜索"
+], p = [
+  {
+    name: "fields",
+    type: "(keyof T)[]",
+    default: "[]",
+    description: "参与匹配的字段；空则匹配全部自有字段"
+  },
+  {
+    name: "scrollToTop",
+    type: "boolean",
+    default: "false",
+    description: "关键词变化后回顶"
+  },
+  {
+    name: "scrollBehavior",
+    type: '"auto" | "smooth"',
+    default: '"auto"',
+    description: "回顶行为"
+  }
+], y = `// 按 props.searchQuery 做大小写不敏感的多字段包含匹配。
+const Waterfall = withPlugins(WaterfallCore, [
+  createSearchPlugin({
+    fields: [],
+    scrollToTop: false,
+    scrollBehavior: "auto",
+  }),
+]);
+
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, g = [
+  "大小写不敏感",
+  "多字段 OR 匹配",
+  "空关键词直接放行（不触发过滤）"
+], T = [
+  "站内搜索结果页",
+  "后台列表即时搜索",
+  "商品名 / 店铺名联合搜索"
+], S = [
+  "纯前端 `includes`，不排序也不做拼音；要相关性排序请在 Search 之后接 SortPlugin。"
+], b = {
+  name: f,
+  description: d,
+  since: h,
+  tags: m,
+  config: p,
+  example: y,
+  features: g,
+  useCases: T,
+  notes: S
+};
+export {
+  C as c,
+  b as d
+};

package/dist/chunks/doc-CTUoMe7o.js

@@ -0,0 +1,79 @@
+function b(n) {
+  if (!(n.minColumnWidth > 0))
+    throw new Error("[vane-waterfall] AutoColumnPlugin 需要正数的 minColumnWidth");
+  return {
+    name: "AutoColumnPlugin",
+    priority: 55,
+    enabled: !0,
+    hooks: {
+      calculateColumns: (s, i) => {
+        const t = s.props, e = t.columnGap ?? t.gap ?? 0, o = t.padding, l = typeof o == "number" ? o * 2 : (o?.left ?? 0) + (o?.right ?? 0), a = Math.max(0, i - l);
+        if (!a) return t.columns ?? 1;
+        const m = Math.max(
+          1,
+          Math.floor((a + e) / (n.minColumnWidth + e))
+        ), u = Math.max(1, n.minColumns ?? 1), c = n.maxColumns ?? Number.POSITIVE_INFINITY;
+        return Math.min(Math.max(m, u), c);
+      }
+    }
+  };
+}
+const r = "AutoColumnPlugin", d = "按「容器可用宽度 ÷ 最小列宽」自动决定列数，取代写死 3 列。走 D1-A 布局钩子（calculateColumns），拿到的是真实容器宽度，不是 window.innerWidth。", p = "2.0.0", C = [
+  "layout",
+  "layout-hook",
+  "响应式"
+], f = [
+  {
+    name: "minColumnWidth",
+    type: "number",
+    default: "—",
+    description: "每列最小宽度 px（必填）"
+  },
+  {
+    name: "maxColumns",
+    type: "number",
+    default: "Infinity",
+    description: "列数上限"
+  },
+  {
+    name: "minColumns",
+    type: "number",
+    default: "1",
+    description: "列数下限"
+  }
+], h = `// 按容器宽与最小列宽自动算列数，窄屏自动降列。
+const Waterfall = withPlugins(WaterfallCore, [
+  createAutoColumnPlugin({
+    maxColumns: "Infinity",
+    minColumns: 1,
+  }),
+]);
+
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, g = [
+  "ResponsiveColumnsPlugin"
+], x = [
+  "按容器宽度（不是视口宽度）算列数",
+  "列数上下限可夹",
+  "与 Gap / Padding 一起算，留白不吞列宽"
+], P = [
+  "响应式信息流",
+  "侧边栏宽度可拖动的后台看板",
+  "移动端 → 桌面端同一套代码"
+], y = [
+  "与 ResponsiveColumnsPlugin 同时装会互相覆盖列数，只选一个。"
+], I = {
+  name: r,
+  description: d,
+  since: p,
+  tags: C,
+  config: f,
+  example: h,
+  conflicts: g,
+  features: x,
+  useCases: P,
+  notes: y
+};
+export {
+  b as c,
+  I as d
+};

package/dist/chunks/doc-CcPFavOs.js

@@ -0,0 +1,56 @@
+function d(n) {
+  return {
+    name: "FixedHeightPlugin",
+    priority: 45,
+    enabled: !0,
+    hooks: {
+      transformProps: (t) => {
+        const { itemHeight: i } = n, s = (t.items || []).map((e) => typeof e == "object" && e !== null && "height" in e ? { ...e, height: i } : e);
+        return { ...t, items: s };
+      },
+      onResize: (t) => {
+        t.relayout?.();
+      }
+    }
+  };
+}
+const o = "FixedHeightPlugin", a = "把数据里带 height 字段的项统一改写为固定高度，瀑布流变成等高网格。适合「图少字多」的卡片流——等高反而更好扫读。", r = "2.0.0", c = [
+  "layout",
+  "网格"
+], g = [
+  {
+    name: "itemHeight",
+    type: "number",
+    default: "—",
+    description: "统一项高 px（必填）"
+  }
+], l = `// 把项高度统一成固定值，瀑布流退化为等高网格。
+const Waterfall = withPlugins(WaterfallCore, [
+  createFixedHeightPlugin(),
+]);
+
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, u = [
+  "等高网格（严格对齐）",
+  "只改数据里已有的 height 字段",
+  "与 Pagination / Filter 组合仍然成立"
+], h = [
+  "商品列表（图固定比例）",
+  "后台看板卡片",
+  "需要严格栅格对齐的页面"
+], m = [
+  "数据里没有 height 字段时不会生效——高度由 renderItem 自己的内容决定。"
+], f = {
+  name: o,
+  description: a,
+  since: r,
+  tags: c,
+  config: g,
+  example: l,
+  features: u,
+  useCases: h,
+  notes: m
+};
+export {
+  d as c,
+  f as d
+};

package/dist/chunks/doc-CraXjOaA.js

@@ -0,0 +1,68 @@
+function y(s) {
+  const e = /* @__PURE__ */ new Set(), o = () => {
+    if (e.size <= s.poolSize) return;
+    const t = e.values().next().value;
+    typeof t == "number" && e.delete(t);
+  };
+  return {
+    name: "RecyclePlugin",
+    enabled: !0,
+    hooks: {
+      onItemEnterViewport: (t, n) => {
+        const i = t.getItemRef(n);
+        i && (i.style.visibility = "visible"), e.add(n), o();
+      },
+      onItemLeaveViewport: (t, n) => {
+        const i = t.getItemRef(n);
+        i && (i.style.visibility = "hidden"), e.delete(n);
+      },
+      onItemUnmount: (t, n) => {
+        e.delete(n);
+      },
+      onUnmount: () => {
+        e.clear();
+      }
+    }
+  };
+}
+const c = "RecyclePlugin", l = "纯绘制层优化：项离开视口就 `visibility: hidden`，回来再显示。DOM 节点不销毁，滚动位置与已加载的图片都保留，适合「项里有视频/Canvas，重建代价高」的场景。", a = "2.0.0", r = [
+  "interaction",
+  "性能"
+], u = [
+  {
+    name: "poolSize",
+    type: "number",
+    default: "—",
+    description: "同时保持可见的项数上限（超出则回收最早的）"
+  }
+], m = `// 视口外的项设 \`visibility: hidden\`，降低长列表的绘制压力。
+const Waterfall = withPlugins(WaterfallCore, [
+  createRecyclePlugin(),
+]);
+
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, d = [
+  "不销毁 DOM，只隐藏",
+  "项内媒体不重新加载",
+  "与虚拟化正交（一个省绘制、一个省节点）"
+], f = [
+  "项内含视频 / canvas",
+  "长列表滚动发虚",
+  "低端设备省电"
+], v = [
+  "与 Core 的 `virtualize` 同开会让项被卸载又隐藏，收益互相抵消，建议只选一个。",
+  "只改 visibility 不改布局，所以不会引起重排。"
+], p = {
+  name: c,
+  description: l,
+  since: a,
+  tags: r,
+  config: u,
+  example: m,
+  features: d,
+  useCases: f,
+  notes: v
+};
+export {
+  y as c,
+  p as d
+};

package/dist/chunks/doc-DElLNjIc.js

@@ -0,0 +1,61 @@
+function b(e) {
+  const c = Object.values(e.breakpoints).sort((s, n) => s.width - n.width);
+  return {
+    name: "ResponsiveColumnsPlugin",
+    priority: 55,
+    enabled: !0,
+    hooks: {
+      calculateColumns: (s, n) => {
+        const t = e.fallbackColumns ?? s.props.columns ?? 3;
+        if (!n) return t;
+        let o = t;
+        for (const l of c)
+          n >= l.width && (o = l.columns);
+        return o;
+      }
+    }
+  };
+}
+const u = "ResponsiveColumnsPlugin", a = "用一张断点表控制列数，命中哪档用哪档。走 D1-A 布局钩子（calculateColumns），按容器宽度匹配断点。", i = "2.0.0", r = [
+  "layout",
+  "layout-hook",
+  "响应式"
+], m = [
+  {
+    name: "breakpoints",
+    type: "Record<string, { width: number; columns: number }>",
+    default: "—",
+    description: "断点表，按 width 升序匹配"
+  }
+], p = `// 按断点表决定列数（如 640 → 2 列、1024 → 3 列、1440 → 4 列）。
+const Waterfall = withPlugins(WaterfallCore, [
+  createResponsiveColumnsPlugin(),
+]);
+
+<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;`, f = [
+  "AutoColumnPlugin"
+], d = [
+  "断点表驱动，设计稿几档就写几档",
+  "按容器宽度而非视口宽度匹配",
+  "未命中任何断点时回退到 props.columns"
+], C = [
+  "严格对齐设计断点的站点",
+  "同一个组件嵌在不同宽度的容器里"
+], g = [
+  "与 AutoColumnPlugin 互斥。"
+], h = {
+  name: u,
+  description: a,
+  since: i,
+  tags: r,
+  config: m,
+  example: p,
+  conflicts: f,
+  features: d,
+  useCases: C,
+  notes: g
+};
+export {
+  b as c,
+  h as d
+};