Add flexible references, positional title syntax, counter continuation, and input validation

Co-authored-by: OrangeX4 <34951714+OrangeX4@users.noreply.github.com>

Author: Copilot

core.typ

@@ -120,14 +120,20 @@
 
   // `update` method for this richer-counter
   // only support array of integers as counter value
-  let update(counter-value) = [
-    #metadata((
-      kind: "richer-counter:update",
-      identifier: identifier,
-      value: counter-value,
-    ))
-    #label("richer-counter:update:" + identifier)
-  ]
+  let update(counter-value) = {
+    assert(
+      type(counter-value) == array and counter-value.all(v => type(v) == int),
+      message: "Counter value for '" + identifier + "' must be an array of integers, e.g. (1, 2).",
+    )
+    [
+      #metadata((
+        kind: "richer-counter:update",
+        identifier: identifier,
+        value: counter-value,
+      ))
+      #label("richer-counter:update:" + identifier)
+    ]
+  }
 
   // find updates of own partial (!) counter in certain range
   let updates-during(after-key, before-key) = {
@@ -315,10 +321,16 @@
   }
 
   /// Useful functions for the frame.
+  // Helper: check whether a title value is non-empty (works for both str and content)
+  let has-nonempty-title(title) = (type(title) == str and title != "") or (type(title) == content and title != [] and title != [#""])
   let get-prefix(get-loc, number: auto, supplement: auto) = [#if supplement == auto { supplement-i18n } else {
       supplement
-    } #if number == auto { display-number(get-loc: get-loc)() } else { number }]
-  let get-full-title(prefix, title) = [#prefix#{ if title != "" [ (#title)] }]
+    } #if number == auto { display-number(get-loc: get-loc)() } else if type(number) == array {
+      context std.numbering(get-numbering(get-loc()), ..number)
+    } else { number }]
+  let get-full-title(prefix, title) = [#prefix#{
+      if has-nonempty-title(title) [ (#title)]
+    }]
   /// Frame with the counter.
   let frame(
     title: "",
@@ -330,44 +342,66 @@
     get-full-title: get-full-title,
     ..args,
     body,
-  ) = figure(
-    kind: identifier,
-    supplement: if supplement == auto { supplement-i18n } else { supplement },
-    caption: title,
-    outlined: outlined,
-    numbering: if number == auto { numbering } else { (..args) => (kind: "static", value: number) },
-    {
-      [#metadata((
-          identifier: identifier,
-          number: number,
+  ) = {
+    // Support positional title syntax: #theorem[Title][Body]
+    let actual-title = if args.pos().len() > 0 and title == "" {
+      args.pos().first()
+    } else {
+      title
+    }
+    // For array numbers, emit counter update BEFORE the figure so that
+    // theorion-display-number (which reads at el.location()) sees the updated value.
+    if type(number) == array and number.len() > 0 {
+      let target = number.slice(0, -1) + (number.last() - 1,)
+      (frame-counter.update)(target)
+    }
+    figure(
+      kind: identifier,
+      supplement: if supplement == auto { supplement-i18n } else { supplement },
+      caption: actual-title,
+      outlined: outlined,
+      numbering: if number == auto or type(number) == array {
+        numbering
+      } else {
+        (..fig-args) => (kind: "static", value: number)
+      },
+      {
+        [#metadata((
+            identifier: identifier,
+            number: number,
+            supplement: supplement,
+            supplement-map: supplement-map,
+            supplement-i18n: supplement-i18n,
+            kind: identifier,
+            counter: frame-counter,
+            title: actual-title,
+            numbering: numbering,
+            outlined: outlined,
+            get-prefix: get-prefix,
+            get-full-title: get-full-title,
+            render: render,
+            args: args,
+            body: body,
+          )) <theorion-frame-metadata>]
+        let prefix = get-prefix(
+          here,
+          number: if type(number) == array { auto } else { number },
           supplement: supplement,
-          supplement-map: supplement-map,
-          supplement-i18n: supplement-i18n,
-          kind: identifier,
-          counter: frame-counter,
-          title: title,
-          numbering: numbering,
-          outlined: outlined,
-          get-prefix: get-prefix,
-          get-full-title: get-full-title,
-          render: render,
-          args: args,
-          body: body,
-        )) <theorion-frame-metadata>]
-      let prefix = get-prefix(here, number: number, supplement: supplement)
-      render(
-        prefix: prefix,
-        title: title,
-        full-title: get-full-title(prefix, title),
-        ..args,
-        body,
-      )
-      // Update the counter.
-      if numbering != none and number == auto {
-        (frame-counter.step)()
-      }
-    },
-  )
+        )
+        render(
+          prefix: prefix,
+          title: actual-title,
+          full-title: get-full-title(prefix, actual-title),
+          ..args.named(),
+          body,
+        )
+        // Update the counter.
+        if numbering != none and (number == auto or type(number) == array) {
+          (frame-counter.step)()
+        }
+      },
+    )
+  }
   /// Frame without the counter.
   let frame-box = frame.with(
     numbering: none,
@@ -406,12 +440,29 @@
       let el = it.element
       if el != none and el.func() == figure and el.kind == identifier {
         link(el.location(), {
-          let supplement = if it.supplement == auto { el.supplement } else { it.supplement }
-          if supplement != none {
-            supplement
-            " "
+          if it.supplement == [-] {
+            // @label[-]: number only, no supplement
+            context theorion-display-number(el)
+          } else if it.supplement == [!!] {
+            // @label[!!]: supplement + number + title
+            let supplement = el.supplement
+            if supplement != none {
+              supplement
+              " "
+            }
+            context theorion-display-number(el)
+            context {
+              let title = el.caption.body
+              if has-nonempty-title(title) [ (#title)]
+            }
+          } else {
+            let supplement = if it.supplement == auto { el.supplement } else { it.supplement }
+            if supplement != none {
+              supplement
+              " "
+            }
+            context theorion-display-number(el)
           }
-          context theorion-display-number(el)
         })
       } else {
         it

tests/features/flexible-references/ref/1.png

@@ -0,0 +1,37 @@
+/// Test: flexible reference supplements - @label[-] for number only, @label[!!] for full with title
+#import "/lib.typ": *
+
+#set page(width: 300pt, height: auto, margin: (x: 15pt, y: 15pt))
+#set heading(numbering: "1.")
+
+#show: show-theorion
+
+= Flexible References
+
+#theorem(title: "Euclid's Theorem")[
+  There are infinitely many prime numbers.
+] <thm:euclid>
+
+#definition[
+  A prime has no divisors other than 1 and itself.
+] <def:prime>
+
+== Default Reference
+
+@thm:euclid (supplement + number)
+
+== Number Only Reference
+
+@thm:euclid[-] (number only, no supplement)
+
+== Full Reference with Title
+
+@thm:euclid[!!] (supplement + number + title)
+
+== References to Untitled Theorem
+
+@def:prime (supplement + number)
+
+@def:prime[-] (number only)
+
+@def:prime[!!] (supplement + number, no title to append)

tests/features/flexible-references/test.typ

@@ -0,0 +1,33 @@
+/// Test: nested proof environments with separate QED symbols
+#import "/lib.typ": *
+
+#set page(width: 300pt, height: auto, margin: (x: 15pt, y: 15pt))
+
+#show: show-theorion
+
+= Nested Proofs
+
+== Simple nested proof
+
+#proof[
+  This is the outer proof.
+  #proof[
+    This is the inner proof.
+    Both proofs get their own QED symbol.
+  ]
+  The outer proof continues and ends here.
+]
+
+== Triple nesting
+
+#proof[
+  Outer start.
+  #proof[
+    Middle start.
+    #proof[
+      Innermost proof.
+    ]
+    Middle end.
+  ]
+  Outer end.
+]

tests/features/nested-proof/ref/1.png

@@ -0,0 +1,34 @@
+/// Test: number continuation - #theorem(number: (n1, n2)) updates counter for continuation
+#import "/lib.typ": *
+
+#set page(width: 300pt, height: auto, margin: (x: 15pt, y: 15pt))
+#set heading(numbering: "1.")
+
+#show: show-theorion
+
+= Counter Continuation
+
+== Set counter via array number
+
+#theorem(number: (1, 3))[
+  This theorem is explicitly set to 1.3.
+  The counter is updated so the next auto-numbered theorem continues from here.
+]
+
+#theorem[
+  This should be 1.4 (continues from 1.3).
+]
+
+#theorem[
+  This should be 1.5.
+]
+
+== String number (no continuation)
+
+#theorem(number: "99.99")[
+  This uses a static string number. The counter is NOT updated.
+]
+
+#theorem[
+  This continues from where it left off before the static override (1.6).
+]

tests/features/nested-proof/test.typ

@@ -0,0 +1,35 @@
+/// Test: positional title syntax - #theorem[Title][Body]
+#import "/lib.typ": *
+
+#set page(width: 300pt, height: auto, margin: (x: 15pt, y: 15pt))
+#set heading(numbering: "1.")
+
+#show: show-theorion
+
+= Positional Title Syntax
+
+== Named parameter (current syntax)
+
+#theorem(title: "Named Theorem")[
+  This uses the named title parameter.
+]
+
+== Positional title (new syntax)
+
+#theorem[Positional Theorem][
+  This uses positional title as first content argument.
+]
+
+#definition[Prime Number][
+  A natural number greater than 1 with no divisors other than 1 and itself.
+] <def:prime-pos>
+
+== Reference to positionally-titled theorem
+
+@def:prime-pos[!!] shows the positional title in the reference.
+
+== No title (body only)
+
+#theorem[
+  This theorem has no title.
+]