Skip to content

fix(documents): tighten heading spacing and stop blank lines in appended blocks - #955

Open
ilyabo wants to merge 3 commits into
mainfrom
fix/document-heading-margins
Open

ilyabo wants to merge 3 commits into
mainfrom
fix/document-heading-margins

Conversation

@ilyabo

@ilyabo ilyabo commented Oct 21, 2026 •

Copy link
Copy Markdown
Collaborator

Two fixes for uneven spacing in block documents, most visible in AI-built ones.

1. Headings had no more space above than below

Headings used equal top/bottom margins (my-2 / my-3) smaller than the margins on paragraphs (~16px in prose-sm) and embedded blocks (my-4). Because vertical margins collapse, the neighbours set the spacing on both sides of a heading.

Case (px, above → below) Before After
paragraph → h1 → paragraph 16 → 16 32 → 16
list → h2 → list 8 → 8 28 → 8
paragraph → h2 → chart 16 → 16 28 → 16
paragraph → h2/h3 → paragraph 16 → 8 28 / 20 → 8

BLOCK_DOCUMENT_CONTENT_CLASS_NAME now uses larger top margins (h1 mt-8, h2 mt-7, h3 mt-5) and small bottom margins (mb-3 / mb-2).

2. Appended blocks landed after an empty paragraph

Tiptap's StarterKit enables TrailingNode, which adds an empty paragraph whenever the document ends with a heading, list or embed. The editor persists that paragraph to the store, and appendBlocks then inserted new blocks after it. An agent that appends a heading and then a paragraph produced heading, empty paragraph, paragraph: a visible blank line after headings and before lists.

appendBlocks now inserts before a trailing empty paragraph. This also fixes documents that already have one stored. insertBlocks with an explicit index is unchanged.

Testing

  • @sqlrooms/documents tests pass (163), including a new test for appending before the trailing empty paragraph.
  • Heading gaps measured in a static page with the same Tailwind classes; the append fix is covered by the unit test, not yet re-checked in a running app.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Style
    • Improved heading spacing in block documents, with separate top and bottom margins for clearer content hierarchy.
  • Bug Fixes
    • Appended blocks now appear before the editor’s trailing empty paragraph, preserving the expected document order.

Headings used equal top and bottom margins (my-2/my-3) that were smaller
than the margins on paragraphs and embedded blocks, so margin collapsing
left as much space after a heading as before it (or more after lists).
Use larger top margins and small bottom margins so headings group with
the content they introduce.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 21, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review 🔄 Running since 2026-10-21T13:46:04.290392Z 3185595 New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@coderabbitai

coderabbitai Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 23 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 4 included reviews currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration
  • Configuration used: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 1b91b8cf-dced-4910-bd8a-b749d6a26bdb
📥 Commits

Reviewing files that changed from the base of the PR and between 2eddab1 and 3185595.

📒 Files selected for processing: 3
  • packages/documents/__tests__/restoreTextSelection.test.ts
  • packages/documents/src/BlockDocumentEditor/BlockDocumentEditorRoot.tsx
  • packages/documents/src/BlockDocumentEditor/restoreTextSelection.ts

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Configuration used: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: df216085-ec6a-40cf-aa56-0c391bb2d5f8
📥 Commits

Reviewing files that changed from the base of the PR and between 777f7a2 and 2eddab1.

📒 Files selected for processing: 2
  • packages/documents/__tests__/BlockDocumentsSlice.test.ts
  • packages/documents/src/BlockDocumentsSlice.ts

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 1 remain after this review.

📝 Walkthrough

Changes

Document updates

Layer / File(s) Summary
Set heading margins
packages/documents/src/BlockDocumentEditor/blockDocumentLayout.ts
H1, H2, and H3 now use separate top and bottom margin utilities. Comments describe the spacing rules.
Insert blocks before trailing paragraphs
packages/documents/src/BlockDocumentsSlice.ts, packages/documents/__tests__/BlockDocumentsSlice.test.ts
appendBlocks inserts new blocks before a persisted trailing empty paragraph. Missing documents retain end insertion behavior. A regression test verifies the resulting order.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix

Suggested reviewers: dmitriy-kostianetskiy

Merge Risk: ⚪ Minimal · up to 2edda

The reviewed changes preserve heading spacing and append ordering without an established merge-blocking risk.

Pre-merge checks: Passed 4 · Failed 1

Failed Failed checks: 1 warning

Check name Status Explanation Resolution
Docstring Coverage Warning Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 3 files. Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed Passed checks: 4 passed
Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title clearly summarizes both main changes: tighter heading spacing and corrected insertion of appended blocks before the trailing blank paragraph.
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches: 💡 1
📝 Generate docstrings: 💡
  • Commit to this branch
  • Create a new PR
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

…graph

Tiptap's TrailingNode adds an empty paragraph after a trailing heading,
list or embed, and the editor persists it. appendBlocks then inserted new
blocks after it, so AI-built documents got a blank line after headings
and before lists. Insert before a trailing empty paragraph instead.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@ilyabo ilyabo changed the title fix(documents): give headings more space above than below fix(documents): tighten heading spacing and stop blank lines in appended blocks Oct 21, 2026

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2eddab1f27

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

get().blockDocuments.insertBlocks(
artifactId,
Number.POSITIVE_INFINITY,
content ? appendIndex(content) : Number.POSITIVE_INFINITY,

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Preserve the active trailing paragraph’s cursor

When a user is typing in the editor-created trailing empty paragraph and an external appendBlocks call arrives (for example, an AI append), this inserts before that focused paragraph and shifts it right. BlockDocumentEditorRoot restores focused text selections by their previous numeric offsets rather than by block ID, so the caret is restored into the newly inserted block or its boundary instead of the empty paragraph; before this change that paragraph remained at its original offset. Map or preserve the trailing paragraph's selection when moving it so external appends do not disrupt active typing.

Useful? React with 👍 / 👎.

When the store replaces editor content, a focused text selection was
restored by numeric offset. An append that lands before the trailing
empty paragraph shifts that paragraph, so a user typing there had the
caret moved into the new block. Restore the selection relative to its
top-level block, found by block ID, and fall back to offsets otherwise.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

This branch has not been deployed

No deployments
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.

1 participant