Add subpar-grid convenience function

README.md

@@ -4,24 +4,23 @@
 Subpar is a [Typst] package allowing you to create easily referencable subfigures.
 
 ```typst
-#import "@preview/subpar:0.0.1": subpar
+#import "@preview/subpar:0.0.1": subpar-grid
 
 #set page(height: auto)
 #set par(justify: true)
 
-#subpar(
-  grid(columns: (1fr, 1fr), gutter: 1em,
-    [#figure(image("/assets/andromeda.jpg"), caption: [
-      An image of the andromeda galaxy.
-    ]) <a>],
-    [#figure(image("/assets/mountains.jpg"), caption: [
-      A sunset illuminating the sky above a mountain range.
-    ]) <b>],
-  ),
+#subpar-grid(columns: (1fr, 1fr),
+  (figure(image("/assets/andromeda.jpg"), caption: [
+    An image of the andromeda galaxy.
+  ]), <a>),
+  (figure(image("/assets/mountains.jpg"), caption: [
+    A sunset illuminating the sky above a mountain range.
+  ]), <b>),
   caption: [A figure composed of two subfigures.],
   label: <full>,
 )
 
+
 Above in @full, we see a figure which is composed of 2 other figures, namely @a and @b.
 ```
 ![ex]
@@ -30,13 +29,14 @@ Above in @full, we see a figure which is composed of 2 other figures, namely @a
 - [x] Relative numbering is incorrect for super-figures, see [#1]
 - [ ] Supplement is always "Figure", regardless of `text.lang`, see: [#2]
 - [x] Figure show rule cannot be easily reconfigured
+- [ ] Sub figure captions are not vertically aligned
 
 ## TODO
 The following tasks remain before the first version of subpar is released:
 - [x] documentation
 - [ ] manual generation
 - [x] allow more control over figure layout
-- [ ] add convenient warppers for common types of super figures
+- [x] add convenient warppers for common types of super figures
 - [x] add input validation
 - [ ] add a more comprehensive test suite
 

examples/example.typ

@@ -1,17 +1,17 @@
-#import "/src/lib.typ": subpar
+#import "/src/lib.typ": subpar-grid
 
 #set page(height: auto)
 #set par(justify: true)
 
-#subpar(
-  grid(columns: (1fr, 1fr), gutter: 1em,
-    [#figure(image("/assets/andromeda.jpg"), caption: [
-      An image of the andromeda galaxy.
-    ]) <a>],
-    [#figure(image("/assets/mountains.jpg"), caption: [
-      A sunset illuminating the sky above a mountain range.
-    ]) <b>],
-  ),
+#subpar-grid(
+  (figure(image("/assets/andromeda.jpg"), caption: [
+    An image of the andromeda galaxy.
+  ]), <a>),
+  (figure(image("/assets/mountains.jpg"), caption: [
+    A sunset illuminating the sky above a mountain range.
+  ]), <b>),
+  columns: (1fr, 1fr),
+  align: top,
   caption: [A figure composed of two subfigures.],
   label: <full>,
 )

src/lib.typ

@@ -125,3 +125,118 @@
     )#label]
   }
 }
+
+/// Provides a convenient wrapper around @@subpar() which puts sub figures in a
+/// grid.
+///
+/// - columns (auto, int, relative, fraction, array): Corresponds to the grid's
+///   `columns` parameter.
+/// - rows (auto, int, relative, fraction, array): Corresponds to the grid's
+///   `rows` parameter.
+/// - gutter (auto, int, relative, fraction, array): Corresponds to the grid's
+///   `gutter` parameter.
+/// - column-gutter (auto, int, relative, fraction, array): Corresponds to the
+///   grid's `column-gutter` parameter.
+/// - row-gutter (auto, int, relative, fraction, array): Corresponds to the
+///   grid's `row-gutter` parameter.
+/// - align (auto, array, alignement, function): Corresponds to the grid's
+///   `align` parameter.
+/// - inset (relaltive, array, dictionary, function): Corresponds to the grid's
+///   `inset` parameter.
+/// - numbering (): Corressponds to the super figure's `numbering`.
+/// - numbering-sub (): Corressponds to the super figure's `numbering-sub`.
+/// - numbering-sub-ref (): Corressponds to the super figure's
+///   `numbering-sub-ref`.
+/// - supplement (): Corressponds to the super figure's `supplement`.
+/// - caption (): Corressponds to the super figure's `caption`.
+/// - placement (): Corressponds to the super figure's `placement`.
+/// - gap (): Corressponds to the super figure's `gap`.
+/// - outlined (): Corressponds to the super figure's `outlined`.
+/// - outlined-sub (): Corressponds to the super figure's `outlined-sub`.
+/// - label (): Corressponds to the super figure's `label`.
+/// - show-sub (): Corressponds to the super figure's `show-sub`.
+/// - show-sub-caption (): Corressponds to the super figure's
+///   `show-sub-caption`.
+/// -> content
+#let subpar-grid(
+  columns: auto,
+  rows: auto,
+  gutter: 1em,
+  column-gutter: auto,
+  row-gutter: auto,
+  align: horizon,
+  inset: (:),
+
+  kind: image,
+
+  numbering: "1",
+  numbering-sub: "(a)",
+  numbering-sub-ref: "1a",
+
+  // TODO: see subpar
+  supplement: [Figure],
+  caption: none,
+  placement: none,
+  gap: 0.65em,
+  outlined: true,
+  outlined-sub: false,
+  label: none,
+
+  show-sub: auto,
+  show-sub-caption: auto,
+  ..args,
+) = {
+  if args.named().len() != 0 {
+    panic("Unexpectd arguments: `" + repr(args.named()) + "`")
+  }
+
+  let figures = args.pos()
+
+  let unwrap-figure(f) = if _pkg.t4t.is.elem(figure, f) {
+    f
+  } else if _pkg.t4t.is.arr(f) and f.len() == 2 and _pkg.t4t.is.elem(figure, f.first()) and _pkg.t4t.is.label(f.last()) {
+    [#f.first()#f.last()]
+  } else {
+    panic("Expected either a figure, or an array containing a figure and a label")
+  }
+
+  // NOTE: the mere existence of an argument seems to change how grid behaves, so we discard any that are auto ourselves
+  let grid-args = (
+    columns: columns,
+    rows: rows,
+    align: align,
+    inset: inset,
+  )
+
+  if gutter != auto {
+    grid-args.gutter = gutter
+  }
+  if column-gutter != auto {
+    grid-args.column-gutter = column-gutter
+  }
+  if row-gutter != auto {
+    grid-args.row-gutter = row-gutter
+  }
+
+  subpar(
+    numbering: numbering,
+    numbering-sub: numbering-sub,
+    numbering-sub-ref: numbering-sub-ref,
+
+    supplement: supplement,
+    caption: caption,
+    placement: placement,
+    gap: gap,
+    outlined: outlined,
+    outlined-sub: outlined-sub,
+    label: label,
+
+    show-sub: show-sub,
+    show-sub-caption: show-sub-caption,
+
+    grid(
+      ..figures.map(unwrap-figure),
+      ..grid-args,
+    ),
+  )
+}

test/example/default/test.typ

@@ -1,13 +1,13 @@
 #import "/test/util.typ": *
 
-#import "/src/lib.typ": subpar
+#import "/src/lib.typ": subpar, subpar-grid
 
 #outline(target: figure.where(kind: image))
 
 #figure(fake-image, caption: [aaa])
 
 #subpar(
-  grid(columns: (1fr, 1fr),
+  grid(columns: (1fr, 1fr), gutter: 1em, align: horizon,
     [#figure(fake-image, caption: [Inner caption]) <a>],
     [#figure(fake-image, caption: [Inner caption]) <b>],
   ),
@@ -20,11 +20,9 @@
   caption: [aaa],
 )
 
-#subpar(
-  grid(columns: (1fr, 1fr),
-    [#figure(`adas`, caption: [Inner caption]) <c>],
-    [#figure(fake-image, caption: [Inner caption]) <d>],
-  ),
+#subpar-grid(columns: (1fr, 1fr),
+  (figure(`adas`, caption: [Inner caption]), <c>),
+  (figure(fake-image, caption: [Inner caption]), <d>),
   caption: [Outer caption],
   label: <full2>,
 )