Merge branch 'main' into fix/text-angle-wiring

# Conflicts:
#	CHANGELOG.md

Author: mcanouil

CHANGELOG.md

@@ -13,6 +13,8 @@
 - 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: `element-text(angle:)`/`element-typst(angle:)` rotate axis tick labels (seeding the `guide-axis(angle:)` default) and the plot title, subtitle, and caption, instead of being ignored. (#59)
+- 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)
 - fix: a `stage`/`after-scale` channel now trains its scale on the marker's source column, so the closure receives the channel's scale-resolved value as documented. (#52)

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/plot.typ

@@ -1,6 +1,18 @@
 #import "render.typ": render-plot
 #import "data.typ": _normalise-data
 
+// Effective alt text: an explicit `plot(alt:)` wins; otherwise a `labs(alt:)`
+// fills in (its `auto` default and `none` both count as unset), so the labs
+// field reaches `get-alt-text` instead of being dropped.
+#let _resolve-alt(alt, labs) = {
+  if alt != none { return alt }
+  if labs != none {
+    let labs-alt = labs.at("alt", default: auto)
+    if labs-alt != auto and labs-alt != none { return labs-alt }
+  }
+  none
+}
+
 /// Compose a layered plot from data, aesthetics, and geom layers.
 ///
 /// `plot` is the entry point of the grammar: it resolves the dataset, wires up
@@ -104,6 +116,7 @@
   strict: false,
   defer: false,
 ) = {
+  let alt = _resolve-alt(alt, labs)
   // Deferred plots skip the context block because `context` returns
   // content; compose() resolves the active theme from its own context
   // before handing the spec to the renderer.

src/render.typ

@@ -3093,6 +3093,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")
@@ -3113,6 +3114,9 @@
     if style.angle != none { body = rotate(style.angle, reflow: true, body) }
     box(width: inner-w, align(a, body))
   } 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 }
@@ -3129,17 +3133,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")
@@ -3154,14 +3163,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)
@@ -3201,19 +3222,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))

tests/unit/test-labs-alt.typ

@@ -0,0 +1,20 @@
+// `_resolve-alt`: plot(alt:) wins, else labs(alt:) fills in.
+
+#import "../../src/plot.typ": _resolve-alt
+#import "../../src/labs.typ": labs
+
+// --- explicit plot alt wins over a labs alt -------------------------------
+
+#assert.eq(_resolve-alt("explicit", labs(alt: "from labs")), "explicit")
+
+// --- labs alt fills in when plot alt is unset -----------------------------
+
+#assert.eq(_resolve-alt(none, labs(alt: "from labs")), "from labs")
+
+// --- both unset resolves to none ------------------------------------------
+// labs(alt:) defaults to `auto`, which counts as unset.
+
+#assert.eq(_resolve-alt(none, labs(title: "t")), none)
+#assert.eq(_resolve-alt(none, none), none)
+
+Labs alt tests passed.