Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

47.8 KB
Raw Blame
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
// Selection, keyboard motion, the clipboard's TSV, and the fill handle.
//
// A SELECTION IS DATA. Nothing here touches the DOM: the grid renders what this
// says, and this never reads what the grid drew. That is what makes every rule
// below provable in node — which matters more here than anywhere else in the
// app, because these are the behaviours nobody writes down and everybody
// notices the instant they are wrong.
//
// COORDINATES ARE VISIBLE POSITIONS, not row ids. The grid reads through an
// order vector (grid.ts: sorting sorts the vector, not the data), so row 3 of a
// sorted view is not rid 3. A selection that stored rids would silently
// re-target the moment somebody clicked a column header — the cells stay
// selected, the highlight jumps. The grid maps position → rid at the edge;
// everything in here is (row, col) into what the reader can see.
//
// THE CURSOR IS NOT THE HEAD, and conflating them is what breaks Tab inside a
// selected block. A range has an anchor and a head — the end shift+arrow moves
// — and, SEPARATELY, one active cell where typing lands. Tab inside a block
// walks the active cell while the block stays perfectly still; if Tab moved the
// head, the selection would grow by one cell per keystroke.
//
// THE TAB RUN is the piece implementations miss. Tab across a row, press Enter,
// and you must land under the cell the run STARTED in — not under the last one
// you typed. Without it, entering a table row by row walks diagonally down and
// to the right, and the grid feels broken in a way people cannot name.
//
// A JUMP IS BOUNDED. ⌘↓ runs to the far end of the data BLOCK, and where there
// is no more data it stops at the last row of the sheet. This grid HAS a last
// row — that is the point of a columnar sheet over an infinite canvas — so
// there is no Excel row 1,048,576 to fall into and no way back from.
//
// TSV IS NOT CSV, and this is deliberately not import.ts's parser. Clipboard
// text is the one format every spreadsheet on earth speaks and it has to
// round-trip EXACTLY. import.ts sniffs a delimiter (wrong here: the delimiter
// is a tab, always, and a column of "a,b" values must not become two columns)
// and drops a trailing empty row (right for a file, wrong here: a copied blank
// cell must paste as a blank and CLEAR what it lands on, and a paste that
// quietly does nothing is an edit the user believes landed).

// --- Ranges ----------------------------------------------------------------

export interface CellRef { row: number; col: number }

/**
 * `anchor` is where the drag began and `head` is where it is now; either may be
 * the smaller. Storing them un-normalised is what lets shift+arrow shrink a
 * selection back through its anchor instead of flipping it inside out.
 *
 * NOTE this shadows the DOM's `Range` inside any module that imports it. That
 * is the name the whole spreadsheet world uses and renaming it to `CellRange`
 * would be a worse trade than the shadow.
 */
export interface Range { anchor: CellRef; head: CellRef }

export interface Box { top: number; left: number; bottom: number; right: number }

export const normalize = (r: Range): Box => ({
  top: Math.min(r.anchor.row, r.head.row),
  left: Math.min(r.anchor.col, r.head.col),
  bottom: Math.max(r.anchor.row, r.head.row),
  right: Math.max(r.anchor.col, r.head.col),
})

export function contains(r: Range, row: number, col: number): boolean {
  const b = normalize(r)
  return row >= b.top && row <= b.bottom && col >= b.left && col <= b.right
}

export function size(r: Range): { rows: number; cols: number } {
  const b = normalize(r)
  return { rows: b.bottom - b.top + 1, cols: b.right - b.left + 1 }
}

/** A range from a box, for callers that think in corners (row/col headers). */
export const rangeOf = (top: number, left: number, bottom: number, right: number): Range =>
  ({ anchor: { row: top, col: left }, head: { row: bottom, col: right } })

// --- Keys ------------------------------------------------------------------

/**
 * What a key MEANS, decided once and away from the DOM.
 *
 * Split from what a key DOES so the mapping is testable without a grid and so
 * the clipboard and history verbs — which are not selection operations at all —
 * come out of the same switch instead of a second one that drifts from it.
 */
export type Action =
  /** `unit` is the distance: one cell, one screen, or to the edge of the data
   *  block. `dr`/`dc` stay ±1 and the caller multiplies, because only the grid
   *  knows how many rows a page is. */
  | { kind: 'move'; dr: number; dc: number; unit: 'cell' | 'page' | 'edge'; extend: boolean }
  | { kind: 'tab'; back: boolean }
  | { kind: 'enter'; back: boolean }
  /** `whole` is the ⌘ variant: ⌘Home is the first cell of the sheet, not of the row. */
  | { kind: 'home'; whole: boolean; extend: boolean }
  | { kind: 'end'; whole: boolean; extend: boolean }
  | { kind: 'selectAll' }
  | { kind: 'selectRow' }
  | { kind: 'selectCol' }
  | { kind: 'clear' }
  | { kind: 'edit' }
  | { kind: 'cancel' }
  | { kind: 'copy' }
  | { kind: 'cut' }
  | { kind: 'paste' }
  | { kind: 'undo' }
  | { kind: 'redo' }
  /**
   * ⌘B / ⌘I / ⌘U — the appearance of the selected CELLS, on either kind of
   * sheet. Declared here rather than as three actions because the field is the
   * only thing that differs and the card should say so once per key.
   *
   * NOT handled by `Grid.handleKey`: it falls through (no motion, no match),
   * and main.ts picks it up beside ⌘D, because a style write goes through
   * cellfmt.ts's patch builders and the grid does not write cells for the
   * panel. Same division `fill` already uses.
   */
  | { kind: 'style'; field: 'bold' | 'italic' | 'underline' }
  /** Push the top row of the selection down through the rest of it (⌘D, ⌘↵). */
  | { kind: 'fill' }
  /**
   * PASTE SPECIAL — open the menu of what to paste (values, formulas,
   * formats, transposed).
   *
   * NOT handled by `Grid.handleKey`, and not by the document `paste` listener
   * either: the browser only delivers a `paste` EVENT for the browser's own
   * paste chord, so a second chord has to read the clip this app remembered
   * when the copy happened. main.ts owns both, beside `fill` and `style`, for
   * the reason those two are there — this WRITES CELLS, which the selection
   * model cannot do.
   *
   * ⌘⇧V is the chord because Excel's own ⌘⌃V cannot be described by this map
   * (it probes ⌘ and ctrl separately, never together) and because ⇧ is what
   * Sheets uses for the same family. keyToAction ALSO answers pasteSpecial for
   * ⌘⌃V — it costs one condition and it is the key half the world's fingers
   * already know.
   */
  | { kind: 'pasteSpecial' }
  /**
   * TEXT TO COLUMNS — split the selected column on a delimiter or at fixed
   * widths.
   *
   * Excel has no shortcut for this (it is a ribbon button), and the reason to
   * claim one here is the SPREADSHEET kind: a dataset reaches the command from
   * its cell menu and its column-header menu, and `kind:'canvas'` has neither
   * — grid.ts declines to open the dataset cell menu over a spreadsheet, and
   * it is right to. Without a key, half the app cannot reach the feature at
   * all. ⌘⇧D sits beside ⌘D, which is already this map's answer to "the
   * browser wanted that key for a bookmark".
   */
  | { kind: 'textToColumns' }
  /**
   * OPEN THE FIND BAR — and this map entry is why ⌘F is safe to claim at all.
   *
   * The grid is windowed: about 55 of a 5,000-row sheet's rows exist in the
   * DOM, so the BROWSER's ⌘F searches those 55 and tells the reader that a
   * value in their own file is not there. Leaving the key unclaimed is not
   * neutral, it is a wrong answer with the browser's authority behind it. The
   * implementation lives in find.ts, in the CAPTURE phase, exactly as help.ts
   * implements '?': this map says what the key MEANS, and it is the only place
   * that does — the shortcut card is generated from it.
   */
  | { kind: 'find' }
  /**
   * ctrl+PageUp / ctrl+PageDown: the previous and next sheet, as they have been
   * in every spreadsheet since Excel 5. tabs.ts owns the verb and implements it
   * in the capture phase, the way panels.ts owns `]`.
   */
  | { kind: 'sheetStep'; dir: -1 | 1 }
  /** ⌘G / ⇧⌘G: the next and previous match, without going back to the field. */
  | { kind: 'findNext'; back: boolean }
  /**
   * The three verbs below are NOT the grid's, and they are in this map anyway.
   *
   * A keyboard that cannot list itself is a keyboard nobody finds: every one of
   * these is a key this application already claims, so leaving them out of the
   * one place that says what a key means guarantees the shortcut card is a
   * hand-written copy that drifts. Declaring them changes nothing at run time —
   * `applyMotion` reports them unhandled, so whoever owns the verb still runs
   * it (main.ts saves, help.ts opens the card, panels.ts toggles the panels).
   */
  | { kind: 'save' }
  | { kind: 'help' }
  | { kind: 'panel'; side: 'left' | 'right' }

/** Structurally a KeyboardEvent, so a real event passes straight in. */
export interface KeyLike {
  key: string
  shiftKey?: boolean
  metaKey?: boolean
  ctrlKey?: boolean
  altKey?: boolean
}

const ARROWS: Record<string, [number, number]> = {
  ArrowUp: [-1, 0], ArrowDown: [1, 0], ArrowLeft: [0, -1], ArrowRight: [0, 1],
}

/**
 * The real spreadsheet key set, or null for a key this model does not own.
 *
 * NULL IS THE IMPORTANT RETURN. A grid that claims every keystroke swallows the
 * ones that should start an edit (typing a digit), and one that claims a
 * modified key it does not implement turns a shortcut into a cursor move.
 *
 * THREE PRINTABLE KEYS ARE CLAIMED — '?', '[' and ']' — and none of them is
 * claimed HERE: help.ts and panels.ts take them in the CAPTURE phase, before
 * main.ts's typing route runs. They are declared anyway, because a keyboard
 * described in three files is a keyboard described wrongly in two of them, and
 * because main.ts's printable-key route should ask this map whether a key is
 * spoken for before handing it to `grid.typeInto`. That question is what makes
 * ⇧Space select a row: without it the printable route sees a space, opens a
 * cell editor, and the binding below never runs (measured — ⇧Space typed a
 * space into the cell for as long as it has existed).
 */
export function keyToAction(e: KeyLike): Action | null {
  const shift = e.shiftKey === true
  // ⌘ on a Mac, ctrl everywhere else. Treating them as one is right for every
  // binding here — there is no combination where they must differ.
  const cmd = e.metaKey === true || e.ctrlKey === true

  // A modifier we do not own is NOT the unmodified key. Alt+↓ opens the filter
  // menu in every spreadsheet on earth; reading it as "move down" is how a
  // shortcut silently becomes a cursor move.
  if (e.altKey === true) return null

  const arrow = ARROWS[e.key]
  if (arrow) {
    return { kind: 'move', dr: arrow[0], dc: arrow[1], unit: cmd ? 'edge' : 'cell', extend: shift }
  }

  switch (e.key) {
    case 'Tab': return { kind: 'tab', back: shift }
    // ⌘↵ FILLS rather than moving. It used to fall through to a plain Enter,
    // which made the one key a spreadsheet user presses to push a value through
    // a selected block a second, indistinguishable way of moving down one cell.
    case 'Enter': return cmd ? { kind: 'fill' } : { kind: 'enter', back: shift }
    case 'Home': return { kind: 'home', whole: cmd, extend: shift }
    case 'End': return { kind: 'end', whole: cmd, extend: shift }
    case 'PageUp': return cmd
      ? { kind: 'sheetStep', dir: -1 }
      : { kind: 'move', dr: -1, dc: 0, unit: 'page', extend: shift }
    case 'PageDown': return cmd
      ? { kind: 'sheetStep', dir: 1 }
      : { kind: 'move', dr: 1, dc: 0, unit: 'page', extend: shift }
    case 'Escape': return { kind: 'cancel' }
    // Mac keyboards send Backspace where a PC sends Delete, and both mean
    // "empty these cells" in a grid.
    case 'Delete': case 'Backspace': return { kind: 'clear' }
    case 'F2': return { kind: 'edit' }
    // A bare space types a space; only the modified forms select. ⌘⇧Space is
    // the whole sheet — Excel and Sheets both widen the selection one step at a
    // time (cell → column → sheet) and a user who has learned that reaches for
    // it before they reach for ⌘A.
    case ' ': return cmd && shift ? { kind: 'selectAll' }
      : shift ? { kind: 'selectRow' }
        : cmd ? { kind: 'selectCol' } : null
    /**
     * '?' opens the shortcut card — and this entry alone opens nothing.
     *
     * '?' is PRINTABLE, and main.ts hands printable keys to `grid.typeInto`
     * before it ever consults this map, so help.ts claims the keystroke in the
     * CAPTURE phase exactly as panels.ts claims '[' and ']'. What this entry
     * buys is that the card can describe the key that opens it without anybody
     * typing the row by hand. The cost is one character that can no longer
     * START a cell entry: F2 first (or double-click), then type it.
     *
     * ⌘? is deliberately NOT help. It is ⌘⇧/ on a US layout, and claiming a
     * modified key we do not implement is how a shortcut becomes a dead key.
     */
    case '?': return cmd ? null : { kind: 'help' }
    /**
     * '[' and ']' are IMPLEMENTED IN panels.ts, in the capture phase. They are
     * declared here so the keyboard has ONE description and the card stays
     * generated; nothing reads this entry to toggle a panel. ⌘[ is not a panel
     * toggle for the same reason ⌘? is not help — panels.ts ignores modified
     * forms, so the map must too or the card advertises a key that does nothing.
     */
    case '[': return cmd ? null : { kind: 'panel', side: 'left' }
    case ']': return cmd ? null : { kind: 'panel', side: 'right' }
  }

  if (!cmd) return null
  // Shift changes the KEY, not just the flag: ⌘⇧Z arrives as 'Z'. Comparing
  // against 'z' without folding case is why redo stops working on the one
  // shortcut users reach for after an undo they did not mean.
  switch (e.key.toLowerCase()) {
    case 'a': return { kind: 'selectAll' }
    case 'c': return { kind: 'copy' }
    case 'x': return { kind: 'cut' }
    // ⇧ is the paste-special menu, and so is holding ⌘ AND ctrl together —
    // Excel's own ⌘⌃V. The map folds ⌘ and ctrl into one `cmd` everywhere
    // else because no binding has ever needed them apart; this one does, so it
    // asks for both explicitly rather than changing the fold for everybody.
    case 'v': return shift || (e.metaKey === true && e.ctrlKey === true)
      ? { kind: 'pasteSpecial' } : { kind: 'paste' }
    case 'z': return shift ? { kind: 'redo' } : { kind: 'undo' }
    case 'y': return { kind: 'redo' }
    // ⌘D is the fill people actually press — ⌘↵ is Excel's, ⌘D is Sheets' and
    // Excel's both. Unclaimed it is the browser's bookmark dialog, which is
    // what a spreadsheet user gets today for reaching for fill-down.
    case 'd': return shift ? { kind: 'textToColumns' } : { kind: 'fill' }
    // ⌘F and ⌘G are the two keys every application on the platform already
    // means by "find" and "find again", and both are the browser's by default
    // — which is precisely the problem, because the browser can only see the
    // rows the virtualiser left in the DOM. Shift is deliberately ignored on
    // 'f' (⇧⌘F is the same verb) and load-bearing on 'g'.
    // ⌘B / ⌘I / ⌘U. The browser's own defaults here (bookmarks bar, view
    // source on some builds) are the reason a grid must claim them explicitly;
    // every spreadsheet on the platform already means bold/italic/underline.
    case 'b': return { kind: 'style', field: 'bold' }
    case 'i': return { kind: 'style', field: 'italic' }
    case 'u': return { kind: 'style', field: 'underline' }
    case 'f': return { kind: 'find' }
    case 'g': return { kind: 'findNext', back: shift }
    case 's': return { kind: 'save' }
    // Sheets' shortcut-card key, and the one that does not cost a printable
    // character. '?' above is the same verb for people who learned it in slides.
    case '/': return { kind: 'help' }
  }
  return null
}

// --- Describing the map ------------------------------------------------------
//
// THE SHORTCUT CARD IS GENERATED FROM keyToAction, never written beside it.
//
// A hand-kept list of keys drifts inside one release and then teaches people
// bindings that no longer exist — worse than no list, because a wrong list is
// believed. So the card asks the map: probe it across the whole key space and
// report what it answers. Add a case to the switch above and the row appears
// with no other edit; delete one and the row disappears.
//
// The probe is EXHAUSTIVE rather than a curated list of keys to ask about,
// because a curated list is the same maintenance burden with an extra step in
// front of it. It is a few hundred pure function calls, run when the card
// opens.
//
// What is NOT derivable, and must not be faked here: gestures that never reach
// this map at all (a bare printable key opens the editor; double-click; the
// fill handle). help.ts writes those as prose, clearly labelled as prose.

/** One key combination, in the shape a shortcut card wants to draw. */
export interface KeyChord {
  key: string
  /** 'either' = ⌘ or ctrl, which is the usual case — the map folds them. */
  mod: 'none' | 'either' | 'meta' | 'ctrl'
  shift: boolean
  alt: boolean
}

/** Every key that produces one action, and the action itself. */
export interface BindingRow {
  /** the action's identity with direction left out: 'move.edge.extend', 'copy' */
  sig: string
  action: Action
  chords: KeyChord[]
}

/**
 * What an action IS, with the parts a key already expresses left out.
 *
 * ↑ and ↓ are ONE binding ("move one cell") because the arrow says which way,
 * so dr/dc are not in the signature. ↓ and ⌘↓ are TWO, so `unit` is. Getting
 * this wrong in either direction produces a card with four rows saying the same
 * thing, or one row hiding a shortcut.
 */
export function actionSig(a: Action): string {
  switch (a.kind) {
    case 'move': return `move.${a.unit}${a.extend ? '.extend' : ''}`
    case 'tab': case 'enter': case 'findNext': return `${a.kind}${a.back ? '.back' : ''}`
    case 'home': case 'end':
      return `${a.kind}${a.whole ? '.whole' : ''}${a.extend ? '.extend' : ''}`
    case 'panel': return `panel.${a.side}`
    // Three keys, three rows: the field IS the difference, so leaving it out
    // would collapse bold, italic and underline into one line reading "⌘B".
    case 'style': return `style.${a.field}`
    default: return a.kind
  }
}

const FN_KEYS = Array.from({ length: 12 }, (_, i) => `F${i + 1}`)
const NAMED_KEYS = [
  'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight',
  'Tab', 'Enter', 'Escape', 'Home', 'End', 'PageUp', 'PageDown',
  'Delete', 'Backspace', 'Insert', ...FN_KEYS,
]
// Printable ASCII, minus A–Z: the map folds case, so probing 'z' covers 'Z',
// and probing both would report every letter shortcut twice.
const PRINTABLE_KEYS = Array.from({ length: 0x7f - 0x20 }, (_, i) => String.fromCharCode(0x20 + i))
  .filter((c) => !(c >= 'A' && c <= 'Z'))
const PROBE_KEYS = [...NAMED_KEYS, ...PRINTABLE_KEYS]

/**
 * Every binding the map holds, grouped by what it does.
 *
 * `map` is a parameter so the rig can prove this is DERIVED: hand it a mapper
 * with an extra binding and the extra binding must appear in the output. A
 * hardcoded table passes every other test and fails that one.
 */
export function describeBindings(map: (e: KeyLike) => Action | null = keyToAction): BindingRow[] {
  interface Found { key: string; mod: 'meta' | 'ctrl' | 'none'; shift: boolean; alt: boolean; action: Action }
  const found: Found[] = []

  for (const key of PROBE_KEYS) {
    for (const mod of ['none', 'meta', 'ctrl'] as const) {
      const ask = (shift: boolean, alt: boolean): Action | null =>
        map({ key, shiftKey: shift, altKey: alt, metaKey: mod === 'meta', ctrlKey: mod === 'ctrl' })
      const bare = (shift: boolean, alt: boolean): Action | null =>
        map({ key, shiftKey: shift, altKey: alt })
      const sameAs = (a: Action, other: Action | null): boolean =>
        other !== null && actionSig(other) === actionSig(a)
      for (const alt of [false, true]) {
        for (const shift of [false, true]) {
          const action = ask(shift, alt)
          if (!action) continue
          // A MODIFIER THAT DOES NOT CHANGE THE ANSWER IS NOT PART OF THE
          // BINDING. ⇧Delete still clears and so does ⌘Delete; printing all
          // three as though they were three shortcuts is noise the reader has
          // to rule out one row at a time — and it is how a card ends up
          // teaching ⌘Esc.
          if (shift && sameAs(action, ask(false, alt))) continue
          if (alt && sameAs(action, ask(shift, false))) continue
          if (mod !== 'none' && sameAs(action, bare(shift, alt))) continue
          found.push({ key, mod, shift, alt, action })
        }
      }
    }
  }

  // ⌘ and ctrl are one binding wherever the map folds them (it does, today,
  // everywhere) — but they are probed separately so that the day one of them
  // means something different, the card says so instead of picking a winner.
  const twin = (c: Found, want: 'meta' | 'ctrl'): Found | undefined => found.find((o) =>
    o.mod === want && o.key === c.key && o.shift === c.shift && o.alt === c.alt &&
    actionSig(o.action) === actionSig(c.action))

  const rows: BindingRow[] = []
  const bySig = new Map<string, BindingRow>()
  const put = (action: Action, chord: KeyChord): void => {
    const sig = actionSig(action)
    let row = bySig.get(sig)
    if (!row) { row = { sig, action, chords: [] }; bySig.set(sig, row); rows.push(row) }
    row.chords.push(chord)
  }
  for (const c of found) {
    if (c.mod === 'ctrl' && twin(c, 'meta')) continue          // emitted as 'either'
    const mod = c.mod === 'meta' ? (twin(c, 'ctrl') ? 'either' : 'meta') : c.mod
    put(c.action, { key: c.key, mod, shift: c.shift, alt: c.alt })
  }
  return rows
}

// --- Selection -------------------------------------------------------------

export interface MoveOpts {
  /** shift held: move the head and leave the anchor and the cursor where they are */
  extend?: boolean
  /** ⌘/ctrl held: run to the edge of the data block rather than one cell */
  jump?: boolean
  /**
   * What counts as data, for a jump. Absent, a jump runs to the grid boundary —
   * the honest degenerate, and a bounded one, because this sheet has a last row.
   */
  filled?: (row: number, col: number) => boolean
}

export class Selection {
  rows: number
  cols: number
  /** the live range: the one shift+arrow extends and ⌘-click replaces */
  active: Range
  /** earlier ⌘-clicked ranges, oldest first. The active range is not in here. */
  extra: Range[]
  /** the one cell typing lands in — inside the active range, never the head */
  cursor: CellRef

  /**
   * Where the current Tab run began, or null when there is no run.
   *
   * This is the whole of Enter's "return home" behaviour and it is one field.
   * Any navigation that is not a Tab or an Enter clears it, because a run is a
   * sequence of entries and a click or an arrow ends the sequence.
   */
  private run: CellRef | null

  constructor(rows: number, cols: number) {
    this.rows = Math.max(0, rows)
    this.cols = Math.max(0, cols)
    this.active = { anchor: { row: 0, col: 0 }, head: { row: 0, col: 0 } }
    this.extra = []
    this.cursor = { row: 0, col: 0 }
    this.run = null
  }

  /** Rows/columns changed under us (an import, a delete). Nothing may point off the grid. */
  resize(rows: number, cols: number): this {
    this.rows = Math.max(0, rows)
    this.cols = Math.max(0, cols)
    const fix = (r: Range): Range => ({
      anchor: this.clamp(r.anchor.row, r.anchor.col),
      head: this.clamp(r.head.row, r.head.col),
    })
    this.active = fix(this.active)
    this.extra = this.extra.map(fix)
    this.cursor = this.clamp(this.cursor.row, this.cursor.col)
    // THE RUN SURVIVES A RESIZE THAT DID NOT MOVE IT. The grid calls resize()
    // on EVERY document event — a typed value included — and this used to
    // clear the run unconditionally. So the one thing that always happens
    // between a Tab and the Enter that should come home is the commit of
    // what was typed, and that commit erased the run just before enter()
    // looked for it. Every Enter after a Tab run then moved plainly down,
    // and the typist walked diagonally across their table — the exact bug
    // test-dash-select.ts names and proves the model does not have, because
    // the model was never told the grid does this. The run only goes when the
    // sheet actually shrank past it.
    if (this.run && (this.run.row >= this.rows || this.run.col >= this.cols)) this.run = null
    return this
  }

  clamp(row: number, col: number): CellRef {
    return {
      row: Math.max(0, Math.min(this.rows - 1, row)),
      col: Math.max(0, Math.min(this.cols - 1, col)),
    }
  }

  /** Every selected range, oldest first, with the active one last. */
  ranges(): Range[] { return [...this.extra, this.active] }

  /** More than one cell is selected — the test Tab and Enter branch on. */
  isRange(): boolean {
    const b = normalize(this.active)
    return b.top !== b.bottom || b.left !== b.right
  }

  /** Collapse to one cell. This is a click. */
  moveTo(row: number, col: number): this {
    const p = this.clamp(row, col)
    this.active = { anchor: { ...p }, head: { ...p } }
    this.extra = []
    this.cursor = { ...p }
    this.run = null
    return this
  }

  /** Drag or shift+click: the anchor stays, the head goes here. */
  extendTo(row: number, col: number): this {
    this.active = { anchor: { ...this.active.anchor }, head: this.clamp(row, col) }
    // The active cell must stay inside the selection. Shrinking a range back
    // past the cursor would otherwise leave typing landing outside the
    // highlight — visible nowhere, wrong everywhere.
    if (!contains(this.active, this.cursor.row, this.cursor.col)) {
      this.cursor = { ...this.active.anchor }
    }
    this.run = null
    return this
  }

  move(dr: number, dc: number, opts: MoveOpts = {}): this {
    const from = opts.extend ? this.active.head : this.cursor
    const to = opts.jump
      ? this.edge(from, dr, dc, opts.filled)
      : this.clamp(from.row + dr, from.col + dc)
    return opts.extend ? this.extendTo(to.row, to.col) : this.moveTo(to.row, to.col)
  }

  extend(dr: number, dc: number): this { return this.move(dr, dc, { extend: true }) }

  /**
   * Excel's ⌘↓, exactly: three cases, and the third is the one that matters.
   *
   *   next cell filled → run to the LAST filled cell of that block
   *   next cell blank  → skip the blanks and land on the first filled cell
   *   nothing ahead    → stop at the sheet's boundary
   *
   * The naive version — "walk until blank" — collapses the second case: from a
   * blank cell it never moves at all, which is the half of the shortcut people
   * use to get from the end of one block to the start of the next.
   */
  private edge(
    from: CellRef, dr: number, dc: number,
    filled?: (row: number, col: number) => boolean,
  ): CellRef {
    // Stepping a whole grid's worth and clamping IS the far edge, in any
    // direction, without a second sign-dependent branch to get wrong.
    const boundary = this.clamp(
      from.row + dr * Math.max(1, this.rows),
      from.col + dc * Math.max(1, this.cols),
    )
    if (!filled) return boundary

    const inside = (p: CellRef): boolean =>
      p.row >= 0 && p.row < this.rows && p.col >= 0 && p.col < this.cols
    const step = (p: CellRef): CellRef => ({ row: p.row + dr, col: p.col + dc })

    let p = step(from)
    if (!inside(p)) return { ...from }

    if (filled(p.row, p.col)) {
      for (;;) {
        const next = step(p)
        if (!inside(next) || !filled(next.row, next.col)) return p
        p = next
      }
    }
    while (inside(p)) {
      if (filled(p.row, p.col)) return p
      p = step(p)
    }
    return boundary
  }

  /**
   * Tab.
   *
   * With a RANGE selected it walks the active cell inside the block and wraps —
   * that is how a person fills in a form-shaped selection, and the block must
   * not move while they do it. With a SINGLE cell it moves plainly and stops at
   * the last column: there is no range to wrap inside, and teleporting to the
   * next row's first cell would be a jump the typist did not ask for.
   */
  tab(back = false): this {
    const step = back ? -1 : 1
    if (this.isRange()) return this.cycle(0, step)
    // The run starts at the cell Tab was pressed FROM, and survives the move —
    // moveTo clears it, so it is restored deliberately rather than by accident.
    const start = this.run ?? { ...this.cursor }
    const col = this.cursor.col + step
    if (col >= 0 && col < this.cols) this.moveTo(this.cursor.row, col)
    this.run = start
    return this
  }

  /**
   * Enter.
   *
   * Down one, except that after a Tab run it comes home to the column the run
   * started in — and the landing cell becomes the new run start, so the next
   * Tab/Tab/Enter lands under it too. Inside a selected range it cycles the
   * range instead, wrapping into the next column at the bottom.
   */
  enter(back = false): this {
    const step = back ? -1 : 1
    if (this.isRange()) return this.cycle(step, 0)
    if (this.run) {
      const row = this.run.row + step
      if (row < 0 || row >= this.rows) return this
      const home = { row, col: this.run.col }
      this.moveTo(home.row, home.col)
      this.run = home
      return this
    }
    const row = this.cursor.row + step
    if (row >= 0 && row < this.rows) this.moveTo(row, this.cursor.col)
    return this
  }

  /**
   * Walk the active cell inside the active range, wrapping at the edge and
   * again at the corner. The range itself never moves.
   *
   * Only the ACTIVE range cycles. ⌘-clicked extras are left out because
   * ordering disjoint rectangles is a decision with no obvious right answer,
   * and guessing it would be worse than not having it.
   */
  private cycle(dr: number, dc: number): this {
    const b = normalize(this.active)
    let { row, col } = this.cursor
    if (!contains(this.active, row, col)) { row = b.top; col = b.left }
    if (dc) {
      col += dc
      if (col > b.right) { col = b.left; row = row + 1 > b.bottom ? b.top : row + 1 }
      else if (col < b.left) { col = b.right; row = row - 1 < b.top ? b.bottom : row - 1 }
    } else {
      row += dr
      if (row > b.bottom) { row = b.top; col = col + 1 > b.right ? b.left : col + 1 }
      else if (row < b.top) { row = b.bottom; col = col - 1 < b.left ? b.right : col - 1 }
    }
    this.cursor = { row, col }
    this.run = null
    return this
  }

  /** ⌘A. The active cell stays put — you selected everything to act on it, not to move. */
  selectAll(): this {
    this.active = { anchor: { row: 0, col: 0 }, head: this.clamp(this.rows - 1, this.cols - 1) }
    this.extra = []
    this.cursor = this.clamp(this.cursor.row, this.cursor.col)
    this.run = null
    return this
  }

  selectRow(r: number): this {
    const { row } = this.clamp(r, 0)
    this.active = { anchor: { row, col: 0 }, head: this.clamp(row, this.cols - 1) }
    this.extra = []
    this.cursor = this.clamp(row, this.cursor.col)
    this.run = null
    return this
  }

  selectCol(c: number): this {
    const { col } = this.clamp(0, c)
    this.active = { anchor: { row: 0, col }, head: this.clamp(this.rows - 1, col) }
    this.extra = []
    this.cursor = this.clamp(this.cursor.row, col)
    this.run = null
    return this
  }

  /**
   * Shift-click a column header: the columns from the active range's anchor to
   * `c`, every row. The anchor column stays, as it does for a shift-click on a
   * cell, so A then shift-D is A:D and a second shift-B shrinks it to A:B.
   */
  extendCol(c: number): this {
    const { col } = this.clamp(0, c)
    this.active = {
      anchor: { row: 0, col: this.active.anchor.col },
      head: this.clamp(this.rows - 1, col),
    }
    if (!contains(this.active, this.cursor.row, this.cursor.col)) {
      this.cursor = { row: this.clamp(this.cursor.row, 0).row, col: this.active.anchor.col }
    }
    this.run = null
    return this
  }

  /** ⌘-click a column header: that whole column joins the selection. */
  addCol(c: number): this {
    const { col } = this.clamp(0, c)
    this.addRange({ anchor: { row: 0, col }, head: { row: this.rows - 1, col } })
    this.cursor = this.clamp(this.cursor.row, col)
    return this
  }

  /**
   * ⌘-click a second block.
   *
   * The NEW range becomes the active one and the old active joins `extra`,
   * because the range you just drew is the one the next shift+arrow must
   * extend. Pushing the new one into `extra` instead reads the same on screen
   * and behaves wrongly the moment a key is pressed.
   */
  addRange(r: Range): this {
    this.extra.push(this.active)
    this.active = {
      anchor: this.clamp(r.anchor.row, r.anchor.col),
      head: this.clamp(r.head.row, r.head.col),
    }
    this.cursor = { ...this.active.anchor }
    this.run = null
    return this
  }

  /**
   * Every selected cell, row-major within each range.
   *
   * Deduplication costs a Set the size of the selection, and ⌘A on a 250k-row
   * sheet is millions of keys — so it is paid ONLY when there is more than one
   * range, since a single rectangle cannot overlap itself.
   */
  *cells(): Generator<CellRef> {
    const all = this.ranges()
    const seen = all.length > 1 ? new Set<string>() : null
    for (const r of all) {
      const b = normalize(r)
      for (let row = b.top; row <= b.bottom; row++) {
        for (let col = b.left; col <= b.right; col++) {
          if (seen) {
            const k = `${row}:${col}`
            if (seen.has(k)) continue
            seen.add(k)
          }
          yield { row, col }
        }
      }
    }
  }

  /** The bounding box over every range — what a paste or a chart binds to. */
  bounds(): Box {
    const boxes = this.ranges().map(normalize)
    return {
      top: Math.min(...boxes.map((b) => b.top)),
      left: Math.min(...boxes.map((b) => b.left)),
      bottom: Math.max(...boxes.map((b) => b.bottom)),
      right: Math.max(...boxes.map((b) => b.right)),
    }
  }
}

// --- Driving a selection from an Action ------------------------------------

export interface MotionCtx {
  /** rows a PageUp/PageDown covers — the grid's visible row count */
  page?: number
  filled?: (row: number, col: number) => boolean
}

/**
 * Apply the motion half of an Action, and report whether it was consumed.
 *
 * FALSE IS A REAL ANSWER: copy, paste, undo and clear are not selection
 * operations, and this returning true for them would let a caller believe the
 * selection had handled a paste.
 */
export function applyMotion(sel: Selection, a: Action, ctx: MotionCtx = {}): boolean {
  switch (a.kind) {
    case 'move': {
      const k = a.unit === 'page' ? Math.max(1, Math.floor(ctx.page ?? 1)) : 1
      sel.move(a.dr * k, a.dc * k, {
        extend: a.extend, jump: a.unit === 'edge', filled: ctx.filled,
      })
      return true
    }
    case 'tab': sel.tab(a.back); return true
    case 'enter': sel.enter(a.back); return true
    case 'home': {
      const row = a.whole ? 0 : sel.cursor.row
      if (a.extend) sel.extendTo(row, 0)
      else sel.moveTo(row, 0)
      return true
    }
    case 'end': {
      const row = a.whole ? sel.rows - 1 : sel.cursor.row
      if (a.extend) sel.extendTo(row, sel.cols - 1)
      else sel.moveTo(row, sel.cols - 1)
      return true
    }
    case 'selectAll': sel.selectAll(); return true
    case 'selectRow': sel.selectRow(sel.cursor.row); return true
    case 'selectCol': sel.selectCol(sel.cursor.col); return true
    default: return false
  }
}

// --- The clipboard ---------------------------------------------------------

const NEEDS_QUOTE = /[\t\n\r"]/

const quoteTsv = (v: unknown): string => {
  const s = v == null ? '' : String(v)
  return NEEDS_QUOTE.test(s) ? `"${s.replace(/"/g, '""')}"` : s
}

/**
 * The selection as clipboard text.
 *
 * `get` is a callback rather than a grid because this must serialise DISPLAYED
 * values — a formula column's computed number, an override's corrected value —
 * and only the caller knows which layer wins.
 */
export function tsvFromRange(get: (row: number, col: number) => unknown, r: Range): string {
  const b = normalize(r)
  const lines: string[] = []
  for (let row = b.top; row <= b.bottom; row++) {
    const cells: string[] = []
    for (let col = b.left; col <= b.right; col++) cells.push(quoteTsv(get(row, col)))
    lines.push(cells.join('\t'))
  }
  return lines.join('\n')
}

/**
 * Clipboard text back into a grid of strings.
 *
 * A quote only OPENS a field at the start of one: Excel writes bare `5" pipe`
 * unquoted, and treating that quote as an opener eats the rest of the row into
 * one field. Same rule as import.ts, and it is the rule for the same reason.
 */
export function parseTsv(text: string): string[][] {
  const rows: string[][] = []
  let row: string[] = []
  let field = ''
  let inQ = false
  let i = 0
  const push = (): void => { row.push(field); field = '' }
  const endRow = (): void => { push(); rows.push(row); row = [] }

  while (i < text.length) {
    const c = text[i]
    if (inQ) {
      if (c === '"') {
        if (text[i + 1] === '"') { field += '"'; i += 2; continue } // doubled = literal
        inQ = false; i++; continue
      }
      // A line break INSIDE a cell is one character, whichever pair of bytes
      // the source used. Excel writes CRLF; a cell that came back carrying a
      // stray CR compares unequal to the one that was copied.
      if (c === '\r') {
        if (text[i + 1] === '\n') i++
        field += '\n'; i++; continue
      }
      field += c; i++; continue
    }
    if (c === '"' && field === '') { inQ = true; i++; continue }
    if (c === '\t') { push(); i++; continue }
    if (c === '\r') { if (text[i + 1] === '\n') i++; endRow(); i++; continue }
    if (c === '\n') { endRow(); i++; continue }
    field += c; i++
  }

  // A trailing newline ends the last row rather than starting an empty one —
  // but EMPTY INPUT is one empty cell, not nothing. A copied blank cell has to
  // paste as a blank and clear what it lands on; returning [] here makes that
  // paste a silent no-op, and the old value stays while the user believes it
  // went.
  if (field !== '' || row.length || !rows.length) endRow()
  return rows
}

// --- The fill handle -------------------------------------------------------
//
// `target` is the TOTAL length of the result, seeds included — a drag covers
// rows 5..20, so the caller asks for 16 and gets 16, with no off-by-one
// arithmetic at the call site. Asking for fewer than there are seeds truncates.

/**
 * A cell as a FILL reads it: the formula it holds, or the value it stores.
 *
 * NEVER the computed value of a formula, and that distinction is the whole
 * reason this type exists. A fill that seeds from what a cell SHOWS turns a
 * formula into the constant it happened to evaluate to — and, when the
 * evaluation failed, writes the ERROR OBJECT into the column as if somebody had
 * typed it. Both are silent data loss: the file afterwards holds no record that
 * there was ever a formula, or a number, there.
 */
export interface FillCell {
  /** the stored value, when the cell has no formula */
  v?: unknown
  /** the formula SOURCE (`=B1*2`), when it has one */
  f?: string
  /**
   * Which seed this output came from, for a formula. The caller translates the
   * references by however far the cell moved, and only it knows the distance —
   * a dataset reads through a sort order, so the visible gap is not the gap the
   * addresses moved by.
   */
  src?: number
}

/**
 * The two fill GESTURES, which are not one operation:
 *
 *   'copy'   — ⌘D. The top row of the selection is laid over the rest, exactly
 *              as it stands. Excel's Fill Down, and the reason ⌘D on a column
 *              of numbers does not invent a count.
 *   'series' — the fill HANDLE. The selected block IS the seed and the drag
 *              extends it, so two seeds mean a step and the fill continues.
 *
 * Sharing one implementation is what made ⌘D over a two-row selection read TWO
 * seeds and alternate them down the column, overwriting every other row with
 * its neighbour's value.
 */
export type FillMode = 'copy' | 'series'

/**
 * Fill `target` cells from `seeds`.
 *
 * A FORMULA IS COPIED, NEVER CONTINUED. Excel does not read a series out of
 * expressions and neither does this: when any seed holds a formula the seeds
 * repeat in order, each output remembering (`src`) which seed it came from so
 * the caller can translate its references. Values fill by the mode's rule.
 */
export function fillCells(seeds: FillCell[], target: number, mode: FillMode): FillCell[] {
  if (target <= 0 || !seeds.length) return []
  if (mode === 'copy' || seeds.some((s) => s.f !== undefined)) {
    return Array.from({ length: target }, (_, i) => {
      const k = i % seeds.length
      return seeds[k].f !== undefined ? { f: seeds[k].f, src: k } : { v: seeds[k].v }
    })
  }
  return fillSeries(seeds.map((s) => s.v), target).map((v) => ({ v }))
}

/** Repeat the seeds until the target is covered. The fill handle's plain drag. */
export function fillDown(values: unknown[], target: number): unknown[] {
  if (target <= 0 || !values.length) return []
  const out: unknown[] = []
  for (let i = 0; i < target; i++) out.push(values[i % values.length])
  return out
}

/**
 * Continue the seeds as a series where one can be read out of them, and repeat
 * where one cannot.
 *
 * ONE NUMBER IS NOT ONE DATE, deliberately. Dragging a lone `1` gives 1, 1, 1;
 * a lone `2026-01-01` gives consecutive days and a lone `Q1` gives Q2, Q3. It
 * reads as inconsistent written down and it is exactly right in the hand — a
 * lone number is as likely to be a constant as the start of a count, while a
 * lone date or a numbered label almost never is. Excel and Sheets both make
 * this distinction, and users have twenty years of muscle memory in it.
 */
export function fillSeries(values: unknown[], target: number): unknown[] {
  if (target <= 0 || !values.length) return []
  const term = detectSeries(values)
  if (!term) return fillDown(values, target)
  const out = values.slice(0, target)
  for (let i = values.length; i < target; i++) out.push(term(i))
  return out
}

/** How many decimals a number is written with — the precision to round back to. */
function decimals(n: number): number {
  const s = String(n)
  const dot = s.indexOf('.')
  return dot < 0 || s.includes('e') ? 0 : s.length - dot - 1
}

const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})$/
const TRAILING_NUM = /^(.*?)(\d+)$/

const pad2 = (n: number): string => String(n).padStart(2, '0')
const iso = (y: number, m: number, d: number): string =>
  `${String(y).padStart(4, '0')}-${pad2(m)}-${pad2(d)}`

const DAY_MS = 86_400_000
/** UTC throughout: a local-time Date turns 2026-01-01 into 2025-12-31 west of Greenwich. */
const dayNumber = (y: number, m: number, d: number): number => Date.UTC(y, m - 1, d) / DAY_MS
function fromDayNumber(n: number): string {
  const t = new Date(n * DAY_MS)
  return iso(t.getUTCFullYear(), t.getUTCMonth() + 1, t.getUTCDate())
}

/** Month arithmetic clamps: one month after 31 January is 28 February, not 3 March. */
function addMonths(y: number, m: number, d: number, k: number): string {
  const t = y * 12 + (m - 1) + k
  const ny = Math.floor(t / 12)
  const nm = ((t % 12) + 12) % 12 + 1
  const last = new Date(Date.UTC(ny, nm, 0)).getUTCDate()
  return iso(ny, nm, Math.min(d, last))
}

/** Every gap is the same one, within float slop. */
function constantStep(xs: number[]): number | null {
  if (xs.length < 2) return null
  const d = xs[1] - xs[0]
  for (let i = 2; i < xs.length; i++) {
    // Exact equality refuses an obviously arithmetic column: 0.3 - 0.2 and
    // 0.2 - 0.1 are different doubles, so [0.1, 0.2, 0.3] would fill by
    // repetition. A relative tolerance is the whole fix.
    if (Math.abs((xs[i] - xs[i - 1]) - d) > 1e-9 * Math.max(1, Math.abs(d))) return null
  }
  return d
}

/**
 * A function giving the i-th term (i is a 0-based index into the FILLED range,
 * so i >= values.length for everything this produces), or null when the seeds
 * are not a series and the honest answer is to repeat them.
 */
function detectSeries(values: unknown[]): ((i: number) => unknown) | null {
  // --- numbers
  if (values.every((v) => typeof v === 'number' && Number.isFinite(v))) {
    const xs = values as number[]
    const d = constantStep(xs)
    // A single number, or a flat run, is a CONSTANT until something says
    // otherwise — filling 5,5,5 with 5,6,7 invents data nobody asked for.
    if (d === null || d === 0) return null
    // Precision comes from the SEEDS, never from the step. 0.9 - 0.8 is
    // 0.09999999999999998 in binary floating point, so decimals(step) reports
    // 17 and the fill emits "1.000000000000" — a float artefact presented to
    // the user as significant figures.
    const dp = Math.min(12, xs.reduce((n, x) => Math.max(n, decimals(x)), 0))
    const f = 10 ** dp
    // Multiply rather than accumulate: repeated addition drifts, and the drift
    // shows up as 0.30000000000000004 in a cell somebody is about to total.
    return (i) => Math.round((xs[0] + i * d) * f) / f
  }

  if (!values.every((v) => typeof v === 'string' && v !== '')) return null
  const ss = values as string[]

  // --- ISO dates: months first, because a month step is not a constant number
  // of days and the day check would happily "fit" 31 to a January→February pair
  // and then land on 4 March.
  const parts: Array<{ y: number; m: number; d: number }> = []
  for (const s of ss) {
    const m = ISO_DATE.exec(s)
    if (!m) { parts.length = 0; break }
    parts.push({ y: +m[1], m: +m[2], d: +m[3] })
  }
  if (parts.length === ss.length) {
    const first = parts[0]
    const day0 = dayNumber(first.y, first.m, first.d)
    if (parts.length === 1) return (i) => fromDayNumber(day0 + i)
    if (parts.every((p) => p.d === first.d)) {
      const km = constantStep(parts.map((p) => p.y * 12 + p.m))
      if (km !== null && km !== 0) return (i) => addMonths(first.y, first.m, first.d, i * km)
    }
    const kd = constantStep(parts.map((p) => dayNumber(p.y, p.m, p.d)))
    if (kd === null || kd === 0) return null
    return (i) => fromDayNumber(day0 + i * kd)
  }

  // --- numeric STRINGS. A text column can still hold numbers — an import that
  // could not settle a type leaves them as text, which is the case this whole
  // app is built around. They must be continued NUMERICALLY, because the label
  // path below splits on a trailing digit run and would read "0.8" as the label
  // "0." followed by 8: the fill then emits 0.10, 0.11, which is not merely
  // wrong, it is SMALLER than the value it follows.
  if (ss.every((x) => x.trim() !== '' && Number.isFinite(Number(x.trim())))) {
    const xs = ss.map((x) => Number(x.trim()))
    const d = constantStep(xs)
    if (d === null || d === 0) return null
    const dp = Math.min(12, xs.reduce((n, x) => Math.max(n, decimals(x)), 0))
    const f = 10 ** dp
    // back to a STRING, at the seeds' own precision: the column is text, and a
    // fill must not change what type the cells hold
    return (i) => (Math.round((xs[0] + i * d) * f) / f).toFixed(dp)
  }

  // --- text ending in a number: "Q1" → "Q2", "Item 01" → "Item 02"
  const nums: number[] = []
  let prefix: string | null = null
  let digits = ''
  for (const s of ss) {
    const m = TRAILING_NUM.exec(s)
    if (!m) return null
    if (prefix === null) prefix = m[1]
    else if (m[1] !== prefix) return null   // "Q1" then "P2" is two labels, not a series
    nums.push(Number(m[2]))
    digits = m[2]
  }
  const k = nums.length === 1 ? 1 : constantStep(nums)
  if (k === null || k === 0) return null
  // Zero padding is part of the label: "item09" continues "item10", not "item1 0".
  const width = digits.startsWith('0') ? digits.length : 0
  const head = prefix ?? ''
  return (i) => `${head}${String(nums[0] + i * k).padStart(width, '0')}`
}