Repository navigation
PT-4614: Add no verses above chapter text when starting chapter 1 - #37
Conversation
`insertFirstChapter(verseCount)` put its empty verses above whatever followed the front matter. A book typed or imported without chapter markers already holds its text there, so all of it ended up in the last verse. The host tried to prevent that with its own list of front-matter markers, which could disagree with where the stylesheet starts chapter content: for `\mt1`, `\b`, `\ip Intro`, the chapter starts at `\b`, the host counted `\ip` as front matter, and the introduction landed after the last verse. The editor now leaves the verses out itself when the chapter content, from where `\c 1` goes to the end of the document, already holds text or a verse. Markers, whitespace and caret-holding zero-width spaces are not text, so an empty paragraph still gets its verses. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
irahopkinson
left a comment
There was a problem hiding this comment.
@irahopkinson+AI made 7 comments.
Reviewable status: 0 of 7 files reviewed, 6 unresolved discussions (waiting on katherinejensen00).
a discussion (no related file):
I reviewed the source changes in this PR (firstChapter.utils.ts, its tests, the EditorRef.insertFirstChapter doc and the changelog entry), and checked that the rebuilt dist matches the source. There are 7 findings, each as its own comment on the line it concerns. Each comment shows the severity it settled at; checked and confirmed means the finding was verified against the code, and needs a human call means it could not be settled either way and is yours to judge.
(AI-assisted, with my guidance)
packages/platform/src/editor/markerEdit/firstChapter.utils.ts line 128 at r1 (raw file):
/** * Whether `node` is text of the document, as opposed to a marker glyph, whitespace, a zero-width
#3 - low · checked and confirmed
The $isDocumentText TSDoc says Standard view never saves attribute text, but that text is saved as an attribute value.
What happens: the TSDoc at firstChapter.utils.ts:128 describes attribute display runs as "the attribute text Standard view shows but never saves". That text is saved, just not as running text: \w word|gloss\w* saves lemma="gloss".
Why it matters: maintenance only; a reader could conclude attribute runs are throwaway display and treat them that way elsewhere.
Fix: reword the $isDocumentText TSDoc to "the attribute text Standard view shows, which is saved as an attribute value rather than as text".
How this was checked: The TSDoc at packages/platform/src/editor/markerEdit/firstChapter.utils.ts:128 was added by this PR (git diff shows the line as an addition) and says Standard view shows attribute text "but never saves" it. docs/standard-view-invariants.md:40 lists attribute-run text among the display bytes that make up the document, and the attribute display grammar section (around line 311) describes it round-tripping into attribute values (for example a bare |gloss on \w becomes the lemma attribute). The text is therefore saved, as an attribute value rather than as running text. The code in $isDocumentText is correct; only the comment misleads. Impact is maintenance only.
Other findings in this file: #1, #4, #5, #6, #7
packages/platform/src/editor/markerEdit/firstChapter.utils.ts line 131 at r1 (raw file):
* space holding a caret, or the attribute text Standard view shows but never saves. */ function $isDocumentText(node: LexicalNode): boolean {
#4 - low · checked and confirmed
$isDocumentText keeps its own list of display-only text that $isDisplayAnnotationCarrier already maintains, and the copy treats a note's editable caller as document text where the shared helper does not.
What happens: $isDocumentText (firstChapter.utils.ts:131) hand-lists $isMarkerNode, $isImmutableUnmatchedNode, $isAttributeDisplayRun and an AttributeRunNode ancestor. $isDisplayAnnotationCarrier (libs/shared/src/nodes/features/displayAnnotations.utils.ts:81, exported from shared) already covers all of those; the AttributeRunNode-ancestor arm is redundant, since a run's children are markers and attribute-tagged text. The one difference is a note's editable caller, which the shared helper excludes via $isElementOwnerRunAnchor and $isDocumentText counts as text.
Why it matters: mostly maintenance: each new kind of display text has to be added to every copy, the drift docs/standard-view-invariants.md section II warns about. The caller difference affects only a note whose caller is its only text. With the swap, all 111 tests in chapterLineEditing.test.tsx still pass.
Fix: In $isDocumentText (firstChapter.utils.ts:131), replace the $isMarkerNode, $isImmutableUnmatchedNode, $isAttributeDisplayRun and $findMatchingParent(node, $isAttributeRunNode) checks with !$isDisplayAnnotationCarrier(node) (imported from shared), keeping $isTextNode(node) and the zero-width-space-and-trim() test. Remove the imports that become unused ($findMatchingParent, $isAttributeRunNode, $isMarkerNode, $isImmutableUnmatchedNode, $isAttributeDisplayRun). This stops a note's editable caller from counting as chapter text, so update the PR's description of that edge case to match, and add a case to chapterLineEditing.test.tsx that pins the new behavior for a note whose only text is its caller.
How this was checked: $isDocumentText (firstChapter.utils.ts:131-140, added by this PR) does keep a hand-written copy of the exclusions that $isDisplayAnnotationCarrier (libs/shared/src/nodes/features/displayAnnotations.utils.ts:81-94, exported through shared) already holds. But the two listed gaps change no behavior. Verse glyphs: $holdsChapterContent (firstChapter.utils.ts:148) already returns true on $isSomeVerseNode before $isDocumentText is consulted, so a verse counted as text there is harmless. AttributeRunNode ancestor: its children are marker glyphs and the attribute-tagged value text (AttributeRunNode.ts:10-12), which the carrier already excludes through $isMarkerNode and $isAttributeDisplayRun, so that arm is redundant rather than missing. The one real difference is a note's editable caller, which the carrier excludes and $isDocumentText counts; that affects only a note whose caller is its only text. The swap was run: with the carrier in place of the four exclusions, chapterLineEditing.test.tsx passes (111/111) and eslint is clean on the file. The remaining value is maintenance only.
Other findings in this file: #1, #3, #5, #6, #7
packages/platform/src/editor/markerEdit/firstChapter.utils.ts line 138 at r1 (raw file):
!$isAttributeDisplayRun(node) && !$findMatchingParent(node, $isAttributeRunNode) && node.getTextContent().replaceAll(ZWSP, "").trim() !== ""
#5 - low · checked and confirmed
A paragraph holding only no-break spaces gets verses inserted above it in Formatted and Paragraph-structure view but none in Standard view.
What happens: Standard view shows each no-break space as the text ~. At firstChapter.utils.ts:138, "~~".trim() is not empty, so $isDocumentText counts it and $insertFirstChapter adds no verses, saving [BOOK, c1, {para p: [NBSP NBSP]}]. In Formatted and Paragraph-structure view the text node holds real no-break spaces, which trim() removes, so the save is [BOOK, c1, v1, v2, {para p: [NBSP NBSP]}]. A paragraph of exactly one no-break space differs the same way, though in those two views that lone no-break space is already dropped on every save, by the exact-NBSP check at editor-usj.adaptor.ts:834, whether or not a chapter is inserted.
Why it matters: the result of inserting chapter 1 depends on which view is open; the input, a paragraph of nothing but no-break spaces, is rare.
Fix: Make $isDocumentText (firstChapter.utils.ts:131) and its caller $holdsChapterContent give the same answer in every view: where the markers show, remove ~ (Standard view's display of a no-break space) along with ZWSP before the trim() at :138, so a paragraph of only no-break spaces counts as empty in all three. Thread the viewOptions that $insertFirstChapter already receives down to $isDocumentText (it currently takes only the node) so the ~ strip applies only where ~ displays a no-break space. Add a test next to the existing $insertFirstChapter tests that runs a paragraph of two no-break spaces in Standard and Formatted view and asserts the same verses are inserted (use two: a lone one is dropped on save in Formatted view), and add an entry under Unreleased in packages/platform/CHANGELOG.md.
How this was checked: Read firstChapter.utils.ts:130-140: $isDocumentText ends with node.getTextContent().replaceAll(ZWSP, "").trim() !== "", and git blame shows line 138 was added by this PR (ceb1755). In Standard view a data no-break space is displayed as the text ~ (editor-usj.adaptor.ts:317 "An NBSP is data (~)", :832 "displayed as ~, never as a bare NBSP node"), and "~".trim() is non-empty, so $holdsChapterContent returns true and no verses are inserted. In Formatted view the text node holds U+00A0, which String.prototype.trim removes, so the paragraph is not counted and verses are inserted above it. The view-dependent result follows directly from the code; I did not run the editor.
Re-checked by running it: a paragraph of two no-break spaces saves with no verses in Standard view and with v1 and v2 above it in Formatted and Paragraph-structure view, and the two no-break spaces survive the save in all three; a lone no-break space is dropped on save in Formatted and Paragraph-structure view even with no chapter inserted (editor-usj.adaptor.ts:834).
Other findings in this file: #1, #3, #4, #6, #7
packages/platform/src/editor/markerEdit/firstChapter.utils.ts line 147 at r1 (raw file):
* Any text counts, a section heading or a remark included. */ function $holdsChapterContent(start: LexicalNode): boolean {
#1 - medium · checked and confirmed
In every view, inserting chapter 1 with verses over content that is only a caption-less figure, a milestone or an empty footnote still puts the verses above it, leaving that content in the last verse.
What happens: $holdsChapterContent (firstChapter.utils.ts:147) returns true only for a verse or a node that passes $isDocumentText (:131), which requires a non-marker text node. A figure with no caption (\p \fig |src="a.jpg"\fig*) has no text node, and a \ts\* milestone and an empty \f + \f* footnote carry only marker glyphs. So versesToAdd (:184) stays at verseCount, and insertFirstChapter(2) saves [BOOK, c1, v1, v2, {para p: [item]}] for each. A captioned figure, or a footnote with text in it, is handled correctly.
Why it matters: this is the failure the change exists to prevent, left open for books whose only chapter content is such an item. The empty footnote fails in Standard view too, so it is not the caller-text edge case the description sets aside. The input is rare.
Fix: In $holdsChapterContent (firstChapter.utils.ts:147), also return true for a note node, a milestone node and a figure node, using the node guards exported from shared; keep returning false for a paragraph's own marker glyph ($isMarkerNode text), a caret's zero-width space and the attribute display text, so an empty \p still gets verses above it (the existing "adds verses above an empty paragraph" test). Add figure-without-caption, milestone and empty-footnote cases to the "over content already in the chapter" block in chapterLineEditing.test.tsx, each expecting [BOOK, CHAPTER_1, para], and add an entry under Unreleased in packages/platform/CHANGELOG.md if the published behavior changes.
How this was checked: Ran a probe that loads [id, {para p: [item]}] and calls insertFirstChapter(2) in Standard, Formatted and Paragraph-structure views. A figure without a caption, a \ts\* milestone and an empty \f + \f* footnote each save as [id, c1, v1, v2, {para p: [item]}] in all three views, so the item lands in the last verse (firstChapter.utils.ts:147-152 returns false because $isDocumentText at :131 needs a non-marker text node; :184-187 then keeps versesToAdd at verseCount). A figure with a caption, and a footnote with text inside, are handled correctly (no verses added). The empty-footnote case is not limited to the disclosed Standard-only caller-text edge: it fails in Standard view too, so it is a real gap rather than the disclosed one. The anchor lines 127-152 are new in this PR.
Other findings in this file: #3, #4, #5, #6, #7
#6 - low · checked and confirmed
$holdsChapterContent builds a full array of each block's subtree before checking it, even though it stops at the first match.
What happens: $holdsChapterContent (firstChapter.utils.ts:147) walks siblings with getNextSibling() and calls $dfs(block) on each; $dfs materializes the whole subtree as an array before the early return true can run. $dfsIterator walks lazily, and libs/shared-react/src/nodes/usj/note-index.utils.ts:19 uses it for that reason.
Why it matters: efficiency and readability only; it runs once per chapter insertion on a document with no chapters yet.
Fix: replace both loops in $holdsChapterContent with one for (const { node } of $dfsIterator(start, $getRoot().getLastDescendant() ?? start)).
How this was checked: $dfs in the installed Lexical utils package is Array.from($dfsIterator(startNode, endNode)) (LexicalUtils.dev.js:449-451), so $holdsChapterContent (firstChapter.utils.ts:147-152) materializes each block's whole subtree before its return true can run. The function does not exist at the merge base, so the code is new in this PR. $getNoteIndex already uses the lazy iterator for this reason (note-index.utils.ts:19-26). $findChapterContentStart returns a root child, so walking from it to the root's last descendant covers the same nodes in the same order as the two loops: its own subtree, then every later sibling's subtree. $dfsIterator includes the end node (LexicalUtils.dev.js:488-516). The cost is small and bounded because it runs once per chapter insertion into a document that has no chapters yet.
Other findings in this file: #1, #3, #4, #5, #7
packages/platform/src/editor/markerEdit/firstChapter.utils.ts line 184 at r1 (raw file):
const chapterContentStart = $findChapterContentStart(styleInfo); const versesToAdd =
#7 - low · checked and confirmed
A book whose chapter content is only a section heading gets chapter 1 with no verses, even when the caller asks for verses.
What happens: for [BOOK, {para s1: ["The Creation"]}], $findChapterContentStart places \c 1 before the \s1. $holdsChapterContent counts the heading's text, so versesToAdd at firstChapter.utils.ts:184 is 0 and the save is [BOOK, c1, {para s1}].
Why it matters: this is a documented choice (the $holdsChapterContent TSDoc says "a section heading or a remark included", and EditorRef.insertFirstChapter in editor.model.ts says a \s1 already belongs to the chapter), but no test in the "over content already in the chapter" block pins it, so it can change unnoticed. Someone who typed a heading first has to add every verse by hand.
Fix: Keep the documented behavior and pin it: add a case to the "over content already in the chapter" block in chapterLineEditing.test.tsx that calls insertWithVerses([BOOK, { type: "para", marker: "s1", content: ["The Creation"] }]) and expects [BOOK, CHAPTER_1, heading] with no verses. If heading-only books should get verses instead, the change must not put verses above the heading, and it would also have to update the TSDoc in firstChapter.utils.ts and EditorRef.insertFirstChapter in editor.model.ts, regenerate the dist and API report with nx extract-api platform-editor, and add an Unreleased entry to packages/platform/CHANGELOG.md.
How this was checked: The behavior is real: $findChapterContentStart (firstChapter.utils.ts:111) returns the \s1 paragraph as chapter content start, $holdsChapterContent (:146) counts any document text including a heading, so versesToAdd is 0 at :182-185 and the heading-only book saves as [BOOK, c1, s1]. It is deliberate and documented, not an accident: the TSDoc at firstChapter.utils.ts:145 ("a section heading or a remark included") and EditorRef.insertFirstChapter at editor.model.ts:677 ("a section heading such as \s1 already belongs to the chapter") both say it. The remaining gap is that no test in chapterLineEditing.test.tsx (the "over content already in the chapter" block, :1243-1330) covers a heading-only book, so the documented choice is unpinned. The consequence is small: a user with only a heading must add the verses by hand.
Other findings in this file: #1, #3, #4, #5, #6
packages/platform/src/editor/markerEdit/chapterLineEditing.test.tsx line 1287 at r1 (raw file):
}); it("adds verses above a paragraph holding only whitespace and a caret's zero-width space", async () => {
#2 - low · checked and confirmed
The whitespace-and-zero-width-space test still passes if the paragraph below the inserted verses is dropped or moved.
What happens: the test at chapterLineEditing.test.tsx:1287 compares only .slice(0, 4) of the saved content against [BOOK, CHAPTER_1, V1, V2]. The saved content is [BOOK, c1, v1, v2, {para p: ["\u200B "]}], so nothing checks that the paragraph survives or stays after the verses. The name also says "a caret's zero-width space", but here the zero-width space comes from the loaded USJ, not from a caret.
Why it matters: test only, with no behavior effect; a regression that drops or reorders the paragraph would go unnoticed.
Fix: In chapterLineEditing.test.tsx (the test at :1287), replace the .slice(0, 4) comparison with a full toEqual of the saved content ending in the normalized paragraph: [BOOK, CHAPTER_1, V1, V2, { type: "para", marker: "p", content: [${ZWSP} ] }] (loading collapses the ${ZWSP} text to ${ZWSP} ). Delete the comment at :1290 and rename the test to describe a paragraph whose loaded text holds only whitespace and a zero-width space.
How this was checked: The test (chapterLineEditing.test.tsx:1287-1297, added by this PR) compares only slice(0, 4) of the saved content. I ran it in a scratch worktree and logged the full result: [book, c1, v1, v2, {type:"para", marker:"p", content:["\u200B "]}]. The normalized paragraph is deterministic, so the comment at :1290 does not justify skipping it; a regression that drops or reorders the paragraph would still pass. The anchor is on a line this PR added. Test-only impact.
Review of the first-chapter insert found content it missed: a figure with no caption, a milestone or an empty footnote holds no text, so verses still went above it. Those now count, along with any block the editor keeps whole. A paragraph of no-break spaces counts as whitespace in Standard view too, where each one shows as `~`, so every view gives the same answer. Also: use the shared `$isDisplayAnnotationCarrier` instead of a local list of display-only text, walk the tree lazily with `$dfsIterator`, pin the heading-only case, and compare the whole document in the whitespace test. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Thanks, Ira. All 7 are fixed in c28e074, with the
I checked that removing any one content check (verse, note, milestone, figure, display glyphs, (AI-assisted) |
`MarkerObject` doesn't declare a figure's `file`, so the inline literal failed the test typecheck in CI. Build the figure in a variable first. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
irahopkinson
left a comment
There was a problem hiding this comment.
Thanks, all 7 check out. At 27ea01a, chapterLineEditing.test.tsx passes (124/124) and lint is clean on the changed files. Resolving the threads.
@irahopkinson+AI made 1 comment and resolved 6 discussions.
Reviewable status: 0 of 7 files reviewed, all discussions resolved.
irahopkinson
left a comment
There was a problem hiding this comment.
thanks so much for all your work
@irahopkinson made 1 comment.
Reviewable status: 0 of 7 files reviewed, all discussions resolved (waiting on irahopkinson+AI).
|
|
||
| const chapterContentStart = $findChapterContentStart(styleInfo); | ||
| for (const node of nodes) { | ||
| if (chapterContentStart) chapterContentStart.insertBefore(node); |
There was a problem hiding this comment.
Follow-up (this has been the behavior since #35): when chapter content starts with an empty paragraph, the verses go in before it, outside any paragraph, and the empty paragraph ends up after the last verse. "adds verses above an empty paragraph" and "adds verses below a titled front matter" both pin this (BOOK, title, CHAPTER_1, V1, V2, empty).
The easy way to get there is to type a title and press Enter, which leaves \id, \mt1 Genesis, \p (empty). "Add chapter number" then produces \c 1 \v 1 … \v 31 \p. In Simple mode the user then types into verses that belong to no paragraph, and their \p hangs after \v 31. Under the default personal lock they can't repair the structure. It's the same "existing content lands after the last verse" problem this PR fixes for text.
Suggestion: when the chapter content starts with an empty paragraph, put the verses inside that paragraph instead of before it, so the result is \c 1 \p \v 1 … \v 31.
| }); | ||
|
|
||
| // Only the chapter content counts: text in the front matter above it does not. | ||
| it("adds verses below a titled front matter", async () => { |
There was a problem hiding this comment.
Follow-up: moving this decision into the editor dropped the host test that pinned verses still being added below a full front matter with intro text (\h, \toc1, \mt1, \is1 Introduction, \ip <text> → verses). Here the only front matter is a lone \mt1. If chapter content were ever found to start at \is1 or \ip, say through a stylesheet change or a $findChapterContentStart regression, $holdsChapterContent would see the intro text, and every book with an introduction would silently get \c 1 with no verses. No test would fail. Could you add that case here?
A book Paratext creates holds `\h` and `\toc` lines under its `\id` line. Adds `insertFirstChapter` cases for that shape, with an `\id` text full of special characters, in Standard view and the paragraph-structure view that Simple mode's "Add chapter number" button uses: chapter 1 and its verses go below the header lines, and the `\id` line stays the book's only one. Test-only; the behavior came with PT-4614 (#35, #37). Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Summary
EditorRef.insertFirstChapter(verseCount)now leaves the verses out when the chapter content already holds text or a verse. Before, it put them above that content, so a book typed or imported without chapter markers got all its text in the last verse.Follow-up to #35, from review of the paranext-core half (#2948). The host used to make this call itself, from saved USJ with its own list of front-matter markers, and that list could disagree with where the stylesheet starts chapter content. For
\mt1,\b,\ip Intro, the chapter starts at\b(it needs a chapter), the host counted\ipas front matter, and the introduction landed after the last verse. Only the editor knows where chapter content starts, so it now decides both.Where to look
packages/platform/src/editor/markerEdit/firstChapter.utils.ts:$isDocumentText,$holdsChapterContent, and theversesToAddline in$insertFirstChapter.packages/platform/src/editor/markerEdit/chapterLineEditing.test.tsx: the new "over content already in the chapter" block, plus one hidden-markers case.editor.model.tsdoc and the CHANGELOG's Unreleased entry forinsertFirstChapter.distrebuild.Details
\c 1goes to the end of the document: text, a verse, a note, a milestone, or a figure, table or other block the editor keeps whole. A section heading or aemcounts too, since anything there already belongs to chapter 1.$isDisplayAnnotationCarrier), whitespace, a zero-width space, and no-break spaces, including Standard view's~. So an empty paragraph still gets its verses, and the result is the same in every view mode.\menu and the\cmarker action) skip the scan.AI Involvement
Written with Claude Code (Claude Opus 5.5) and reviewed by a separate adversarial review pass, whose findings were fixed before opening. The author chose to move this decision into the editor. Commits carry
Co-Authored-Bytrailers.Testing
chapterLineEditing.test.tsx: 124 passed, including new cases for text, text past the start block (the\b/\ipexample), an existing verse, an empty paragraph, whitespace and a zero-width space only, titled front matter, and text in a hidden-markers view, a heading only, and, in all three views, an uncaptioned figure, a milestone, an empty footnote and a paragraph of no-break spaces. Mutation-checked: removing any one content check (verse, note, milestone, figure, display glyphs, Standard view's~) turns tests red.tscon the package's lib config.packages/platformsuite runs in CI.Risk Level
Low. Only
insertFirstChapterwith a verse count changes, and only where the chapter content already holds something.🤖 Generated with Claude Code
This change is