Skip to content

PT-4965: Put chapter 1's verses in a paragraph - #40

Merged
katherinejensen00 merged 5 commits into
mainfrom
pt-4965-verses-in-empty-paragraph
Nov 13, 2026
Merged

katherinejensen00 merged 5 commits into
mainfrom
pt-4965-verses-in-empty-paragraph

Conversation

@katherinejensen00

@katherinejensen00 katherinejensen00 commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

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:

  • A book that is all front matter gets them in a new \p: \id … \c 1 \p \v 1 … \v N. Every new book in Simple mode is like this.
  • An empty paragraph of verse text after the front matter (\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 \p left by typing a title and pressing Enter. Simple mode never produces one:

  • A new book holds only \id, plus \h/\toc* lines.
  • Simple mode shows only the "Add chapter number" button until chapter 1 exists.
  • Enter there gives the new paragraph the current paragraph's marker.

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

  • An empty \s1, \ms, \r, \d or \b as the first block still gets the verses above it, outside a paragraph, as the ticket specified. Wrapping them in a \p would put them above the heading. Putting them after it (\c 1 \s1 \p \v 1) is a design call I left out.
  • \d and \b are excluded by name. The stylesheet declares \d the same way as \p. A stylesheet that lets \v go 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:
    • canHoldVerses and $removeBlankText.
    • In $insertFirstChapter, versePara and the new \p for an all-front-matter book.
  • markerValidation.utils.ts: occursUnderAllows now holds the validator's "empty occursUnder allows 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 $createCaretHostNode for a test.
  • The EditorRef.insertFirstChapter doc and the CHANGELOG's Unreleased entry. That entry is amended rather than added to, since the method hasn't been published yet.
  • The second commit is the dist rebuild.

Details

  • What the reused paragraph keeps: its marker, its attributes, the separator after its marker in Standard view, no-break spaces, a zero-width space from the file, and non-text content such as an empty character style. Plain spaces and a caret's own zero-width space are removed, since they would sit before verse 1.
  • The paragraph is kept, not rebuilt. One undo restores it.
  • The caret follows the existing rule: in Standard view, the end of the chapter line; where markers are hidden, after verse 1, now inside the paragraph. Verse 1 is found by node type, because a view without spacing puts a line break before each verse.
  • Known gap, not addressed: if the empty paragraph's marker has been retyped (e.g. \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 carry Co-Authored-By trailers.

Testing

  • chapterLineEditing.test.tsx: 162 passed. New or changed cases:
    • the new-book header lines (\id, \h, \toc1) in all three views, the \id-only book, and the introduction book
    • empty \p and \q1, and only the first of two empty paragraphs taking the verses
    • kept content: no-break spaces, an empty \nd, a zero-width space from the file
    • headings and \b in all three views, including \b under a stylesheet that allows \v anywhere
    • custom-stylesheet cases, an unsettled \p→\q1 edit, and the \ menu leaving an empty \p alone
    • one-step undo, the caret at the exact end of the chapter line, typing after verse 1 in hidden-marker views, and separator and caret-host handling within the insertion's own update
  • Full packages/platform suite: 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-react suite: 2291 passed.
  • typecheck and lint for both projects; the only warnings were already there.

Risk Level

Low. Only insertFirstChapter with a verse count changes. The \ menu's \c and insertMarker("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; move platform-yalc after merge.

🤖 Generated with Claude Code


This change is Reviewable

@jolierabideau jolierabideau left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

  1. Over-long doc line — firstChapter.utils.ts:217 is 131 chars; the rest of the block wraps at 100 and Prettier won't reflow comments. Similarly, the CHANGELOG entry's last line ("Returns false, …") was left as a short unreflowed line.
  2. occursUnderAllows has a third copy — markerMenu/markerItemSource.ts:210-211 still inlines the same occursUnder.length === 0 || includes(...) check. Worth switching it over too (or a follow-up). The helper's doc ("a char or verse marker … under contextMarker") could also mention it's now used outside validation.
  3. Empty ImpliedParaNode as chapter content start — $findChapterContentStart returns a block with no tag marker (e.g. an implied para) as the content start. versePara requires $isParaNode, and the new-\p branch 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".
  4. Unsettled heading retype — you already call this out as a known gap. Just to make the consequence explicit: \p retyped to \s1 but unsettled → verses are appended, then the paragraph settles as \s1 holding \v 1 …. Fine to defer, but maybe worth a follow-up ticket so it covers both checks as you suggested.
  5. 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. $removeBlankText could also take ParaNode instead of ElementNode (it's only ever passed one, and drops an import).
  6. Test coverage gaps (breadth only):
    • No \li1 or \m case, though \li1 is named in the EditorRef doc.
    • The negative stylesheet branch of canHoldVerses isn't tested (a verse-text paragraph that \v's occursUnder excludes, or a sheet with no \v).
    • The Standard-view caret isn't asserted on the new-\p path (same selectEnd() code, so low risk).
    • \q1, first-of-two, undo, unsettled-edit and custom-stylesheet cases run in Standard view only.
  7. Test-only export from shared-react — $createCaretHostNode is exported from the barrel just for the platform test. Acceptable since shared-react is 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).

@katherinejensen00

katherinejensen00 commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor Author

Replies to the review, addressed in eb1f122 (source) and 512a672 (dist rebuild):

  1. Long lines: fixed. Rewrapped the TSDoc and the CHANGELOG line.
  2. occursUnderAllows third copy: fixed. The marker menu's character list now uses occursUnderAllows, and the helper's doc covers both callers and the note context. The in-note list is unchanged on purpose: PT9 requires the note marker to be listed there, so an empty occursUnder doesn't qualify.
  3. Empty implied paragraph: this one is reachable. An empty document (content: []) loads as one empty implied paragraph, and stray whitespace after \id loads as one holding it. Both gave \c 1 \v 1 \v 2 outside any paragraph in all three views. Now a new \p takes its place. Spaces are dropped and anything else, such as no-break spaces, stays ahead of verse 1, the same as for a reused \p. Covered in all views, plus the hidden-markers caret.
  4. Unsettled marker edit: agreed, deferring to a follow-up that covers both checks: PT-5070.
  5. Two "blank" definitions: fixed. Added SPACES_ONLY with a note on why it is narrower than $isDocumentText. $removeBlankText now takes ParaNode | ImpliedParaNode, since item 3 passes it the implied paragraph too.
  6. Test coverage: added \m/\li1, the stylesheet cases that refuse the verses (\v kept out of \p, no \v), and the Standard-view caret when the verses get a new \p. \q1, first-of-two, undo and custom-stylesheet now run in all three views. The unsettled-edit test stays Standard-only, since only Standard view has that kind of edit.
  7. Test-only export: kept, as shared-react is private with no API report.

Testing: chapterLineEditing.test.tsx 196 passed (was 162). Full packages/platform suite 4264 passed; the one failure was the same blockVersePositions timeout under load noted in the description, and it passes on its own. typecheck and lint pass.

katherinejensen00 and others added 4 commits November 13, 2026 13:15
"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>
@katherinejensen00
katherinejensen00 force-pushed the pt-4965-verses-in-empty-paragraph branch from 512a672 to 6d0e90b Compare November 13, 2026 22:04
@katherinejensen00
katherinejensen00 merged commit 3e9b614 into main Nov 13, 2026
5 checks passed
@katherinejensen00
katherinejensen00 deleted the pt-4965-verses-in-empty-paragraph branch November 13, 2026 23:35
tjcouch-sil added a commit that referenced this pull request Nov 17, 2026
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants