initial commit

Author: tingerrr

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 tinger <me@tinger.dev>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,84 @@
+# hydra
+Hydra is a [typst] package allowing you to easily display the current section anywhere in your
+document. By default, it will assume that it is used in the header of your document and display
+the last heading if and only if it is numbered and the next heading is not the first on the current
+page.
+
+By default hdyra assumes that you use `a4` page size, see the FAQ if you use different page size or
+margins.
+
+## Example
+```typst
+#import "@preview/hydra:0.0.1": hydra
+#set page(header: hydra())
+#set heading(numbering: "1.1")
+#show heading.where(level: 1): it => pagebreak(weak: true) + it
+
+= Introduction
+#lorem(750)
+
+= Content
+== First Section
+#lorem(500)
+== Second Section
+#lorem(250)
+== Third Section
+#lorem(500)
+
+= Annex
+#lorem(10)
+```
+![example1][example1]
+![example2][example2]
+
+## Non-default behavior
+### Configuring filter and display
+By default it will hydra will display `[#numbering #body]` of the heading and this reject unnumbered
+ones. This filtering can be configured using `prev-filter` and `next-filter`, if those are changed
+to include unnumbered headings `display` be changed too.
+```typst
+#set page(header: hydra(prev-filter: _ => true, display: h => h.body))
+```
+
+Keep in mind that `next-filter` is also responsible for checking that the next heading is on the
+current page.
+
+### In the footer
+To use the hydra functon in the footer of your doc, pass `is-footer: true` and place a
+`#metadata(()) <hydra>` somewhere in your header.
+
+```typst
+#set page(header: [#metadata(()) <hydra>], footer: hydra(is-footer: true))
+```
+
+Using it outside of footer or header should work as expected.
+
+### Different heading levels or custom heading types
+If you use a `figure`-based element for special 0-level chapters or you wish to only consider
+specific levels of headings, pass the appropriate selector.
+
+```typst
+// only consider level 1
+#set page(header: hydra(sel: heading.where(level: 1)))
+
+// only consider level 1 - 3
+#set page(header: hydra(sel: (heading, h => h.level <= 3)))
+
+// consider also figures with this kind, must likely override all default functions other than
+// resolve, or resolve directly, see source
+#set page(header: hydra(sel: figure.where(kind: "chapter").or(heading), display: ...)
+```
+
+In short, `sel` can be a selector, or a selector and a filter function. When using anything other
+than headings only, consider setting `display` too.
+
+## FAQ
+**Q:** Why does hydra display the previous heading if there is a heading at the top of my page?
+
+**A:** If you use non `a4` page margins make sure to pass
+`next-filter: default.next-filter.with(top-margin: ...)`. This margin must be known for the default
+implementation. If it does but you are using `a4`, then you found a bug.
+
+[example1]: example1.png
+[example2]: example2.png
+[typst]: https://github.com/typst/typst

example1.png

@@ -0,0 +1,61 @@
+// get the adjacent headings
+#let get-adjacent(is-footer: false, sel, loc) = {
+  import "/src/util.typ": into-sel-filter-pair
+  let (sel, filter) = into-sel-filter-pair(sel)
+
+  if is-footer {
+    loc = query(selector(<hydra>).before(loc), loc).last().location()
+  }
+
+  let prev = query(sel.before(loc), loc).filter(filter)
+  let next = query(sel.after(loc), loc).filter(filter)
+
+  let prev = if prev != () { prev.last() }
+  let next = if next != () { next.first() }
+
+  (prev, next)
+}
+
+// check if the previous heading is numbered
+#let prev-filter(element, loc) = {
+  import "/src/util.typ": assert-element
+  assert-element(element, heading)
+  element.numbering != none
+}
+
+// check if the next heading is on the curent page
+#let next-filter(top-margin: 2.5cm, element, loc) = {
+  import "/src/util.typ": assert-element
+  assert-element(element, heading)
+  (element.numbering != none
+    and element.location().page() == loc.page()
+    and element.location().position().y <= top-margin)
+}
+
+// display the heading as closely as it occured at the given loc
+#let display(element, loc) = {
+  import "/src/util.typ": assert-element
+  assert-element(element, heading)
+  numbering(element.numbering, ..counter(heading).at(element.location()))
+  [ ]
+  element.body
+}
+
+#let resolve(
+  sel: heading,
+  getter: get-adjacent,
+  prev-filter: prev-filter,
+  next-filter: next-filter,
+  display: display,
+  is-footer: false,
+  loc,
+) = {
+  let (last, next) = getter(sel, is-footer: is-footer, loc)
+
+  let last-eligible = last != none and prev-filter(last, loc)
+  let next-eligible = next != none and next-filter(next, loc)
+
+  if last-eligible and not next-eligible {
+    display(last, loc)
+  }
+ }

example2.png

@@ -0,0 +1,19 @@
+#import "/src/default.typ"
+
+#let hydra(
+  sel: heading,
+  getter: default.get-adjacent,
+  prev-filter: default.prev-filter,
+  next-filter: default.next-filter,
+  display: default.display,
+  resolve: default.resolve,
+  is-footer: false,
+) = locate(loc => resolve(
+    sel: sel,
+    getter: getter,
+    prev-filter: prev-filter,
+    next-filter: next-filter,
+    display: display,
+    is-footer: is-footer,
+    loc
+))

src/default.typ

@@ -0,0 +1,21 @@
+// assert the element is of the given typ
+#let assert-element(element, func) = {
+  assert.eq(type(element), content, message: "element must be content, was " + repr(type(element)))
+  assert.eq(element.func(), func, message: "element must be a " + repr(func))
+}
+
+// split a selector into a pair of selector and post filter
+#let into-sel-filter-pair(sel) = {
+  if type(sel) in (selector, function) {
+    (selector(sel), _ => true)
+  } else if (
+    type(sel) == array and sel.len() == 2
+    and type(sel.at(0)) in (selector, function) and type(sel.at(1)) == function
+  ) {
+    let (sel, func) = sel
+    (selector(sel), func)
+  } else {
+    panic("sel must be a selector or a selector and filter function")
+  }
+}
+

src/lib.typ

@@ -0,0 +1,11 @@
+[package]
+entrypoint = "src/lib.typ"
+name = "hydra"
+version = "0.0.1"
+compiler = "0.8.0"
+authors = ["tinger <me@tinger.dev>"]
+repository = "https://github.com/tingerrr/hydra"
+description = "Query and display headings of the currently active section"
+keywords = ["heading", "introspection"]
+license = "MIT"
+exclude = ["example1.png", "example2.png", "LICENSE", "README.md"]