fix: render labs(tag:) above the title (#58)

Author: mcanouil

CHANGELOG.md

@@ -12,6 +12,7 @@
 - feat: `labs()` fields default to `auto`; pass `none` to suppress an axis or legend title and reclaim the space it reserved. (#12)
 - feat: `element-blank()` on a text surface (axis, plot, or legend title) collapses the space the text would reserve. (#12)
 - feat: `width`/`height` accept `auto` to fill the available space of a bounded container. (#10)
+- fix: `labs(tag:)` draws the figure tag above the title on a standalone plot, styled by the `plot-tag` theme element, instead of being ignored. (#58)
 - fix: `labs(alt:)` fills in the figure's accessibility alt text when `plot(alt:)` is unset, instead of being stored and ignored. (#57)
 - fix: `geom-qq()`/`geom-qq-line()` honour the `distribution` argument (`uniform`/`exponential`) instead of always plotting against the normal reference. (#56)
 - fix: the `font` set on `element-text`/`element-typst`/`element-geom` is applied to every text surface and to the text-drawing geoms, inheriting the base `text` font when unset. (#54)

docs/examples/gallery.yml

@@ -23,6 +23,12 @@
   description: 'Title, subtitle, caption, and axis labels set in a single [`labs`](../reference/labs/labs.qmd) call.'
   alt: "Scatter and line chart of count against month showing a rising trend, framed by a title, subtitle, caption, and axis labels."
 
+- slug: labs-tag
+  section: basics
+  title: "Figure tag"
+  description: 'A figure tag drawn above the title via [`labs`](../reference/labs/labs.qmd) `tag`, styled by the `plot-tag` theme element.'
+  alt: "Scatter plot of highway fuel economy against engine displacement, marked with a bold 'A' tag above the title and subtitle."
+
 - slug: factor-inline
   section: basics
   title: "Inline factor coercion"

examples/labs-tag.typ

@@ -0,0 +1,21 @@
+// A figure tag drawn above the title, styled by the plot-tag theme element.
+
+#import "../lib.typ": *
+
+#set page(width: auto, height: auto, margin: 0cm)
+
+#plot(
+  data: mpg,
+  mapping: aes(x: "displ", y: "hwy"),
+  layers: (geom-point(size: 2.5pt, alpha: 0.75),),
+  labs: labs(
+    tag: "A",
+    title: "Engine Displacement Versus Highway Fuel Economy",
+    subtitle: "One panel of a larger figure",
+    x: "Displacement (L)",
+    y: "Highway mpg",
+  ),
+  theme: theme-minimal(),
+  width: 12cm,
+  height: 9cm,
+)

src/render.typ

@@ -3069,6 +3069,7 @@
       - outer-pad.right
       - inner-inset.right
   )
+  let tag = _text-style(theme, "plot-tag")
   let title = _text-style(theme, "plot-title")
   let subtitle = _text-style(theme, "plot-subtitle")
   let caption = _text-style(theme, "plot-caption")
@@ -3093,6 +3094,9 @@
       ),
     )
   } else { none }
+  let tag-block = if labs != none {
+    _chrome-block(labs.tag, tag, left, weight: tag.weight)
+  } else { none }
   let title-block = if labs != none {
     _chrome-block(labs.title, title, left, weight: title.weight)
   } else { none }
@@ -3109,17 +3113,22 @@
     _text-margin-cm(style, side, 0.6em) * 1cm
   }
 
+  // Bottom margin of the lowest header block sets the gap above the canvas.
   let above-canvas = if subtitle-block != none {
     subtitle
-  } else if title-block != none { title } else { none }
+  } else if title-block != none {
+    title
+  } else if tag-block != none { tag } else { none }
 
   (
     plot-bg: plot-bg,
     outer-pad: outer-pad,
     inner-inset: inner-inset,
+    tag-block: tag-block,
     title-block: title-block,
     subtitle-block: subtitle-block,
     caption-block: caption-block,
+    tag-gap: _gap-length(tag, "bottom"),
     inter-title-gap: _gap-length(title, "bottom"),
     above-gap: if above-canvas != none {
       _gap-length(above-canvas, "bottom")
@@ -3134,14 +3143,26 @@
 #let _decorate-extents(parts) = {
   let _h(b) = if b == none { 0cm } else { measure(b).height }
   let top = parts.outer-pad.top + parts.inner-inset.top
-  if parts.title-block != none { top += _h(parts.title-block) }
+  let headers = 0
+  if parts.tag-block != none {
+    top += _h(parts.tag-block)
+    headers += 1
+  }
+  if parts.title-block != none {
+    if headers > 0 { top += parts.tag-gap }
+    top += _h(parts.title-block)
+    headers += 1
+  }
   if parts.subtitle-block != none {
-    if parts.title-block != none { top += parts.inter-title-gap }
+    if headers > 0 {
+      top += if parts.title-block != none { parts.inter-title-gap } else {
+        parts.tag-gap
+      }
+    }
     top += _h(parts.subtitle-block)
+    headers += 1
   }
-  if parts.title-block != none or parts.subtitle-block != none {
-    top += parts.above-gap
-  }
+  if headers > 0 { top += parts.above-gap }
   let bottom = parts.outer-pad.bottom + parts.inner-inset.bottom
   if parts.caption-block != none {
     bottom += parts.caption-gap + _h(parts.caption-block)
@@ -3181,19 +3202,26 @@
       ),
     )
   } else { content }
+  let tag-block = parts.tag-block
   let title-block = parts.title-block
   let subtitle-block = parts.subtitle-block
   let caption-block = parts.caption-block
 
   let items = ()
-  if title-block != none { items.push(title-block) }
+  if tag-block != none { items.push(tag-block) }
+  if title-block != none {
+    if items.len() > 0 { items.push(v(parts.tag-gap)) }
+    items.push(title-block)
+  }
   if subtitle-block != none {
-    if items.len() > 0 { items.push(v(parts.inter-title-gap)) }
+    if items.len() > 0 {
+      items.push(v(if title-block != none { parts.inter-title-gap } else {
+        parts.tag-gap
+      }))
+    }
     items.push(subtitle-block)
   }
-  if title-block != none or subtitle-block != none {
-    items.push(v(parts.above-gap))
-  }
+  if items.len() > 0 { items.push(v(parts.above-gap)) }
   items.push(canvas)
   if caption-block != none {
     items.push(v(parts.caption-gap))