@kopexa/extension-table 17.0.45 → 17.1.0

package/dist/lib/table-utils.d.ts

@@ -0,0 +1,263 @@
+import { Node } from '@tiptap/pm/model';
+import { Transaction, EditorState, Command } from '@tiptap/pm/state';
+import { TableMap, FindNodeResult, Rect } from '@tiptap/pm/tables';
+import { Editor } from '@tiptap/react';
+
+type Orientation = "row" | "column";
+type TableInfo = {
+    map: TableMap;
+} & FindNodeResult;
+interface CellInfo extends FindNodeResult {
+    row: number;
+    column: number;
+}
+type DomCellAroundResult = {
+    type: "cell";
+    domNode: HTMLElement;
+    tbodyNode: HTMLTableSectionElement | null;
+} | {
+    type: "wrapper";
+    domNode: HTMLElement;
+    tbodyNode: HTMLTableSectionElement | null;
+};
+/**
+ * Walk up from an element until we find a TD/TH or the table wrapper.
+ * Returns the found element plus its tbody (if present).
+ */
+declare function domCellAround(target: Element): DomCellAroundResult | undefined;
+/**
+ * Given a DOM cell element, find its (row, col) indices within the table.
+ *
+ * This function:
+ * - Locates the nearest ancestor table element
+ * - Uses the editor's document model to resolve the cell's position
+ * - Traverses up the node hierarchy to find the corresponding table cell node
+ * - Uses `TableMap` to translate the cell's position into (row, col) indices
+ *
+ * Returns null if:
+ * - the table or cell cannot be found in the editor's document
+ * - any error occurs during position resolution
+ *
+ * @param cell      The HTMLTableCellElement (td or th)
+ * @param tableNode The table node in the ProseMirror document
+ * @param editor    The Tiptap editor instance
+ * @returns An object with { rowIndex, colIndex } or null if not found
+ */
+declare function getCellIndicesFromDOM(cell: HTMLTableCellElement, tableNode: Node | null, editor: Editor): {
+    rowIndex: number;
+    colIndex: number;
+} | null;
+/**
+ * Checks if a cell is merged (has colspan or rowspan > 1)
+ */
+declare function isCellMerged(node: Node | null): boolean;
+/**
+ * Collect cells (and unique merged cells) from the current table.
+ * - If `columnIndex` is provided, scans that column.
+ * - If omitted, uses the first (leftmost) selected column based on the current selection.
+ */
+declare function getColumnCells(editor: Editor | null, columnIndex?: number, tablePos?: number): {
+    cells: CellInfo[];
+    mergedCells: CellInfo[];
+};
+/**
+ * Get information about the table at the current selection or a specific position.
+ *
+ * If `tablePos` is provided, it looks for a table at that exact position.
+ * Otherwise, it finds the nearest table containing the current selection.
+ *
+ * Returns an object with:
+ * - `node`: the table node
+ * - `pos`: the position of the table in the document
+ * - `start`: the position just after the table node (where its content starts)
+ * - `map`: the `TableMap` for layout info (rows, columns, spans)
+ *
+ * If no table is found, returns null.
+ */
+declare function getTable(editor: Editor | null, tablePos?: number): {
+    map: TableMap;
+    node: Node;
+    pos: number;
+    start: number;
+    depth: number;
+} | null;
+/**
+ * Get all (row, col) coordinates for a given row or column index.
+ *
+ * - If `orientation` is "row", returns all columns in that row.
+ * - If `orientation` is "column", returns all rows in that column.
+ *
+ * Returns null if:
+ * - the editor or table is not found
+ * - the index is out of bounds
+ *
+ * @param editor      The Tiptap editor instance
+ * @param index       The row or column index (0-based)
+ * @param orientation "row" to get row coordinates, "column" for column coordinates
+ * @param tablePos    Optional position of the table node in the document
+ * @returns Array of {row, col} objects or null if invalid
+ */
+declare function getIndexCoordinates({ editor, index, orientation, tablePos, }: {
+    editor: Editor | null;
+    index: number;
+    orientation?: Orientation;
+    tablePos?: number;
+}): {
+    row: number;
+    col: number;
+}[] | null;
+/**
+ * Collect cells (and unique merged cells) from a specific row.
+ * - If `rowIndex` is provided, scans that row.
+ * - If omitted, uses the first (topmost) selected row based on the current selection.
+ */
+declare function getRowCells(editor: Editor | null, rowIndex?: number, tablePos?: number): {
+    cells: CellInfo[];
+    mergedCells: CellInfo[];
+};
+/**
+ * Given a DOM element inside a table, find the corresponding table node and its position.
+ *
+ * This function:
+ * - Locates the nearest ancestor table element
+ * - Uses the editor's document model to resolve the table's position
+ * - Traverses up the node hierarchy to find the corresponding table node
+ *
+ * Returns null if:
+ * - the table cannot be found in the editor's document
+ * - any error occurs during position resolution
+ *
+ * @param tableElement The HTMLTableElement or an element inside it
+ * @param editor       The Tiptap editor instance
+ * @returns An object with { node: tableNode, pos: tablePos } or null if not found
+ */
+declare function getTableFromDOM(tableElement: HTMLElement, editor: Editor): {
+    node: Node;
+    pos: number;
+} | null;
+/**
+ * Checks if a node is a table node
+ */
+declare function isTableNode(node: Node | null | undefined): node is Node;
+type TransactionSelectionOptions = {
+    mode: "transaction";
+};
+type StateSelectionOptions = {
+    mode?: "state";
+};
+type SelectionReturnMode = "state" | "transaction" | "dispatch";
+type DispatchSelectionOptions = {
+    mode: "dispatch";
+    dispatch: (tr: Transaction) => void;
+};
+/**
+ * Selects table cells by their (row, col) coordinates.
+ *
+ * This function can be used in three modes:
+ * - `"state"` (default) → Returns a new `EditorState` with the selection applied, or null if failed.
+ * - `"transaction"` → Returns a `Transaction` with the selection set, or null if failed.
+ * - `"dispatch"` → Immediately dispatches the selection and returns boolean success status.
+ *
+ * @param editor - The editor instance
+ * @param tablePos - Position of the table in the document
+ * @param coords - Array of {row, col} coordinates to select
+ * @param options - Mode and dispatch options
+ */
+declare function selectCellsByCoords(editor: Editor | null, tablePos: number, coords: {
+    row: number;
+    col: number;
+}[], options?: StateSelectionOptions): EditorState;
+declare function selectCellsByCoords(editor: Editor | null, tablePos: number, coords: {
+    row: number;
+    col: number;
+}[], options: TransactionSelectionOptions): Transaction;
+declare function selectCellsByCoords(editor: Editor | null, tablePos: number, coords: {
+    row: number;
+    col: number;
+}[], options: DispatchSelectionOptions): void;
+/**
+ * Determine if the current selection is a full row or column selection.
+ *
+ * If the selection is a `CellSelection` that spans an entire row or column,
+ * returns an object indicating the type and index:
+ * - `{ type: "row", index: number }` for full row selections
+ * - `{ type: "column", index: number }` for full column selections
+ *
+ * If the selection is not a full row/column, or if no table is found, returns null.
+ */
+declare function getTableSelectionType(editor: Editor | null, index?: number, orientation?: Orientation, tablePos?: number): {
+    orientation: Orientation;
+    index: number;
+} | null;
+/**
+ * Get all cells (and unique merged cells) in the selected row or column.
+ *
+ * - If `index` is provided, uses that row/column index.
+ * - If omitted, uses the first selected row/column based on current selection.
+ *
+ * Returns an object with:
+ * - `cells`: all cells in the row/column
+ * - `mergedCells`: only the unique cells that have rowspan/colspan > 1
+ *
+ * If no valid selection or index is found, returns empty arrays.
+ */
+declare function getRowOrColumnCells(editor: Editor | null, index?: number, orientation?: Orientation, tablePos?: number): {
+    cells: CellInfo[];
+    mergedCells: CellInfo[];
+    index?: number;
+    orientation?: Orientation;
+    tablePos?: number;
+};
+/**
+ * After moving a row or column, update the selection to the moved item.
+ *
+ * This ensures that after a move operation, the selection remains on the
+ * moved row or column, providing better user feedback.
+ *
+ * @param editor - The editor instance
+ * @param orientation - "row" or "column" indicating what was moved
+ * @param newIndex - The new index of the moved row/column
+ * @param tablePos - Optional position of the table in the document
+ */
+declare function updateSelectionAfterAction(editor: Editor, orientation: Orientation, newIndex: number, tablePos?: number): void;
+/**
+ * Determines whether a table cell is effectively empty.
+ *
+ * A cell is considered empty when:
+ *  - it has no children, or
+ *  - it contains only whitespace text, or
+ *  - it contains no text and no non-text leaf nodes (images, embeds, etc.)
+ *
+ * Early-outs as soon as any meaningful content is found.
+ *
+ * @param cellNode - The table cell node to check
+ * @returns true if the cell is empty; false otherwise
+ */
+declare function isCellEmpty(cellNode: Node): boolean;
+/**
+ * Returns a command that sets the given attributes to the given values,
+ * and is only available when the currently selected cell doesn't
+ * already have those attributes set to those values.
+ *
+ * @public
+ */
+declare function setCellAttr(attrs: Record<string, unknown>): Command;
+declare function setCellAttr(name: string, value: unknown): Command;
+/**
+ * Cells overlap a rectangle if any of the cells in the rectangle are merged
+ * with cells outside the rectangle.
+ */
+declare function cellsOverlapRectangle({ width, height, map }: TableMap, rect: Rect): boolean;
+/**
+ * Compares two DOMRect objects for equality.
+ *
+ * Treats `undefined` as a valid state, where two `undefined` rects are equal,
+ * and `undefined` is not equal to any defined rect.
+ *
+ * @param a - The first DOMRect or undefined
+ * @param b - The second DOMRect or undefined
+ * @returns true if both rects are equal or both are undefined; false otherwise
+ */
+declare function rectEq(a?: DOMRect | null, b?: DOMRect | null): boolean;
+
+export { type CellInfo, type DispatchSelectionOptions, type DomCellAroundResult, type Orientation, type SelectionReturnMode, type StateSelectionOptions, type TableInfo, type TransactionSelectionOptions, cellsOverlapRectangle, domCellAround, getCellIndicesFromDOM, getColumnCells, getIndexCoordinates, getRowCells, getRowOrColumnCells, getTable, getTableFromDOM, getTableSelectionType, isCellEmpty, isCellMerged, isTableNode, rectEq, selectCellsByCoords, setCellAttr, updateSelectionAfterAction };