@jackuait/blok 0.6.0-beta.4 → 0.6.0-beta.5

package/src/tools/table/index.ts

@@ -18,7 +18,7 @@ import { TableGrid } from './table-core';
 import {
   applyPixelWidths,
   computeHalfAvgWidth,
-  computeInsertColumnWidths,
+  computeInitialColWidth,
   deleteColumnWithBlockCleanup,
   deleteRowWithBlockCleanup,
   enableScrollOverflow,
@@ -30,14 +30,14 @@ import {
   normalizeTableData,
   populateNewCells,
   readPixelWidths,
-  redistributePercentWidths,
   SCROLL_OVERFLOW_CLASSES,
   setupKeyboardNavigation,
-  syncColWidthsAfterMove,
   updateHeadingColumnStyles,
   updateHeadingStyles,
 } from './table-operations';
 import { TableResize } from './table-resize';
+import { executeRowColAction } from './table-row-col-action-handler';
+import type { PendingHighlight } from './table-row-col-action-handler';
 import { TableRowColControls } from './table-row-col-controls';
 import type { RowColAction } from './table-row-col-controls';
 import type { TableData, TableConfig } from './types';
@@ -71,7 +71,7 @@ export class Table implements BlockTool {
   private cellSelection: TableCellSelection | null = null;
   private element: HTMLDivElement | null = null;
   private blockId: string | undefined;
-  private pendingHighlight: { type: 'row' | 'col'; index: number } | null = null;
+  private pendingHighlight: PendingHighlight | null = null;
 
   constructor({ data, config, api, readOnly, block }: BlockToolConstructorOptions<TableData, TableConfig>) {
     this.api = api;
@@ -178,6 +178,14 @@ export class Table implements BlockTool {
 
     this.data.content = this.cellBlocks?.initializeCells(this.data.content) ?? this.data.content;
 
+    if (this.data.initialColWidth === undefined) {
+      const widths = this.data.colWidths ?? readPixelWidths(gridEl);
+
+      this.data.initialColWidth = widths.length > 0
+        ? computeInitialColWidth(widths)
+        : undefined;
+    }
+
     this.initResize(gridEl);
     this.initAddControls(gridEl);
     this.initRowColControls(gridEl);
@@ -197,6 +205,7 @@ export class Table implements BlockTool {
       stretched: this.data.stretched,
       content,
       ...(colWidths ? { colWidths } : {}),
+      ...(this.data.initialColWidth !== undefined ? { initialColWidth: this.data.initialColWidth } : {}),
     };
   }
 
@@ -252,6 +261,8 @@ export class Table implements BlockTool {
   }
 
   public destroy(): void {
+    this.cellBlocks?.deleteAllBlocks();
+
     this.resize?.destroy();
     this.resize = null;
     this.addControls?.destroy();
@@ -296,9 +307,12 @@ export class Table implements BlockTool {
       return;
     }
 
+    const dragState = { addedCols: 0 };
+
     this.addControls = new TableAddControls({
       wrapper: this.element,
       grid: gridEl,
+      i18n: this.api.i18n,
       onAddRow: () => {
         this.grid.addRow(gridEl);
         populateNewCells(gridEl, this.cellBlocks);
@@ -310,10 +324,12 @@ export class Table implements BlockTool {
       },
       onAddColumn: () => {
         const colWidths = this.data.colWidths ?? readPixelWidths(gridEl);
-        const halfAvgWidth = computeHalfAvgWidth(colWidths);
+        const halfWidth = this.data.initialColWidth !== undefined
+          ? Math.round((this.data.initialColWidth / 2) * 100) / 100
+          : computeHalfAvgWidth(colWidths);
 
-        this.grid.addColumn(gridEl, undefined, colWidths);
-        this.data.colWidths = [...colWidths, halfAvgWidth];
+        this.grid.addColumn(gridEl, undefined, colWidths, halfWidth);
+        this.data.colWidths = [...colWidths, halfWidth];
         populateNewCells(gridEl, this.cellBlocks);
         updateHeadingColumnStyles(this.element, this.data.withHeadingColumn);
         this.initResize(gridEl);
@@ -342,14 +358,22 @@ export class Table implements BlockTool {
       },
       onDragAddCol: () => {
         const colWidths = this.data.colWidths ?? readPixelWidths(gridEl);
-        const halfAvgWidth = computeHalfAvgWidth(colWidths);
+        const halfWidth = this.data.initialColWidth !== undefined
+          ? Math.round((this.data.initialColWidth / 2) * 100) / 100
+          : computeHalfAvgWidth(colWidths);
 
-        this.grid.addColumn(gridEl, undefined, colWidths);
-        this.data.colWidths = [...colWidths, halfAvgWidth];
+        this.grid.addColumn(gridEl, undefined, colWidths, halfWidth);
+        this.data.colWidths = [...colWidths, halfWidth];
         applyPixelWidths(gridEl, this.data.colWidths);
         populateNewCells(gridEl, this.cellBlocks);
         updateHeadingColumnStyles(this.element, this.data.withHeadingColumn);
         this.initResize(gridEl);
+
+        dragState.addedCols++;
+
+        if (this.element) {
+          this.element.scrollLeft = this.element.scrollWidth;
+        }
       },
       onDragRemoveCol: () => {
         const colCount = this.grid.getColumnCount(gridEl);
@@ -365,6 +389,8 @@ export class Table implements BlockTool {
         }
 
         this.initResize(gridEl);
+
+        dragState.addedCols--;
       },
       onDragEnd: () => {
         this.initResize(gridEl);
@@ -372,8 +398,10 @@ export class Table implements BlockTool {
         this.rowColControls?.refresh();
 
         if (this.element) {
-          this.element.scrollLeft = 0;
+          this.element.scrollLeft = dragState.addedCols > 0 ? this.element.scrollWidth : 0;
         }
+
+        dragState.addedCols = 0;
       },
     });
   }
@@ -391,6 +419,7 @@ export class Table implements BlockTool {
       getRowCount: () => this.grid.getRowCount(gridEl),
       isHeadingRow: () => this.data.withHeadings,
       isHeadingColumn: () => this.data.withHeadingColumn,
+      i18n: this.api.i18n,
       onAction: (action: RowColAction) => this.handleRowColAction(gridEl, action),
       onDragStateChange: (isDragging: boolean) => {
         if (this.resize) {
@@ -434,72 +463,37 @@ export class Table implements BlockTool {
   }
 
   private handleRowColAction(gridEl: HTMLElement, action: RowColAction): void {
-    switch (action.type) {
-      case 'insert-row-above':
-        this.grid.addRow(gridEl, action.index);
-        populateNewCells(gridEl, this.cellBlocks);
-        this.pendingHighlight = { type: 'row', index: action.index };
-        break;
-      case 'insert-row-below':
-        this.grid.addRow(gridEl, action.index + 1);
-        populateNewCells(gridEl, this.cellBlocks);
-        this.pendingHighlight = { type: 'row', index: action.index + 1 };
-        break;
-      case 'insert-col-left':
-        this.data.colWidths = computeInsertColumnWidths(gridEl, action.index, this.data, this.grid);
-        populateNewCells(gridEl, this.cellBlocks);
-        this.pendingHighlight = { type: 'col', index: action.index };
-        break;
-      case 'insert-col-right':
-        this.data.colWidths = computeInsertColumnWidths(gridEl, action.index + 1, this.data, this.grid);
-        populateNewCells(gridEl, this.cellBlocks);
-        this.pendingHighlight = { type: 'col', index: action.index + 1 };
-        break;
-      case 'move-row':
-        this.grid.moveRow(gridEl, action.fromIndex, action.toIndex);
-        break;
-      case 'move-col':
-        this.grid.moveColumn(gridEl, action.fromIndex, action.toIndex);
-        this.data.colWidths = syncColWidthsAfterMove(this.data.colWidths, action.fromIndex, action.toIndex);
-        break;
-      case 'delete-row': {
-        deleteRowWithBlockCleanup(gridEl, action.index, this.grid, this.cellBlocks);
-        const newRowCount = this.grid.getRowCount(gridEl);
-        const neighborRow = action.index < newRowCount ? action.index : action.index - 1;
-
-        this.pendingHighlight = { type: 'row', index: neighborRow };
-        break;
-      }
-      case 'delete-col': {
-        this.data.colWidths = deleteColumnWithBlockCleanup(gridEl, action.index, this.data.colWidths, this.grid, this.cellBlocks);
-
-        if (this.data.colWidths) {
-          applyPixelWidths(gridEl, this.data.colWidths);
-        } else {
-          redistributePercentWidths(gridEl);
-        }
-
-        const newColCount = this.grid.getColumnCount(gridEl);
-        const neighborCol = action.index < newColCount ? action.index : action.index - 1;
+    const result = executeRowColAction(
+      gridEl,
+      action,
+      { grid: this.grid, data: this.data, cellBlocks: this.cellBlocks },
+    );
 
-        this.pendingHighlight = { type: 'col', index: neighborCol };
-        break;
-      }
-      case 'toggle-heading':
-        this.data.withHeadings = !this.data.withHeadings;
-        this.pendingHighlight = { type: 'row', index: 0 };
-        break;
-      case 'toggle-heading-column':
-        this.data.withHeadingColumn = !this.data.withHeadingColumn;
-        this.pendingHighlight = { type: 'col', index: 0 };
-        break;
-    }
+    this.data.colWidths = result.colWidths;
+    this.data.withHeadings = result.withHeadings;
+    this.data.withHeadingColumn = result.withHeadingColumn;
+    this.pendingHighlight = result.pendingHighlight;
 
     updateHeadingStyles(this.element, this.data.withHeadings);
     updateHeadingColumnStyles(this.element, this.data.withHeadingColumn);
     this.initResize(gridEl);
     this.addControls?.syncRowButtonWidth();
     this.rowColControls?.refresh();
+
+    if (!result.moveSelection) {
+      return;
+    }
+
+    // After move operations, select the moved row/column to show where it landed
+    const { type: moveType, index: moveIndex } = result.moveSelection;
+
+    if (moveType === 'row') {
+      this.cellSelection?.selectRow(moveIndex);
+    } else {
+      this.cellSelection?.selectColumn(moveIndex);
+    }
+
+    this.rowColControls?.setActiveGrip(moveType, moveIndex);
   }
 
   private initResize(gridEl: HTMLElement): void {
@@ -547,6 +541,7 @@ export class Table implements BlockTool {
     this.cellSelection = new TableCellSelection({
       grid: gridEl,
       rectangleSelection, // Pass reference
+      i18n: this.api.i18n,
       onSelectionActiveChange: (hasSelection) => {
         if (this.resize) {
           this.resize.enabled = !hasSelection;
@@ -567,3 +562,5 @@ export class Table implements BlockTool {
     });
   }
 }
+
+export { isInsideTableCell, isRestrictedInTableCell, convertToParagraph } from './table-restrictions';

package/src/tools/table/table-add-controls.ts

@@ -1,3 +1,4 @@
+import type { I18n } from '../../../types/api';
 import { IconPlus } from '../../components/icons';
 import { createTooltipContent } from '../../components/modules/toolbar/tooltip';
 import { hide as hideTooltip, onHover } from '../../components/utils/tooltip';
@@ -46,6 +47,7 @@ interface DragState {
 interface TableAddControlsOptions {
   wrapper: HTMLElement;
   grid: HTMLElement;
+  i18n: I18n;
   onAddRow: () => void;
   onAddColumn: () => void;
   onDragStart: () => void;
@@ -64,6 +66,7 @@ interface TableAddControlsOptions {
 export class TableAddControls {
   private wrapper: HTMLElement;
   private grid: HTMLElement;
+  private i18n: I18n;
   private addRowBtn: HTMLElement;
   private addColBtn: HTMLElement;
   private rowHideTimeout: ReturnType<typeof setTimeout> | null = null;
@@ -90,6 +93,7 @@ export class TableAddControls {
   constructor(options: TableAddControlsOptions) {
     this.wrapper = options.wrapper;
     this.grid = options.grid;
+    this.i18n = options.i18n;
 
     this.boundAddRowClick = options.onAddRow;
     this.boundAddColClick = options.onAddColumn;
@@ -151,10 +155,15 @@ export class TableAddControls {
    * Disables pointer events and hover effects during cell selection.
    */
   public setInteractive(interactive: boolean): void {
-    const pointerEvents = interactive ? '' : 'none';
+    if (!interactive) {
+      this.addRowBtn.style.pointerEvents = 'none';
+      this.addColBtn.style.pointerEvents = 'none';
 
-    this.addRowBtn.style.pointerEvents = pointerEvents;
-    this.addColBtn.style.pointerEvents = pointerEvents;
+      return;
+    }
+
+    this.addRowBtn.style.pointerEvents = this.rowVisible ? '' : 'none';
+    this.addColBtn.style.pointerEvents = this.colVisible ? '' : 'none';
   }
 
   public destroy(): void {
@@ -314,6 +323,7 @@ export class TableAddControls {
 
     if (!this.rowVisible) {
       this.addRowBtn.style.opacity = '1';
+      this.addRowBtn.style.pointerEvents = '';
       this.rowVisible = true;
     }
   }
@@ -323,6 +333,7 @@ export class TableAddControls {
 
     if (!this.colVisible) {
       this.addColBtn.style.opacity = '1';
+      this.addColBtn.style.pointerEvents = '';
       this.colVisible = true;
     }
   }
@@ -334,6 +345,7 @@ export class TableAddControls {
 
     this.rowHideTimeout = setTimeout(() => {
       this.addRowBtn.style.opacity = '0';
+      this.addRowBtn.style.pointerEvents = 'none';
       this.rowVisible = false;
       this.rowHideTimeout = null;
     }, HIDE_DELAY_MS);
@@ -346,6 +358,7 @@ export class TableAddControls {
 
     this.colHideTimeout = setTimeout(() => {
       this.addColBtn.style.opacity = '0';
+      this.addColBtn.style.pointerEvents = 'none';
       this.colVisible = false;
       this.colHideTimeout = null;
     }, HIDE_DELAY_MS);
@@ -372,6 +385,10 @@ export class TableAddControls {
     btn.setAttribute(ADD_ROW_ATTR, '');
     btn.setAttribute('contenteditable', 'false');
     btn.style.opacity = '0';
+    btn.style.pointerEvents = 'none';
+    btn.style.position = 'absolute';
+    btn.style.left = '0';
+    btn.style.bottom = '-36px';
     btn.style.boxSizing = 'content-box';
     btn.style.width = '100%';
     btn.style.height = '32px';
@@ -388,8 +405,8 @@ export class TableAddControls {
     btn.appendChild(visual);
 
     onHover(btn, createTooltipContent([
-      'Click to add a new row',
-      'Drag to add or remove rows',
+      this.i18n.t('tools.table.clickToAddRow'),
+      this.i18n.t('tools.table.dragToAddRemoveRows'),
     ]), { placement: 'bottom', marginTop: -16 });
 
     return btn;
@@ -402,6 +419,7 @@ export class TableAddControls {
     btn.setAttribute(ADD_COL_ATTR, '');
     btn.setAttribute('contenteditable', 'false');
     btn.style.opacity = '0';
+    btn.style.pointerEvents = 'none';
     btn.style.position = 'absolute';
     btn.style.right = '-36px';
     btn.style.top = '0px';
@@ -418,8 +436,8 @@ export class TableAddControls {
     btn.appendChild(visual);
 
     onHover(btn, createTooltipContent([
-      'Click to add a new column',
-      'Drag to add or remove columns',
+      this.i18n.t('tools.table.clickToAddColumn'),
+      this.i18n.t('tools.table.dragToAddRemoveColumns'),
     ]), { placement: 'bottom' });
 
     return btn;

package/src/tools/table/table-cell-blocks.ts

@@ -71,6 +71,7 @@ export class TableCellBlocks {
     this.onNavigateToCell = options.onNavigateToCell;
 
     this.api.events.on('block changed', this.handleBlockMutation);
+    this.gridElement.addEventListener('click', this.handleCellBlankSpaceClick);
   }
 
   /**
@@ -575,10 +576,71 @@ export class TableCellBlocks {
     });
   }
 
+  /**
+   * Delete all blocks managed by this table from the BlockManager.
+   * Called before the table block itself is removed to prevent orphaned cell blocks.
+   */
+  public deleteAllBlocks(): void {
+    const allCells = this.gridElement.querySelectorAll(`[${CELL_ATTR}]`);
+    const blockIds = this.getBlockIdsFromCells(allCells);
+
+    this.deleteBlocks(blockIds);
+  }
+
+  /**
+   * Handle clicks on blank cell space.
+   * When a click lands on the cell or blocks container (not on block content),
+   * set the caret to the end of the last block in that cell.
+   */
+  private handleCellBlankSpaceClick = (event: Event): void => {
+    const target = event.target as HTMLElement | null;
+
+    if (!target) {
+      return;
+    }
+
+    const isCell = target.hasAttribute(CELL_ATTR);
+    const isBlocksContainer = target.hasAttribute(CELL_BLOCKS_ATTR);
+
+    if (!isCell && !isBlocksContainer) {
+      return;
+    }
+
+    const cell = isCell ? target : target.closest<HTMLElement>(`[${CELL_ATTR}]`);
+
+    if (!cell) {
+      return;
+    }
+
+    const container = isCell
+      ? cell.querySelector<HTMLElement>(`[${CELL_BLOCKS_ATTR}]`)
+      : target;
+
+    if (!container) {
+      return;
+    }
+
+    const blockHolders = container.querySelectorAll('[data-blok-id]');
+    const lastHolder = blockHolders[blockHolders.length - 1];
+
+    if (!lastHolder) {
+      return;
+    }
+
+    const blockId = lastHolder.getAttribute('data-blok-id');
+
+    if (!blockId) {
+      return;
+    }
+
+    this.api.caret.setToBlock(blockId, 'end');
+  };
+
   /**
    * Clean up event listeners
    */
   destroy(): void {
+    this.gridElement.removeEventListener('click', this.handleCellBlankSpaceClick);
     this.api.events.off('block changed', this.handleBlockMutation);
     this._activeCellWithBlocks = null;
     this.cellsPendingCheck.clear();

package/src/tools/table/table-cell-selection.ts

@@ -1,3 +1,4 @@
+import type { I18n } from '../../../types/api';
 import { IconCross } from '../../components/icons';
 import { PopoverDesktop } from '../../components/utils/popover';
 import { twMerge } from '../../components/utils/tw';
@@ -56,6 +57,7 @@ interface CellSelectionOptions {
   rectangleSelection?: { cancelActiveSelection: () => void };
   onSelectionActiveChange?: (hasSelection: boolean) => void;
   onClearContent?: (cells: HTMLElement[]) => void;
+  i18n: I18n;
 }
 
 export class TableCellSelection {
@@ -63,6 +65,7 @@ export class TableCellSelection {
   private rectangleSelection?: { cancelActiveSelection: () => void };
   private onSelectionActiveChange: ((hasSelection: boolean) => void) | undefined;
   private onClearContent: ((cells: HTMLElement[]) => void) | undefined;
+  private i18n: I18n;
   private anchorCell: CellCoord | null = null;
   private extentCell: CellCoord | null = null;
   private isSelecting = false;
@@ -77,12 +80,14 @@ export class TableCellSelection {
   private boundPointerUp: () => void;
   private boundClearSelection: (e: PointerEvent) => void;
   private boundCancelRectangle: (e: MouseEvent) => void;
+  private boundKeyDown: (e: KeyboardEvent) => void;
 
   constructor(options: CellSelectionOptions) {
     this.grid = options.grid;
     this.rectangleSelection = options.rectangleSelection;
     this.onSelectionActiveChange = options.onSelectionActiveChange;
     this.onClearContent = options.onClearContent;
+    this.i18n = options.i18n;
     this.grid.style.position = 'relative';
 
     this.boundPointerDown = this.handlePointerDown.bind(this);
@@ -90,8 +95,10 @@ export class TableCellSelection {
     this.boundPointerUp = this.handlePointerUp.bind(this);
     this.boundClearSelection = this.handleClearSelection.bind(this);
     this.boundCancelRectangle = this.handleCancelRectangle.bind(this);
+    this.boundKeyDown = this.handleKeyDown.bind(this);
 
     this.grid.addEventListener('pointerdown', this.boundPointerDown);
+    document.addEventListener('keydown', this.boundKeyDown);
   }
 
   public destroy(): void {
@@ -102,6 +109,7 @@ export class TableCellSelection {
     document.removeEventListener('pointerup', this.boundPointerUp);
     document.removeEventListener('pointerdown', this.boundClearSelection);
     document.removeEventListener('mousemove', this.boundCancelRectangle, true);
+    document.removeEventListener('keydown', this.boundKeyDown);
   }
 
   /**
@@ -276,6 +284,25 @@ export class TableCellSelection {
     this.clearSelection();
   }
 
+  private handleKeyDown(e: KeyboardEvent): void {
+    // Only trigger when selection is active
+    if (!this.hasSelection) {
+      return;
+    }
+
+    // Check for Delete or Backspace
+    if (e.key !== 'Delete' && e.key !== 'Backspace') {
+      return;
+    }
+
+    // Prevent default behavior
+    e.preventDefault();
+
+    // Clear content and dismiss selection
+    this.onClearContent?.([...this.selectedCells]);
+    this.clearSelection();
+  }
+
   private clearSelection(): void {
     const hadSelection = this.hasSelection;
 
@@ -348,26 +375,10 @@ export class TableCellSelection {
     const rows = this.grid.querySelectorAll(`[${ROW_ATTR}]`);
 
     // Mark selected cells
-    for (let r = minRow; r <= maxRow; r++) {
-      const row = rows[r];
-
-      if (!row) {
-        continue;
-      }
-
-      const cells = row.querySelectorAll(`[${CELL_ATTR}]`);
-
-      for (let c = minCol; c <= maxCol; c++) {
-        const cell = cells[c] as HTMLElement | undefined;
-
-        if (!cell) {
-          continue;
-        }
-
-        cell.setAttribute(SELECTED_ATTR, '');
-        this.selectedCells.push(cell);
-      }
-    }
+    this.selectedCells = this.collectCellsInRange(rows, minRow, maxRow, minCol, maxCol);
+    this.selectedCells.forEach(cell => {
+      cell.setAttribute(SELECTED_ATTR, '');
+    });
 
     // Calculate overlay position from bounding rects of corner cells
     const firstCell = rows[minRow]?.querySelectorAll(`[${CELL_ATTR}]`)[minCol] as HTMLElement | undefined;
@@ -388,16 +399,14 @@ export class TableCellSelection {
     const borderTop = parseFloat(gridStyle.borderTopWidth) || 0;
     const borderLeft = parseFloat(gridStyle.borderLeftWidth) || 0;
 
-    let top = firstRect.top - gridRect.top - borderTop;
-    let left = firstRect.left - gridRect.left - borderLeft;
     const width = lastRect.right - firstRect.left + 1;
     const height = lastRect.bottom - firstRect.top + 1;
 
     // Extend overlay 1px outward to cover adjacent borders:
     // grid border-top/border-left at row 0/col 0, or the previous
     // row's border-bottom / previous column's border-right otherwise.
-    top -= 1;
-    left -= 1;
+    const top = firstRect.top - gridRect.top - borderTop - 1;
+    const left = firstRect.left - gridRect.left - borderLeft - 1;
 
     // Create overlay once, reuse on subsequent paints
     if (!this.overlay) {
@@ -476,7 +485,7 @@ export class TableCellSelection {
     const items: PopoverItemParams[] = [
       {
         icon: IconCross,
-        title: 'Clear',
+        title: this.i18n.t('tools.table.clearSelection'),
         closeOnActivate: true,
         onActivate: (): void => {
           this.onClearContent?.([...this.selectedCells]);
@@ -592,27 +601,8 @@ export class TableCellSelection {
       return;
     }
 
-    // Clamp row
-    let row: number;
-
-    if (e.clientY < gridRect.top) {
-      row = 0;
-    } else if (e.clientY > gridRect.bottom) {
-      row = rowCount - 1;
-    } else {
-      row = this.extentCell?.row ?? this.anchorCell.row;
-    }
-
-    // Clamp col
-    let col: number;
-
-    if (e.clientX < gridRect.left) {
-      col = 0;
-    } else if (e.clientX > gridRect.right) {
-      col = colCount - 1;
-    } else {
-      col = this.extentCell?.col ?? this.anchorCell.col;
-    }
+    const row = this.clampAxis(e.clientY, gridRect.top, gridRect.bottom, rowCount, this.extentCell?.row ?? this.anchorCell.row);
+    const col = this.clampAxis(e.clientX, gridRect.left, gridRect.right, colCount, this.extentCell?.col ?? this.anchorCell.col);
 
     const clamped = { row, col };
 
@@ -621,4 +611,38 @@ export class TableCellSelection {
       this.paintSelection();
     }
   }
+
+  private collectCellsInRange(
+    rows: NodeListOf<Element>,
+    minRow: number,
+    maxRow: number,
+    minCol: number,
+    maxCol: number,
+  ): HTMLElement[] {
+    return Array.from(rows)
+      .slice(minRow, maxRow + 1)
+      .flatMap(row => {
+        const cells = row.querySelectorAll(`[${CELL_ATTR}]`);
+
+        return Array.from(cells)
+          .slice(minCol, maxCol + 1)
+          .filter((cell): cell is HTMLElement => cell instanceof HTMLElement);
+      });
+  }
+
+  /**
+   * Clamp a pointer coordinate to an axis range, returning the edge index
+   * when outside or the fallback when inside.
+   */
+  private clampAxis(pointer: number, min: number, max: number, count: number, fallback: number): number {
+    if (pointer < min) {
+      return 0;
+    }
+
+    if (pointer > max) {
+      return count - 1;
+    }
+
+    return fallback;
+  }
 }