Improve and document next-heading

book/src/SUMMARY.md

@@ -17,6 +17,7 @@
   - [Side by side](./toolbox/side-by-side.md)
   - [Progress](./toolbox/progress.md)
   - [Sections](./toolbox/sections.md)
+  - [Next heading](./toolbox/next-heading.md)
   - [Big](./toolbox/big.md)
   - [Full width](./toolbox/full-width.md)
 - [External tools](./external/external.md)

book/src/toolbox/next-heading.md

@@ -0,0 +1,23 @@
+# Find next heading
+
+It can be very convenient to specify something like slide titles using headings
+as they have a dedicated Typst syntax.
+While it might suffice to just style how a heading is displayed using a show
+rule, this is not feasible when the slide title is supposed to be part of the
+page header, for example.
+
+For these situations, the toolbox provides `#toolbox.next-heading`.
+It takes a function mapping the body of the first heading on the same page (if
+it exists) to some content.
+
+The intended use is as such:
+
+```typ
+{{#include next-heading.typ:4:100}}
+```
+![next-heading](next-heading.png)
+
+Note the extra show rule for level-one headings making them invisible.
+
+You can make `#toolbox.next-heading` look for headings of other levels as well,
+just specify the optional `level` argument that defaults to `1`.

book/src/toolbox/next-heading.typ

@@ -0,0 +1,28 @@
+#import "../../../src/polylux.typ": *
+#set text(size: 40pt, font: "Atkinson Hyperlegible")
+
+#set page(
+  paper: "presentation-16-9",
+  header: toolbox.next-heading(h => underline(h))
+)
+
+#show heading.where(level: 1): none
+
+#set align(horizon)
+
+#slide[
+  = My slide title
+
+  #lorem(10)
+]
+
+#slide[
+  slide without a title
+]
+
+#slide[
+  = Another title
+
+  #lorem(10)
+]
+

book/src/toolbox/previews.fish

@@ -1,8 +1,9 @@
 typst-compose side-by-side 1 gray --root ../../..
 typst-compose side-by-side-kwargs 1 gray --root ../../..
 typst-compose big 1 gray --root ../../..
-typst-compose big-complex 1 gray --root ../../..
+typst-compose big-complex 3 gray --root ../../..
 typst-compose progress 3 gray --root ../../..
 typst-compose sections-band 2 gray --root ../../..
 typst-compose sections 4 gray --root ../../..
 typst-compose full-width 1 gray --root ../../..
+typst-compose next-heading 3 gray --root ../../..

src/toolbox/toolbox-impl.typ

@@ -99,9 +99,9 @@
 #let next-heading(level: 1, fn) = context {
   let hs = query(heading.where(level: level).after(here()))
   if hs.len() > 0 {
-    let h = hs.first().body
-    if h != [] {
-      fn(h)
+    let h = hs.first()
+    if h.location().page() == here().page() {
+      fn(h.body)
     }
   }
 }