Editing

Nothing changes unless you ask for it. With no commit hook the grid behaves exactly as before: the value is written, history is recorded, cell:changed fires, and there is no pending state to think about. Subscribe to cell:changed, fire your request and ignore the result: that keeps working and costs nothing.

The mode is declared, never guessed. A websocket or event-sourced backend acknowledges on a different channel from the one the write went out on, so there is no promise to resolve. confirm: 'manual' says so explicitly. The grid does not infer it from what commit returns, because then a synchronous hook that happens to return nothing would leave every cell pending for ever with nothing in your code that looks wrong. If a write does stay pending, you get a console warning naming the cell: tune the threshold with pendingTimeout.

Rollback goes to the last confirmed value, not the previous one. This is the part that is easy to get wrong by hand. Suppose a cell holding 1 is edited to 2, then to 3, then to 4, all before any answer comes back. If the second write fails, restoring “the value before it” would put back 2, a value the server never held, and one the user has since replaced twice. So each cell remembers the newest value a confirmation has actually vouched for, and a write that a later edit has superseded reports its failure without writing anything back. You will see cell:reverted with applied: false for those.

The rejected value travels on the event as rejected, so you can offer a retry rather than losing what the user typed.

Two behaviours worth knowing. An unconfirmed edit goes through the normal pipeline, so if it changes a sorted or filtered column the row moves immediately and moves back if the write fails. And undo of an in-flight edit issues a compensating write, a fresh write back to the previous value, itself tracked: rather than pretending to cancel a request that has already gone out.

Ctrl+Shift+Arrow is the keyboard form of ctrl-dragging. The first press opens a block at the focused cell without discarding what is already selected; the presses after it extend that block, so holding the chord draws one rectangle rather than a new one per key repeat. A plain Shift+Arrow goes back to extending a single block, and clicking anywhere ends the run.

What multiple ranges do and do not support. Painting, cells() and the status-bar summary all work over the union of the selected blocks. Copy is narrower, because tab-separated text is a rectangle: blocks stacked over the same columns, or joined over the same rows, copy fine, a diagonal pair has no rectangular form, so rangeText() returns '' and clipboard:copy reports reason: 'discontiguous' rather than emitting misaligned rows. Filling is narrower still: with more than one block selected there is no single source to extend, so the fill handle is hidden and fillTo and fillDown decline.

Months step as months. 15 January to 15 February is thirty-one days, and continuing in days would land on 18 March and drift further every step. A month step holds the date the user picked, and clamps where the month is short: 31 January plus a month is 28 February, not 3 March.

Month ends are their own case. 31 Jan, 28 Feb is a month series whose second value has already been clamped, so the two share no day of month and the day-preserving rule cannot see it. Where every source value is the last day of its own month, the fill stays on the month end: 31 March, 30 April, 31 May, and 29 February in a leap year. Values that share a day of month keep the day-preserving answer, so 30 Apr, 30 Jun still gives 30 August rather than the 31st.

One limit worth knowing. Filling upwards is not supported; the handle extends downwards only.

A domain series (order codes, fiscal periods, seat numbers) is not something the grid can infer, so selection.fill takes precedence when you supply it. It must return one value per target row; anything else is ignored in favour of the built-in detection, rather than being partly applied.

References name columns, not cells. A spreadsheet can say A1 because its rows do not move. A grid sorts, filters, groups, pages and virtualises, so the row at position 1 is a different row a moment later and a formula written against it would silently change meaning. quantity * price means the same thing wherever the row goes.

No eval, no new Function. This is text a user typed into a cell. Handing it to the JavaScript engine would let anyone who can edit a cell read your cookies, call your API with your credentials, or post the grid's contents anywhere. It is a hand-written tokeniser and recursive-descent parser, and the only callable things are the built-in functions: constructor, globalThis and constructor.constructor("return 1")() all simply fail to resolve.

The result is stored, not the expression. A formula is a way of entering a value, exactly like 1,200 or (50) or 12%. It commits as one undo step, fires one cell:changed, and passes through the column's own validation.

The result is stored, not the formula. The expression is evaluated once, at the moment you commit it, and what lands in the cell is a value like any other, so it does not recalculate when a cell it referred to changes later. For a value that must stay in step with its inputs, use a computed column, which is re-evaluated whenever its dependencies move.

Bare arithmetic is deliberately not a formula. 2-1 is a plausible product code and 1/2 a plausible date. A reader that evaluated either on a guess would have to guess wrong sometimes, and the wrong answer is not a visible error but a plausible number: 2*3 stored as 23 looks like data. Arithmetic without a leading = is refused outright, so the cell keeps what it had rather than taking a number nobody typed.

Handed the defaults, rather than replacing them. A builder that had to return every item in order to append one would be written once as a copy of the built-ins and would then drift from them, the copy keeps the menu it was forked from, and stops gaining whatever the grid adds later. Spreading defaults costs one line and never goes stale.

Return the array you want shown: add, remove, reorder, or replace outright. An empty array suppresses the menu deliberately. Returning nothing leaves the defaults alone, because a missing return is a typo and deleting the whole menu is a harsh reading of one.

Your properties are on column.def, not on the column itself. column is the grid's resolved interpretation of your definition and carries only keys the grid understands; column.def is the object you wrote, untouched. Keeping them apart means an application property can never collide with one the grid adds in a later version, and you do not have to maintain a lookup table keyed by column id alongside the columns themselves.

The order is your data, not a view of it. A move reorders the array you gave the grid and tells you it happened; writing it somewhere permanent is yours, because only you know where the order lives. A grid that rearranged rows on screen and stopped there would look finished and lose the order on the next load, which is worse than not offering the feature.

If the save fails, move it back: grid.rows.move(key, from).

Off by default, and both ends have to agree. Rows leaving a grid is a data change you have to want: a grid that quietly let its rows be dragged away would lose one to a mis-drag, and there is no gesture a user would think to try to get it back. A one-way relationship is a declaration on both grids rather than a convention, the sender refuses to receive, and the receiver never starts a drag.

The target adds before the source removes. If the add is refused: a duplicate key, most likely: nothing is removed, so a rejected transfer loses no data. The other order would delete a row and then discover it had nowhere to go.

The row object is cloned, not shared. Two grids holding the same object would edit each other's rows through it, which is the sort of coupling nobody goes looking for when a cell changes in a grid they were not touching.

A picker opens when it is asked to. A popup editor, a date, a dropdown, a tree, a colour, a code panel: is its panel: in a cell it opens the moment the cell does, which is right, because the user has just asked to edit that one cell. A form builds every field at once, so on a form the field shows the current value on a control and the panel opens over it when clicked. Choosing puts the panel away again and updates the control.

The panel opens before the record arrives. A click that does nothing for half a second reads as a click that was missed, and the user clicks again. So the panel appears immediately with a loading state and fills in when the record lands.

A failure keeps the panel open and offers a retry inside it. Closing would discard the intent and leave the user nothing to act on but the row they already double-clicked.

And a load that never answers is a failure too. A promise that neither resolves nor rejects is what a dropped request looks like from the page; left alone it spins until the user gives up, which reads as an application that has hung rather than a request that failed. After timeout milliseconds, two seconds unless you say otherwise, the form stops waiting and shows the same message and retry as any other failure. Set timeout: false to wait indefinitely, which is right only where your own loader already has a limit and would rather report that one. A record that turns up after the form gave up on it is discarded rather than dropped into a panel the user may have moved on from.

The form takes the double click. On an editable grid that gesture also opens a cell editor, and the two cannot both own it, a form that quietly did nothing where a cell happened to be editable would be worse than no form. So where rowForm is configured, double-clicking a row opens the form and the cell editor stays reachable by Enter or by typing into the cell. Set trigger: false to leave opening entirely to form.open() and keep double-click for cells.

A form in your own container is not modal. It sits beside the grid rather than over it, so it takes nothing away: it is announced as a region rather than a dialog, and Tab moves out of it into the rest of your page instead of being trapped. Claiming otherwise would tell a screen reader user the page had gone away when it plainly has not. Escape still closes it, and it still takes focus when it opens.