vane-waterfall 1.0.4 → 2.0.0

package/dist/components/WaterfallPlugin/core/WaterfallCore.d.ts

@@ -1,174 +0,0 @@
-import { ItemKeyExtractor, ItemPosition, LayoutInfo, ViewportInfo } from '../plugins/types';
-import { default as React } from 'react';
-export interface WaterfallCoreProps<T = any> {
-    /**
-     * 数据源
-     */
-    items: T[];
-    /**
-     * 渲染函数
-     */
-    renderItem: (item: T, index: number) => React.ReactNode;
-    /**
-     * 键提取函数（用于 React key）
-     */
-    keyExtractor?: ItemKeyExtractor<T>;
-    /**
-     * 列数（可由插件动态计算）
-     */
-    columns?: number;
-    /**
-     * 列间距
-     */
-    gap?: number;
-    /**
-     * 行间距（可选，默认等于 gap）
-     */
-    rowGap?: number;
-    /**
-     * 列间距（可选，默认等于 gap）
-     */
-    columnGap?: number;
-    /**
-     * 列分配策略（默认 shortest）
-     * - shortest：将下一项放入当前最矮列（默认）
-     * - sequential：按顺序轮转分配列（0,1,2...）
-     * - balanced：尽量使各列项数均衡（按项数最少列放置）
-     */
-    alignmentMode?: "shortest" | "balanced" | "sequential";
-    /**
-     * 容器内边距
-     */
-    padding?: number | {
-        top?: number;
-        right?: number;
-        bottom?: number;
-        left?: number;
-    };
-    /**
-     * 容器样式
-     */
-    containerStyle?: React.CSSProperties;
-    /**
-     * 容器类名
-     */
-    containerClassName?: string;
-    /**
-     * 项容器样式
-     */
-    itemStyle?: React.CSSProperties;
-    /**
-     * 项容器类名
-     */
-    itemClassName?: string;
-    /**
-     * 是否使用 transform 定位（性能更好）
-     */
-    useTransform?: boolean;
-    /**
-     * 节流延迟（ms）
-     */
-    throttleDelay?: number;
-    /**
-     * 防抖延迟（ms）
-     */
-    debounceDelay?: number;
-    onMount?: () => void;
-    onUnmount?: () => void;
-    onBeforeLayout?: () => boolean | Promise<boolean>;
-    onLayout?: () => void;
-    onLayoutComplete?: () => void;
-    onItemMount?: (index: number, element: HTMLElement) => void;
-    onItemUnmount?: (index: number) => void;
-    onItemEnterViewport?: (index: number) => void;
-    onItemLeaveViewport?: (index: number) => void;
-    onScroll?: (scrollTop: number, scrollLeft: number) => void;
-    onResize?: (width: number, height: number) => void;
-    onReachBottom?: (distance: number) => void;
-    onItemClick?: (index: number, item: T, event: React.MouseEvent) => void;
-    /**
-     * 子元素（用于插件渲染覆盖层等）
-     */
-    children?: React.ReactNode;
-    /**
-     * 外部容器引用（供 HOC 传入）
-     */
-    containerRefExternal?: React.RefObject<HTMLDivElement | null>;
-    /**
-     * 外部项引用映射（供 HOC 传入）
-     */
-    itemRefsExternal?: React.MutableRefObject<Map<number, HTMLElement>>;
-    /**
-     * 是否启用调试模式
-     */
-    debug?: boolean;
-}
-export interface WaterfallCoreRef {
-    /**
-     * 重新布局
-     */
-    relayout: () => void;
-    /**
-     * 滚动到指定项
-     */
-    scrollToItem: (index: number, options?: ScrollToItemOptions) => void;
-    /**
-     * 滚动到顶部
-     */
-    scrollToTop: (options?: ScrollToOptions) => void;
-    /**
-     * 滚动到底部
-     */
-    scrollToBottom: (options?: ScrollToOptions) => void;
-    /**
-     * 获取项位置
-     */
-    getItemPosition: (index: number) => ItemPosition | null;
-    /**
-     * 获取所有项位置
-     */
-    getAllItemPositions: () => Map<number, ItemPosition>;
-    /**
-     * 获取列高度
-     */
-    getColumnHeights: () => number[];
-    /**
-     * 获取布局信息
-     */
-    getLayoutInfo: () => LayoutInfo;
-    /**
-     * 获取视口信息
-     */
-    getViewportInfo: () => ViewportInfo;
-    /**
-     * 强制更新
-     */
-    forceUpdate: () => void;
-    /**
-     * 获取容器 DOM
-     */
-    getContainer: () => HTMLDivElement | null;
-    /**
-     * 获取项 DOM
-     */
-    getItemElement: (index: number) => HTMLElement | null;
-    /**
-     * 测量项尺寸
-     */
-    measureItem: (index: number) => Promise<{
-        width: number;
-        height: number;
-    }>;
-}
-export interface ScrollToItemOptions {
-    behavior?: "auto" | "smooth";
-    block?: "start" | "center" | "end" | "nearest";
-    inline?: "start" | "center" | "end" | "nearest";
-    offset?: number;
-}
-export interface ScrollToOptions {
-    behavior?: "auto" | "smooth";
-    offset?: number;
-}
-declare const WaterfallCore: React.ForwardRefExoticComponent<WaterfallCoreProps<any> & React.RefAttributes<WaterfallCoreRef>>;
-export default WaterfallCore;

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

@@ -1,16 +0,0 @@
-import { WaterfallPlugin } from '../../plugins/types';
-type A11yConfig = {
-    /** 为容器设置 ARIA role（默认 list） */
-    containerRole?: string;
-    /** 为项设置 ARIA role（默认 listitem） */
-    itemRole?: string;
-    /** 是否给项添加 tabindex 便于键盘焦点 */
-    enableTabIndex?: boolean;
-};
-/**
- * A11yPlugin - 可访问性增强
- * - 为容器与项添加合理的 ARIA 角色与属性
- * - 为项添加 tabindex，支持键盘导航与聚焦
- */
-export declare function createA11yPlugin<T = any>(config?: A11yConfig): WaterfallPlugin<T>;
-export {};

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

@@ -1,17 +0,0 @@
-import { WaterfallPlugin } from '../../plugins/types';
-type AutoColumnConfig = {
-    /** 每列最小宽度（含内容区，不含列间距） */
-    minColumnWidth: number;
-    /** 最大列数（可选） */
-    maxColumns?: number;
-    /** 最小列数（可选，默认 1） */
-    minColumns?: number;
-};
-/**
- * 根据视口宽度和最小列宽自动计算列数
- * 公式（近似）：columns = floor((availableWidth + columnGap) / (minColumnWidth + columnGap))
- * - availableWidth 近似取 window.innerWidth，避免强依赖容器 ref
- * - 考虑 padding 与 columnGap，提高真实布局的贴合度
- */
-export declare function createAutoColumnPlugin<T = any>(config: AutoColumnConfig): WaterfallPlugin<T>;
-export {};

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

@@ -1,12 +0,0 @@
-import { WaterfallPlugin } from '../../plugins/types';
-type ClickAnalyticsConfig = {
-    /** 是否在控制台输出点击日志 */
-    log?: boolean;
-};
-/**
- * ClickAnalyticsPlugin - 点击分析（基础版）
- * - 统计点击次数，向 bus 发送事件：analytics:click
- * - 可选控制台输出日志
- */
-export declare function createClickAnalyticsPlugin<T = any>(config?: ClickAnalyticsConfig): WaterfallPlugin<T>;
-export {};

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

@@ -1,13 +0,0 @@
-import { WaterfallPlugin } from '../../plugins/types';
-type DragReorderConfig = {
-    /** 是否启用（默认 true） */
-    enabled?: boolean;
-};
-/**
- * DragReorderPlugin - 拖拽重排
- * - 为项包装器添加可拖拽样式与属性
- * - 记录最后一次拖拽的 from/to 索引（sharedData）
- * - 实际数据重排需外层配合（示例页提供）
- */
-export declare function createDragReorderPlugin<T = any>(config?: DragReorderConfig): WaterfallPlugin<T>;
-export {};

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

@@ -1,12 +0,0 @@
-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

@@ -1,14 +0,0 @@
-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

@@ -1,13 +0,0 @@
-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/PinItem/index.d.ts

@@ -1,13 +0,0 @@
-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/ReducedMotion/index.d.ts

@@ -1,13 +0,0 @@
-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

@@ -1,10 +0,0 @@
-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/StickyHeader/index.d.ts

@@ -1,11 +0,0 @@
-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/VirtualWaterfall/index.d.ts

@@ -1,12 +0,0 @@
-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

@@ -1,30 +0,0 @@
-/**
- * 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/plugins/PluginBus.d.ts

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

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

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

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

@@ -1,8 +0,0 @@
-/**
- * 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';