Grid navigation

/**
 * Moving through the cells of a grid by the keyboard, as spreadsheets do.
 *
 * Arrow keys move one cell; with the command key they go to the edge. Home and
 * End go to the ends of the row; with the command key, to the first and last
 * cells of the grid. Page Up and Page Down move by a page of rows. Left and
 * right are mirrored where text reads right to left.
 */
import type { Direction } from "./navigation.ts";
import type { Cell } from "./grid-selection.ts";

export type GridMove =
  | { readonly kind: "step"; readonly rows: number; readonly columns: number }
  | { readonly kind: "edge"; readonly rows: number; readonly columns: number }
  | { readonly kind: "page"; readonly pages: 1 | -1 }
  | { readonly kind: "first" | "last" };

export interface GridKey {
  readonly key: string;
  /** The platform's command key: ⌘ on Apple platforms, Ctrl elsewhere. */
  readonly command: boolean;
}

export function gridMoveForKey({ key, command }: GridKey, direction: Direction): GridMove | null {
  const forward = direction === "rtl" ? -1 : 1;
  const kind = command ? "edge" : "step";
  switch (key) {
    case "ArrowDown":
      return { kind, rows: 1, columns: 0 };
    case "ArrowUp":
      return { kind, rows: -1, columns: 0 };
    case "ArrowRight":
      return { kind, rows: 0, columns: forward };
    case "ArrowLeft":
      return { kind, rows: 0, columns: -forward };
    case "Home":
      return command ? { kind: "first" } : { kind: "edge", rows: 0, columns: -1 };
    case "End":
      return command ? { kind: "last" } : { kind: "edge", rows: 0, columns: 1 };
    case "PageDown":
      return { kind: "page", pages: 1 };
    case "PageUp":
      return { kind: "page", pages: -1 };
    default:
      return null;
  }
}

export interface GridExtent {
  readonly rowCount: number;
  readonly columnCount: number;
  /** How many rows a page is: the rows in view. */
  readonly pageSize: number;
}

/** Where a move from `cell` lands, held inside the grid. */
export function applyGridMove(
  cell: Cell,
  move: GridMove,
  { rowCount, columnCount, pageSize }: GridExtent,
): Cell {
  const lastRow = Math.max(rowCount - 1, 0);
  const lastColumn = Math.max(columnCount - 1, 0);
  const hold = (row: number, column: number): Cell => ({
    row: Math.min(Math.max(row, 0), lastRow),
    column: Math.min(Math.max(column, 0), lastColumn),
  });
  switch (move.kind) {
    case "step":
      return hold(cell.row + move.rows, cell.column + move.columns);
    case "edge":
      return hold(
        move.rows === 0 ? cell.row : move.rows > 0 ? lastRow : 0,
        move.columns === 0 ? cell.column : move.columns > 0 ? lastColumn : 0,
      );
    case "page":
      return hold(cell.row + move.pages * Math.max(pageSize, 1), cell.column);
    case "first":
      return hold(0, 0);
    case "last":
      return hold(lastRow, lastColumn);
  }
}