Responding to clicks and the context menu

The operations contract is responsible for the workbook’s meaning; your interface is responsible for pointer events. Keep these responsibilities separate:

Event or task	Who’s responsible	What to pass
Click and double-click	Your interface	The coordinate, what was hit, the current selection
Context menu	Your interface	The object type and the commands allowed for it
A cell’s value or formula	The core	sheetKey, row, col, inputKind, input
Undo and redo	The core	subsetId and the direction
Save	The core	subsetId and the destination address

What the interface passes along with a click

{
  "subsetId": "subset-...",
  "sheetKey": "xl/worksheets/sheet1.xml",
  "selection": { "top": 0, "left": 0, "rows": 1, "cols": 1 },
  "hit": { "kind": "cell", "row": 0, "col": 0 },
  "pointer": { "kind": "double-click", "button": 0 }
}

This is your own shape, not a request to the core. The hit and pointer fields don’t exist in the contract at all, and selection is there, but means something else: a string like A1:B4, not an object with area bounds. You can’t copy this block straight into a request — what goes to the core is the cell address and the value type.

The interface uses an object like this to decide which menu to show. A command that changes the workbook then turns into a strictly typed request to the core. Don’t send the core markup nodes or chunks of HTML: it works with cell addresses and value types, not with what’s drawn on screen.

What inputKind is

A cell edit is described by the CellInputEdit type. Along with the address (sheetKey, row, col), you pass inputKind — the input kind. It determines how the core interprets what’s passed, so the result depends on it. There are thirteen kinds in all.

A value in a cell. raw-user-input is what a person typed into the formula bar: the core decides for itself whether it’s a number, a date, a boolean, or text (you can add locale). text and number are already-parsed values, no guessing. formula is a formula, for example =B1*2. legacy-array-formula is an array formula, which additionally needs refRange.

raw-user-input has two behaviors none of the other kinds have, and both mirror Excel:

• A string starting with = is parsed as a formula, and an unparseable one is refused — with the code raw-input-invalid-formula, without changing the cell. The one exception is exactly =: it’s stored as text. The formula kind has no such check at this step.
• If the destination cell has a text number format, the whole string is stored as text. =B1*2 in such a cell becomes a label, not a formula, and there’s no refusal.

Clearing. empty-string — an empty string, clear-to-blank — clear the cell, clear-formatting — remove formatting while keeping the value.

Formatting. formatting — fill and font color, number format, style, alignment, and other cell properties.

Fill and utility. drag-fill and fill-series — drag-filling, prepared-cell — a whole ready-made cell, sheet-protection — a companion to a batch formatting operation.

Each kind’s fields are in the type definition.