import { Node as ProseMirrorNode } from 'prosemirror-model';
import { FlowBlock, Layout, Measure } from '../../../../../../../layout-engine/contracts/src/index.js';
import { PageGeometryHelper, TableHitResult } from '../../../../../../../layout-engine/layout-bridge/src/index.js';
/**
 * Calculates the ProseMirror document position for a table cell identified by a hit test result.
 *
 * This function traverses the ProseMirror document tree to locate the table node corresponding
 * to the hit result, then navigates through the table structure (accounting for colspan) to find
 * the exact position of the target cell.
 *
 * @param tableHit - Hit test result containing the table block ID and cell coordinates
 * @param doc - ProseMirror document node to search within
 * @param blocks - Array of layout blocks used to locate the target table
 * @returns The document position at the start of the target cell, or null if not found
 *
 * @remarks
 * This function handles several edge cases:
 * - Validates all input parameters and cell indices for safety
 * - Accounts for colspan when calculating logical column positions
 * - Returns null if the table or cell cannot be located
 * - Logs warnings for invalid inputs to aid debugging
 *
 * The position returned is at the start of the cell node (before any cell content).
 * Table structure: table > tableRow > tableCell
 *
 * @example
 * ```typescript
 * const tableHit = hitTestTable(layout, blocks, measures, x, y, ...);
 * if (tableHit) {
 *   const cellPos = getCellPosFromTableHit(tableHit, doc, blocks);
 *   if (cellPos !== null) {
 *     // Use cellPos to create a selection or perform operations
 *   }
 * }
 * ```
 */
export declare function getCellPosFromTableHit(tableHit: TableHitResult, doc: ProseMirrorNode | null, blocks: FlowBlock[]): number | null;
/**
 * Retrieves the ProseMirror document position for the start of a table identified by a hit test result.
 *
 * This function locates the table node in the document by matching the table block ID from the
 * hit test result against the layout blocks array.
 *
 * @param tableHit - Hit test result containing the table block ID
 * @param doc - ProseMirror document node to search within
 * @param blocks - Array of layout blocks used to locate the target table
 * @returns The document position at the start of the table node, or null if not found
 *
 * @remarks
 * Unlike getCellPosFromTableHit, this function returns the position of the table node itself,
 * not a specific cell within it. This is useful for operations that need to reference the
 * entire table structure.
 *
 * The position returned is at the start of the table node (before the first row).
 *
 * @example
 * ```typescript
 * const tableHit = hitTestTable(layout, blocks, measures, x, y, ...);
 * if (tableHit) {
 *   const tablePos = getTablePosFromHit(tableHit, doc, blocks);
 *   if (tablePos !== null) {
 *     const tableNode = doc.nodeAt(tablePos);
 *     // Perform table-level operations
 *   }
 * }
 * ```
 */
export declare function getTablePosFromHit(tableHit: TableHitResult, doc: ProseMirrorNode | null, blocks: FlowBlock[]): number | null;
/**
 * Determines whether cell selection mode should be used based on the current drag state and position.
 *
 * This function implements the state machine logic for transitioning between regular text selection
 * and table cell selection during pointer interactions. It handles cases where the user drags within
 * a table, across cell boundaries, or outside the table entirely.
 *
 * @param currentTableHit - Current hit test result, or null if pointer is outside any table
 * @param cellAnchor - The cell where the drag started, or null if not dragging from a table cell
 * @param cellDragMode - Current drag mode state: 'none', 'pending', or 'active'
 * @returns True if cell selection should be used, false for regular text selection
 *
 * @remarks
 * The function implements the following logic:
 * - Returns false if no cell anchor exists (drag didn't start in a table)
 * - Returns true if drag mode is active and pointer is outside any table (preserves last cell selection)
 * - Returns true if drag mode is active and pointer is in a different table (preserves last cell selection)
 * - Returns true if the pointer has crossed a cell boundary within the same table
 * - Returns true if drag mode is active and pointer is still in the same cell
 * - Returns false otherwise (same cell, pending mode)
 *
 * This enables a smooth user experience where cell selection activates when crossing cell boundaries
 * and persists when dragging outside the table.
 *
 * @example
 * ```typescript
 * if (shouldUseCellSelection(currentTableHit, cellAnchor, cellDragMode)) {
 *   // Use CellSelection for multi-cell selection
 *   const cellSelection = createCellSelection(...);
 * } else {
 *   // Use TextSelection for normal selection
 *   const textSelection = createTextSelection(...);
 * }
 * ```
 */
export declare function shouldUseCellSelection(currentTableHit: TableHitResult | null, cellAnchor: {
    tableBlockId: string;
    cellRowIndex: number;
    cellColIndex: number;
} | null, cellDragMode: 'none' | 'pending' | 'active'): boolean;
/**
 * Performs hit testing to determine which table cell (if any) is at the given coordinates.
 *
 * This function combines page-level hit testing with table fragment hit testing to accurately
 * identify the table cell at a specific point in the document. It handles multi-page tables,
 * page virtualization, and provides fallback logic when geometry helpers are unavailable.
 *
 * @param layout - Current layout state containing pages and fragments
 * @param blocks - Array of layout blocks (tables, paragraphs, etc.)
 * @param measures - Array of measurement data corresponding to blocks
 * @param normalizedX - X coordinate in document space (not page-relative)
 * @param normalizedY - Y coordinate in document space (not page-relative)
 * @param configuredPageHeight - Configured page height from layout options
 * @param pageGapFallback - Gap between pages when layout.pageGap is not available
 * @param geometryHelper - Optional helper for efficient page geometry queries
 * @returns Hit test result with table block ID and cell coordinates, or null if no table hit
 *
 * @remarks
 * The function performs a two-stage hit test:
 * 1. Identify which page contains the coordinates (using geometryHelper or manual scan)
 * 2. Convert to page-relative coordinates and delegate to hitTestTableFragment
 *
 * The geometryHelper (when available) provides optimized page lookups for better performance.
 * If unavailable, the function falls back to a linear scan through all pages.
 *
 * Coordinate systems:
 * - Input coordinates (normalizedX, normalizedY) are in document space (absolute from top)
 * - Converted to page-relative coordinates before table fragment hit testing
 * - Page heights and gaps account for multi-page layout
 *
 * @example
 * ```typescript
 * const tableHit = hitTestTable(
 *   layout,
 *   blocks,
 *   measures,
 *   event.clientX,
 *   event.clientY,
 *   792,
 *   20,
 *   geometryHelper
 * );
 *
 * if (tableHit) {
 *   console.log(`Hit cell [${tableHit.cellRowIndex}, ${tableHit.cellColIndex}]`);
 * }
 * ```
 */
export declare function hitTestTable(layout: Layout | null, blocks: FlowBlock[], measures: Measure[], normalizedX: number, normalizedY: number, configuredPageHeight: number, pageGapFallback: number, geometryHelper: PageGeometryHelper | null): TableHitResult | null;
//# sourceMappingURL=TableSelectionUtilities.d.ts.map