useUndo: optional onEditEvent corrector for async-reject history

[CarlosNZ]

Stacked on #391 (dont-run-setdata-on-synchronous-onupdate-errors). Review/merge that first; this branch only adds the useUndo change.

Problem

PR #391 stopped synchronous onUpdate rejects from writing to setData, so useUndo's history stays clean for the common local/JSON-Schema validation case. But an asynchronous onUpdate can't be decided in time: it commits optimistically (setData(new)), then reverts (setData(old)) when the promise rejects. Both writes reach useUndo's set, so a rejected async edit pushes two snapshots and "Undo" steps back to the invalid value.

This is rare (it needs async validation that rejects — sync validation is already handled, and async gating is better done with hold()), so the fix is opt-in and unobtrusive.

Change

useUndo now returns an optional onEditEvent:

const { set, undo, redo, onEditEvent } = useUndo(data, setData)
return <JsonEditor data={data} setData={set} onEditEvent={onEditEvent} />

• set is unchanged — drop onEditEvent and the hook behaves exactly as before (correct for all sync cases).
• The handler is a pure corrector: it captures the stacks on submitEdit/submitRename/submitAdd (tagged with the operation), restores them on a matching updateError (erasing the apply+revert pair), and clears the marker on updateSuccess. The operation tag prevents a delete/move updateError (no submit*, different op) from consuming an edit's marker.
• A synchronous reject never reaches set, so its updateError restores stacks that never moved — a harmless no-op.

Why a corrector rather than gating

set is (data) => void — it never learns which path/operation triggered a write, so snapshots can't be tagged per-op; the event stream knows the op but holds no reference to a snapshot. The two channels are decoupled, so the pragmatic design leaves set untouched and uses onEditEvent purely to undo the damage of a reverted optimistic commit.

Scope (documented, not engineered around)

Corrects a single in-flight edit — the realistic case. It does not unwind two genuinely-concurrent async rejections (single marker), nor an async-rejected delete/move (instant ops have no submit* to anchor to). Both are rare; the README points to hold() for watertight history under heavy concurrent async validation.

Tests & docs

• Extended the UndoEditor harness; added the without-onEditEvent case (pins the documented pollution), the with-onEditEvent fix, a valid async edit (one step, no over-correction), a sync-reject no-op, and two renderHook unit tests of the corrector mechanics.
• 693 tests pass; pnpm compile and pnpm lint clean.
• Documented as an "Async validation (optional)" section in the useUndo README only — not promoted in the main README.

🤖 Generated with Claude Code

[github-actions]

Bundle size impact

@json-edit-react/utils

Format	Base raw	PR raw	Δ raw	Base gzip	PR gzip	Δ gzip
esm	4.62 KB	5.02 KB	🔺 +410 B (+8.67%)	2.09 KB	2.21 KB	🔺 +122 B (+5.69%)
cjs	4.70 KB	5.12 KB	🔺 +429 B (+8.91%)	2.09 KB	2.21 KB	🔺 +122 B (+5.71%)

_{Measured from build/index.{cjs,esm}.js. Gzip at level 9.}

[Copilot]

Pull request overview

Adds an opt-in onEditEvent handler from useUndo to correct undo history pollution caused by async onUpdate rejections (optimistic apply followed by revert), without changing the existing set behavior for all other cases.

Changes:

• Extend useUndo to return an onEditEvent corrector that restores pre-submit undo/redo stacks on a matching updateError.
• Add integration + unit coverage demonstrating the “polluted history” case when not wired, and the corrected behavior when wired.
• Document the optional wiring pattern and its intended scope/limitations in the useUndo README.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
test/useUndo.test.tsx	Adds integration and unit tests covering async-reject history pollution and the new correction mechanism.
packages/utils/src/undo/useUndo.ts	Implements the onEditEvent corrector via a single in-flight marker (queues + operation).
packages/utils/src/undo/types.ts	Extends the public UseUndoResult API surface to include onEditEvent.
packages/utils/src/undo/README.md	Documents the optional onEditEvent wiring and when it’s needed (async validation that can reject).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.