Repository navigation
PT-4965: Put chapter 1's verses in a paragraph - #40
Conversation
jolierabideau
left a comment
There was a problem hiding this comment.
Review summary — PT-4965: Put chapter 1's verses in a paragraph
Nice work — this solves the ticket cleanly, and the scope widening to the all-front-matter case is well justified (it's the case Simple mode actually hits, so without it the ticket's trap wouldn't really be fixed). CI is green, including the committed-dist freshness check. No blocking issues; a few minor items below.
How it solves PT-4965
| Definition of Done | Status | Evidence |
|---|---|---|
| Empty verse-text paragraph takes the verses, all 3 views | ✅ | "puts verses in an empty paragraph" (all-views block) |
| Caret when markers hidden | ✅ | Both the reused-paragraph and new-\p paths in the hidden-markers block |
| Two existing tests updated | ✅ | Plus the whitespace/ZWSP and no-break-space ones, as noted in the ticket comments |
\q1 and empty-heading cases |
✅ | \q1 (Standard), \s1 \ms \r \d \b in all views |
| Introduction test (Change 2) | ✅ | "adds verses after a book's introduction" — stronger than asked: asserts they land in a new \p after \ip |
EditorRef doc, CHANGELOG, dist |
✅ | Docs/CHANGELOG/TSDoc describe the same behavior; dist/index.d.ts is the rolled-up output |
Move platform-yalc after merge |
⏳ | Post-merge |
On the two "for the reviewer to confirm" items: keeping verses above an empty \s1/\ms/\r/\d/\b matches the ticket, and excluding \d/\b by name is reasonable given the stylesheet can't distinguish them (nothing else in the codebase reads textType to decide this). The TSDoc on canHoldVerses explains it well. 👍
Code patterns
Adheres well to the repo's conventions: no null, editor.getEditorState().read in tests, $create* helpers, $isSomeVerseNode instead of the spelled-out union, getAllTextNodes() for marker lookup, no issue-tracker refs in code, new private helpers placed beside the file's other predicates, and tests extend the existing insertWithVerses/mountEmptyBook patterns. Keeping the paragraph rather than rebuilding it (preserving attributes, annotations, an unsettled marker edit, and one-step undo) is the right call and is both commented and tested. Finding verse 1 by type rather than position is a good fix for the no-spacing view.
Minor findings
- Over-long doc line —
firstChapter.utils.ts:217is 131 chars; the rest of the block wraps at 100 and Prettier won't reflow comments. Similarly, the CHANGELOG entry's last line ("Returnsfalse, …") was left as a short unreflowed line. occursUnderAllowshas a third copy —markerMenu/markerItemSource.ts:210-211still inlines the sameoccursUnder.length === 0 || includes(...)check. Worth switching it over too (or a follow-up). The helper's doc ("a char or verse marker … undercontextMarker") could also mention it's now used outside validation.- Empty
ImpliedParaNodeas chapter content start —$findChapterContentStartreturns a block with no tag marker (e.g. an implied para) as the content start.versePararequires$isParaNode, and the new-\pbranch requires!chapterContentStart, so an empty implied para after the front matter would still get the verses as a bare implied para above it — the original symptom. I couldn't find a user gesture that produces this state, so it may be unreachable; worth a quick thought on whether to treat an empty implied para like "no content start". - Unsettled heading retype — you already call this out as a known gap. Just to make the consequence explicit:
\pretyped to\s1but unsettled → verses are appended, then the paragraph settles as\s1holding\v 1 …. Fine to defer, but maybe worth a follow-up ticket so it covers both checks as you suggested. - Two "blank" definitions side by side —
$isDocumentText(.replaceAll(ZWSP,"").trim()) vs$removeBlankText(/^[ \t\r\n]*$/+$isCaretHost). The difference is intentional, but a named const for the regex and one sentence noting it's deliberately narrower would protect it from a well-meaning "unification" later.$removeBlankTextcould also takeParaNodeinstead ofElementNode(it's only ever passed one, and drops an import). - Test coverage gaps (breadth only):
- No
\li1or\mcase, though\li1is named in theEditorRefdoc. - The negative stylesheet branch of
canHoldVersesisn't tested (a verse-text paragraph that\v'soccursUnderexcludes, or a sheet with no\v). - The Standard-view caret isn't asserted on the new-
\ppath (sameselectEnd()code, so low risk). \q1, first-of-two, undo, unsettled-edit and custom-stylesheet cases run in Standard view only.
- No
- Test-only export from
shared-react—$createCaretHostNodeis exported from the barrel just for the platform test. Acceptable sinceshared-reactis private with no API report; just noting it now reads as public surface.
Overall: approve-worthy once you've decided on the minor items. 🙂
AI-assisted review (Claude Opus 5.5).
|
Replies to the review, addressed in eb1f122 (source) and 512a672 (
Testing: |
"Add chapter number" (EditorRef.insertFirstChapter) put the new verses outside any paragraph, which Simple mode's structure lock then kept the user from repairing. - An empty paragraph of verse text (\p, \q1, ...) after the front matter now takes the verses, keeping its marker and anything it holds other than spaces. An empty \s1, \ms, \r, \d or \b keeps them above it. - A book that is all front matter, as every new book in Simple mode is, gets the verses in a new \p. - occursUnderAllows shares the validator's "empty occursUnder allows it anywhere" rule. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Give the verses a new \p in place of blank text in no paragraph, as an empty document loads, instead of leaving them outside a paragraph. - Share occursUnderAllows with the marker menu's character list. - Name the spaces-only pattern and note why it is narrower than the verse check; narrow $removeBlankText's parameter type. - Rewrap the insertFirstChapter doc and CHANGELOG lines. - Widen test coverage: \m and \li1, stylesheets that refuse the verses, the Standard-view caret on a new \p, and more cases in all views. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
512a672 to
6d0e90b
Compare
main's insertFirstChapter (#40) called selectNext() on verse 1, which no-raw-carrier-accessors flags: an annotation can cut a verse into pieces. Use $lastPiece, as the other verse selectNext sites do. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Summary
EditorRef.insertFirstChapter("Add chapter number") put chapter 1's new verses outside any paragraph. In Simple mode the structure lock then stops the user from fixing that. The verses now always go in a paragraph:\p:\id … \c 1 \p \v 1 … \v N. Every new book in Simple mode is like this.\p,\q1,\li1, …) takes them instead of having them land above it:\c 1 \p \v 1 …. The paragraph keeps its marker and anything it holds other than spaces.Follow-up to #37, from PT-4965.
Scope differs from the ticket
The ticket expected the common case to be an empty
\pleft by typing a title and pressing Enter. Simple mode never produces one:\id, plus\h/\toc*lines.So the all-front-matter case is the one that fixes the Simple-mode trap, and it was added here. The details are in the ticket's comments.
For the reviewer to confirm
\s1,\ms,\r,\dor\bas the first block still gets the verses above it, outside a paragraph, as the ticket specified. Wrapping them in a\pwould put them above the heading. Putting them after it (\c 1 \s1 \p \v 1) is a design call I left out.\dand\bare excluded by name. The stylesheet declares\dthe same way as\p. A stylesheet that lets\vgo anywhere would admit\b, and where markers are hidden the editor empties a\b, which would lose the verses.Where to look
packages/platform/src/editor/markerEdit/firstChapter.utils.ts:canHoldVersesand$removeBlankText.$insertFirstChapter,verseParaand the new\pfor an all-front-matter book.markerValidation.utils.ts:occursUnderAllowsnow holds the validator's "emptyoccursUnderallows it anywhere" rule. It is a refactor of two existing checks, with no behavior change.chapterLineEditing.test.tsx: the "over content already in the chapter" block, the all-views block and the hidden-markers block.libs/shared-react: exports$createCaretHostNodefor a test.EditorRef.insertFirstChapterdoc and the CHANGELOG's Unreleased entry. That entry is amended rather than added to, since the method hasn't been published yet.distrebuild.Details
\p→\s1) and the edit hasn't settled when the button is clicked, the decision uses the old marker. The front-matter check has the same gap, so a fix should cover both.AI Involvement
Written with Claude Code (Claude Opus 5.5). It was reviewed by an adversarial plan review, a multi-agent
/code-review, and a further adversarial pass over that review. The confirmed findings were fixed before opening, and one was refuted by testing. The author chose the scope. Commits carryCo-Authored-Bytrailers.Testing
chapterLineEditing.test.tsx: 162 passed. New or changed cases:\id,\h,\toc1) in all three views, the\id-only book, and the introduction book\pand\q1, and only the first of two empty paragraphs taking the verses\nd, a zero-width space from the file\bin all three views, including\bunder a stylesheet that allows\vanywhere\p→\q1edit, and the\menu leaving an empty\palonepackages/platformsuite: 4230 passed. One test,blockVersePositions.test.tsx"reports and accepts the inline layout's locations at every point", timed out while running alongside other jobs. It passed when its file was re-run alone, and it doesn't touch chapter insertion.libs/shared-reactsuite: 2291 passed.typecheckandlintfor both projects; the only warnings were already there.Risk Level
Low. Only
insertFirstChapterwith a verse count changes. The\menu's\candinsertMarker("c")ask for no verses and behave as before. The new nodes come from the same conversion that loads a file, so they match a loaded\c 1 \p \v 1. No paranext-core change is needed; moveplatform-yalcafter merge.🤖 Generated with Claude Code
This change is