vane-waterfall 1.0.1

package/dist/components/WaterfallPlugin/custom-plugins/Gap/index.d.ts

@@ -0,0 +1,31 @@
+import { WaterfallPlugin } from '../../plugins/types';
+type GapConfig = {
+    /** 列间距（像素） */
+    columnGap?: number;
+    /** 行间距（像素） */
+    rowGap?: number;
+    /** 响应式：根据窗口宽度覆盖间距 */
+    responsive?: {
+        sm?: {
+            columnGap?: number;
+            rowGap?: number;
+        };
+        md?: {
+            columnGap?: number;
+            rowGap?: number;
+        };
+        lg?: {
+            columnGap?: number;
+            rowGap?: number;
+        };
+        xl?: {
+            columnGap?: number;
+            rowGap?: number;
+        };
+    };
+};
+/**
+ * GapPlugin - 控制瀑布流的列间距和行间距，支持响应式
+ */
+export declare function createGapPlugin<T = any>(config: GapConfig): WaterfallPlugin<T>;
+export {};

package/dist/components/WaterfallPlugin/custom-plugins/Grouping/index.d.ts

@@ -0,0 +1,12 @@
+import { WaterfallPlugin } from '../../plugins/types';
+type GroupingConfig<T = any> = {
+    /** 分组函数，返回组键 */
+    groupBy?: (item: T, index: number) => string | number;
+};
+/**
+ * GroupingPlugin - 按组聚合（实验版）
+ * - 计算分组信息，写入 sharedData(GROUPS)
+ * - 仅提供覆盖层标签展示当前分组数量
+ */
+export declare function createGroupingPlugin<T = any>(config?: GroupingConfig<T>): WaterfallPlugin<T>;
+export {};

package/dist/components/WaterfallPlugin/custom-plugins/HeatmapAnalytics/index.d.ts

@@ -0,0 +1,14 @@
+import { WaterfallPlugin } from '../../plugins/types';
+type HeatmapAnalyticsConfig = {
+    /** 是否显示简单统计叠层 */
+    showOverlay?: boolean;
+    /** 别名：示例页使用的 showOverlaySummary */
+    showOverlaySummary?: boolean;
+};
+/**
+ * HeatmapAnalyticsPlugin - 点击/曝光热力分析（基础版）
+ * - 统计每项进入视口次数与点击次数
+ * - 可选在顶部显示统计摘要叠层
+ */
+export declare function createHeatmapAnalyticsPlugin<T = any>(config?: HeatmapAnalyticsConfig): WaterfallPlugin<T>;
+export {};

package/dist/components/WaterfallPlugin/custom-plugins/InfiniteScroll/index.d.ts

@@ -0,0 +1,13 @@
+import { WaterfallPlugin } from '../../plugins/types';
+type InfiniteScrollConfig = {
+    /** 触发加载的距离阈值（像素） */
+    threshold?: number;
+    /** 加载更多的回调，由页面传入 */
+    onLoadMore?: () => Promise<void> | void;
+};
+/**
+ * InfiniteScrollPlugin - 到达底部触发加载更多
+ * 通过 transformProps 包装 onReachBottom，实现基于阈值的加载触发
+ */
+export declare function createInfiniteScrollPlugin<T = any>(config?: InfiniteScrollConfig): WaterfallPlugin<T>;
+export {};

package/dist/components/WaterfallPlugin/custom-plugins/Pagination/index.d.ts

@@ -0,0 +1,15 @@
+import { WaterfallPlugin } from '../../plugins/types';
+type PaginationConfig = {
+    /** 每页数量 */
+    pageSize?: number;
+    /** 翻页后自动滚动到顶部 */
+    scrollToTop?: boolean;
+    /** 滚动行为（auto/smooth），仅在启用 scrollToTop 时生效 */
+    scrollBehavior?: "auto" | "smooth";
+};
+/**
+ * PaginationPlugin - 基于 props 中的 pageIndex/pageSize 对 items 进行分页切片
+ * 支持通过 config.pageSize 设定默认每页数量
+ */
+export declare function createPaginationPlugin<T = any>(config?: PaginationConfig): WaterfallPlugin<T>;
+export {};

package/dist/components/WaterfallPlugin/custom-plugins/PinItem/index.d.ts

@@ -0,0 +1,13 @@
+import { WaterfallPlugin } from '../../plugins/types';
+type PinItemConfig = {
+    /** 置顶的项索引列表 */
+    pinnedIndices: number[];
+    /** 固定到的列（默认 0） */
+    column?: number;
+};
+/**
+ * PinItemPlugin - 将指定索引的项固定在顶部某列
+ * - 通过 calculateItemPosition 覆盖其位置，使其始终位于顶部
+ */
+export declare function createPinItemPlugin<T = any>(config: PinItemConfig): WaterfallPlugin<T>;
+export {};

package/dist/components/WaterfallPlugin/custom-plugins/Recycle/index.d.ts

@@ -0,0 +1,12 @@
+import { WaterfallPlugin } from '../../plugins/types';
+type RecycleConfig = {
+    /** 视口外隐藏项以降低渲染压力（最大可见项数，近似控制） */
+    poolSize: number;
+};
+/**
+ * RecyclePlugin - 简化版 DOM 回收：
+ * - 当项离开视口时，设置其元素为 `visibility:hidden`，减少绘制压力
+ * - 当项进入视口时，恢复为 `visibility:visible`
+ */
+export declare function createRecyclePlugin<T = any>(config: RecycleConfig): WaterfallPlugin<T>;
+export {};

package/dist/components/WaterfallPlugin/custom-plugins/ReducedMotion/index.d.ts

@@ -0,0 +1,13 @@
+import { WaterfallPlugin } from '../../plugins/types';
+type ReducedMotionConfig = {
+    /** 当用户偏好减少动画时，是否禁用 transform 定位 */
+    disableTransform?: boolean;
+    /** 当用户偏好减少动画时，是否移除项过渡效果 */
+    removeTransitions?: boolean;
+};
+/**
+ * ReducedMotionPlugin - 尊重系统的减少动画偏好
+ * - 通过 transformProps 调整核心配置与项样式
+ */
+export declare function createReducedMotionPlugin<T = any>(config?: ReducedMotionConfig): WaterfallPlugin<T>;
+export {};

package/dist/components/WaterfallPlugin/custom-plugins/ResponsiveColumns/index.d.ts

@@ -0,0 +1,10 @@
+import { WaterfallPlugin } from '../../plugins/types';
+type Breakpoint = {
+    width: number;
+    columns: number;
+};
+type Breakpoints = Record<string, Breakpoint>;
+export declare function createResponsiveColumnsPlugin<T = any>(config: {
+    breakpoints: Breakpoints;
+}): WaterfallPlugin<T>;
+export {};

package/dist/components/WaterfallPlugin/custom-plugins/ScrollAnchor/index.d.ts

@@ -0,0 +1,12 @@
+import { WaterfallPlugin } from '../../plugins/types';
+type ScrollAnchorConfig<T = any> = {
+    /** 通过此函数提取锚点 id（默认使用 item.id） */
+    getAnchorId?: (item: T, index: number) => string | number | undefined;
+};
+/**
+ * ScrollAnchorPlugin - 滚动锚点（实验版）
+ * - 渲染一个简单的锚点跳转控件
+ * - 支持通过 bus 事件 anchor:scrollToId 跳转
+ */
+export declare function createScrollAnchorPlugin<T = any>(config?: ScrollAnchorConfig<T>): WaterfallPlugin<T>;
+export {};

package/dist/components/WaterfallPlugin/custom-plugins/Search/index.d.ts

@@ -0,0 +1,15 @@
+import { WaterfallPlugin } from '../../plugins/types';
+type SearchConfig<T = any> = {
+    /** 要搜索的字段名列表（仅用于对象项） */
+    fields?: (keyof T)[];
+    /** 条件变化后自动滚动到顶部 */
+    scrollToTop?: boolean;
+    /** 滚动行为（auto/smooth），仅在启用 scrollToTop 时生效 */
+    scrollBehavior?: "auto" | "smooth";
+};
+/**
+ * SearchPlugin - 基于 props.searchQuery 对 items 执行包含匹配过滤
+ * 仅在对象项中按指定字段进行大小写不敏感的包含匹配
+ */
+export declare function createSearchPlugin<T = any>(config?: SearchConfig<T>): WaterfallPlugin<T>;
+export {};

package/dist/components/WaterfallPlugin/custom-plugins/Sort/index.d.ts

@@ -0,0 +1,15 @@
+import { WaterfallPlugin } from '../../plugins/types';
+type SortConfig<T = any> = {
+    /** 初始比较函数，可被 props.sortComparator 覆盖 */
+    comparator?: (a: T, b: T) => number;
+    /** 条件变化后自动滚动到顶部 */
+    scrollToTop?: boolean;
+    /** 滚动行为（auto/smooth），仅在启用 scrollToTop 时生效 */
+    scrollBehavior?: "auto" | "smooth";
+};
+/**
+ * SortPlugin - 基于比较函数对 items 排序
+ * 优先使用 props.sortComparator，其次使用创建插件时传入的 comparator
+ */
+export declare function createSortPlugin<T = any>(config?: SortConfig<T>): WaterfallPlugin<T>;
+export {};

package/dist/components/WaterfallPlugin/custom-plugins/StatePersistence/index.d.ts

@@ -0,0 +1,16 @@
+import { WaterfallPlugin } from '../../plugins/types';
+type StatePersistenceConfig = {
+    /** 存储键（localStorage） */
+    storageKey?: string;
+    /** 是否持久化滚动位置 */
+    persistScroll?: boolean;
+    /** 是否持久化分页与查询（从 props 读取） */
+    persistKeys?: string[];
+};
+/**
+ * StatePersistencePlugin - 状态快照与恢复（基础版）
+ * - 挂载时尝试恢复快照；卸载时写入快照
+ * - 快照包含：scrollTop（可选）与部分 props 键
+ */
+export declare function createStatePersistencePlugin<T = any>(config?: StatePersistenceConfig): WaterfallPlugin<T>;
+export {};

package/dist/components/WaterfallPlugin/custom-plugins/StickyHeader/index.d.ts

@@ -0,0 +1,11 @@
+import { WaterfallPlugin } from '../../plugins/types';
+type StickyHeaderConfig = {
+    /** 标题文本（默认：当前分组） */
+    title?: string;
+};
+/**
+ * StickyHeaderPlugin - 吸顶标题（实验版）
+ * - 简化实现：始终显示一个吸顶条，可与 GroupingPlugin 联动
+ */
+export declare function createStickyHeaderPlugin<T = any>(config?: StickyHeaderConfig): WaterfallPlugin<T>;
+export {};

package/dist/components/WaterfallPlugin/custom-plugins/Throttle/index.d.ts

@@ -0,0 +1,12 @@
+import { WaterfallPlugin } from '../../plugins/types';
+type ThrottleConfig = {
+    /** 滚动节流（ms） */
+    scroll: number;
+    /** 尺寸变化防抖（ms），用于容器 Resize 相关 */
+    resize?: number;
+};
+/**
+ * ThrottlePlugin - 通过 transformProps 调整核心的滚动节流与尺寸变化防抖
+ */
+export declare function createThrottlePlugin<T = any>(config: ThrottleConfig): WaterfallPlugin<T>;
+export {};

package/dist/components/WaterfallPlugin/custom-plugins/Transition/index.d.ts

@@ -0,0 +1,13 @@
+import { WaterfallPlugin } from '../../plugins/types';
+type TransitionConfig = {
+    /** 过渡时长（ms） */
+    duration?: number;
+    /** 过渡缓动 */
+    easing?: string;
+};
+/**
+ * TransitionPlugin - 布局变化过渡
+ * - 为项元素应用 transform/opacity 的过渡，提升布局更新的视觉平滑度
+ */
+export declare function createTransitionPlugin<T = any>(config?: TransitionConfig): WaterfallPlugin<T>;
+export {};

package/dist/components/WaterfallPlugin/custom-plugins/URLSync/index.d.ts

@@ -0,0 +1,14 @@
+import { WaterfallPlugin } from '../../plugins/types';
+type URLSyncConfig = {
+    /** URL 同步使用 hash 还是 search（默认 hash） */
+    mode?: "hash" | "search";
+    /** 需要同步的键列表（从 props 读取） */
+    keys?: string[];
+};
+/**
+ * URLSyncPlugin - 将部分状态同步到 URL（基础版）
+ * - 监听 props 变化，更新 URL
+ * - 初次挂载时读取 URL 并向 bus 广播（页面可据此设置状态）
+ */
+export declare function createURLSyncPlugin<T = any>(config?: URLSyncConfig): WaterfallPlugin<T>;
+export {};

package/dist/components/WaterfallPlugin/custom-plugins/VirtualWaterfall/index.d.ts

@@ -0,0 +1,12 @@
+import { WaterfallPlugin } from '../../plugins/types';
+export type VirtualWaterfallConfig<T = any> = {
+    /** 视口上下额外渲染的像素范围（overscan） */
+    overscanPx?: number;
+    /** 获取项高度（可选；不可预测时走测量） */
+    getItemHeight?: (item: T, index: number) => number;
+    /** 动态高度测量模式：开启后使用 ResizeObserver 实时测量 */
+    dynamicHeights?: boolean;
+    /** 初始估算高度（用于首屏布局与未测量项） */
+    estimateItemHeight?: number;
+};
+export declare function createVirtualWaterfallPlugin<T = any>(config: VirtualWaterfallConfig<T>): WaterfallPlugin<T>;

package/dist/components/WaterfallPlugin/custom-plugins/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * WaterfallPlugin 自定义插件导出
+ */
+export { createResponsiveColumnsPlugin } from './ResponsiveColumns';
+export { createAutoColumnPlugin } from './AutoColumn';
+export { createAlignmentPlugin } from './Alignment';
+export { createGapPlugin } from './Gap';
+export { createFixedHeightPlugin } from './FixedHeight';
+export { createVirtualWaterfallPlugin } from './VirtualWaterfall';
+export { createThrottlePlugin } from './Throttle';
+export { createDebounceLayoutPlugin } from './DebounceLayout';
+export { createRecyclePlugin } from './Recycle';
+export { createInfiniteScrollPlugin } from './InfiniteScroll';
+export { createPaginationPlugin } from './Pagination';
+export { createFilterPlugin } from './Filter';
+export { createSortPlugin } from './Sort';
+export { createSearchPlugin } from './Search';
+export { createClickAnalyticsPlugin } from './ClickAnalytics/index.tsx';
+export { createBookmarkPlugin } from './Bookmark/index.tsx';
+export { createURLSyncPlugin } from './URLSync';
+export { createA11yPlugin } from './A11y';
+export { createReducedMotionPlugin } from './ReducedMotion';
+export { createTransitionPlugin } from './Transition';
+export { createPinItemPlugin } from './PinItem';
+export { createHeatmapAnalyticsPlugin } from './HeatmapAnalytics';
+export { createStatePersistencePlugin } from './StatePersistence';
+export { createGroupingPlugin } from './Grouping/index.tsx';
+export { createStickyHeaderPlugin } from './StickyHeader/index.tsx';
+export { createScrollAnchorPlugin } from './ScrollAnchor/index.tsx';
+export { createDragReorderPlugin } from './DragReorder/index.tsx';

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

@@ -0,0 +1,10 @@
+/**
+ * WaterfallPlugin 系统入口
+ */
+export { default as WaterfallCore } from './core/WaterfallCore';
+export type { WaterfallCoreProps, WaterfallCoreRef, ScrollToOptions, ScrollToItemOptions, } from './core/WaterfallCore';
+export type { WaterfallPlugin, PluginManager, PluginBus, WaterfallPluginContext, WaterfallPluginHooks, PluginCreator, WithPluginsConfig, ItemPosition, LayoutInfo, ViewportInfo, ItemVisibility, PerformanceMetrics, DeviceInfo, NetworkInfo, AnimationConfig, DragInfo, ItemRenderer, ItemKeyExtractor, } from './plugins';
+export { createPluginBus } from './plugins';
+export { createPluginManager } from './plugins';
+export { withPlugins } from './plugins';
+export * from './custom-plugins';

package/dist/components/WaterfallPlugin/plugins/PluginBus.d.ts

@@ -0,0 +1,2 @@
+import { PluginBus } from './types';
+export declare function createPluginBus(): PluginBus;

package/dist/components/WaterfallPlugin/plugins/PluginManager.d.ts

@@ -0,0 +1,2 @@
+import { PluginManager } from './types';
+export declare function createPluginManager<T = any>(): PluginManager<T>;

package/dist/components/WaterfallPlugin/plugins/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * WaterfallPlugin 插件系统导出
+ */
+export type { WaterfallPlugin, PluginManager, PluginBus, WaterfallPluginContext, WaterfallPluginHooks, PluginCreator, ItemPosition, LayoutInfo, ViewportInfo, ItemVisibility, PerformanceMetrics, DeviceInfo, NetworkInfo, AnimationConfig, DragInfo, ItemRenderer, ItemKeyExtractor, ScrollToOptions, } from './types';
+export type { WithPluginsConfig } from './withPlugins';
+export { createPluginBus } from './PluginBus';
+export { createPluginManager } from './PluginManager';
+export { withPlugins } from './withPlugins';