@lotics/xlsx 0.1.0

package/src/selection_model.ts

@@ -0,0 +1,364 @@
+// =============================================================================
+// Selection Model
+// =============================================================================
+//
+// Manages spreadsheet selection state: active cell, selected ranges,
+// drag state, and fill handle.
+// =============================================================================
+
+import { rowColToRef } from "./excel_utils";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface CellRef {
+  row: number;
+  col: number;
+}
+
+export interface CellRange {
+  start: CellRef;
+  end: CellRef;
+}
+
+export interface SelectionState {
+  /** The active cell (where keyboard input goes). */
+  activeCell: CellRef;
+  /** Selected ranges. At least one (containing activeCell). */
+  ranges: CellRange[];
+  /** Whether a drag is in progress. */
+  dragging: boolean;
+  /** Whether a fill-handle drag is in progress. */
+  fillDragging: boolean;
+  /** The range being extended to during fill drag. */
+  fillTarget?: CellRange;
+  /** Edit mode: inline cell editing. */
+  editing: boolean;
+  /** The text being edited (only valid when editing=true). */
+  editText: string;
+}
+
+export type SelectionEvent =
+  | { type: "active_cell_changed"; cell: CellRef }
+  | { type: "selection_changed"; ranges: CellRange[] }
+  | { type: "edit_start"; cell: CellRef; text: string }
+  | { type: "edit_end"; cell: CellRef; text: string; commit: boolean }
+  | { type: "fill_drag"; target: CellRange };
+
+// =============================================================================
+// SelectionModel
+// =============================================================================
+
+export class SelectionModel {
+  private state: SelectionState;
+  private maxRow: number;
+  private maxCol: number;
+  onChange: ((event: SelectionEvent) => void) | undefined;
+
+  constructor(maxRow: number, maxCol: number) {
+    this.maxRow = maxRow;
+    this.maxCol = maxCol;
+    this.state = {
+      activeCell: { row: 1, col: 1 },
+      ranges: [{ start: { row: 1, col: 1 }, end: { row: 1, col: 1 } }],
+      dragging: false,
+      fillDragging: false,
+      editing: false,
+      editText: "",
+    };
+  }
+
+  /** Get current state (read-only snapshot). */
+  getState(): Readonly<SelectionState> {
+    return this.state;
+  }
+
+  /** Get the A1-style reference for the active cell. */
+  getActiveCellRef(): string {
+    return rowColToRef(this.state.activeCell.row, this.state.activeCell.col);
+  }
+
+  /** Get the A1-style reference for the selection range (e.g., "A1:C3"). */
+  getSelectionRef(): string {
+    const range = this.state.ranges[0];
+    if (!range) return this.getActiveCellRef();
+    const nr = normalizeRange(range);
+    if (nr.start.row === nr.end.row && nr.start.col === nr.end.col) {
+      return rowColToRef(nr.start.row, nr.start.col);
+    }
+    return `${rowColToRef(nr.start.row, nr.start.col)}:${rowColToRef(nr.end.row, nr.end.col)}`;
+  }
+
+  // ===========================================================================
+  // Mouse interactions
+  // ===========================================================================
+
+  /** Single click: set active cell and selection. */
+  click(row: number, col: number, shiftKey = false, ctrlKey = false): void {
+    if (this.state.editing) {
+      this.commitEdit();
+    }
+
+    row = clamp(row, 1, this.maxRow);
+    col = clamp(col, 1, this.maxCol);
+
+    if (shiftKey) {
+      // Extend selection from active cell to clicked cell
+      const active = this.state.activeCell;
+      this.state.ranges = [{
+        start: { ...active },
+        end: { row, col },
+      }];
+      this.emit({ type: "selection_changed", ranges: this.state.ranges });
+      return;
+    }
+
+    if (ctrlKey) {
+      // Add new range
+      this.state.ranges.push({
+        start: { row, col },
+        end: { row, col },
+      });
+      this.state.activeCell = { row, col };
+      this.emit({ type: "selection_changed", ranges: this.state.ranges });
+      this.emit({ type: "active_cell_changed", cell: this.state.activeCell });
+      return;
+    }
+
+    // Simple click
+    this.state.activeCell = { row, col };
+    this.state.ranges = [{ start: { row, col }, end: { row, col } }];
+    this.emit({ type: "active_cell_changed", cell: this.state.activeCell });
+    this.emit({ type: "selection_changed", ranges: this.state.ranges });
+  }
+
+  /** Start drag selection. */
+  dragStart(row: number, col: number): void {
+    this.state.dragging = true;
+    this.click(row, col);
+  }
+
+  /** Continue drag. */
+  dragMove(row: number, col: number): void {
+    if (!this.state.dragging) return;
+    row = clamp(row, 1, this.maxRow);
+    col = clamp(col, 1, this.maxCol);
+    const active = this.state.activeCell;
+    this.state.ranges = [{ start: { ...active }, end: { row, col } }];
+    this.emit({ type: "selection_changed", ranges: this.state.ranges });
+  }
+
+  /** End drag. */
+  dragEnd(): void {
+    this.state.dragging = false;
+  }
+
+  // ===========================================================================
+  // Keyboard navigation
+  // ===========================================================================
+
+  /** Move active cell by delta. */
+  move(dRow: number, dCol: number, shiftKey = false): void {
+    if (this.state.editing) {
+      this.commitEdit();
+    }
+
+    const active = this.state.activeCell;
+    const newRow = clamp(active.row + dRow, 1, this.maxRow);
+    const newCol = clamp(active.col + dCol, 1, this.maxCol);
+
+    if (shiftKey) {
+      // Extend selection
+      const range = this.state.ranges[0] ?? { start: { ...active }, end: { ...active } };
+      this.state.ranges = [{ start: range.start, end: { row: newRow, col: newCol } }];
+      this.state.activeCell = { row: newRow, col: newCol };
+      this.emit({ type: "selection_changed", ranges: this.state.ranges });
+    } else {
+      this.state.activeCell = { row: newRow, col: newCol };
+      this.state.ranges = [{ start: { row: newRow, col: newCol }, end: { row: newRow, col: newCol } }];
+      this.emit({ type: "selection_changed", ranges: this.state.ranges });
+    }
+    this.emit({ type: "active_cell_changed", cell: this.state.activeCell });
+  }
+
+  /** Move to a specific cell. */
+  goTo(row: number, col: number): void {
+    if (this.state.editing) this.commitEdit();
+    row = clamp(row, 1, this.maxRow);
+    col = clamp(col, 1, this.maxCol);
+    this.state.activeCell = { row, col };
+    this.state.ranges = [{ start: { row, col }, end: { row, col } }];
+    this.emit({ type: "active_cell_changed", cell: this.state.activeCell });
+    this.emit({ type: "selection_changed", ranges: this.state.ranges });
+  }
+
+  /** Programmatically select a multi-cell range. Active cell is set to top-left. */
+  selectRange(startRow: number, startCol: number, endRow: number, endCol: number): void {
+    if (this.state.editing) this.commitEdit();
+    startRow = clamp(startRow, 1, this.maxRow);
+    startCol = clamp(startCol, 1, this.maxCol);
+    endRow = clamp(endRow, 1, this.maxRow);
+    endCol = clamp(endCol, 1, this.maxCol);
+    this.state.activeCell = { row: startRow, col: startCol };
+    this.state.ranges = [{ start: { row: startRow, col: startCol }, end: { row: endRow, col: endCol } }];
+    this.emit({ type: "active_cell_changed", cell: this.state.activeCell });
+    this.emit({ type: "selection_changed", ranges: this.state.ranges });
+  }
+
+  // ===========================================================================
+  // Cell editing
+  // ===========================================================================
+
+  /** Enter edit mode on the active cell. */
+  startEdit(initialText?: string): void {
+    if (this.state.editing) return;
+    this.state.editing = true;
+    this.state.editText = initialText ?? "";
+    this.emit({
+      type: "edit_start",
+      cell: this.state.activeCell,
+      text: this.state.editText,
+    });
+  }
+
+  /** Update the edit text. */
+  updateEditText(text: string): void {
+    this.state.editText = text;
+  }
+
+  /** Commit the edit (Enter). */
+  commitEdit(): void {
+    if (!this.state.editing) return;
+    this.state.editing = false;
+    this.emit({
+      type: "edit_end",
+      cell: this.state.activeCell,
+      text: this.state.editText,
+      commit: true,
+    });
+    this.state.editText = "";
+  }
+
+  /** Cancel the edit (Escape). */
+  cancelEdit(): void {
+    if (!this.state.editing) return;
+    this.state.editing = false;
+    this.emit({
+      type: "edit_end",
+      cell: this.state.activeCell,
+      text: this.state.editText,
+      commit: false,
+    });
+    this.state.editText = "";
+  }
+
+  // ===========================================================================
+  // Fill handle drag
+  // ===========================================================================
+
+  /** Start a fill-handle drag from the current selection. */
+  fillDragStart(): void {
+    this.state.fillDragging = true;
+    this.state.fillTarget = undefined;
+  }
+
+  /** Update the fill target during a fill drag. Extends from the active selection
+   *  to the drag position, constrained to row or column based on drag direction. */
+  fillDragMove(row: number, col: number): void {
+    if (!this.state.fillDragging) return;
+    row = clamp(row, 1, this.maxRow);
+    col = clamp(col, 1, this.maxCol);
+
+    const range = this.state.ranges[0];
+    if (!range) return;
+    const nr = normalizeRange(range);
+
+    // Determine drag direction: compare distance from selection edge
+    const dRow = row > nr.end.row ? row - nr.end.row : nr.start.row > row ? nr.start.row - row : 0;
+    const dCol = col > nr.end.col ? col - nr.end.col : nr.start.col > col ? nr.start.col - col : 0;
+
+    if (dRow === 0 && dCol === 0) {
+      this.state.fillTarget = undefined;
+      return;
+    }
+
+    if (dRow >= dCol) {
+      // Extend vertically: keep same columns as selection
+      if (row > nr.end.row) {
+        this.state.fillTarget = {
+          start: { row: nr.end.row + 1, col: nr.start.col },
+          end: { row, col: nr.end.col },
+        };
+      } else {
+        this.state.fillTarget = {
+          start: { row, col: nr.start.col },
+          end: { row: nr.start.row - 1, col: nr.end.col },
+        };
+      }
+    } else {
+      // Extend horizontally: keep same rows as selection
+      if (col > nr.end.col) {
+        this.state.fillTarget = {
+          start: { row: nr.start.row, col: nr.end.col + 1 },
+          end: { row: nr.end.row, col },
+        };
+      } else {
+        this.state.fillTarget = {
+          start: { row: nr.start.row, col },
+          end: { row: nr.end.row, col: nr.start.col - 1 },
+        };
+      }
+    }
+  }
+
+  /** End fill drag. Returns the fill target range and resets state. */
+  fillDragEnd(): CellRange | undefined {
+    const target = this.state.fillTarget;
+    this.state.fillDragging = false;
+    this.state.fillTarget = undefined;
+    if (target) {
+      this.emit({ type: "fill_drag", target });
+    }
+    return target;
+  }
+
+  // ===========================================================================
+  // Bounds
+  // ===========================================================================
+
+  updateBounds(maxRow: number, maxCol: number): void {
+    this.maxRow = maxRow;
+    this.maxCol = maxCol;
+  }
+
+  // ===========================================================================
+  // Event emission
+  // ===========================================================================
+
+  private emit(event: SelectionEvent): void {
+    this.onChange?.(event);
+  }
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function clamp(v: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, v));
+}
+
+/** Normalize a range so start <= end. */
+export function normalizeRange(range: CellRange): CellRange {
+  return {
+    start: {
+      row: Math.min(range.start.row, range.end.row),
+      col: Math.min(range.start.col, range.end.col),
+    },
+    end: {
+      row: Math.max(range.start.row, range.end.row),
+      col: Math.max(range.start.col, range.end.col),
+    },
+  };
+}