@lotics/xlsx 0.1.0

package/src/keyboard_nav.ts

@@ -0,0 +1,891 @@
+// =============================================================================
+// Keyboard Navigation
+// =============================================================================
+//
+// Pure TypeScript keyboard event handler for the spreadsheet editor.
+// Translates KeyboardEvent into selection model, command, and clipboard actions.
+// No DOM dependencies beyond the KeyboardEvent interface.
+// =============================================================================
+
+import type { SelectionModel } from "./selection_model";
+import { normalizeRange } from "./selection_model";
+import type { WorkbookModel } from "./workbook_model";
+import type { CommandHistory } from "./command_history";
+import type { FormulaEngine } from "./formula_engine";
+import type { ClipboardData } from "./clipboard";
+import {
+  setRangeStyleCommand,
+  clearRangeCommand,
+  setHiddenRowsCommand,
+  setHiddenColsCommand,
+  setCellValueCommand,
+} from "./spreadsheet_commands";
+import { copyRange, pasteRange, clipboardToText, clipboardToHtml } from "./clipboard";
+import { rowColToRef } from "./excel_utils";
+
+// =============================================================================
+// Context
+// =============================================================================
+
+export interface KeyboardNavContext {
+  selection: SelectionModel;
+  workbook: WorkbookModel;
+  sheetIndex: number;
+  history: CommandHistory;
+  engine: FormulaEngine | undefined;
+  /** Internal clipboard buffer. */
+  clipboardData: ClipboardData | undefined;
+  setClipboardData: (data: ClipboardData | undefined) => void;
+  /** Callback to start inline cell editing. */
+  onStartEdit: (initialText?: string) => void;
+  /** Callback to request a canvas redraw. */
+  onRedraw: () => void;
+  /** Callback to open paste special dialog. */
+  onPasteSpecial?: () => void;
+  /** Callback to open find/replace bar. */
+  onFindReplace?: (replaceMode: boolean) => void;
+  /** Callback to save/download the workbook. */
+  onSave?: () => void;
+  /** Viewport size for page up/down (in rows). */
+  pageSize: number;
+}
+
+// =============================================================================
+// Main handler
+// =============================================================================
+
+/**
+ * Handle a keydown event. Returns true if the event was consumed
+ * (caller should preventDefault).
+ */
+export function handleKeyDown(
+  event: KeyboardEvent,
+  ctx: KeyboardNavContext,
+): boolean {
+  const { selection, workbook, sheetIndex, history } = ctx;
+  const state = selection.getState();
+  const ctrl = event.ctrlKey || event.metaKey;
+  const shift = event.shiftKey;
+
+  // If currently editing, only handle navigation keys that exit editing
+  if (state.editing) {
+    return handleEditingKeys(event, ctx);
+  }
+
+  // --- Ctrl shortcuts ---
+  if (ctrl) {
+    switch (event.key.toLowerCase()) {
+      case "z":
+        if (shift) {
+          history.redo();
+        } else {
+          history.undo();
+        }
+        ctx.onRedraw();
+        return true;
+
+      case "y":
+        history.redo();
+        ctx.onRedraw();
+        return true;
+
+      case "c":
+        handleCopy(ctx, false);
+        return true;
+
+      case "x":
+        handleCopy(ctx, true);
+        return true;
+
+      case "v":
+        if (shift && ctx.onPasteSpecial) {
+          ctx.onPasteSpecial();
+        } else {
+          handlePasteWithFallback(ctx);
+        }
+        return true;
+
+      case "b":
+        toggleStyle(ctx, "fontBold");
+        return true;
+
+      case "i":
+        toggleStyle(ctx, "fontItalic");
+        return true;
+
+      case "u":
+        toggleStyle(ctx, "fontUnderline");
+        return true;
+
+      case "a":
+        selectAll(ctx);
+        return true;
+
+      case "f":
+        ctx.onFindReplace?.(false);
+        return true;
+
+      case "h":
+        ctx.onFindReplace?.(true);
+        return true;
+
+      case "s":
+        ctx.onSave?.();
+        return true;
+
+      case "home":
+        selection.goTo(1, 1);
+        ctx.onRedraw();
+        return true;
+
+      case "end": {
+        // Ctrl+End → last cell of the used range (Excel parity).
+        const sheet = workbook.sheets[sheetIndex];
+        const used = sheet.getUsedRange();
+        const targetRow = Math.max(used.maxRow || 1, 1);
+        const targetCol = Math.max(used.maxCol || 1, 1);
+        selection.goTo(targetRow, targetCol);
+        ctx.onRedraw();
+        return true;
+      }
+
+      case ";": {
+        // Ctrl+; → insert today's date as YYYY-MM-DD (Excel parity).
+        // Excel writes the date as a serial; we write the rendered string,
+        // which our number-format engine will recognize as a date.
+        const today = formatToday();
+        commitToActiveCell(ctx, today);
+        return true;
+      }
+
+      case ":": {
+        // Ctrl+Shift+; (US layout) — same key code as ":" — inserts current
+        // time. We accept the bare ":" key as well for non-US layouts where
+        // ":" is its own key.
+        const time = formatNow();
+        commitToActiveCell(ctx, time);
+        return true;
+      }
+
+      case "9": {
+        // Ctrl+9 → hide selected rows.
+        const sheet = workbook.sheets[sheetIndex];
+        const range = state.ranges[0];
+        if (!range) return false;
+        const sr = Math.min(range.start.row, range.end.row);
+        const er = Math.max(range.start.row, range.end.row);
+        const newHidden = new Set(sheet.hiddenRows);
+        for (let r = sr; r <= er; r++) newHidden.add(r);
+        ctx.history.execute(setHiddenRowsCommand(workbook, sheetIndex, newHidden));
+        ctx.onRedraw();
+        return true;
+      }
+
+      case "0": {
+        // Ctrl+0 → hide selected columns.
+        const sheet = workbook.sheets[sheetIndex];
+        const range = state.ranges[0];
+        if (!range) return false;
+        const sc = Math.min(range.start.col, range.end.col);
+        const ec = Math.max(range.start.col, range.end.col);
+        const newHidden = new Set(sheet.hiddenCols);
+        for (let c = sc; c <= ec; c++) newHidden.add(c);
+        ctx.history.execute(setHiddenColsCommand(workbook, sheetIndex, newHidden));
+        ctx.onRedraw();
+        return true;
+      }
+    }
+    // Ctrl+Arrow: jump to edge of data region
+    if (isArrowKey(event.key)) {
+      handleCtrlArrow(event.key, ctx);
+      return true;
+    }
+    return false;
+  }
+
+  // --- Non-ctrl keys ---
+  switch (event.key) {
+    case "ArrowUp":
+      selection.move(-1, 0, shift);
+      ctx.onRedraw();
+      return true;
+
+    case "ArrowDown":
+      selection.move(1, 0, shift);
+      ctx.onRedraw();
+      return true;
+
+    case "ArrowLeft":
+      selection.move(0, -1, shift);
+      ctx.onRedraw();
+      return true;
+
+    case "ArrowRight":
+      selection.move(0, 1, shift);
+      ctx.onRedraw();
+      return true;
+
+    case "Tab": {
+      // When the active cell is inside a multi-cell selection, wrap within
+      // the range — pressing Tab past the last column moves to the next
+      // row's first column. Excel and Sheets both do this; without it,
+      // "fill in this row" workflows break the second the user reaches the
+      // edge.
+      const range = state.ranges[0];
+      if (range && rangeIsMulti(range)) {
+        moveWithinRange(selection, range, "horizontal", shift);
+      } else {
+        selection.move(0, shift ? -1 : 1);
+      }
+      ctx.onRedraw();
+      return true;
+    }
+
+    case "Enter": {
+      const range = state.ranges[0];
+      if (range && rangeIsMulti(range)) {
+        moveWithinRange(selection, range, "vertical", shift);
+      } else {
+        selection.move(shift ? -1 : 1, 0);
+      }
+      ctx.onRedraw();
+      return true;
+    }
+
+    case "Escape":
+      return false;
+
+    case "Home":
+      selection.goTo(state.activeCell.row, 1);
+      ctx.onRedraw();
+      return true;
+
+    case "End":
+      // End key alone does nothing — handled in combo with arrow
+      return false;
+
+    case "PageUp":
+      selection.move(-ctx.pageSize, 0, shift);
+      ctx.onRedraw();
+      return true;
+
+    case "PageDown":
+      selection.move(ctx.pageSize, 0, shift);
+      ctx.onRedraw();
+      return true;
+
+    case "Delete":
+      handleDelete(ctx);
+      return true;
+
+    case "Backspace":
+      handleDelete(ctx);
+      ctx.onStartEdit("");
+      return true;
+
+    case "F2": {
+      const ref = rowColToRef(state.activeCell.row, state.activeCell.col);
+      const cell = workbook.sheets[sheetIndex].getCell(ref);
+      const existing = cell?.formula ? `=${cell.formula}` : cell?.displayValue ?? "";
+      ctx.onStartEdit(existing);
+      return true;
+    }
+  }
+
+  // Printable character → enter edit mode with that character (replace mode)
+  if (isPrintableKey(event)) {
+    ctx.onStartEdit(event.key);
+    return true;
+  }
+
+  return false;
+}
+
+// =============================================================================
+// Keys while editing
+// =============================================================================
+
+function handleEditingKeys(
+  event: KeyboardEvent,
+  ctx: KeyboardNavContext,
+): boolean {
+  const { selection } = ctx;
+  const shift = event.shiftKey;
+
+  switch (event.key) {
+    case "Enter":
+      // Alt+Enter inserts a newline inside the cell (Excel parity); plain
+      // Enter commits and advances. The input element handles the literal
+      // newline insert; we just signal "don't commit" so the editor keeps
+      // focus.
+      if (event.altKey) {
+        return false;
+      }
+      selection.commitEdit();
+      selection.move(shift ? -1 : 1, 0);
+      ctx.onRedraw();
+      return true;
+
+    case "Tab":
+      selection.commitEdit();
+      selection.move(0, shift ? -1 : 1);
+      ctx.onRedraw();
+      return true;
+
+    case "Escape":
+      selection.cancelEdit();
+      ctx.onRedraw();
+      return true;
+
+    case "F4":
+      // F4 in edit mode cycles the reference type at the cursor:
+      //   A1 → $A$1 → A$1 → $A1 → A1
+      // Returning false lets the input handle its native default; the actual
+      // cycle is implemented at the editor input layer (cell_editor.ts) since
+      // it needs cursor position. We just preventDefault here so the browser
+      // doesn't trigger Find Next.
+      return false;
+  }
+
+  // All other keys are handled by the input element itself
+  return false;
+}
+
+// =============================================================================
+// F4 reference-type cycling (called by the cell editor input)
+// =============================================================================
+
+/**
+ * Cycle the reference at the given cursor position through the four absolute
+ * states. Returns the new text + new cursor position, or null if no reference
+ * is found at the cursor.
+ *
+ *   A1     → $A$1
+ *   $A$1   → A$1
+ *   A$1    → $A1
+ *   $A1    → A1
+ */
+export function cycleReferenceAtCursor(
+  text: string,
+  cursor: number,
+): { text: string; cursor: number } | null {
+  // Match a cell reference touching the cursor. Walk backwards/forwards from
+  // the cursor to find a contiguous reference token.
+  const refRegex = /(\$?)([A-Za-z]+)(\$?)([0-9]+)/g;
+  let match: RegExpExecArray | null;
+  while ((match = refRegex.exec(text)) !== null) {
+    const start = match.index;
+    const end = start + match[0].length;
+    if (cursor < start || cursor > end) continue;
+    const colAbs = match[1] === "$";
+    const rowAbs = match[3] === "$";
+    let nextCol: boolean;
+    let nextRow: boolean;
+    if (!colAbs && !rowAbs) { nextCol = true; nextRow = true; }
+    else if (colAbs && rowAbs) { nextCol = false; nextRow = true; }
+    else if (!colAbs && rowAbs) { nextCol = true; nextRow = false; }
+    else { nextCol = false; nextRow = false; }
+    const newRef = `${nextCol ? "$" : ""}${match[2]}${nextRow ? "$" : ""}${match[4]}`;
+    const newText = text.slice(0, start) + newRef + text.slice(end);
+    return { text: newText, cursor: start + newRef.length };
+  }
+  return null;
+}
+
+// =============================================================================
+// Copy / Cut (exported for toolbar use)
+// =============================================================================
+
+export function performCopy(ctx: KeyboardNavContext, isCut: boolean): void {
+  handleCopy(ctx, isCut);
+}
+
+export function performPaste(ctx: KeyboardNavContext): void {
+  handlePasteWithFallback(ctx);
+}
+
+function handleCopy(ctx: KeyboardNavContext, isCut: boolean): void {
+  const { selection, workbook, sheetIndex } = ctx;
+  const range = normalizeRange(selection.getState().ranges[0]);
+  const data = copyRange(
+    workbook,
+    sheetIndex,
+    range.start.row,
+    range.start.col,
+    range.end.row,
+    range.end.col,
+    isCut,
+  );
+  ctx.setClipboardData(data);
+
+  // Write to system clipboard
+  const text = clipboardToText(data);
+  const html = clipboardToHtml(data, workbook.styles);
+  writeToSystemClipboard(text, html);
+}
+
+// =============================================================================
+// Paste
+// =============================================================================
+
+function handlePaste(ctx: KeyboardNavContext): void {
+  const { selection, workbook, sheetIndex, engine, history } = ctx;
+  const clipboard = ctx.clipboardData;
+  if (!clipboard) return;
+
+  const active = selection.getState().activeCell;
+  const targetSheet = workbook.sheets[sheetIndex];
+
+  // Snapshot target cells before paste so we can undo
+  const snapshot = new Map<string, { value: import("./workbook_model").CellValue; displayValue: string; formula?: string; styleIndex: number; numFmtCode: string } | null>();
+  for (let r = 0; r < clipboard.rowCount; r++) {
+    for (let c = 0; c < clipboard.colCount; c++) {
+      const ref = rowColToRef(active.row + r, active.col + c);
+      const existing = targetSheet.getCell(ref);
+      snapshot.set(ref, existing ? {
+        value: existing.value,
+        displayValue: existing.displayValue,
+        formula: existing.formula,
+        styleIndex: existing.styleIndex,
+        numFmtCode: existing.numFmtCode,
+      } : null);
+    }
+  }
+
+  // Snapshot cut source cells if needed
+  const cutSnapshot = new Map<string, { value: import("./workbook_model").CellValue; displayValue: string; formula?: string; styleIndex: number; numFmtCode: string }>();
+  if (clipboard.isCut) {
+    const srcSheet = workbook.sheets[clipboard.sourceSheet];
+    for (let r = 0; r < clipboard.rowCount; r++) {
+      for (let c = 0; c < clipboard.colCount; c++) {
+        const ref = rowColToRef(clipboard.origin.row + r, clipboard.origin.col + c);
+        const cell = srcSheet.getCell(ref);
+        if (cell) {
+          cutSnapshot.set(ref, {
+            value: cell.value,
+            displayValue: cell.displayValue,
+            formula: cell.formula,
+            styleIndex: cell.styleIndex,
+            numFmtCode: cell.numFmtCode,
+          });
+        }
+      }
+    }
+  }
+
+  const wasCut = clipboard.isCut;
+  const sourceSheetIndex = clipboard.sourceSheet;
+
+  const cmd = {
+    description: `Paste at ${rowColToRef(active.row, active.col)}`,
+    execute() {
+      const result = pasteRange(workbook, clipboard, sheetIndex, active.row, active.col);
+
+      if (wasCut) {
+        const srcSheet = workbook.sheets[sourceSheetIndex];
+        for (let r = 0; r < clipboard.rowCount; r++) {
+          for (let c = 0; c < clipboard.colCount; c++) {
+            const ref = rowColToRef(clipboard.origin.row + r, clipboard.origin.col + c);
+            srcSheet.deleteCell(ref);
+          }
+        }
+      }
+
+      if (engine) {
+        const sheet = workbook.sheets[sheetIndex];
+        for (const w of result.written) {
+          engine.onCellChanged(sheet.name, w.ref, w.formula);
+        }
+      }
+    },
+    undo() {
+      // Restore target cells from snapshot
+      for (const [ref, snap] of snapshot) {
+        if (snap) {
+          targetSheet.set(ref, snap.value, targetSheet.styles?.get(snap.styleIndex), snap.numFmtCode, snap.formula);
+        } else {
+          targetSheet.deleteCell(ref);
+        }
+        if (engine) {
+          engine.onCellChanged(targetSheet.name, ref, snap?.formula);
+        }
+      }
+
+      // Restore cut source cells
+      if (wasCut) {
+        const srcSheet = workbook.sheets[sourceSheetIndex];
+        for (const [ref, snap] of cutSnapshot) {
+          srcSheet.set(ref, snap.value, srcSheet.styles?.get(snap.styleIndex), snap.numFmtCode, snap.formula);
+          if (engine) {
+            engine.onCellChanged(srcSheet.name, ref, snap.formula);
+          }
+        }
+      }
+    },
+  };
+  history.execute(cmd);
+
+  if (wasCut) {
+    ctx.setClipboardData(undefined);
+  }
+
+  ctx.onRedraw();
+}
+
+// =============================================================================
+// Delete / Clear
+// =============================================================================
+
+function handleDelete(ctx: KeyboardNavContext): void {
+  const { selection, workbook, sheetIndex, history, engine } = ctx;
+  const range = normalizeRange(selection.getState().ranges[0]);
+
+  const cmd = clearRangeCommand(
+    workbook,
+    engine,
+    sheetIndex,
+    range.start.row,
+    range.start.col,
+    range.end.row,
+    range.end.col,
+  );
+  history.execute(cmd);
+  ctx.onRedraw();
+}
+
+// =============================================================================
+// Style toggling
+// =============================================================================
+
+type ToggleableBoolStyle = "fontBold" | "fontItalic";
+type ToggleableUnderlineStyle = "fontUnderline";
+
+function toggleStyle(
+  ctx: KeyboardNavContext,
+  prop: ToggleableBoolStyle | ToggleableUnderlineStyle,
+): void {
+  const { selection, workbook, sheetIndex, history } = ctx;
+  const range = normalizeRange(selection.getState().ranges[0]);
+  const active = selection.getState().activeCell;
+  const ref = rowColToRef(active.row, active.col);
+  const cell = workbook.sheets[sheetIndex].getCell(ref);
+  const style = workbook.styles.get(cell?.styleIndex ?? 0);
+
+  let override: Record<string, unknown>;
+  if (prop === "fontUnderline") {
+    override = { fontUnderline: style.fontUnderline ? undefined : "single" as const };
+  } else {
+    override = { [prop]: !style[prop] };
+  }
+
+  const cmd = setRangeStyleCommand(
+    workbook,
+    sheetIndex,
+    range.start.row,
+    range.start.col,
+    range.end.row,
+    range.end.col,
+    override,
+  );
+  history.execute(cmd);
+  ctx.onRedraw();
+}
+
+// =============================================================================
+// Select All
+// =============================================================================
+
+function selectAll(ctx: KeyboardNavContext): void {
+  const { selection, workbook, sheetIndex } = ctx;
+  const sheet = workbook.sheets[sheetIndex];
+  const used = sheet.getUsedRange();
+  selection.click(1, 1);
+  selection.click(used.maxRow, used.maxCol, true);
+  ctx.onRedraw();
+}
+
+// =============================================================================
+// Ctrl+Arrow — jump to data edge
+// =============================================================================
+
+function handleCtrlArrow(key: string, ctx: KeyboardNavContext): void {
+  const { selection, workbook, sheetIndex } = ctx;
+  const state = selection.getState();
+  const active = state.activeCell;
+  const sheet = workbook.sheets[sheetIndex];
+  const used = sheet.getUsedRange();
+
+  let targetRow = active.row;
+  let targetCol = active.col;
+
+  const hasData = (r: number, c: number): boolean => {
+    const ref = rowColToRef(r, c);
+    const cell = sheet.getCell(ref);
+    return cell !== undefined && cell.value !== null && cell.value !== "";
+  };
+
+  switch (key) {
+    case "ArrowUp":
+      targetRow = findEdge(active.row, -1, 1, used.maxRow, (r) => hasData(r, active.col));
+      break;
+    case "ArrowDown":
+      targetRow = findEdge(active.row, 1, 1, used.maxRow, (r) => hasData(r, active.col));
+      break;
+    case "ArrowLeft":
+      targetCol = findEdge(active.col, -1, 1, used.maxCol, (c) => hasData(active.row, c));
+      break;
+    case "ArrowRight":
+      targetCol = findEdge(active.col, 1, 1, used.maxCol, (c) => hasData(active.row, c));
+      break;
+  }
+
+  if (ctx.selection.getState().dragging) return;
+  selection.goTo(targetRow, targetCol);
+  ctx.onRedraw();
+}
+
+/**
+ * Find the edge of a data region.
+ * If current position has data, jump to the last consecutive data cell in the direction.
+ * If current position is empty, jump to the next data cell in the direction.
+ * If no data found, jump to the boundary.
+ */
+function findEdge(
+  current: number,
+  direction: 1 | -1,
+  min: number,
+  max: number,
+  hasData: (pos: number) => boolean,
+): number {
+  const currentHasData = hasData(current);
+  let pos = current + direction;
+
+  if (currentHasData) {
+    // Skip consecutive data cells
+    while (pos >= min && pos <= max && hasData(pos)) {
+      pos += direction;
+    }
+    // Back up to last data cell (or stay if we hit a non-data immediately)
+    pos -= direction;
+    if (pos === current) {
+      // No consecutive data — jump to next data cell or boundary
+      pos = current + direction;
+      while (pos >= min && pos <= max && !hasData(pos)) {
+        pos += direction;
+      }
+      if (pos < min || pos > max) {
+        return direction === -1 ? min : max;
+      }
+    }
+  } else {
+    // Current empty — find next data cell
+    while (pos >= min && pos <= max && !hasData(pos)) {
+      pos += direction;
+    }
+    if (pos < min || pos > max) {
+      return direction === -1 ? min : max;
+    }
+  }
+
+  return pos;
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+// =============================================================================
+// Tab/Enter wrap within a multi-cell selection range
+// =============================================================================
+
+function rangeIsMulti(range: import("./selection_model").CellRange): boolean {
+  return range.start.row !== range.end.row || range.start.col !== range.end.col;
+}
+
+/**
+ * Move the active cell inside an existing range with wrap-around. Direction
+ * is "horizontal" (Tab) or "vertical" (Enter). When `reverse` is true, wraps
+ * backwards; e.g. Shift+Tab from the top-left corner wraps to the
+ * bottom-right of the range.
+ */
+function moveWithinRange(
+  selection: import("./selection_model").SelectionModel,
+  range: import("./selection_model").CellRange,
+  direction: "horizontal" | "vertical",
+  reverse: boolean,
+): void {
+  const sr = Math.min(range.start.row, range.end.row);
+  const er = Math.max(range.start.row, range.end.row);
+  const sc = Math.min(range.start.col, range.end.col);
+  const ec = Math.max(range.start.col, range.end.col);
+  const width = ec - sc + 1;
+  const height = er - sr + 1;
+  const total = width * height;
+
+  const { activeCell } = selection.getState();
+  // Linearize current position within the range, in row-major or col-major
+  // order depending on direction.
+  const rowIdx = activeCell.row - sr;
+  const colIdx = activeCell.col - sc;
+  let linear = direction === "horizontal"
+    ? rowIdx * width + colIdx
+    : colIdx * height + rowIdx;
+  linear = (linear + (reverse ? -1 : 1) + total) % total;
+
+  let newRow: number;
+  let newCol: number;
+  if (direction === "horizontal") {
+    newRow = sr + Math.floor(linear / width);
+    newCol = sc + (linear % width);
+  } else {
+    newCol = sc + Math.floor(linear / height);
+    newRow = sr + (linear % height);
+  }
+  selection.goTo(newRow, newCol);
+}
+
+// =============================================================================
+// Date / Time insertion (Ctrl+; and Ctrl+:)
+// =============================================================================
+
+function formatToday(): string {
+  const d = new Date();
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+}
+
+function formatNow(): string {
+  const d = new Date();
+  return `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}:${String(d.getSeconds()).padStart(2, "0")}`;
+}
+
+/**
+ * Commit a string to the active cell via setCellValueCommand. Used by Ctrl+;
+ * (date) and Ctrl+: (time) — both bypass edit mode and write directly.
+ */
+function commitToActiveCell(ctx: KeyboardNavContext, text: string): void {
+  const { row, col } = ctx.selection.getState().activeCell;
+  ctx.history.execute(setCellValueCommand(ctx.workbook, ctx.engine, ctx.sheetIndex, row, col, text));
+  ctx.onRedraw();
+}
+
+function isArrowKey(key: string): boolean {
+  return key === "ArrowUp" || key === "ArrowDown" || key === "ArrowLeft" || key === "ArrowRight";
+}
+
+function isPrintableKey(event: KeyboardEvent): boolean {
+  // Single character, not a control/meta key
+  if (event.ctrlKey || event.metaKey || event.altKey) return false;
+  if (event.key.length !== 1) return false;
+  // Exclude non-printable ranges
+  const code = event.key.charCodeAt(0);
+  return code >= 0x20; // space and above
+}
+
+/**
+ * Paste from internal clipboard if available, otherwise read from system clipboard.
+ * System clipboard text is parsed as TSV and pasted as values.
+ */
+async function handlePasteWithFallback(ctx: KeyboardNavContext): Promise<void> {
+  if (ctx.clipboardData) {
+    handlePaste(ctx);
+    return;
+  }
+
+  // No internal clipboard — try reading from system clipboard
+  const systemData = await readSystemClipboard();
+  if (!systemData) return;
+
+  const { selection, workbook, sheetIndex, history, engine } = ctx;
+  const active = selection.getState().activeCell;
+  const sheet = workbook.sheets[sheetIndex];
+
+  // Parse TSV into a grid of strings
+  const rows = systemData.split("\n").filter((line) => line.length > 0);
+  const grid = rows.map((row) => row.split("\t"));
+
+  // Snapshot target cells for undo
+  const snapshot = new Map<string, { value: import("./workbook_model").CellValue; displayValue: string; formula?: string; styleIndex: number; numFmtCode: string } | null>();
+  for (let r = 0; r < grid.length; r++) {
+    for (let c = 0; c < grid[r].length; c++) {
+      const ref = rowColToRef(active.row + r, active.col + c);
+      const existing = sheet.getCell(ref);
+      snapshot.set(ref, existing ? {
+        value: existing.value,
+        displayValue: existing.displayValue,
+        formula: existing.formula,
+        styleIndex: existing.styleIndex,
+        numFmtCode: existing.numFmtCode,
+      } : null);
+    }
+  }
+
+  const cmd = {
+    description: `Paste from clipboard at ${rowColToRef(active.row, active.col)}`,
+    execute() {
+      for (let r = 0; r < grid.length; r++) {
+        for (let c = 0; c < grid[r].length; c++) {
+          const ref = rowColToRef(active.row + r, active.col + c);
+          const existing = sheet.getCell(ref);
+          const styleIndex = existing?.styleIndex ?? 0;
+          const numFmtCode = existing?.numFmtCode ?? "General";
+          const text = grid[r][c];
+          const value = inferValue(text);
+          sheet.set(ref, value, sheet.styles?.get(styleIndex), numFmtCode);
+          engine?.onCellChanged(sheet.name, ref, undefined);
+        }
+      }
+    },
+    undo() {
+      for (const [ref, snap] of snapshot) {
+        if (snap) {
+          sheet.set(ref, snap.value, sheet.styles?.get(snap.styleIndex), snap.numFmtCode, snap.formula);
+        } else {
+          sheet.deleteCell(ref);
+        }
+        engine?.onCellChanged(sheet.name, ref, snap?.formula);
+      }
+    },
+  };
+  history.execute(cmd);
+  ctx.onRedraw();
+}
+
+/** Infer a typed value from clipboard text. */
+function inferValue(text: string): import("./workbook_model").CellValue {
+  if (!text) return null;
+  if (text === "TRUE") return true;
+  if (text === "FALSE") return false;
+  const num = Number(text);
+  if (!isNaN(num) && text.trim() !== "") return num;
+  return text;
+}
+
+async function readSystemClipboard(): Promise<string | null> {
+  try {
+    if (navigator?.clipboard?.readText) {
+      return await navigator.clipboard.readText();
+    }
+  } catch {
+    // Clipboard read may not be permitted
+  }
+  return null;
+}
+
+async function writeToSystemClipboard(text: string, html: string): Promise<void> {
+  try {
+    if (navigator?.clipboard?.write) {
+      const blob = new Blob([html], { type: "text/html" });
+      const textBlob = new Blob([text], { type: "text/plain" });
+      await navigator.clipboard.write([
+        new ClipboardItem({
+          "text/html": blob,
+          "text/plain": textBlob,
+        }),
+      ]);
+    } else if (navigator?.clipboard?.writeText) {
+      await navigator.clipboard.writeText(text);
+    }
+  } catch {
+    // Clipboard API may not be available in all contexts
+  }
+}