Most common operation
Set the value of one cell
To set A1, make that cell active, open an editing session, update its draft, then commit the session. The grid follows the same sequence for typing and formula-bar edits.
- selectCellAtomMake the target coordinate the active cell.
- startEditingAtomOpen an editing session for that cell with its current text.
- editingDraftAtomWrite the next text or formula while the editor is open.
- runEditingCommitAtomCommit the current draft and optionally move to the next cell.
This is the frontend API used by an application surface. Every entry says which UI state it changes, which value to give it, and what interaction it completes.
Select and navigate
Use these APIs whenever a button, name box, keyboard handler, or custom UI needs to control the active cell or range.
WRITE ATOM
selectCellAtom
Makes one cell active, or extends the current selection to a rectangular range.
- Give it
- A row and column coordinate; optionally a sheet id and extend flag.
- Result
- The canonical selected cell or range becomes the current UI selection.
- Use it when
- Use for “go to cell”, cell click, or a keyboard move that should update visible selection state.
WRITE ATOM
setSelectionAtom
Replaces the current selection with a complete cell, range, row, column, or all-sheet selection.
- Give it
- One SelectionState object with its sheet id and bounds.
- Result
- A normalized selection that every spreadsheet surface can read.
- Use it when
- Use when your UI already knows the exact selection shape, such as after parsing a name-box address.
PURE FUNCTION
getActiveCell
Reads the active coordinate from any valid selection, including a multi-cell range.
- Give it
- A selection plus the sheet bounds.
- Result
- The active row, column, and sheet id.
- Use it when
- Use before positioning an editor, formula bar, context menu, or keyboard command.
PURE FUNCTION
moveSelection
Calculates the next selection without touching application state.
- Give it
- Current selection, sheet bounds, and a row/column move or absolute target.
- Result
- The next clamped cell selection, or an extended range when requested.
- Use it when
- Use in custom keyboard navigation; write the returned selection through setSelectionAtom.
Edit one cell
These atoms form the deliberate lifecycle for changing a displayed value or formula: open, update, commit, or cancel.
WRITE ATOM
startEditingAtom
Opens an editable session for one cell and switches the interaction into editing mode.
- Give it
- Sheet id, cell coordinate, initial draft text, and input source.
- Result
- The new editing session, with its draft available to the editor UI.
- Use it when
- Call after a double-click, Enter, F2, or formula-bar focus. Do not start a second session while one is committing.
READ / WRITE ATOM
editingDraftAtom
Holds exactly the text currently being edited, whether it is a value or a formula.
- Give it
- Write a draft string; optionally state which UI surface supplied it.
- Result
- The latest draft for rendering in the cell editor or formula bar.
- Use it when
- Bind an input’s value and input event to this atom while the editing session is active.
ASYNC WRITE ATOM
runEditingCommitAtom
Finishes the current editing session and applies its draft as the cell’s next value or formula.
- Give it
- The configured edit action plus an optional post-commit move direction.
- Result
- A completion, rejection, refresh-failure, unknown-outcome, or blocked status.
- Use it when
- Call on Enter, Tab, or an explicit save action. Read editingCommitLifecycleAtom to present pending or failed feedback.
WRITE ATOM
cancelEditingAtom
Discards the current uncommitted draft and returns interaction to navigation mode.
- Give it
- No arguments.
- Result
- A cancellation intent, or null when there is no active editable session.
- Use it when
- Call on Escape or when an editor closes without saving. It never turns a discarded draft into a cell value.
Clipboard and history
These APIs give menus and keyboard handlers one shared interaction state for copy, paste, undo, and redo.
WRITE ATOM
copyClipboardAtom
Creates the UI copy intent for the current source range and remembers it as clipboard state.
- Give it
- A source range, target descriptor, and optional payload.
- Result
- A copy intent and clipboard status for the UI to observe.
- Use it when
- Call from a Copy menu item or keyboard shortcut, then let the clipboard surface complete the user-visible transfer.
WRITE ATOM
pasteClipboardAtom
Creates a paste intent that identifies the saved source content and the target range.
- Give it
- A source descriptor, target descriptor, and optional clipboard payload.
- Result
- A paste intent and a pasting status.
- Use it when
- Call after the user chooses a destination cell or range. Use clipboardStateAtom to render pending and error states.
ASYNC WRITE ATOM
runUndoHistoryAtom
Moves the spreadsheet interaction back one recorded user action.
- Give it
- The configured undo action and projection refresh callback.
- Result
- A completed, blocked, refresh-failed, or unknown-outcome status.
- Use it when
- Call from Ctrl/Cmd+Z or an Undo menu item only when canUndoAtom reports that an entry is available.
ASYNC WRITE ATOM
runRedoHistoryAtom
Reapplies the next action in the interaction history after an undo.
- Give it
- The configured redo action and projection refresh callback.
- Result
- A completed, blocked, refresh-failed, or unknown-outcome status.
- Use it when
- Call from Ctrl/Cmd+Shift+Z or Redo when canRedoAtom reports that an entry is available.