lemming:0.3.1 (#5210)

Co-authored-by: fgolke <fgolke@noreply.codeberg.org>

Author: fGolke

packages/preview/lemming/0.3.1/CHANGELOG.md

@@ -0,0 +1,16 @@
+# 0\.3\.1
+- fix: Change default show rule of `environment` to make use of `end-marker`
+
+# 0\.3\.0
+- feat: Emit `math-environment` and `math-proof` tags when exporting to html
+- feat: Add `end-marker` parameter to `environment`. This allows putting a symbol at the end of math environments, similar to the QED symbol.
+- fix: Make proofs and environments full width, such that equation-only statements display correctly
+- fix: Do not insert QED symbols to figure captions, place them afterwards instead.
+
+
+# 0\.2\.0
+- feat: Provide a wrapper for `elembic.fields` to facilitate custom `show`-rules.
+- fix: References now link to their targets.
+
+# 0\.1\.0
+- First release with support for `environment` and `proof`. Based on elembic.

packages/preview/lemming/0.3.1/LICENSE

@@ -0,0 +1,161 @@
+# Lemming
+Provides customizable theorem-like and proof environments that aim to behave closely to the way native elements behave.
+This package will upgrade to [native custom elements](https://github.com/typst/typst/issues/147), once they arrive.
+For now it employs the great [elembic](https://typst.app/universe/package/elembic).
+
+![Usage example with a theorem and a proof.](gallery/readme-example.png)
+
+See the [CHANGELOG](CHANGELOG.md) for differences between versions.
+
+
+## Basic usage
+
+First, create the environments you want to use. 
+By default, the `supplement` of the environment will be a capitalized version of the `kind` specified.
+```typ
+#import "@preview/lemming:0.3.1" as lem
+
+#let theorem = lem.environment.with(kind: "theorem")
+#let lemma = lem.environment.with(kind: "lemma")
+
+#let proof = lem.proof
+
+// Unfortunately necessary for now to make references work
+#show: lem.prepare()
+```
+If you want your environments to use a shared counter, set their `supplement` instead of `kind`, i.e.: [^1]
+```typ
+#let theorem = lem.environment.with(supplement: [Theorem])
+#let lemma = lem.environment.with(supplement: [Lemma])
+```
+[^1]:
+	Note that you should pass a value of type `content` and not `str` to `supplement`.
+	Otherwise `show`-rules might not work as expected.
+
+
+Now, just use your environments in your document.
+
+```typ
+#theorem(name: "Noether")[
+  #lorem(20)
+]
+
+#theorem(numbering: none, supplement: [Satz])[
+  #lorem(20)
+]
+```
+
+## Labels and references
+Due to implementation constraints, you have to specify labels as below instead of attaching it at the back of your environments.
+Hopefully, this will become unnecessary in the future.
+```typ
+#theorem(name: "Noether", label: <theorem:noether>)[
+  #lorem(20)
+]
+```
+If references do not work, make sure you have applied the following `show` rule.
+```typ
+#show: lem.prepare()
+```
+
+## Set rules
+You can change the defaults of all parameters using `set` rules.
+```typ
+// Unnecessary as "1.1" is the default numbering
+// Think: #set lem.environment(numbering: "1")
+#show: lem.set_(lem.environment, numbering: "1")
+```
+
+## Show-Set rules
+You can use `show set` rules too.
+For example, you can make the body text `upright` instead of the default `italic`
+```typ
+// Think: #show lem.environment.body: set text(style: "normal")
+#show lem.selector(lem.environment-body): set text(style: "normal")
+```
+Self-referential `show set` rules work a bit different than native ones.
+```typ
+// Think: #show lem.environment.where(kind: "theorem"): set lem.environment(
+//   numbering: heading-subnumbering(
+//     lem.environment.where(kind: "theorem"), 1, "H.1.1"
+//   )
+// )
+#show: lem.cond-set(
+  theorem, 
+  numbering: heading-subnumbering(lem.counter-name("theorem"), 1, "H.1.1"),
+)
+```
+This rules employs the `heading-subnumbering` function from the [discount](https://typst.app/universe/package/discount) package.
+
+**Advice**: Instead of setting block properties
+```typ
+#show lem.selector(lem.proof): set block(inset: (left: 1cm)) // DON'T DO THIS
+```
+wrapping elements in blocks leads to less unwanted side-effects
+```typ
+#show: lem.show_(lem.proof, it => block(inset: (left: 1cm), it))
+```
+
+## Show rules
+To customize the display of your environment even further, you can write a custom `show` rule.
+```typ
+// Think: #show lem.environment: box(stroke: blue)
+ #show: lem.show_(lem.environment, it => box(stroke: blue, it))
+```
+These can be conditional too.
+```typ
+// Think: #show lem.environment.where(kind: "lemma"): it => box(stroke: red, inset: 0.5em, it)
+#show: lem.show_(lemma, it => box(stroke: red, inset: 0.5em, it))
+```
+
+To change the visuals further, you can write a full custom `show`-rule.
+For example, if you want the number at front and the supplement in smallcaps, you can write the following.
+```typ
+#show: lem.show_(lem.environment, it => {
+  it = lem.fields(it) // Hopefully not necessary in the future
+  block({
+    strong(
+      if it.numbering != none {
+        numbering(it.numbering, ..it.counter.get())
+        sym.space.nobreak
+      } + smallcaps(it.supplement),
+    )
+    if it.name != none {
+      [ (#emph(it.name))]
+    }
+    strong(it.separator)
+
+    // For convenience, by default it just makes text italic
+    lem.environment-body(it.body)
+  })
+})
+```
+
+![Usage example with a theorem and a proof.](gallery/show-example.png)
+
+## HTML
+In HTML export, `environment` elements emit a `math-environment` tag and `proof` elements emit a `math-proof` tag.
+
+## Enviroment Fields
+While writing your `show` rule, you can acess the following fields on `it`:
+| name | type | description |
+| -- | -- | -- |
+| body | `content` | The body of the environment, required and positional. |
+| name | `content \| none` | Additional note for the environment, for example the name of a theorem. |
+| kind | `str` | The kind of math environment. Default: `"theorem"`|
+| supplement | `content \| auto` | The word used for the environment. Defaults to the capizalized kind. |
+| separator | `content` | The symbol between between the header and body. Default: `[. ]` | 
+| numbering | `str \| function \| none` | How to number the environment. Accepts a numbering pattern or function. Default: `"1.1"` |
+| end-marker | `content \| none` | The symbol to place at the end of the environment. Default: `none` |
+| counter | `counter` | The counter corresponding to the environment, synthesized. |
+
+## Proofs
+The `proof` environment works similar and should do exactly what you expect.
+Its fields are:
+
+| name | type | description |
+| -- | -- | -- |
+| body | `content` | The body of the proof, required and positional. |
+| supplement | `content` | The term before the proof body, Default `"Proof"` |
+| separator | `content` | The symbol between proof supplement and body, Default: `[. ]` |
+| qed | `content \| none` | The Symbol to insert after the body, Default: `$square$` |

packages/preview/lemming/0.3.1/README.md

@@ -0,0 +1,98 @@
+#let sequence-func = [. ].func()
+#let space-func = [. ].children.last().func()
+#let styled-func = [#set text(fill: red)].func()
+
+#let get-last-nonempty(content_) = {
+	for (i, part) in content_.children.enumerate().rev() {
+		let func = part.func()
+		if func in (space-func, parbreak, linebreak, colbreak, pagebreak) {
+			continue
+		}
+		return (func, i)
+	}
+	return (it => it, content_.children.len() - 1)
+}
+
+/// Similar to
+/// ```typ
+/// #h(1fr)
+/// #marker
+/// ```
+/// but keeps the spacing even after soft line-breaks
+///
+/// - marker (content): The content to place at the end
+/// ->
+#let space-marker(marker, minimal-spacing) = {
+	if minimal-spacing != none {
+			h(minimal-spacing)
+		}
+	box(
+		// Don't apply user set-rules
+		baseline: 0% + 0pt, fill:  none, height: auto, inset: (:), outset: (:), stroke: (:),
+		width: 1fr, align(right, marker)
+	)
+}
+
+
+#let clone-without(dict, keys) = for (k, value) in dict {
+	if not keys.contains(k) {
+		({ k }: value)
+	}
+}
+
+#let append(body, qed, minimal-spacing: 2em) = if type(body) == content {
+	if qed == none {
+		return body
+	}
+
+	let func = body.func()
+	if func == sequence-func and body.children.len() > 0 {
+		let (child-func, index) = get-last-nonempty(body)
+		for part in body.children.slice(0, index) {
+			part
+		}
+		append(body.children.at(index), qed)
+		for part in body.children.slice(index + 1) {
+			part
+		}
+	} else if func == math.equation and body.block {
+		body
+		place(bottom + right, qed)
+		context if math.equation.numbering != none {
+			let number-align = math.equation.number-align
+			let equation-height = measure(body).height
+			let numbering-height = measure(numbering(math.equation.numbering, 1)).height
+			let qed-height = measure(qed).height
+
+			if number-align.x == end or number-align.x == none {
+				if number-align.y == top {
+					let remaining-height = equation-height - numbering-height - qed-height
+					if remaining-height < par.leading.to-absolute() {
+						h(par.leading - remaining-height)
+					}
+				} else if number-align.y == horizon {
+					let remaining-height = (equation-height - numbering-height) / 2 - qed-height
+					if remaining-height < par.leading.to-absolute() {
+						h(par.leading - remaining-height)
+					}
+				} else if number-align.y == bottom {
+					h(par.leading)
+				}
+			}
+		}
+	} else if func in (list.item, enum.item, block) {
+		func(append(body.body, qed), ..clone-without(body.fields(), ("body",)))
+	} else if func == terms.item {
+		func(body.term, append(body.description, qed))
+	} else if func == columns {
+		func(append(body.body, qed), body.count)
+	} else if func == styled-func {
+		func(append(body.child, qed), body.styles)
+	} else {
+		// if func != text {panic("Unknown: " + repr(func))}
+		body
+		space-marker(qed, minimal-spacing)
+	}
+} else {
+	panic("Can't append qed to non-content.")
+}

packages/preview/lemming/0.3.1/gallery/readme-example.png

@@ -0,0 +1,26 @@
+// Thin wrappers around elembic to enable deprecation warnings once native custom types land
+#import "@preview/elembic:1.1.1" as e
+
+#let set_(elem, ..fields) = {
+	e.set_(elem, ..fields)
+}
+
+#let show_(filter, replacement, mode: auto) = {
+	e.show_(filter, replacement, mode: mode)
+}
+
+#let cond-set(filter, ..fields) = {
+	e.cond-set(filter, ..fields)
+}
+
+#let selector(elem, outline: false, outer: false, meta: false) = {
+	e.selector(elem, outline: outline, outer: outer, meta: meta)
+}
+
+#let prepare(..args) = {
+	e.prepare(..args)
+}
+
+#let fields(elem) = {
+	e.fields(elem)
+}