Repository navigation
Conversation
Add the merge-blocks-on-delete change for #135. A single BlocksAPI.merge overloaded for a block or a cross-block range joins neighbouring blocks; Backspace/Delete at boundaries and deletions over cross-block selections map to it from the DOM adapter. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.
An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.
| - **Browser differences around boundary events** → boundary detection relies on the collapsed DOM selection and the input type, not on the reported target range; covered by Playwright e2e on chromium and webkit (the browsers the e2e project runs). | ||
| - **Caret races with adapter-side caret updates.** The adapter's model-to-DOM text sync also updates the caret index after `TextAddedEvent`/`TextRemovedEvent`. The adapter sets the caret to the returned junction after `merge` returns, so its write is last; e2e tests assert the caret lands at the junction. | ||
| - **Formatting bleed at the junction** → explicit unformat-then-reformat step (Decision 6), covered by a test that merges into an input ending with a formatted run. | ||
| - **Content outside the export is dropped.** A range ending in a quote's caption, or Backspace into a quote with a caption, drops what the quote's export does not carry. Same rule as `convert`, and v2's behaviour; worth stating in the `merge` docs. |
There was a problem hiding this comment.
Dropping fields outside export on merge is fine for the MVP.
TODO: multi-field export. merge({ index }) should keep the unselected tail and the neighbouring text fields, not only the export key.
| | backward/forward delete type at an edge between two inputs of the same block | caret moves to the end of the previous / start of the next input; no document change | | ||
| | anything within one input | unchanged (`api.text.remove` / `insert` / `split`) | | ||
|
|
||
| Backward types are `deleteContentBackward`, `deleteWordBackward`, `deleteSoftLineBackward`, `deleteHardLineBackward`; forward types are their `Forward` counterparts. Boundary detection uses the collapsed DOM selection and the input type, **not** the browser's target range, because browsers disagree on the target range they report for Backspace at the start of a block. Neighbours are found with `api.blocks.getIdByIndex` and their text inputs with `InputsRegistry.getBlockInputs`. |
There was a problem hiding this comment.
TODO: word/line delete at a block boundary.
Right now any backward delete at offset 0 does a full merge({ block }). For
Hello world
|Foo
Option+Backspace (deleteWordBackward) should also remove world and leave Hello|Foo. Same for line-delete in either direction. For the MVP we keep the full merge, as written here.
|
|
||
| 1. If `content.value` is empty, return. | ||
| 2. `model.insertText(userId, blockIndex, key, content.value, offset)`. | ||
| 3. Normalize the inserted range: inserted text takes the formatting of the text it is inserted into, so appending at the end of an input that ends with a bold run makes the merged text bold. This holds for the current inline tree (`ParentInlineNode.insertText` inserts into the child found by `findChildByIndex`) and for the run model proposed in [#198](https://github.com/editor-js/document-model/pull/198) (`RunList.insert` extends the run at the offset with its marks). The clean-up only uses the model's public operations, so it works with either: read `model.getFragments(blockIndex, key, undefined, offset, offset + value.length)` and `model.unformat(...)` every tool found there. |
There was a problem hiding this comment.
On main the signature is getFragments(blockIndexOrId, dataKey, start?, end?, tool?). Passing undefined as the third argument shifts the rest: end becomes offset, and tool receives a number.
It should be getFragments(blockIndex, key, offset, offset + value.length). Call unformat on [offset, offset + length), not on the fragment bounds. A fragment can start before the junction, which would strip formatting from text that was already there.
|
|
||
| 1. **Validate** (Decision 5) before any mutation. | ||
| 2. **Remove the range content in B** (B has the highest index, so lower indexes stay valid): remove `[0, e]` from `keyB` and empty every text input of B that the range fully covers (the segments before `keyB`). | ||
| 3. **Remove the blocks strictly between A and B**, by index range in descending order — not by segment, so blocks without text inputs (which produce no segments) are removed too. |
There was a problem hiding this comment.
After the blocks strictly between A and B are removed, B's index has already changed. Capture both edges' ids before any mutation, then delete and append by id rather than by the indexes taken at the start.
|
|
||
| Blocks without text inputs that lie **strictly between** the edges of a range are not joined, only removed (step 3), so they never make a range merge fail. | ||
|
|
||
| On the keyboard, an unmergeable neighbour is **removed** instead of merged: Backspace at the start of a block right after an image, or Delete at the end of a block right before one, deletes the image through the existing `api.blocks.delete`, and the caret stays where it is. This is the adapter's mapping (Decision 7), not a `merge` rule: `merge` keeps one meaning — joining two text blocks — and a programmatic caller that merges an image gets an error rather than a silent deletion. |
There was a problem hiding this comment.
EditorDocument.removeBlock does not rewrite the caret, and the caret is stored as a blockIndex. After deleting the previous block, that index shifts.
"Caret stays where it is" means the same block id and offset. Set that explicitly. The old index no longer points at the right place.
| 6. **Otherwise convert B into A**: compute B's absorbed content (Decision 3) from B's **current** state, append it into `keyA` at `s` (Decision 6), and remove B. Junction → `(A, keyA, s)`. | ||
| 7. Return the junction. | ||
|
|
||
| All mutations are dispatched synchronously within the caller's browser task, which is what `undo-group-by-task` needs to record them — together with the adapter's follow-up insert or split — as one undo step. |
There was a problem hiding this comment.
Some model events are already dispatched as microtasks (DataNodeAddedEvent while a block is constructed; see the comment in addBlock). Task 3.6 requires every event of one merge to be emitted synchronously, before merge returns.
Otherwise undo-group-by-task will not group them, and the adapter's follow-up insert will run before merge's own microtasks. Worth checking up front whether insertText / format go through that same queue.
There was a problem hiding this comment.
Merge uses only synchronous events, so it's safe here. I've changed the wording a bit though
| ## MODIFIED Requirements | ||
|
|
||
| ### Requirement: EditorAPI surface | ||
| The system SHALL expose an `EditorAPI` aggregating `BlocksAPI` (insert/insertMany/delete/move/render/clear/getBlocksCount/split/convert/merge), `SelectionAPI` (applyInlineTool, selectedBlocks), `DocumentAPI` (serialized data, onUpdate, insertData/removeData/modifyData, undo/redo), and `TextAPI` (insert/remove/format/unformat/getFragments/get) to tools, plugins, and adapters. |
There was a problem hiding this comment.
Once this requirement is archived, the list still omits methods that already exist: getIndexById, getIdByIndex, getData, createData, removeData, updateValue.
On main, blocks.delete is delete({ block }), not a bare delete() (same in the dom-adapters scenarios).
exportTextContent throws when there is no conversionConfig. The "no config → first text input" branch must not go through it. Decision 3 already says so; an implementation can easily do the opposite.
- Resolve merged blocks by id up front so later steps never act on a shifted index - Fix getFragments argument order; unformat exactly the appended range - BlocksAPI.merge keeps the caller's caret despite adapter-driven caret updates - Re-set the caret after blocks.delete of a neighbour, always passing its id - Add read-only BlocksAPI.getTextKeys so the adapter decides from the model, not from a DOM registry that is empty until the block renders - Clarify synchronous dispatch and its relation to undo-group-by-task - List all BlocksAPI methods; record word/line boundary deletes and multi-field export as follow-ups Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
What
Planning only. This PR adds the
merge-blocks-on-deleteOpenSpec change for #135. It contains no code changes.One new API method,
BlocksAPI.merge, with two overloads:merge({ block })merges a block into the block before it. Only neighbouring blocks can be merged, so one block is enough.merge({ index })takes a range that crosses blocks. It removes the content inside the range and the blocks in between, then joins the end block into the start block.{ block, key, offset }).mergenever moves the caret, likesplitandconvert.How merging works:
conversionConfig.export: a key path keeps formatting, a function gives plain text, and with no config the first text input is used. There's no direction and no separate convert step.mergethrows for them. On the keyboard, Backspace or Delete next to such a block removes it.The DOM adapter only maps events to calls:
merge({ index })call, then the insert or split where the blocks joined.merge({ block }).There's no
canMerge, no new tool option, and no change toSelectionAPI,TextAPIor the model.Why
v3 is one contenteditable with cross-block selection, so merging is also needed whenever a deletion crosses a block boundary, not only on Backspace/Delete as in v2. Today none of these cases join anything:
@todo support input merginginBlockToolAdapterat that spot.Notes for reviewers
merge/canMergeplus acanBeMergedoption, a newSelectionAPI.deleteContent, extendingTextAPI.remove, and two-step convert-then-merge on Backspace.undo-group-by-task(docs(openspec): propose undo grouping by browser task #201 / feat(core): group undo steps by browser task #203). That change makes a merge a single undo step and fixes undo of block removal, which currently throws.insertFromPaste, which this change routes throughmerge({ index }).🤖 Generated with Claude Code