Skip to content

fix(xl-typst-exporter): keep headings with the block that follows them - #3365

Merged
nperez0111 merged 1 commit into
TypeCellOS:mainfrom
notluquis:fix/typst-heading-sticky
Nov 18, 2026
Merged

nperez0111 merged 1 commit into
TypeCellOS:mainfrom
notluquis:fix/typst-heading-sticky

Conversation

@notluquis

@notluquis notluquis commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Summary

In the Typst PDF export, make the spacing block that wraps a heading sticky, so a heading is never left alone at the bottom of a page. Closes #3364.

Rationale

wrapBlock → applyBlockProps wraps every block in #block(width: 100%, inset: …) for its spacing. Typst keeps a heading with the next block (heading is sticky by default) only while the heading is a direct child of the flow; inside the wrapper it isn't, so the wrapper can end a page on its own. Marking the wrapper sticky: true restores Typst's own behavior one level up.

Measured with the default schema, mappings and options (A4), sweeping the number of short paragraphs before the heading:

Heading level Positions tried Orphaned before Orphaned after
1 51 1 0
2 41 2 0
3 41 2 0

At every other position the per-page text is identical before and after.

Changes

  • wrapBlock passes sticky: true to applyBlockProps for headings, on both paths: a heading without children, and a heading's own body when it has children.
  • applyBlockProps emits sticky: true on the wrapper block when asked.
  • The fill-only wrapBackground block of a heading with children stays non-sticky: the sticky block is the heading's own body inside it.

Impact

Only heading wrappers change (sticky: true is added); no other block type, spacing or alignment changes. A heading now moves to the next page with the block that follows it, which can shift that one heading to the next page. Alignment wraps the sticky block from outside (#align(center)[#block(sticky: true, …)]); a raw Typst check confirmed a centered heading also stays with its content.

Testing

  • New test "keeps every heading with the block that follows it": a plain heading, a heading with children, one with a background and one with both, each in exactly one sticky wrapper, and no other block sticky. With the fix reverted it fails (as do the snapshot and the alignment test).
  • testDocument.typ snapshot: 9 lines, all heading wrappers.
  • The existing alignment test's expected string now includes sticky: true, .
  • pnpm test in packages/xl-typst-exporter: 14 pass, 1 fails both with and without this change ("spans merged table cells and emits a single multi-row header"), because it needs the built @blocknote/xl-typst-compiler wasm.
  • pnpm lint reports the same 35 errors before and after (unresolved imports from workspace packages that weren't built locally); vp fmt --check passes.
  • Manual: the repro in Typst PDF export: a heading can be left alone at the bottom of a page #3364 compiled to PDF with Typst 0.15.1 (@blocknote/xl-typst-compiler 0.57.0) before and after; see the screenshot.

Screenshots/Video

Before and after

Left: 0.57.0. Right: with this change.

Checklist

  • Code follows the project's coding standards.
  • Unit tests covering the new feature have been added.
  • All existing tests pass. (One existing test needs the built wasm, which wasn't available locally; it fails the same way on main.)
  • The documentation has been updated to reflect the new feature (no user-facing API change)

Additional Notes

Found while exporting clinical documents with @blocknote/xl-pdf-exporter; the app currently works around it by rewriting the generated source, which this change makes unnecessary.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Improvements
    • Typst exports now keep headings together with the following block, including headings with or without child content. This helps prevent headings from appearing separately from the content that follows.
    • Paragraphs remain unaffected, and nested content retains its existing alignment behavior.

Typst headings are sticky, but stickiness doesn't carry out of the block
the exporter wraps every block in for its spacing, so a heading could be
left alone at the bottom of a page. Make the wrapper block of a heading
sticky, including headings with children or a background.
@vercel

vercel Bot commented Nov 18, 2026

Copy link
Copy Markdown

@notluquis is attempting to deploy a commit to the TypeCell Team on Vercel.

A member of the Team first needs to authorize it.

@coderabbitai

coderabbitai Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The Typst exporter now marks heading wrappers as sticky, including headings with children. Tests cover four heading variants and confirm that paragraphs are not wrapped as sticky.

Changes: Sticky Typst headings

Layer / File(s) Summary
Add sticky heading wrappers
packages/xl-typst-exporter/src/typstExporter.ts, packages/xl-typst-exporter/src/typstExporter.test.ts
applyBlockProps accepts a sticky option and emits it on the Typst block. wrapBlock enables the option for headings. Tests check plain, nested, filled, and filled-with-children headings, and verify that paragraphs are not sticky-wrapped.

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

Change: Bug fix · Severity of issue fixed: Low

Suggested reviewers: yousefed, nperez0111

Merge Risk: Minimal · up to 4bc5a

Headings in Typst PDF export now stay with the block that follows them, so a heading is no longer left alone at the bottom of a page. Other blocks are unaffected, and the change is small and easy to revert. No merge-blocking risk was identified.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title names the affected package and the main change: headings are kept with the block that follows them. The raw summary confirms that heading wrappers in wrapBlock and applyBlockProps are now st…
Description check Passed The description follows the template's main sections: Summary, Rationale, Changes, Impact, Testing, Screenshots/Video, Checklist, and Additional Notes. It explains the cause (the wrapper hides the hea…
Linked Issues check Passed [#3364] The issue asks that a heading move to the next page with the block that follows it. The cause is the non-sticky spacing wrapper that wrapBlock → applyBlockProps emits around headings. The …
Out of Scope Changes check Passed The changes stay within the heading wrapper behavior described in #3364. Code changes are in typstExporter.ts: the sticky option for applyBlockProps and the heading branch in wrapBlock. The te…
Full details: Title check

Explanation

The title names the affected package and the main change: headings are kept with the block that follows them. The raw summary confirms that heading wrappers in wrapBlock and applyBlockProps are now sticky, so the title matches the changeset.

Full details: Description check

Explanation

The description follows the template's main sections: Summary, Rationale, Changes, Impact, Testing, Screenshots/Video, Checklist, and Additional Notes. It explains the cause (the wrapper hides the heading from Typst's sticky flow), gives measured before and after results, lists the changes and the test plan, and links the issue. The Summary section is brief but adequate. Two checklist items remain unchecked, and the author discloses that one existing test fails without the built wasm. The description does not state that the docs were updated, and it does not need to, since the author notes there is no user-facing API change.

Full details: Linked Issues check

Explanation

[#3364] The issue asks that a heading move to the next page with the block that follows it. The cause is the non-sticky spacing wrapper that wrapBlock → applyBlockProps emits around headings. The change summary shows TypstExporter.wrapBlock now passes sticky for heading blocks on both paths: headings without children, and the own-body wrapper of headings with children. applyBlockProps accepts a sticky option and emits sticky: true on the generated Typst block. The new test "keeps every heading with the block that follows it" covers plain headings, headings with children, headings with a background, and headings with both, and checks that no other block is sticky. The issue's reproduction scope (default schema, mappings, A4) is the case the PR measures. The PR description reports orphaned-heading counts going from 1 or 2 to 0 across the sweep. I did not run the tests or the Typst compile myself. The conclusion rests on the change summary and the PR description's measurements.

Full details: Out of Scope Changes check

Explanation

The changes stay within the heading wrapper behavior described in #3364. Code changes are in typstExporter.ts: the sticky option for applyBlockProps and the heading branch in wrapBlock. The test file adds the heading stickiness test and updates the alignment test expectation to include sticky: true. That expectation change follows from the heading wrapper change, because the alignment wrapper wraps the sticky block. The testDocument.typ snapshot update is also heading-only, per the PR description. That file is in ignored_files, so I did not inspect its contents. This does not affect the verdict, because the snapshot is a test artifact and not a coding requirement. No unrelated block types, spacing, or alignment logic changed, according to the summary and PR description.

Finishing Touches

Generate unit tests (beta)

  • Create a new PR
Fix failing CI checks

  • 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

A rabbit reads the page with care,
A heading hops, no longer stranded there.
Four forms now stick to what comes next,
While paragraphs keep their usual text.
The rabbit thumps and turns the page!

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 8538e63d-c955-41ea-ac40-c07201955a10
Commits

Reviewing files that changed from the base of the PR and between 7f714c0 and 4bc5ace.

Files ignored due to path filters: 1

  • packages/xl-typst-exporter/src/__snapshots__/testDocument.typ is excluded by !**/__snapshots__/**
Files selected for processing: 2

  • packages/xl-typst-exporter/src/typstExporter.test.ts
  • packages/xl-typst-exporter/src/typstExporter.ts

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

@nperez0111 nperez0111 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.

This is a nice QOL of change. Thanks @notluquis for the submission

@pkg-pr-new

pkg-pr-new Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

@blocknote/ariakit

npm i https://pkg.pr.new/@blocknote/ariakit@3365

@blocknote/code-block

npm i https://pkg.pr.new/@blocknote/code-block@3365

@blocknote/core

npm i https://pkg.pr.new/@blocknote/core@3365

@blocknote/diagram-block

npm i https://pkg.pr.new/@blocknote/diagram-block@3365

@blocknote/mantine

npm i https://pkg.pr.new/@blocknote/mantine@3365

@blocknote/math-block

npm i https://pkg.pr.new/@blocknote/math-block@3365

@blocknote/react

npm i https://pkg.pr.new/@blocknote/react@3365

@blocknote/server-util

npm i https://pkg.pr.new/@blocknote/server-util@3365

@blocknote/shadcn

npm i https://pkg.pr.new/@blocknote/shadcn@3365

@blocknote/xl-ai

npm i https://pkg.pr.new/@blocknote/xl-ai@3365

@blocknote/xl-docx-exporter

npm i https://pkg.pr.new/@blocknote/xl-docx-exporter@3365

@blocknote/xl-email-exporter

npm i https://pkg.pr.new/@blocknote/xl-email-exporter@3365

@blocknote/xl-multi-column

npm i https://pkg.pr.new/@blocknote/xl-multi-column@3365

@blocknote/xl-odt-exporter

npm i https://pkg.pr.new/@blocknote/xl-odt-exporter@3365

@blocknote/xl-pdf-exporter

npm i https://pkg.pr.new/@blocknote/xl-pdf-exporter@3365

@blocknote/xl-typst-exporter

npm i https://pkg.pr.new/@blocknote/xl-typst-exporter@3365

commit: 4bc5ace

@nperez0111
nperez0111 merged commit 0f26215 into TypeCellOS:main Nov 18, 2026
29 of 33 checks passed
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.

Typst PDF export: a heading can be left alone at the bottom of a page

2 participants