Release 0.4.0

.alabasterignore

@@ -0,0 +1,3 @@
+tests
+CONTRIBUTING.md
+Justfile

.github/workflows/tests.yml

@@ -38,10 +38,7 @@ jobs:
       - name: Setup typst
         uses: yusancky/setup-typst@v2
         with:
-          version: 'v0.10.0'
-
-      - name: Test manual and example generation
-        run: just gen
+          version: 'v0.11.0'
 
       - name: Run test suite
-        run: just test
+        run: just ci

CHANGELOG.md

@@ -0,0 +1,50 @@
+# [unreleased](https://github.com/tingerrr/hydra/releases/tags/)
+## Added
+
+## Removed
+
+## Changed
+
+---
+
+# [v0.4.0](https://github.com/tingerrr/hydra/releases/tags/v0.4.0)
+Almost all changes in this release are **BREAKING CHANGES**.
+
+## Added
+- internal util functions and dictionaries for recreating `auto` fallbacks used within the typst
+  compiler
+  - `core.get-text-dir` - returns the text direction
+  - `core.get-binding` - returns the page binding
+  - `core.get-top-margin` - returns the absolute top margin
+  - `util.text-direction` - returns the text direction for a given language
+  - `util.page-binding` - returns the page binding for a given text direction
+
+## Removed
+- various parameters on `hydra` have been removed
+  - `paper` has been removed in favor of get rule
+  - `page-size` has been removed in favor of get rule
+  - `top-margin` has been removed in favor of get rule
+  - `loc` has been removed in favor of user provided context
+- internal util dictionary for page sizes
+
+## Changed
+- hydra now requires a minimum Typst compiler version of `0.11.0`
+- `hydra` is now contextual
+- most internal functions are now contextual
+- the internal context dictionary now holds a `anchor-loc` instead of a `loc`
+- `get-anchor-pos` has been renamed to `locate-last-anchor`
+- the internal `page-sizes` dictionary was changed to function
+- various parameters on `hydra` are now auto by default
+  - `prev-filter`
+  - `next-filter`
+  - `display`
+  - `dir`
+  - `binding`
+
+---
+
+# [v0.3.0](https://github.com/tingerrr/hydra/releases/tags/v0.3.0)
+
+# [v0.2.0](https://github.com/tingerrr/hydra/releases/tags/v0.2.0)
+
+# [v0.1.0](https://github.com/tingerrr/hydra/releases/tags/v0.1.0)

CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contribution
+## Bug fixes
+If you want to fix an issue please leave a comment there so others know you are working on it. If
+you want to fix a bug which doesn't have an issue yet, please create an issue first. Exceptions are
+typos or minor improvements, just making the PR will be enough in those cases.
+
+## Features
+When adding features, make sure you add regression tests for this feature. See the testing section
+below on testing. Make sure to document the feature, see the manual section on manual and examples
+below.
+
+## Testing
+To ensure that your changes don't break exisiting code test it using the package's regression tests.
+This is done automatically on pull requests, so you don't need not install [typst-test], but it's
+nontheless recommended for faster iteration. In general, running `typst-test run` will be enough to
+ensure your changes are correct.
+
+## Manual and examples
+The manual and example images are created from a quite frankly convoluted nushell script. If you
+have, or don't mind installing, [nushell], [just] and [imagemagick], then you can simply run `just
+gen` to generate a new manual and examples.
+
+The examples inside the docs currently don't make it easy to simplify this without generating them
+manually the whole time. Typst is missing a feature or plugin that allows embedding whole other
+Typst documents at the moment.
+
+That being said, it's fine to leave this step out on a PR and have me generate it once the rest of
+the PR is done.
+
+[typst-test]: https://github.com/tingerrr/typst-test
+[just]: https://just.systems/
+[nushell]: https://www.nushell.sh/
+[imagemagick]: https://imagemagick.org/

Justfile

@@ -0,0 +1,57 @@
+set shell := ['nu', '-c']
+
+export TYPST_ROOT := justfile_directory()
+
+# list recipes
+[private]
+default:
+	just --list
+
+# generate example images
+gen-examples:
+	rm --recursive --force pages examples/pages
+	mkdir examples/pages
+	typst compile --ppi 300 examples/pages.typ examples/pages/{n}.png
+	typst compile examples/main.typ examples/example.png
+	rm --recursive --force pages examples/pages
+	oxipng --opt max examples/example.png
+
+# generate doc examples
+gen-doc-examples:
+	#! /usr/bin/env nu
+	ls doc/examples
+		| where type == dir
+		| get name
+		| each {|it|
+			cd $it
+			rm --recursive --force out
+			mkdir out
+			[a b] | each {|it|
+				(typst compile
+					$"($it).typ"
+					$"out/($it){n}.png")
+			};
+			let pages = (ls out | length) / 2;
+			{ pages: $pages } | to toml | save out.toml
+		}
+		| ignore
+
+	oxipng --recursive --opt max doc
+
+# generate the manual
+doc: gen-doc-examples
+	typst compile doc/manual.typ doc/manual.pdf
+
+# copy the files relevant for the package repo
+publish output:
+	alabaster package {{ output }}
+
+# run the test suite
+test filter='':
+	typst-test run {{ filter }}
+
+# run the ci test suite
+ci:
+	# run one single test first to avoid a race condition on package downloads
+	typst-test run regressions/scoped-search
+	typst-test run

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 tinger <[email protected]>
+Copyright (c) 2024 tinger <[email protected]>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,77 +1,44 @@
 # hydra
-Hydra is a [typst] package allowing you to easily display the heading like elements anywhere in your
-document. In short, it will show you the currently active element only when it is not visible.
-
-Some of hydra's features rely on the size of the top-margin, if you use a different page size than
-`a4` or a custom top margin for your pages, make sure to configure hydra, otherwise those checks may
-not work.
+Hydra is a Typst package allowing you to easily display the heading like elements anywhere in your
+document. It's primary focus is to provide the reader with a reminder of where they currently are in
+your document only when it is needed.
 
 ## Example
 ```typst
-#import "@preview/hydra:0.3.0": hydra
-
-#set page(header: hydra() + line(length: 100%))
+#import "@preview/hydra:0.4.0": hydra
+
+#set page(paper: "a7", margin: (y: 4em), numbering: "1", header: context {
+  if calc.odd(here().page()) {
+    align(right, emph(hydra(1)))
+  } else {
+    align(left, emph(hydra(2)))
+  }
+  line(length: 100%)
+})
 #set heading(numbering: "1.1")
 #show heading.where(level: 1): it => pagebreak(weak: true) + it
 
 = Introduction
-#lorem(750)
+#lorem(50)
 
 = Content
 == First Section
-#lorem(500)
+#lorem(50)
 == Second Section
-#lorem(250)
-== Third Section
-#lorem(500)
-
-= Annex
-#lorem(10)
+#lorem(100)
 ```
-![ex1]
-![ex2]
-![ex3]
-![ex4]
-![ex5]
+![ex]
 
 ## Documentation
 For a more in-depth description of hydra's functionality and the reference read its [manual].
 
 ## Contribution
-### Bug fixes
-If you want to fix an issue please leave a comment there so others know. If you want to fix a bug
-which doesn't have an issue yet, please create an issue first. Exceptions are typos or minor
-improvements, just making the PR will be enough.
-
-### Features
-When adding features, make sure you add regression tests for this feature. See the testing section
-below on testing. Make sure to document the feature, see the manual section on manual and examples
-below.
-
-### Testing
-To ensure that your changes don't break exisiting code test it using the package's regression tests.
-This is done automatically on pull requests, so you don't need not install [typst-test], but it's
-nontheless recommended for faster iteration. In general, running `typst-test run` will be enough to
-ensure your changes are correct.
-
-### Manual and examples
-The manual and example images are created from a quite frankly convoluted nushell script. If you
-have, or don't mind installing, [nushell], [just] and [imagemagick], then you can simply run `just
-gen` to generate a new manual and examples.
-
-The examples inside the docs currently don't make it easy to simplify this without generating them
-manually the whole time. Typst is missing a feature or plugin that allows embedding whole other
-typst documents at the moment.
+For contributing, please take a look [CONTRIBUTING][contrib].
 
-[ex1]: examples/example1.png
-[ex2]: examples/example2.png
-[ex3]: examples/example3.png
-[ex4]: examples/example4.png
-[ex5]: examples/example5.png
-[manual]: docs/manual.pdf
+## Etymology
+The package name hydra /ˈhaɪdrə/ is a word play headings and headers, inspired by the monster in
+greek and roman mythology resembling a serpent with many heads.
 
-[typst]: https://github.com/typst/typst
-[typst-test]: https://github.com/tingerrr/typst-test
-[just]: https://just.systems/
-[nushell]: https://www.nushell.sh/
-[imagemagick]: https://imagemagick.org/
+[ex]: examples/example.png
+[manual]: doc/manual.pdf
+[contrib]: CONTRIBUTING.md

doc/.alabasterignore

@@ -0,0 +1,2 @@
+examples
+**.typ

doc/chapters/1-intro.typ

@@ -0,0 +1,52 @@
+Hydra is a package which aims to query and display section elements, such as headings, legal
+paragraphs, documentation sections, and whatever else may semantically declare the start of a
+document's section.
+
+== Terminology & Semantics
+The following terms are frequently used in the remainider of this document.
+
+/ primary: The element which is primarily looked for and meant to be displayed.
+/ ancestor: An element which is the immediate or transitive ancestor to the primary element.
+  A level 3 heading is ancestor to both level 2 (directly) and level 1 headings (transitively).
+/ scope: The scope of a primary element refers to the section of a document which is between the
+  closest ancestors.
+/ active: The active element refers to whatever element is considered for display. While this is
+  usually the previous primary element, it may sometimes be the next primary element.
+/ leading page: A leading page in a book is that, which is further along the content of the two
+  visible pages at any time, this is the `end` alignement with respect to the document readin
+  direction.
+/ trailing page: A trailing page is that, which is not the leading page in a book.
+
+The search for a primary element is always bounded to it's scope. For the following simplified
+document:
+
+```typst
+= Chapter 1
+== Section 1.1
+
+= Chapter 2
+=== Subsection 2.0.1
+#hydra(2)
+```
+```txt
+Chapter 1
+└ Section 1.1
+Chapter 2
+└ <none>
+  └ Subsection 2.0.1
+```
+
+hydra will only search within it's current chapter as it is looking for active sections. In this
+case hydra would not find a suitable candidate. For this the ancestors of an element must be known.
+For headings this is simple:
+#align(center, (
+  `<none>`,
+  `level: 1`,
+  `level: 2`,
+  `level: 3`,
+  `...`,
+).join([ #sym.arrow ]))
+
+If hydra is used to query for level 2 headings it will only do so within the bounds of the closest
+level 1 headings. In principle, elements other than headings can be used (see @custom), as long as
+their semantic relationships are established.