vane-waterfall 1.0.4 → 2.0.0

package/dist/components/WaterfallPlugin/virtualize.d.ts

@@ -0,0 +1,62 @@
+import { ItemPosition } from './plugins/types';
+export interface VirtualizeOptions {
+    /** 视口上下各多渲染几屏，默认 1 */
+    overscan?: number;
+    /** 未测量项的兜底高度，默认 240。不设则虚拟化等于不开（未测量项不占位） */
+    estimateHeight?: number;
+    /**
+     * 是否允许高度动态变化（图片加载后重排），默认 true。
+     * 关掉后项一旦测量就不再重新监听尺寸，适合固定高度的商品卡。
+     */
+    dynamicHeights?: boolean;
+    /**
+     * 未测量项的高度估值是否跟随实测样本自适应，默认 **true**。
+     *
+     * 为什么要有：`estimateHeight` 是一个固定值，而真实项高必然是一个区间。
+     * 只要真实项比估值高，同一列里排在它后面的未测量项就会被压上去 —— 表现为
+     * 快速滚动时卡片重叠。改成跟实测样本的分位数走之后，估值天然贴着这份数据，
+     * 重叠幅度可以压到个位数像素（见 `resolveEstimateHeight`）。
+     *
+     * 设为 false 时严格用 `estimateHeight`：适合「所有项等高」的固定高卡片，
+     * 此时估值就是精确值，不需要样本。
+     */
+    adaptiveEstimate?: boolean;
+    /**
+     * 自适应时取样本的哪个分位，默认 0.5（中位数）。
+     *
+     * 为什么是中位数：总高是「所有项高度之和」决定的，中位数是使总高误差最小的
+     * 单值估计。重叠问题不靠抬高估值解决 —— 抬高估值只是把误差从「重叠」换成
+     * 「滚动条虚长」，后者更持久、更刺眼。真正压住重叠的是「测量到就立刻重排」
+     * （`scheduleLayoutNow`），它让估值误差只存在一帧、且通常落在视口外。
+     *
+     * 如果想更保守（例如项高分布极其离散），可以调到 0.9。
+     */
+    estimateQuantile?: number;
+}
+/** 自适应估值至少要有这么多实测样本才敢用，否则仍走 `estimateHeight` */
+export declare const MIN_ESTIMATE_SAMPLES = 8;
+/**
+ * 算未测量项该用多高。
+ *
+ * @param samples 已测量到的项高（可为空）
+ * @param fallback `estimateHeight`，冷启动 / 关闭自适应时用
+ * @param quantile 分位，默认 0.5（中位数）
+ */
+export declare function resolveEstimateHeight(samples: Iterable<number>, fallback: number, quantile?: number): number;
+export interface VisibleRange {
+    start: number;
+    end: number;
+    /** 命中范围之外还有多少项没渲染（调试面板用） */
+    hiddenCount: number;
+}
+/**
+ * 计算需要渲染的索引区间（闭区间）。
+ *
+ * @param positions 全量布局结果
+ * @param totalCount 数据总长（含尚未进入布局的新项）
+ * @param scrollTop 容器滚动偏移
+ * @param viewportHeight 容器可视高度
+ * @param overscan 上下各多渲染几屏
+ */
+export declare function computeVisibleRange(positions: Map<number, ItemPosition>, totalCount: number, scrollTop: number, viewportHeight: number, overscan?: number): VisibleRange;
+//# sourceMappingURL=virtualize.d.ts.map

package/dist/components/WaterfallPlugin/virtualize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtualize.d.ts","sourceRoot":"","sources":["../../../src/components/WaterfallPlugin/virtualize.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD,MAAM,WAAW,iBAAiB;IAChC,sBAAsB;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;;;;OASG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,gDAAgD;AAChD,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,EACzB,QAAQ,EAAE,MAAM,EAChB,QAAQ,SAAM,GACb,MAAM,CAWR;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,4BAA4B;IAC5B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,EACpC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,EACtB,QAAQ,SAAI,GACX,YAAY,CA+Cd"}

package/dist/components/WaterfallPlugin/{plugins/withPlugins.d.ts → withPlugins.d.ts}

@@ -1,8 +1,10 @@
-import { WaterfallPlugin } from './types';
 import { default as React } from 'react';
-import { WaterfallCoreProps, WaterfallCoreRef } from '../core/WaterfallCore';
+import { WaterfallPlugin } from './plugins/types';
+import { WaterfallCoreProps, WaterfallCoreRef } from './WaterfallCore';
 export interface WithPluginsConfig<T = any> {
     plugins: WaterfallPlugin<T>[];
     enableDebug?: boolean;
 }
 export declare function withPlugins<T = any>(WrappedComponent: React.ForwardRefExoticComponent<React.PropsWithoutRef<WaterfallCoreProps<T>> & React.RefAttributes<WaterfallCoreRef>>, config: WithPluginsConfig<T> | WaterfallPlugin<T>[]): React.ForwardRefExoticComponent<WaterfallCoreProps<T> & React.RefAttributes<WaterfallCoreRef>>;
+export default withPlugins;
+//# sourceMappingURL=withPlugins.d.ts.map

package/dist/components/WaterfallPlugin/withPlugins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withPlugins.d.ts","sourceRoot":"","sources":["../../../src/components/WaterfallPlugin/withPlugins.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAwE,MAAM,OAAO,CAAC;AAG7F,OAAO,KAAK,EAMV,eAAe,EAEhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAE5E,MAAM,WAAW,iBAAiB,CAAC,CAAC,GAAG,GAAG;IACxC,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9B,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AA2DD,wBAAgB,WAAW,CAAC,CAAC,GAAG,GAAG,EACjC,gBAAgB,EAAE,KAAK,CAAC,yBAAyB,CAC/C,KAAK,CAAC,eAAe,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,GAC1C,KAAK,CAAC,aAAa,CAAC,gBAAgB,CAAC,CACxC,EACD,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,EAAE,kGAmYpD;AAED,eAAe,WAAW,CAAC"}

package/dist/custom-plugins/A11yPlugin/create.d.ts

@@ -0,0 +1,23 @@
+import { WaterfallPlugin } from '../../components/WaterfallPlugin/plugins/types';
+export type A11yConfig = {
+    /** 为容器设置 ARIA role（默认 list） */
+    containerRole?: string;
+    /** 为项设置 ARIA role（默认 listitem） */
+    itemRole?: string;
+    /** 是否给项添加 tabindex 便于键盘焦点（默认 true） */
+    enableTabIndex?: boolean;
+    /** 容器 aria-label（默认 "Waterfall list"） */
+    containerLabel?: string;
+};
+/**
+ * A11yPlugin - 可访问性增强：容器 / 项的 ARIA 语义 + 键盘聚焦。
+ *
+ * 与旧版的两处差别：
+ *  1. 容器属性改在 `onMount` / `onLayoutComplete` 里写。旧版写在 `renderOverlay`
+ *     里——那是渲染期副作用，React 并发渲染下可能被丢弃或执行多次；
+ *  2. `renderItemWrapper` 的签名统一成 `(context, node, index)`。旧版写的是
+ *     `(context, content, index)`，而 DragReorder 写的是 `(context, index, item, children)`，
+ *     同一个钩子两套参数顺序，靠"谁先装"决定传入什么，属于隐蔽的错位 bug。
+ */
+export declare function createA11yPlugin<T = any>(config?: A11yConfig): WaterfallPlugin<T>;
+//# sourceMappingURL=create.d.ts.map

package/dist/custom-plugins/A11yPlugin/create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../../src/custom-plugins/A11yPlugin/create.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EAEhB,MAAM,gDAAgD,CAAC;AAExD,MAAM,MAAM,UAAU,GAAG;IACvB,+BAA+B;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,yCAAyC;IACzC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,GAAG,EAAE,MAAM,GAAE,UAAe,GAAG,eAAe,CAAC,CAAC,CAAC,CAqCrF"}

package/dist/custom-plugins/A11yPlugin/doc.json.d.ts

@@ -0,0 +1,52 @@
+declare const _default: {
+  "name": "A11yPlugin",
+  "description": "把瀑布流补成读屏可理解的列表：容器 `role=list` + `aria-label`，每项 `role=listitem` + `aria-posinset` / `aria-setsize`，并可选加 `tabIndex` 让键盘能逐项聚焦。",
+  "since": "2.0.0",
+  "tags": [
+    "ui",
+    "a11y"
+  ],
+  "config": [
+    {
+      "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"
+    }
+  ],
+  "example": "// 给容器与项补 ARIA role / label / posinset，支持键盘 Tab 遍历。\nconst Waterfall = withPlugins(WaterfallCore, [\n  createA11yPlugin({\n    containerRole: \"list\",\n    itemRole: \"listitem\",\n    enableTabIndex: true,\n  }),\n]);\n\n<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;",
+  "features": [
+    "容器 / 项 role 成对补齐",
+    "aria-posinset + aria-setsize 正确标注序号",
+    "键盘可逐项聚焦"
+  ],
+  "useCases": [
+    "政务 / 金融等合规站点",
+    "读屏用户可用的信息流",
+    "键盘操作优先的桌面端"
+  ],
+  "notes": [
+    "项数很多时 `tabIndex=0` 会让 Tab 变长，建议配合「跳转主内容」链接使用。"
+  ]
+}
+;
+
+export default _default;

package/dist/custom-plugins/A11yPlugin/index.d.ts

@@ -0,0 +1,11 @@
+import { createA11yPlugin as create, A11yConfig } from './create';
+import { PluginDoc } from '@vane/plugin-core';
+/**
+ * 工厂 + `.meta`：`typeof create` 保留原工厂的泛型签名，
+ * `.meta` 供 docs:plugins 与 demo 工坊读取配置项。
+ */
+export declare const createA11yPlugin: typeof create & {
+    meta: PluginDoc;
+};
+export type { A11yConfig };
+//# sourceMappingURL=index.d.ts.map

package/dist/custom-plugins/A11yPlugin/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/custom-plugins/A11yPlugin/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,gBAAgB,IAAI,MAAM,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAwD,OAAO,MAAM,GAAG;IACnG,IAAI,EAAE,SAAS,CAAC;CACjB,CAAC;AAEF,YAAY,EAAE,UAAU,EAAE,CAAC"}

package/dist/custom-plugins/A11yPlugin/index.js

@@ -0,0 +1,5 @@
+import { c as e, d as t } from "../../chunks/doc-kTbJE7rY.js";
+const c = Object.assign(e, { meta: t });
+export {
+  c as createA11yPlugin
+};

package/dist/{components/WaterfallPlugin/custom-plugins/Alignment/index.d.ts → custom-plugins/AlignmentPlugin/create.d.ts}

@@ -1,6 +1,6 @@
-import { WaterfallPlugin } from '../../plugins/types';
+import { WaterfallPlugin } from '../../components/WaterfallPlugin/plugins/types';
 export type AlignmentMode = "shortest" | "balanced" | "sequential";
-type AlignmentConfig = {
+export type AlignmentConfig = {
     /** 列分配策略 */
     mode: AlignmentMode;
 };
@@ -9,4 +9,4 @@ type AlignmentConfig = {
  * 通过设置 props.alignmentMode 来影响核心布局算法的列选择逻辑
  */
 export declare function createAlignmentPlugin<T = any>(config: AlignmentConfig): WaterfallPlugin<T>;
-export {};
+//# sourceMappingURL=create.d.ts.map

package/dist/custom-plugins/AlignmentPlugin/create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../../src/custom-plugins/AlignmentPlugin/create.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gDAAgD,CAAC;AAEtF,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,UAAU,GAAG,YAAY,CAAC;AAEnE,MAAM,MAAM,eAAe,GAAG;IAC5B,YAAY;IACZ,IAAI,EAAE,aAAa,CAAC;CACrB,CAAC;AAEF;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,GAAG,GAAG,EAAE,MAAM,EAAE,eAAe,GAAG,eAAe,CAAC,CAAC,CAAC,CAc1F"}

package/dist/custom-plugins/AlignmentPlugin/doc.json.d.ts

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

package/dist/custom-plugins/AlignmentPlugin/index.d.ts

@@ -0,0 +1,11 @@
+import { createAlignmentPlugin as create, AlignmentConfig } from './create';
+import { PluginDoc } from '@vane/plugin-core';
+/**
+ * 工厂 + `.meta`：`typeof create` 保留原工厂的泛型签名，
+ * `.meta` 供 docs:plugins 与 demo 工坊读取配置项。
+ */
+export declare const createAlignmentPlugin: typeof create & {
+    meta: PluginDoc;
+};
+export type { AlignmentConfig };
+//# sourceMappingURL=index.d.ts.map

package/dist/custom-plugins/AlignmentPlugin/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/custom-plugins/AlignmentPlugin/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,qBAAqB,IAAI,MAAM,EAAE,MAAM,UAAU,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAEhD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAwD,OAAO,MAAM,GAAG;IACxG,IAAI,EAAE,SAAS,CAAC;CACjB,CAAC;AAEF,YAAY,EAAE,eAAe,EAAE,CAAC"}

package/dist/custom-plugins/AlignmentPlugin/index.js

@@ -0,0 +1,5 @@
+import { c as e, d as t } from "../../chunks/doc-gTAsLjVx.js";
+const a = Object.assign(e, { meta: t });
+export {
+  a as createAlignmentPlugin
+};

package/dist/custom-plugins/AutoColumnPlugin/create.d.ts

@@ -0,0 +1,18 @@
+import { WaterfallPlugin } from '../../components/WaterfallPlugin/plugins/types';
+export type AutoColumnConfig = {
+    /** 每列最小宽度（含内容区，不含列间距） */
+    minColumnWidth: number;
+    /** 最大列数（可选） */
+    maxColumns?: number;
+    /** 最小列数（可选，默认 1） */
+    minColumns?: number;
+};
+/**
+ * AutoColumnPlugin - 按「容器可用宽度 ÷ 最小列宽」自动决定列数。
+ *
+ * 走 D1-A 布局钩子 `calculateColumns`：容器宽度与 padding / columnGap 都由 Core
+ * 现算好传进来，不用再拿 window.innerWidth 近似（旧版那样在窄容器里会多排一列）。
+ * 公式：columns = floor((available + columnGap) / (minColumnWidth + columnGap))
+ */
+export declare function createAutoColumnPlugin<T = any>(config: AutoColumnConfig): WaterfallPlugin<T>;
+//# sourceMappingURL=create.d.ts.map

package/dist/custom-plugins/AutoColumnPlugin/create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../../src/custom-plugins/AutoColumnPlugin/create.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EAEhB,MAAM,gDAAgD,CAAC;AAExD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,yBAAyB;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oBAAoB;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,GAAG,GAAG,EAC5C,MAAM,EAAE,gBAAgB,GACvB,eAAe,CAAC,CAAC,CAAC,CAgCpB"}

package/dist/custom-plugins/AutoColumnPlugin/doc.json.d.ts

@@ -0,0 +1,50 @@
+declare const _default: {
+  "name": "AutoColumnPlugin",
+  "description": "按「容器可用宽度 ÷ 最小列宽」自动决定列数，取代写死 3 列。走 D1-A 布局钩子（calculateColumns），拿到的是真实容器宽度，不是 window.innerWidth。",
+  "since": "2.0.0",
+  "tags": [
+    "layout",
+    "layout-hook",
+    "响应式"
+  ],
+  "config": [
+    {
+      "name": "minColumnWidth",
+      "type": "number",
+      "default": "—",
+      "description": "每列最小宽度 px（必填）"
+    },
+    {
+      "name": "maxColumns",
+      "type": "number",
+      "default": "Infinity",
+      "description": "列数上限"
+    },
+    {
+      "name": "minColumns",
+      "type": "number",
+      "default": "1",
+      "description": "列数下限"
+    }
+  ],
+  "example": "// 按容器宽与最小列宽自动算列数，窄屏自动降列。\nconst Waterfall = withPlugins(WaterfallCore, [\n  createAutoColumnPlugin({\n    maxColumns: \"Infinity\",\n    minColumns: 1,\n  }),\n]);\n\n<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;",
+  "conflicts": [
+    "ResponsiveColumnsPlugin"
+  ],
+  "features": [
+    "按容器宽度（不是视口宽度）算列数",
+    "列数上下限可夹",
+    "与 Gap / Padding 一起算，留白不吞列宽"
+  ],
+  "useCases": [
+    "响应式信息流",
+    "侧边栏宽度可拖动的后台看板",
+    "移动端 → 桌面端同一套代码"
+  ],
+  "notes": [
+    "与 ResponsiveColumnsPlugin 同时装会互相覆盖列数，只选一个。"
+  ]
+}
+;
+
+export default _default;

package/dist/custom-plugins/AutoColumnPlugin/index.d.ts

@@ -0,0 +1,11 @@
+import { createAutoColumnPlugin as create, AutoColumnConfig } from './create';
+import { PluginDoc } from '@vane/plugin-core';
+/**
+ * 工厂 + `.meta`：`typeof create` 保留原工厂的泛型签名，
+ * `.meta` 供 docs:plugins 与 demo 工坊读取配置项。
+ */
+export declare const createAutoColumnPlugin: typeof create & {
+    meta: PluginDoc;
+};
+export type { AutoColumnConfig };
+//# sourceMappingURL=index.d.ts.map

package/dist/custom-plugins/AutoColumnPlugin/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/custom-plugins/AutoColumnPlugin/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,sBAAsB,IAAI,MAAM,EAAE,MAAM,UAAU,CAAC;AAC5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAEjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAwD,OAAO,MAAM,GAAG;IACzG,IAAI,EAAE,SAAS,CAAC;CACjB,CAAC;AAEF,YAAY,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/custom-plugins/AutoColumnPlugin/index.js

@@ -0,0 +1,5 @@
+import { c as o, d as t } from "../../chunks/doc-CTUoMe7o.js";
+const a = Object.assign(o, { meta: t });
+export {
+  a as createAutoColumnPlugin
+};

package/dist/{components/WaterfallPlugin/custom-plugins/Bookmark/index.d.ts → custom-plugins/BookmarkPlugin/create.d.ts}

@@ -1,5 +1,5 @@
-import { WaterfallPlugin } from '../../plugins/types';
-type BookmarkConfig = {
+import { WaterfallPlugin } from '../../components/WaterfallPlugin/plugins/types';
+export type BookmarkConfig = {
     /** localStorage 键名 */
     storageKey?: string;
     /** 滚动行为 */
@@ -12,4 +12,4 @@ type BookmarkConfig = {
  * - 忽略输入框/可编辑元素中的按键
  */
 export declare function createBookmarkPlugin<T = any>(config?: BookmarkConfig): WaterfallPlugin<T>;
-export {};
+//# sourceMappingURL=create.d.ts.map

package/dist/custom-plugins/BookmarkPlugin/create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../../src/custom-plugins/BookmarkPlugin/create.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gDAAgD,CAAC;AAEtF,MAAM,MAAM,cAAc,GAAG;IAC3B,sBAAsB;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW;IACX,cAAc,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;CACpC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,GAAG,GAAG,EAAE,MAAM,GAAE,cAAmB,GAAG,eAAe,CAAC,CAAC,CAAC,CA8D7F"}

package/dist/custom-plugins/BookmarkPlugin/doc.json.d.ts

@@ -0,0 +1,41 @@
+declare const _default: {
+  "name": "BookmarkPlugin",
+  "description": "长列表读到一半要跳走时按 **B** 存位置，回来按 **R** 复原。焦点在输入框/可编辑区域时不拦截按键。",
+  "since": "2.0.0",
+  "tags": [
+    "ui",
+    "滚动",
+    "快捷键"
+  ],
+  "config": [
+    {
+      "name": "storageKey",
+      "type": "string",
+      "default": "\"waterfall-bookmark\"",
+      "description": "localStorage 键名"
+    },
+    {
+      "name": "scrollBehavior",
+      "type": "\"auto\" | \"smooth\"",
+      "default": "\"smooth\"",
+      "description": "恢复时的滚动行为"
+    }
+  ],
+  "example": "// 按 B 记录滚动位置、按 R 跳回（localStorage），忽略输入框按键。\nconst Waterfall = withPlugins(WaterfallCore, [\n  createBookmarkPlugin({\n    storageKey: \"waterfall-bookmark\",\n    scrollBehavior: \"smooth\",\n  }),\n]);\n\n<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;",
+  "features": [
+    "B 存 / R 取，零 UI 侵入",
+    "自动区分容器滚动与页面滚动",
+    "输入框内不误触"
+  ],
+  "useCases": [
+    "长文列表阅读",
+    "后台大表格浏览",
+    "演示时快速复位"
+  ],
+  "notes": [
+    "键名全局共用，一个页面里多处瀑布流请各自传不同的 storageKey。"
+  ]
+}
+;
+
+export default _default;

package/dist/custom-plugins/BookmarkPlugin/index.d.ts

@@ -0,0 +1,11 @@
+import { createBookmarkPlugin as create, BookmarkConfig } from './create';
+import { PluginDoc } from '@vane/plugin-core';
+/**
+ * 工厂 + `.meta`：`typeof create` 保留原工厂的泛型签名，
+ * `.meta` 供 docs:plugins 与 demo 工坊读取配置项。
+ */
+export declare const createBookmarkPlugin: typeof create & {
+    meta: PluginDoc;
+};
+export type { BookmarkConfig };
+//# sourceMappingURL=index.d.ts.map

package/dist/custom-plugins/BookmarkPlugin/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/custom-plugins/BookmarkPlugin/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,oBAAoB,IAAI,MAAM,EAAE,MAAM,UAAU,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAwD,OAAO,MAAM,GAAG;IACvG,IAAI,EAAE,SAAS,CAAC;CACjB,CAAC;AAEF,YAAY,EAAE,cAAc,EAAE,CAAC"}

package/dist/custom-plugins/BookmarkPlugin/index.js

@@ -0,0 +1,5 @@
+import { c as o, d as a } from "../../chunks/doc-BP0DmB7-.js";
+const r = Object.assign(o, { meta: a });
+export {
+  r as createBookmarkPlugin
+};

package/dist/custom-plugins/ClickAnalyticsPlugin/create.d.ts

@@ -0,0 +1,25 @@
+import { WaterfallPlugin } from '../../components/WaterfallPlugin/plugins/types';
+export type ClickAnalyticsConfig = {
+    /** 是否在控制台打印每次点击（默认 false） */
+    log?: boolean;
+    /** 是否显示右上角计数角标（默认 false，生产版式应关闭） */
+    showOverlay?: boolean;
+};
+/** `getStats()` 的返回形状：够平，直接 `JSON.stringify` 就能上报 */
+export type ClickAnalyticsStats = {
+    total: number;
+    byIndex: Array<{
+        index: number;
+        clicks: number;
+    }>;
+};
+/**
+ * ClickAnalyticsPlugin - 点击分析（基础版）
+ * - 统计点击次数，向 bus 发送事件：analytics:click
+ * - 可选控制台输出日志
+ * - `getStats()` 把内存里的计数吐出来，方便接到自己的上报通道
+ */
+export declare function createClickAnalyticsPlugin<T = any>(config?: ClickAnalyticsConfig): WaterfallPlugin<T> & {
+    getStats: () => ClickAnalyticsStats;
+};
+//# sourceMappingURL=create.d.ts.map

package/dist/custom-plugins/ClickAnalyticsPlugin/create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../../src/custom-plugins/ClickAnalyticsPlugin/create.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gDAAgD,CAAC;AAEtF,MAAM,MAAM,oBAAoB,GAAG;IACjC,6BAA6B;IAC7B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,oCAAoC;IACpC,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,qDAAqD;AACrD,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACnD,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,GAAG,GAAG,EAChD,MAAM,GAAE,oBAAyB,GAChC,eAAe,CAAC,CAAC,CAAC,GAAG;IAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;CAAE,CAgE9D"}

package/dist/custom-plugins/ClickAnalyticsPlugin/doc.json.d.ts

@@ -0,0 +1,41 @@
+declare const _default: {
+  "name": "ClickAnalyticsPlugin",
+  "description": "统计每次项点击并累计总数，向 bus 发 `analytics:click`（带 index / item / total），`getStats()` 可随时取出按 index 的计数。默认只上报不显示角标，接入真实版式时不会被调试面板盖住内容。",
+  "since": "2.0.0",
+  "tags": [
+    "interaction",
+    "埋点"
+  ],
+  "config": [
+    {
+      "name": "log",
+      "type": "boolean",
+      "default": "false",
+      "description": "是否在控制台打印每次点击"
+    },
+    {
+      "name": "showOverlay",
+      "type": "boolean",
+      "default": "false",
+      "description": "是否显示右上角计数角标"
+    }
+  ],
+  "example": "// 统计项点击次数，发 `analytics:click` 事件，可选角标与日志。\nconst Waterfall = withPlugins(WaterfallCore, [\n  createClickAnalyticsPlugin({\n    log: false,\n    showOverlay: false,\n  }),\n]);\n\n<Waterfall items={items} renderItem={(item) => <Card data={item} />} />;",
+  "features": [
+    "点击总量 + 按 index 明细（getStats）",
+    "bus 事件可被外部订阅上报",
+    "角标默认关闭"
+  ],
+  "useCases": [
+    "内容流点击率统计",
+    "AB 实验埋点",
+    "调试点击行为"
+  ],
+  "notes": [
+    "生产环境请把数据从 bus 事件或 getStats() 接到自己的埋点 SDK，不要让插件直接打日志。",
+    "计数只在内存里，刷新即清零 —— 想持久化要自己定时取 getStats() 上报。"
+  ]
+}
+;
+
+export default _default;

package/dist/custom-plugins/ClickAnalyticsPlugin/index.d.ts

@@ -0,0 +1,11 @@
+import { createClickAnalyticsPlugin as create, ClickAnalyticsConfig, ClickAnalyticsStats } from './create';
+import { PluginDoc } from '@vane/plugin-core';
+/**
+ * 工厂 + `.meta`：`typeof create` 保留原工厂的泛型签名，
+ * `.meta` 供 docs:plugins 与 demo 工坊读取配置项。
+ */
+export declare const createClickAnalyticsPlugin: typeof create & {
+    meta: PluginDoc;
+};
+export type { ClickAnalyticsConfig, ClickAnalyticsStats };
+//# sourceMappingURL=index.d.ts.map

package/dist/custom-plugins/ClickAnalyticsPlugin/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/custom-plugins/ClickAnalyticsPlugin/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,0BAA0B,IAAI,MAAM,EAAE,MAAM,UAAU,CAAC;AAChE,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAE1E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,0BAA0B,EAAwD,OAAO,MAAM,GAAG;IAC7G,IAAI,EAAE,SAAS,CAAC;CACjB,CAAC;AAEF,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,CAAC"}

package/dist/custom-plugins/ClickAnalyticsPlugin/index.js

@@ -0,0 +1,5 @@
+import { c, d as t } from "../../chunks/doc-f4Uijujv.js";
+const i = Object.assign(c, { meta: t });
+export {
+  i as createClickAnalyticsPlugin
+};

package/dist/{components/WaterfallPlugin/custom-plugins/DebounceLayout/index.d.ts → custom-plugins/DebounceLayoutPlugin/create.d.ts}

@@ -1,5 +1,5 @@
-import { WaterfallPlugin } from '../../plugins/types';
-type DebounceConfig = {
+import { WaterfallPlugin } from '../../components/WaterfallPlugin/plugins/types';
+export type DebounceConfig = {
     /** 布局防抖延迟（ms） */
     delay: number;
 };
@@ -7,4 +7,4 @@ type DebounceConfig = {
  * DebounceLayoutPlugin - 调整核心布局的防抖延迟
  */
 export declare function createDebounceLayoutPlugin<T = any>(config: DebounceConfig): WaterfallPlugin<T>;
-export {};
+//# sourceMappingURL=create.d.ts.map

package/dist/custom-plugins/DebounceLayoutPlugin/create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../../src/custom-plugins/DebounceLayoutPlugin/create.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gDAAgD,CAAC;AAEtF,MAAM,MAAM,cAAc,GAAG;IAC3B,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,GAAG,GAAG,EAAE,MAAM,EAAE,cAAc,GAAG,eAAe,CAAC,CAAC,CAAC,CAW9F"}

package/dist/custom-plugins/DebounceLayoutPlugin/doc.json.d.ts

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

package/dist/custom-plugins/DebounceLayoutPlugin/index.d.ts

@@ -0,0 +1,11 @@
+import { createDebounceLayoutPlugin as create, DebounceConfig } from './create';
+import { PluginDoc } from '@vane/plugin-core';
+/**
+ * 工厂 + `.meta`：`typeof create` 保留原工厂的泛型签名，
+ * `.meta` 供 docs:plugins 与 demo 工坊读取配置项。
+ */
+export declare const createDebounceLayoutPlugin: typeof create & {
+    meta: PluginDoc;
+};
+export type { DebounceConfig };
+//# sourceMappingURL=index.d.ts.map

package/dist/custom-plugins/DebounceLayoutPlugin/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/custom-plugins/DebounceLayoutPlugin/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,0BAA0B,IAAI,MAAM,EAAE,MAAM,UAAU,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,0BAA0B,EAAwD,OAAO,MAAM,GAAG;IAC7G,IAAI,EAAE,SAAS,CAAC;CACjB,CAAC;AAEF,YAAY,EAAE,cAAc,EAAE,CAAC"}

package/dist/custom-plugins/DebounceLayoutPlugin/index.js

@@ -0,0 +1,5 @@
+import { c as e, d as o } from "../../chunks/doc-BIzjYAZW.js";
+const a = Object.assign(e, { meta: o });
+export {
+  a as createDebounceLayoutPlugin
+};