vane-waterfall 1.0.5 → 2.0.0

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

@@ -1,10 +1,9 @@
-/**
- * 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';
+/** 瀑布流领域装配层与类型（内部入口，对外只经 index / entries 暴露） */
+export { default as WaterfallCore } from './WaterfallCore';
+export type { WaterfallCoreProps, WaterfallCoreRef, ScrollToItemOptions, ScrollToOptions, } from './WaterfallCore';
+export { withPlugins } from './withPlugins';
+export type { WithPluginsConfig } from './withPlugins';
+export * from './plugins/types';
+export { computeLayout, computeScrollTopForItem, normalizePadding, type AlignmentMode, type LayoutHooks, type LayoutParams, type LayoutResult, type Padding, } from './layout';
+export { computeVisibleRange, type VirtualizeOptions, type VisibleRange } from './virtualize';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/WaterfallPlugin/index.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC3D,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,GAChB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,cAAc,iBAAiB,CAAC;AAChC,OAAO,EACL,aAAa,EACb,uBAAuB,EACvB,gBAAgB,EAChB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,OAAO,GACb,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC"}

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

@@ -0,0 +1,41 @@
+import { ItemPosition } from './plugins/types';
+export type AlignmentMode = "shortest" | "balanced" | "sequential";
+export interface Padding {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+export declare function normalizePadding(padding?: number | Partial<Padding>): Padding;
+export interface LayoutHooks {
+    calculateColumns?: (base: number) => number | void;
+    calculateColumnWidth?: (base: number, columns: number, containerWidth: number) => number | void;
+    calculateItemPosition?: (index: number, itemHeight: number, base: ItemPosition) => Partial<ItemPosition> | null | void;
+}
+export interface LayoutParams {
+    /** 每项高度；0 / undefined / NaN 视为「未测量」 */
+    heights: Array<number | undefined>;
+    columns: number;
+    containerWidth: number;
+    columnGap: number;
+    rowGap: number;
+    padding?: number | Partial<Padding>;
+    alignmentMode?: AlignmentMode;
+    /** 未测量项的兜底高度。不给 → 沿用旧行为：跳过不占位 */
+    estimateHeight?: number;
+    hooks?: LayoutHooks;
+}
+export interface LayoutResult {
+    columns: number;
+    columnWidth: number;
+    padding: Padding;
+    columnHeights: number[];
+    totalHeight: number;
+    positions: Map<number, ItemPosition>;
+    /** 本次布局里有多少项是拿估值占位的（虚拟化给调试面板用） */
+    estimatedCount: number;
+}
+export declare function computeLayout(params: LayoutParams): LayoutResult;
+/** `scrollToItem` 的滚动量（纯计算，供 Core 与单测共用） */
+export declare function computeScrollTopForItem(position: ItemPosition, clientHeight: number, block?: "start" | "center" | "end" | "nearest", offset?: number): number;
+//# sourceMappingURL=layout.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../src/components/WaterfallPlugin/layout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,UAAU,GAAG,YAAY,CAAC;AAEnE,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,gBAAgB,CAC9B,OAAO,GAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAK,GACrC,OAAO,CAUT;AAED,MAAM,WAAW,WAAW;IAC1B,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACnD,oBAAoB,CAAC,EAAE,CACrB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,KACnB,MAAM,GAAG,IAAI,CAAC;IACnB,qBAAqB,CAAC,EAAE,CACtB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,YAAY,KACf,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;CAC1C;AAED,MAAM,WAAW,YAAY;IAC3B,uCAAuC;IACvC,OAAO,EAAE,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACpC,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,iCAAiC;IACjC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACrC,kCAAkC;IAClC,cAAc,EAAE,MAAM,CAAC;CACxB;AAUD,wBAAgB,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAiIhE;AAED,4CAA4C;AAC5C,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,YAAY,EACtB,YAAY,EAAE,MAAM,EACpB,KAAK,GAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,GAAG,SAAmB,EACvD,MAAM,SAAI,GACT,MAAM,CAQR"}

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

@@ -1,31 +1,27 @@
 import { default as React } from 'react';
-import { WaterfallCoreProps } from '../core/WaterfallCore';
-/**
- * 瀑布流项的位置信息
- */
+import { Plugin, PluginContext, PluginDoc } from '@vane/plugin-core';
+import { WaterfallCoreProps } from '../WaterfallCore';
+/** 项位置（px，相对内容区左上角） */
 export interface ItemPosition {
     x: number;
     y: number;
     width: number;
     height: number;
+    /** 所属列（0 起） */
     column: number;
+    /** 逻辑行号，= floor(index / columns)，仅用于调试与分组展示 */
     row: number;
 }
-/**
- * 布局信息
- */
 export interface LayoutInfo {
     columns: number;
     columnWidth: number;
+    /** 列间距（旧字段名保留，等价于 columnGap） */
     gap: number;
     columnHeights: number[];
     totalHeight: number;
     containerWidth: number;
     containerHeight: number;
 }
-/**
- * 视口信息
- */
 export interface ViewportInfo {
     scrollTop: number;
     scrollLeft: number;
@@ -36,52 +32,14 @@ export interface ViewportInfo {
     isScrolling: boolean;
     direction: "up" | "down" | "left" | "right" | null;
 }
-/**
- * 项可见性信息
- */
 export interface ItemVisibility {
     index: number;
     isVisible: boolean;
+    /** 0–1，项与视口的重叠比例 */
     visibleRatio: number;
     isAboveViewport: boolean;
     isBelowViewport: boolean;
 }
-/**
- * 性能指标
- */
-export interface PerformanceMetrics {
-    layoutStartTime: number;
-    layoutEndTime?: number;
-    layoutDuration?: number;
-    layoutCount: number;
-    renderStartTime?: number;
-    renderEndTime?: number;
-    renderDuration?: number;
-    renderedItemCount: number;
-    scrollStartTime?: number;
-    scrollEndTime?: number;
-    scrollDuration?: number;
-    scrollDistance?: number;
-    itemCount: number;
-    visibleItemCount: number;
-    memoryUsage?: number;
-}
-/**
- * 设备信息
- */
-export interface DeviceInfo {
-    type: "mobile" | "tablet" | "desktop";
-    os: string;
-    browser: string;
-    devicePixelRatio: number;
-    viewportWidth: number;
-    viewportHeight: number;
-    isTouchDevice: boolean;
-    isRetina: boolean;
-}
-/**
- * 网络信息
- */
 export interface NetworkInfo {
     effectiveType: "4g" | "3g" | "2g" | "slow-2g";
     downlink: number;
@@ -89,18 +47,6 @@ export interface NetworkInfo {
     saveData: boolean;
     online: boolean;
 }
-/**
- * 动画配置
- */
-export interface AnimationConfig {
-    duration: number;
-    delay?: number;
-    easing?: string;
-    stagger?: number;
-}
-/**
- * 拖拽信息
- */
 export interface DragInfo {
     isDragging: boolean;
     draggedIndex: number | null;
@@ -110,19 +56,22 @@ export interface DragInfo {
     dragCurrentY: number;
     dropTargetIndex: number | null;
 }
-export interface PluginBus {
-    emit: <T = any>(event: string, data?: T) => void;
-    on: <T = any>(event: string, handler: (data: T) => void) => () => void;
-    once: <T = any>(event: string, handler: (data: T) => void) => () => void;
-    off: (event: string, handler?: (data: any) => void) => void;
-    getData: <T = any>(key: string) => T | undefined;
-    setData: <T = any>(key: string, value: T) => void;
-    deleteData: (key: string) => void;
-    hasData: (key: string) => boolean;
-    getAll: () => Record<string, any>;
-    clear: () => void;
+/** 内核 data 位：本领域没有独立数据层，统一挂在 Core 状态快照上 */
+export interface WaterfallData {
+    items: unknown[];
+    layout: LayoutInfo;
+    itemPositions: Map<number, ItemPosition>;
+    viewport: ViewportInfo;
+}
+export interface ScrollToOptions {
+    behavior?: "auto" | "smooth";
+    offset?: number;
+}
+export interface ScrollToItemOptions extends ScrollToOptions {
+    block?: "start" | "center" | "end" | "nearest";
+    inline?: "start" | "center" | "end" | "nearest";
 }
-export interface WaterfallPluginContext<T = any> {
+export interface WaterfallPluginContext<T = any> extends PluginContext<WaterfallCoreProps<T>, WaterfallData> {
     items: T[];
     itemCount: number;
     containerRef: React.RefObject<HTMLDivElement | null>;
@@ -143,326 +92,73 @@ export interface WaterfallPluginContext<T = any> {
     isLoading: boolean;
     hasMore: boolean;
     error: Error | null;
-    props: WaterfallCoreProps<T>;
-    bus?: PluginBus;
-    sharedData?: Map<string, any>;
-    deviceInfo?: DeviceInfo;
+    /** 内核 shared（Map）的领域别名，旧插件用它做跨插件通信 */
+    sharedData: Map<string, any>;
     networkInfo?: NetworkInfo;
-    performanceMetrics?: PerformanceMetrics;
     dragInfo?: DragInfo;
+    /**
+     * 请求宿主重渲染一次（不重排）。
+     *
+     * `renderOverlay` / `renderItemWrapper` 只在宿主渲染时求值，而点击、键盘、定时器
+     * 这类事件改的是插件闭包里的状态，宿主无从感知 —— 不调这个，覆盖层要等到下一次
+     * 布局或滚动才更新（"点了数字不动，滚动一下才跳"就是漏了这一步）。
+     */
+    forceUpdate: () => void;
     relayout: () => void;
-    scrollToItem: (index: number, options?: ScrollToOptions) => void;
+    scrollToItem: (index: number, options?: ScrollToItemOptions) => void;
     scrollToTop: (options?: ScrollToOptions) => void;
     scrollToBottom: (options?: ScrollToOptions) => void;
     measureItem: (index: number) => Promise<{
         width: number;
         height: number;
     }>;
-    forceUpdate: () => void;
-}
-export interface ScrollToOptions {
-    behavior?: "auto" | "smooth";
-    block?: "start" | "center" | "end" | "nearest";
-    inline?: "start" | "center" | "end" | "nearest";
 }
 export interface WaterfallPluginHooks<T = any> {
-    /**
-     * 组件挂载时触发
-     * @returns 清理函数（可选）
-     */
-    onMount?: (context: WaterfallPluginContext<T>) => void | (() => void);
-    /**
-     * 组件卸载时触发
-     */
-    onUnmount?: (context: WaterfallPluginContext<T>) => void;
-    /**
-     * Props 变化时触发
-     */
-    onPropsChange?: (context: WaterfallPluginContext<T>, prevProps: WaterfallCoreProps<T>, nextProps: WaterfallCoreProps<T>) => void;
-    /**
-     * 布局开始前触发
-     * @returns false 可以阻止布局
-     */
-    onBeforeLayout?: (context: WaterfallPluginContext<T>) => boolean | Promise<boolean>;
-    /**
-     * 布局计算中触发（可以修改布局逻辑）
-     */
-    onLayout?: (context: WaterfallPluginContext<T>) => void;
-    /**
-     * 布局完成后触发
-     */
-    onLayoutComplete?: (context: WaterfallPluginContext<T>) => void;
-    /**
-     * 计算列数（响应式插件会实现此钩子）
-     * @returns 列数，undefined 表示使用默认值
-     */
-    calculateColumns?: (context: WaterfallPluginContext<T>) => number | undefined;
-    /**
-     * 计算列宽（自定义列宽插件会实现）
-     */
-    calculateColumnWidth?: (context: WaterfallPluginContext<T>, containerWidth: number, columns: number) => number | undefined;
-    /**
-     * 计算项位置（自定义布局算法插件会实现）
-     */
-    calculateItemPosition?: (context: WaterfallPluginContext<T>, index: number, itemHeight: number) => ItemPosition | undefined;
-    /**
-     * 项挂载时触发
-     */
-    onItemMount?: (context: WaterfallPluginContext<T>, index: number, element: HTMLElement) => void;
-    /**
-     * 项卸载时触发
-     */
-    onItemUnmount?: (context: WaterfallPluginContext<T>, index: number) => void;
-    /**
-     * 项进入视口时触发
-     */
-    onItemEnterViewport?: (context: WaterfallPluginContext<T>, index: number, visibility: ItemVisibility) => void;
-    /**
-     * 项离开视口时触发
-     */
-    onItemLeaveViewport?: (context: WaterfallPluginContext<T>, index: number, visibility: ItemVisibility) => void;
-    /**
-     * 项可见性变化时触发
-     */
-    onItemVisibilityChange?: (context: WaterfallPluginContext<T>, index: number, visibility: ItemVisibility) => void;
-    /**
-     * 项点击时触发
-     */
-    onItemClick?: (context: WaterfallPluginContext<T>, index: number, item: T, event: React.MouseEvent) => void;
-    /**
-     * 滚动开始时触发
-     */
-    onScrollStart?: (context: WaterfallPluginContext<T>) => void;
-    /**
-     * 滚动中触发
-     */
-    onScroll?: (context: WaterfallPluginContext<T>, scrollTop: number, scrollLeft: number) => void;
-    /**
-     * 滚动结束时触发
-     */
-    onScrollEnd?: (context: WaterfallPluginContext<T>) => void;
-    /**
-     * 滚动到底部时触发（用于无限滚动）
-     */
-    onReachBottom?: (context: WaterfallPluginContext<T>, distance: number) => void | Promise<void>;
-    /**
-     * 滚动到顶部时触发
-     */
-    onReachTop?: (context: WaterfallPluginContext<T>) => void;
-    /**
-     * 容器尺寸变化时触发
-     */
-    onResize?: (context: WaterfallPluginContext<T>, width: number, height: number) => void;
-    /**
-     * 项尺寸变化时触发
-     */
-    onItemResize?: (context: WaterfallPluginContext<T>, index: number, width: number, height: number) => void;
-    /**
-     * 数据变化前触发
-     * @returns false 可以阻止数据更新
-     */
-    onBeforeItemsChange?: (context: WaterfallPluginContext<T>, oldItems: T[], newItems: T[]) => boolean | Promise<boolean>;
-    /**
-     * 数据变化后触发
-     */
-    onItemsChange?: (context: WaterfallPluginContext<T>, oldItems: T[], newItems: T[]) => void;
-    /**
-     * 单个项数据变化时触发
-     */
-    onItemChange?: (context: WaterfallPluginContext<T>, index: number, oldItem: T, newItem: T) => void;
-    /**
-     * 加载更多数据时触发（无限滚动插件会实现）
-     */
-    onLoadMore?: (context: WaterfallPluginContext<T>, page: number) => Promise<T[]> | T[] | void;
-    /**
-     * 刷新数据时触发（下拉刷新插件会实现）
-     */
-    onRefresh?: (context: WaterfallPluginContext<T>) => Promise<T[]> | T[] | void;
-    /**
-     * 拖拽开始时触发
-     */
-    onDragStart?: (context: WaterfallPluginContext<T>, index: number, event: React.DragEvent) => void;
-    /**
-     * 拖拽中触发
-     */
-    onDrag?: (context: WaterfallPluginContext<T>, index: number, event: React.DragEvent) => void;
-    /**
-     * 拖拽结束时触发
-     */
-    onDragEnd?: (context: WaterfallPluginContext<T>, index: number, event: React.DragEvent) => void;
-    /**
-     * 项被拖放时触发
-     */
-    onDrop?: (context: WaterfallPluginContext<T>, fromIndex: number, toIndex: number) => void;
-    /**
-     * 项被选中时触发
-     */
-    onItemSelect?: (context: WaterfallPluginContext<T>, index: number, item: T, selected: boolean) => void;
-    /**
-     * 多选变化时触发
-     */
-    onSelectionChange?: (context: WaterfallPluginContext<T>, selectedIndices: Set<number>) => void;
-    /**
-     * 筛选逻辑（筛选插件会实现）
-     */
-    filterItem?: (context: WaterfallPluginContext<T>, item: T, index: number) => boolean;
-    /**
-     * 排序逻辑（排序插件会实现）
-     */
-    sortItems?: (context: WaterfallPluginContext<T>, items: T[]) => T[];
-    /**
-     * 搜索逻辑（搜索插件会实现）
-     */
-    searchItem?: (context: WaterfallPluginContext<T>, item: T, query: string) => boolean;
-    /**
-     * 性能指标收集
-     */
-    onPerformanceMetric?: (context: WaterfallPluginContext<T>, metrics: PerformanceMetrics) => void;
-    /**
-     * 虚拟滚动范围计算（虚拟滚动插件会实现）
-     */
-    calculateVisibleRange?: (context: WaterfallPluginContext<T>) => {
-        start: number;
-        end: number;
-    } | undefined;
-    /**
-     * 错误发生时触发
-     */
-    onError?: (context: WaterfallPluginContext<T>, error: Error, errorInfo?: React.ErrorInfo) => void;
-    /**
-     * 项加载失败时触发
-     */
-    onItemLoadError?: (context: WaterfallPluginContext<T>, index: number, error: Error) => void;
-    /**
-     * 自定义容器渲染
-     */
-    renderContainer?: (context: WaterfallPluginContext<T>, children: React.ReactNode) => React.ReactNode;
-    /**
-     * 自定义项包装器渲染
-     */
-    renderItemWrapper?: (context: WaterfallPluginContext<T>, index: number, item: T, children: React.ReactNode) => React.ReactNode;
-    /**
-     * 自定义覆盖层渲染（加载状态、空状态等）
-     */
-    renderOverlay?: (context: WaterfallPluginContext<T>) => React.ReactNode;
-    /**
-     * 自定义加载更多指示器
-     */
-    renderLoadingMore?: (context: WaterfallPluginContext<T>) => React.ReactNode;
-    /**
-     * 自定义空状态
-     */
-    renderEmpty?: (context: WaterfallPluginContext<T>) => React.ReactNode;
-    /**
-     * 自定义错误状态
-     */
-    renderError?: (context: WaterfallPluginContext<T>, error: Error) => React.ReactNode;
-    /**
-     * 转换 Props（可以在组件接收 props 前修改）
-     */
-    transformProps?: (props: WaterfallCoreProps<T>) => WaterfallCoreProps<T>;
-    /**
-     * 转换项数据（可以在渲染前修改项数据）
-     */
-    transformItem?: (context: WaterfallPluginContext<T>, item: T, index: number) => T;
-}
-export interface WaterfallPlugin<T = any> {
-    /**
-     * 插件名称（唯一标识）
-     */
-    name: string;
-    /**
-     * 插件版本
-     */
-    version?: string;
-    /**
-     * 插件描述
-     */
-    description?: string;
-    /**
-     * 插件钩子
-     */
-    hooks: WaterfallPluginHooks<T>;
-    /**
-     * 插件配置
-     */
-    config?: Record<string, any>;
-    /**
-     * 插件依赖（需要先加载的插件名称）
-     */
-    dependencies?: string[];
-    /**
-     * 插件优先级（数字越大优先级越高）
-     */
-    priority?: number;
-    /**
-     * 插件初始化
-     */
-    init?: () => void | Promise<void>;
-    /**
-     * 插件销毁
-     */
-    destroy?: () => void | Promise<void>;
-    /**
-     * 插件是否启用
-     */
-    enabled?: boolean;
-}
-export interface PluginManager<T = any> {
-    /**
-     * 注册插件
-     */
-    register: (plugin: WaterfallPlugin<T>) => void;
-    /**
-     * 批量注册插件
-     */
-    registerAll: (plugins: WaterfallPlugin<T>[]) => void;
-    /**
-     * 注销插件
-     */
-    unregister: (pluginName: string) => void;
-    /**
-     * 获取插件
-     */
-    getPlugin: (pluginName: string) => WaterfallPlugin<T> | undefined;
-    /**
-     * 获取所有插件
-     */
-    getAllPlugins: () => WaterfallPlugin<T>[];
-    /**
-     * 获取启用的插件
-     */
-    getEnabledPlugins: () => WaterfallPlugin<T>[];
-    /**
-     * 启用插件
-     */
-    enablePlugin: (pluginName: string) => void;
-    /**
-     * 禁用插件
-     */
-    disablePlugin: (pluginName: string) => void;
-    /**
-     * 检查插件是否已注册
-     */
-    hasPlugin: (pluginName: string) => boolean;
-    /**
-     * 执行钩子
-     */
-    executeHook: <K extends keyof WaterfallPluginHooks<T>>(hookName: K, context: WaterfallPluginContext<T>, ...args: any[]) => Promise<any>;
-    /**
-     * 清空所有插件
-     */
-    clear: () => void;
+    /** 可返回清理函数；`manager.clear()` 时逆序执行一次 */
+    onMount?(context: WaterfallPluginContext<T>): unknown;
+    onUnmount?(context: WaterfallPluginContext<T>): unknown;
+    onPropsChange?(context: WaterfallPluginContext<T>, prev: WaterfallCoreProps<T>, next: WaterfallCoreProps<T>): unknown;
+    /** 转发前改写 props（链式，按 priority 降序） */
+    transformProps?(props: WaterfallCoreProps<T>): WaterfallCoreProps<T>;
+    /** 返回 false 阻止本次布局 */
+    onBeforeLayout?(context: WaterfallPluginContext<T>): boolean | void | Promise<boolean | void>;
+    onLayout?(context: WaterfallPluginContext<T>): unknown;
+    onLayoutComplete?(context: WaterfallPluginContext<T>): unknown;
+    /** D1-A：返回列数则覆盖 props.columns */
+    calculateColumns?(context: WaterfallPluginContext<T>, containerWidth: number): number | void;
+    /** D1-A：返回列宽则覆盖自动计算值 */
+    calculateColumnWidth?(context: WaterfallPluginContext<T>, containerWidth: number, columns: number): number | void;
+    /** D1-A：返回位置则覆盖列分配结果（置顶、跨列等） */
+    calculateItemPosition?(context: WaterfallPluginContext<T>, index: number, itemHeight: number, base: ItemPosition): Partial<ItemPosition> | null | void;
+    onItemMount?(context: WaterfallPluginContext<T>, index: number, element: HTMLElement): unknown;
+    onItemUnmount?(context: WaterfallPluginContext<T>, index: number): unknown;
+    onItemEnterViewport?(context: WaterfallPluginContext<T>, index: number, visibility: ItemVisibility): unknown;
+    onItemLeaveViewport?(context: WaterfallPluginContext<T>, index: number, visibility: ItemVisibility): unknown;
+    onItemClick?(context: WaterfallPluginContext<T>, index: number, item: T, event: React.MouseEvent): unknown;
+    onScroll?(context: WaterfallPluginContext<T>, scrollTop: number, scrollLeft: number): unknown;
+    onResize?(context: WaterfallPluginContext<T>, width: number, height: number): unknown;
+    onReachBottom?(context: WaterfallPluginContext<T>, distance: number): unknown;
+    /** 覆盖层：HOC 保证渲染在滚动容器内部、内容层之上 */
+    renderOverlay?(context: WaterfallPluginContext<T>): React.ReactNode;
+    /** 项包装管道：把每个项的渲染结果再包一层（拖拽、无障碍语义等） */
+    renderItemWrapper?(context: WaterfallPluginContext<T>, node: React.ReactNode, index: number): React.ReactNode;
 }
 /**
- * 插件创建器类型
+ * 领域插件 = 内核插件把 hooks 收窄成领域钩子。
+ * 用 Omit 而不是交叉：交叉会同时保留内核 PluginHooks 的索引签名，
+ * TS 在推断钩子参数时会取两边的并集，插件里 context 就变成
+ * `PluginContext | WaterfallPluginContext` 而拿不到领域字段。
  */
-export type PluginCreator<T = any, Config = any> = (config?: Config) => WaterfallPlugin<T>;
 /**
- * 项渲染函数类型
+ * 领域插件 = 内核插件把 hooks 收窄成领域钩子。
+ * 用 Omit 而不是交叉类型：交叉会同时保留内核 PluginHooks 的索引签名，
+ * TS 推断钩子参数时会取两边的并集，插件里的 context 就变成
+ * `PluginContext | WaterfallPluginContext`，拿不到领域字段。
  */
-export type ItemRenderer<T = any> = (item: T, index: number, context: WaterfallPluginContext<T>) => React.ReactNode;
-/**
- * 项键提取函数类型
- */
-export type ItemKeyExtractor<T = any> = (item: T, index: number) => string | number;
+export type WaterfallPlugin<T = any> = Omit<Plugin<WaterfallCoreProps<T>>, "hooks"> & {
+    hooks: WaterfallPluginHooks<T>;
+};
+export type WaterfallPluginCreator<Config = any, T = any> = ((config?: Config) => WaterfallPlugin<T>) & {
+    meta: PluginDoc;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/components/WaterfallPlugin/plugins/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/components/WaterfallPlugin/plugins/types.ts"],"names":[],"mappings":"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"}