Repository navigation
PT-4688: Warn before paragraph merges and keep pasted markers out - #32
Conversation
jolierabideau
left a comment
There was a problem hiding this comment.
Review summary
Thanks for this. The two-step merge is carefully done: the Delete arm keeps the caret, one predicate ($canMergeIntoPrevious) gates both plugins, and the tests cover the arm and cancel paths across keydown, beforeinput and DELETE_CHARACTER_COMMAND. I found one blocking regression and a few things worth tightening before merge.
Verified locally on ce992f6b:
- shared-react: tests 2111 passed / 1 skipped; lint and typecheck clean.
- platform-editor: full suite passes (3970 passed / 17 skipped).
- The committed
dist/is byte-identical to a freshbuild+extract-apifrom the final source. No API report change is needed: the platform public API is unchanged, and shared-react is private.
Against the PT-4688 DOD ("Under structure protection, no selection path can remove a paragraph marker")
- ✅ The ticket's repro is fixed. With protection on, in Paragraph Structure view, select a whole
\s1/\p/\mtrow and press Backspace or Delete. The text goes and the marker survives: Lexical narrows the triple-click to the one paragraph, and$restoreGutterMarkerIfMissingputs the glyph back. - ✅ The copy/paste case is fixed and tested. The new
[data-text-type="marker"]strip only removes presentation-only glyphs (onlyImmutableTypedTextNodeemits that attribute), so no real content is dropped. - ✅ These paths were already refused and tested: selections spanning paragraphs, a selected gutter marker, cut and drag-start.
⚠️ There's no regression test for the exact repro. Nothing tests "select the whole\s1/\p/\mtrow, then Backspace/Delete, underprotected, and the marker survives". Could you add a platform<Editor>test for it, in Paragraph Structure view withgetUsj()assertions? It's the DOD's own scenario, and today it holds only because two separate mechanisms happen to combine.⚠️ "No selection path" isn't fully met (pre-existing, not from this PR). Underprotected,StructureKeyboardPlugindoesn't interceptREMOVE_TEXT_COMMAND,DELETE_WORD_COMMANDorDELETE_LINE_COMMAND. Lexical dispatches these frombeforeinput(deleteWord*,deleteSoftLine*/deleteHardLine*,deleteContentForward,deleteByComposition,deleteByDrag,deleteByCut). On a selection that spans paragraphs or a Ctrl+A, they merge paragraphs and drop markers; select-all left no paragraphs in a probe. Hardware keyboards are caught earlier bykeyDownToIntent, so this is only reachable from mobile, virtual-keyboard and IME input. Either fix it here, or split it into a follow-up ticket and say so on PT-4688.- ℹ️ Scope: the larger half of this PR (the two-step warning under
guarded) is protection-off behaviour. It comes from the PT-4688 comment, not the DOD. I'm fine reviewing it here, but it's worth noting on the ticket so QA knows what to test.
Must fix
- Regression: under
guarded, Backspace at the start of a chapter's first paragraph now deletes structure with no warning.- Cause:
structureKeyboard.utils.ts:308,$structuralDeleteTarget, replaced$hasNeighborBlock(…, "backward")with$canMergeIntoPrevious. - Before: a paragraph after
\cwas armed, the second press was a no-op merge, and the key was consumed. - Now: no target is returned, so neither plugin claims the key and Lexical's native
deleteCharacterremoves the adjacent decorator. A throwaway test confirmed it:- With a gutter glyph, the first press deletes the
\pglyph and the second deletes\c 1. - With no glyph, the first press deletes
\c 1outright.
- With a gutter glyph, the first press deletes the
- Why it matters: this happens at the start of every chapter, and it breaks the "visibly refused, no silent no-ops" rule in
docs/standard-view-invariants.md. - Test gap: the new test ("returns undefined at the start of a para after a chapter") checks only the helper, not what the keystroke does to the document.
- Suggested fix: when there is a previous sibling but no merge is possible, claim and refuse the key rather than falling through. Add a plugin-level test that presses Backspace after
\cunderguardedand asserts the document is unchanged. - Related (pre-existing, same root cause): forward Delete at the end of the paragraph before a
\cdeletes the chapter underguardedtoo (:317-320checks$hasNeighborBlockbut only arms whennextis a para). Worth fixing in the same change.
- Cause:
Should address
-
Test trees use the half-flat shape CLAUDE.md forbids. In
StructureKeyboardPlugin.test.tsx, three tests in the "armed DOM signals" block dosecond = $createParaNode("p").append(...); $getRoot().append(..., second):- "Backspace-armed…", which was correctly chained before this PR;
- "Delete-armed…";
- "an armed empty paragraph…".
Hoist only the bare
$createParaNode("p")and append its children inside the root chain, as the new "Backspace twice removes an empty paragraph with no children" test already does. -
Two docs have gone stale.
$structuralDeleteTargetstill says it "mirrors$shouldBlockStructuralEdit's boundary conditions". The guarded backward path now uses$canMergeIntoPrevious, while protected still uses$hasNeighborBlock.$mergeParaIntoPreviousstill says its caller checks$hasNeighborBlock.
This partly resolves with #1.
-
Release coupling with paranext-core#2941. Paragraph arms now set
verse-delete-armed/data-verse-delete-*, with three new kind values. Before, paragraph arms set none. An older host that sees these could show verse wording or nothing at all. The release order in the description covers it; please make sureplatform-yalcdoesn't move forward on its own in between.
Minor / nits
- CSS pin test:
editor.css.test.tspins the selected-marker rules toPARA_MARKER_SELECTED_CLASS_NAME, but there's no matching pin for.para-merge-armed↔PARA_MERGE_ARMED_CLASS_NAME. - Naming: the paragraph-marker family is prefixed (
psc-para-marker-selected,--psc-para-marker-gutter-width), but the new class and custom properties aren't (para-merge-armed,--para-merge-armed-text-*). Considerpsc-…, unless core already depends on the string. - Placement in
StructureKeyboardPlugin.tsx: the siblingParaMarkerSelectionPlugin.tsxputs the exported*_CLASS_NAMEfirst and its private DOM helpers below the component. Here, the private constants andpublishMarkerTextBoundscome first and the export last. - Union spelled out again:
"deleteBackward" | "deleteForward"now appears a third time, in$paraDeleteEffect's parameter. Consider a named alias, orArmedDelete["intent"]. - Parameter types:
$canMergeIntoPrevious(LexicalNode),$isParaEmptyand$paraDeleteEffect(ElementNode) are only ever called with aSomeParaNode.$mergeParaIntoPreviousalready takesSomeParaNode. - Point snapshots: they're built inline twice (the para arm and the selection arm). A small
snapshotPoint()next toPointSnapshotwould pair with the new$isAtSnapshot. - TSDoc describes callers:
$canMergeIntoPrevious's TSDoc explains who calls it ("ParaMarkerSelectionPluginhands …$structuralDeleteTargetarms …"). That goes stale the way #3 did. - Stale NOTE: the NOTE in
libs/shared/src/nodes/features/ImmutableTypedTextNode.ts(~L255) still calls marker-glyph paste an open "behavior decision". This PR decides it, and hard-codes"marker", which duplicates the privateMARKER_TEXT_TYPE. - Line length: the comment at
editor.css:671is 120 chars, and a few TS comment lines run 101–104 (StructureKeyboardPlugin.tsx~L96–97, L187, L265–267;structureKeyboard.utils.ts~L403–404). Prettier doesn't re-wrap comments. - Weak assertion: in
paraMarkerSelection.test.tsx(~L597),.toBeDefined()is weaker than the.toBe("li2")used elsewhere in that file. - Armed class can go stale: the class and the measured bounds are applied once to the element captured at arm time. If Lexical recreates that element while armed, the tint is lost until re-arm. Rare, since
updateDOMreturns false; noting it only. - Uncovered edge cases (all low risk): pasting an inline glyph (
\w); a drop strip; typing or arrowing after a Delete arm;$canMergeIntoPreviousafter a table or sidebar;removeEmptyParavia Delete end to end.
Open question for the team
- Two presses on a selected gutter marker under
guarded. This reverses PT-4540's deliberate "selecting the marker is the arming step" one-press merge. The DOD doesn't ask for it, since it's protection-off behaviour. I'd like product (Ian) to confirm it explicitly before we ship, rather than have it ride along with a protection-on ticket.
Requesting changes for #1; everything else can be addressed here or ticketed.
|
Thanks for the thorough review, @jolierabideau. Fixed in Must fix
Should address
Mobile, virtual-keyboard and IME deletes under Two presses on a selected marker: Ian approved this after a live demo this morning, along with warning on every paragraph merge. The description now says so, and it also notes the scope against the definition of done. Nits, all done:
Naming: I kept Left as noted: the armed class going stale on a re-created element, and the low-risk edge cases. Checks: shared-react 2115 tests passed / 1 skipped, shared 895 passed, platform 3977 passed / 17 skipped. nx typecheck and lint are clean. |
jolierabideau
left a comment
There was a problem hiding this comment.
Thanks, Levi. I checked 762a3923 against my review and everything is addressed. The \c Backspace refusal and its plugin-level tests, the regression test for the PT-4688 repro, the test trees, the docs and the nits all look good.
Before merge:
- Please file a follow-up Jira ticket for the deletes under
protectedthat don't come from a hardware keyboard:REMOVE_TEXT_COMMAND/DELETE_WORD_COMMAND/DELETE_LINE_COMMANDdispatched frombeforeinputon mobile, virtual-keyboard and IME input. On a selection that spans paragraphs, these can still merge paragraphs and drop markers. Then link the ticket on PT-4688, since its "no selection path" definition of done depends on it. - The branch currently conflicts with
main(StructureKeyboardPlugin.tsx,structureKeyboard.utils.ts,dist/). Please resolve the conflicts and rebuilddist/before merging.
…rges Structure protected: a paste or drop no longer brings in a marker glyph. Copying a triple-clicked heading puts its gutter marker in the clipboard HTML; parsed back, it became plain "\s1 " text that saved as a real \s1 paragraph. The sanitizer now drops [data-text-type="marker"] elements before parsing. Guarded: every paragraph merge publishes its armed state, so the host can warn on the first press. data-verse-delete-kind names what the second press does (joinPreviousPara, joinNextPara, removeEmptyPara) and the armed paragraph gets the para-merge-armed class. Guarded: Backspace/Delete on a selected gutter marker now take two presses too. ParaMarkerSelectionPlugin leaves the merge to StructureKeyboardPlugin's two-step delete, which arms it with the marker still selected. This reverses PT-4540's one-press merge from a selected marker. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ndings Guarded: arming a paragraph merge selects and tints only its gutter marker, never the paragraph's text, since a merge keeps the text. The editor measures the marker text's bounds and publishes them as --para-merge-armed-text-left/-width so the tint (and the host's hint) fit the glyph, which the first-line indent pushes outside the marker's box. A paragraph with no visible marker is armed on a snapshot of the caret, which also lets an empty paragraph with no children be removed. A Delete arm at the end of a paragraph leaves the caret there instead of selecting the next paragraph's marker, so typing or an arrow key after the arm acts where the user was. The next marker is still tinted. A Backspace arm now uses $canMergeIntoPrevious, the same check the merge makes, so a paragraph after a chapter, table or sidebar no longer arms a merge that can never happen and swallows every later press. Also: one shared $canMergeIntoPrevious for both plugins, calling-context TSDoc on the new $ helpers, and comment fixes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nits Under "guarded", Backspace at the start of a chapter's first paragraph fell through to the native delete once arming required something to merge into, removing the gutter marker and then the chapter. It is now claimed and refused, as under "protected". Also from review: a platform test for the PT-4688 repro (whole \mt/\s1/\p row selected, Backspace/Delete under protection, marker survives); a CSS pin for the armed-merge class; test trees built in one root chain; stale docs on $structuralDeleteTarget, $mergeParaIntoPrevious and the ImmutableTypedTextNode paste NOTE; DeleteIntent alias, snapshotPoint helper, SomeParaNode parameter types; export-first ordering; MARKER_TEXT_TYPE in the paste sanitizer; comment rewraps; a stronger selected-marker assertion. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
94a6ab5 to
027338b
Compare
Release order: merge this PR first, then move
platform-yalcforward, then merge paranext/paranext-core#2941. Either order is safe; the paranext-core side shows nothing until this editor build reaches it.Product decision (approved): under "guarded" structure protection, every paragraph merge warns first, not only one that removes an empty paragraph. Backspace/Delete on a clicked gutter marker also takes two presses, reversing PT-4540's deliberate one-press merge. Ian approved both after a live demo on 2026-10-26.
Scope against the tickets: PT-4688's definition of done ("under structure protection, no selection path can remove a paragraph marker") is met by PT-4540 plus this PR's paste/drop sanitizer, with a regression test for the ticket's repro. The two-press paragraph warning, the larger half of this PR, is protection-off behaviour. Ian asked for it in his PT-4688 comment 28256, so QA should test it with protection unlocked. The same goes for PT-4677.
Follow-up: PT-4926. This bug predates these PRs: with protection off, Delete at the end of a chapter's last paragraph removes the next
\cwithout warning.Code Review Summary
Branch: pt-4688-protected-paste-and-merge-warning (in both
paranext/scripture-editorsandparanext/paranext-core)Base: origin/main
Date: 2026-10-23 (code-review pass 2026-10-26)
Review model: Claude Opus 5.5
Files changed: 17 (10 in scripture-editors, 2 of them generated
dist/output; 7 in paranext-core)Overview
Follow-up to PT-4688 and PT-4677 after both were found largely fixed on
mainby PT-4540 (scripture-editors #22). With structure protection on, a paste or drop no longer brings in a copied paragraph marker: triple-clicking a\s1heading, copying it and pasting elsewhere used to put its gutter marker's text (\s1) into the paragraph, which was saved as a real\s1and became a new paragraph on reopen. The protected paste/drop sanitizer now drops every marker glyph ([data-text-type="marker"]) from the parsed HTML.With structure protection off (Simple, unlocked,
"guarded"), every paragraph delete is now a visible two-step delete, as Ian Hewerdine asked on PT-4688 (comment 28256): the first Backspace/Delete tints the gutter marker that would be removed red and shows a tooltip ("Press {key} again to join this paragraph to the previous one" / "…join the next paragraph to this one" / "…remove the empty paragraph"); the second press merges. The paragraph's text is never selected or tinted. This applies to Backspace at a paragraph's start (which also selects that marker), Delete at the end of the line before (which tints the next paragraph's marker but leaves the caret where it is), and — a change from PT-4540 — Backspace/Delete on a clicked gutter marker, which used to merge in one press. A paragraph that shows no marker keeps its caret and is armed with no highlight; the tooltip, anchored at the caret, alone signals it. Line breaks (Shift+Enter) are untouched.API Changes
paranext-core: None. All changes are internal to the
platform-scripture-editorextension (two-step-delete-tooltip.utils.tsadds module-localTWO_STEP_DELETE_MESSAGE_STRING_KEYS,hintMessageKey,narrowToArmedMarkerTextandcomputeCaretAnchorRect, and widensArmedHint['kind']), plus three new localized string keys.scripture-editors:
@eten-tech-foundation/platform-editor(packages/platform/src/index.ts): no exports changed.shared-react(private workspace lib): new exportsPARA_MERGE_ARMED_CLASS_NAME,ParaDeleteEffect,$isParaEmpty(),$paraDeleteEffect(),$canMergeIntoPrevious().ArmedDeletegainsparaEffect?; itsanchor/focussnapshot is now also used by a"para"arm on a paragraph that shows no marker.$structuralDeleteTarget()returns a"para"target for a selected gutter marker that can merge, and a Backspace from the caret arms only when$canMergeIntoPreviousholds (was: any previous sibling);$isArmedSelection()holds a"para"arm while its marker stays selected (or the caret stays at the recorded point) instead of while the paragraph's text is selected.data-verse-delete-intent/data-verse-delete-kindare now published for paragraph arms too, with the new kindsjoinPreviousPara | joinNextPara | removeEmptyPara; classpara-merge-armedon the armed paragraph's gutter marker whether or not it is selected (on the paragraph itself when it shows none, and the caret is left in place so the host can anchor there); CSS custom properties--para-merge-armed-text-left/--para-merge-armed-text-widthon the armed marker."guarded", Backspace/Delete on a selected gutter marker takes two presses (was one); a Backspace arm from the caret selects the marker instead of the paragraph's text, and a Delete arm leaves the caret where it is. Under"protected", pasted/dropped HTML has every[data-text-type="marker"]element stripped.Findings
Critical — Must address before merge
None.
Important — Should address before merge
editor.css; would also hit paranext-core once it styles selected markers) (fixed during review: arming now always selects the gutter marker and only the marker is tinted, with selectors that out-rank the gutter marker's own and selected rules; the paragraph row is no longer styled)$isArmedSelectionrejected, so each press re-armed and nothing was ever removed (fixed during review: a paragraph with no marker is armed on a snapshot of the caret; new test "Backspace twice removes an empty paragraph with no children")Author response: both fixed together by the decision to arm on the marker, not the text (see Interview Notes).
Minor — Consider
No test confirms the tooltip anchors to(author: confirmed working in the app; not worth a test).para-merge-armed\pmarker)Only paste, not drop, has a test for the marker-glyph strip(author: drag-and-drop does not work under structure protection in practice; note that a drop from another app still goes through the same sanitizer)$isTwoStepRemovalduplicated$structuralDeleteTarget's merge check, and its name read oddly (fixed during review: one shared$canMergeIntoPrevious; renamed$deferToTwoStepDelete)PARA_MERGE_ARMED_CLASS_NAMEexported but every consumer hard-coded the string (fixed during review: scripture-editors tests use the constant; stylesheets and core cannot import it)verse-attribute/class names now also carry paragraph arms (fixed during review: comment at the publish site says the names predate paragraph arms and cover every two-step delete)(author: matches that file's existing verse styling; paranext-core uses the theme token)editor.csshard-codes#dc2626with no dark variantverse-selectedas the observed signal (fixed during review: both comments namepara-merge-armedtoo)/code-review) (fixed during review:narrowToArmedMarkerTextnarrows the tooltip anchor to the marker-text bounds the editor publishes; unit-tested)platform-yalc. Either order is safe.Author response: release order to be stated in both PR descriptions (merge scripture-editors, move
platform-yalc, then merge paranext-core).Code-review pass (2026-10-26,
/code-review high)\c, a table or a sidebar, the arm checked for any previous sibling but the merge needs a paragraph or the\idline, so every later press was swallowed (fixed: the arm uses$canMergeIntoPrevious; regression test)computeCaretAnchorRect, falling back to the paragraph's box; unit-tested)$isParaEmpty/$paraDeleteEffectTSDoc lacked their calling context (fixed)VerseDeleteTooltipOverlay(fixed)Pressing the other key on an arm from a selected marker cancels it, though both keys remove a selected marker(author: intended — the hint names one key, and a deliberate cancel is safer)\s1text under protection — the plain-text path predates this branch, which only strips the HTML payload.Template Propagation
Shared Regions Modified
None.
Extension Config Changes
extensions/src/platform-scripture-editor/contributions/localizedStrings.json— extension-specific, no propagation needed.Positive Observations
data-verse-delete-kindvalues, and the new host validates against an explicit kind list.MESSAGE_KEYS: Record<ArmedHintKind, LocalizeKey>makes a missing message for a new kind a compile error; the localized-strings test iterates the derived key list, so a kind without en/es text fails CI.beforeinput,DELETE_CHARACTER_COMMAND, mismatched-key cancel and single-step undo; caret arms selecting the marker for Backspace and Delete; DOM signals for all three kinds plus cleanup; the integration test inparaMarkerSelection.test.tsxchecks the first press leaves the document unchanged.editor.css, theme token plus dark variant in core, reduced-motion fallback in both).Interview Notes
main(the earlierpt-4688-protected-para-markerbranches predate PT-4540).platform-yalc, then merge paranext-core.In-Review Quality Check
All checks passed in both repos after the code-review fixes (2026-10-26).
nxlint (shared-react) — 0 errors;tsc(shared-react) clean; shared-react vitest 2111 passed / 1 skipped; platformsrc/editorvitest 3946 passed / 17 skipped; Prettier on changed files clean; committeddist/index.jsrebuilt from the final source.npm run lint— 0 errors; extension vitest (platform-scripture-editor) 4441 passed; Prettier on changed files clean;extensionsbuild compiles (the SCSS builds under sass-loader).npm run typecheckskipped per the author's standing preference.Suggested Review Focus
window.getSelection()and falls back to the paragraph's box when the caret has no rect (as at an empty element). Unit-tested; not yet checked in the running app.StructureKeyboardPluginmeasures the armed marker's text bounds (Range geometry) and publishes them as CSS custom properties; the stylesheets draw the highlight from them. Measured once when armed, not on resize — fine for a short-lived arm, but check the approach.platform-yalc, then the paranext-core PR.\s1 x(plain text, not a copied glyph) is not stripped under protection; with protection off, CommandMenuPlugin refuses any paste containing\.🤖 Generated with Claude Code
This change is