text: rel attribute for relative text positioning

Author: codedstructure

CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+- Added: `<text>` elements can now have a `rel` attribute pointing to another
+  element which provides the bounding box for the new text element, and as the
+  basis for attributes such as `text-loc`. This feature makes it easier to
+  position multiple text elements relative to an element.
+
 ## [0.27.0 - 2026-02-06]
 
 - Changed: `<line>` based connectors are now axis-aligned by default where

src/elements/element.rs

@@ -438,7 +438,7 @@ impl SvgElement {
         let phantom = matches!(self.name(), "point" | "box");
 
         if self.has_attr("text") {
-            let (orig_elem, text_elements) = process_text_attr(self)?;
+            let (orig_elem, text_elements) = process_text_attr(self, ctx)?;
 
             if orig_elem.name != "text" && !phantom {
                 // We only care about the original element if it wasn't a text element

src/elements/text.rs

@@ -1,6 +1,7 @@
 use super::SvgElement;
+use crate::context::ElementMap;
 use crate::geometry::LocSpec;
-use crate::types::{attr_split_cycle, fstr, strp};
+use crate::types::{attr_split_cycle, fstr, strp, ElRef};
 
 use crate::errors::{Error, Result};
 
@@ -36,7 +37,10 @@ fn text_string(text_value: &str) -> String {
     result
 }
 
-fn get_text_position(element: &mut SvgElement) -> Result<(f32, f32, bool, LocSpec, Vec<String>)> {
+fn get_text_position(
+    element: &mut SvgElement,
+    ctx: &impl ElementMap,
+) -> Result<(f32, f32, bool, LocSpec, Vec<String>)> {
     let mut t_dx = 0.;
     let mut t_dy = 0.;
     {
@@ -60,6 +64,19 @@ fn get_text_position(element: &mut SvgElement) -> Result<(f32, f32, bool, LocSpe
         }
     }
 
+    // If a 'rel' attribute is present on a <text> element, resolve it to
+    // determine the bounding box and element type (for inside/outside default).
+    let mut text_ref_element = element.clone();
+    if element.name() == "text" {
+        if let Some(ref_str) = element.pop_attr("rel") {
+            let elref: ElRef = ref_str.parse()?;
+            text_ref_element = ctx
+                .get_element(&elref)
+                .ok_or_else(|| Error::Reference(elref))?
+                .clone();
+        }
+    }
+
     let mut text_classes = vec!["d-text".to_owned()];
     let text_loc_str = element.pop_attr("text-loc").unwrap_or("c".into());
     let text_anchor = text_loc_str.parse::<LocSpec>()?;
@@ -79,7 +96,7 @@ fn get_text_position(element: &mut SvgElement) -> Result<(f32, f32, bool, LocSpe
     } else if element.pop_class("d-text-inside") {
         false
     } else {
-        matches!(element.name(), "line" | "point" | "text")
+        matches!(text_ref_element.name(), "line" | "point" | "text")
     };
     match text_anchor {
         ls if ls.is_top() => {
@@ -140,7 +157,7 @@ fn get_text_position(element: &mut SvgElement) -> Result<(f32, f32, bool, LocSpe
     // Assumption is that text should be centered within the rect,
     // and has styling via CSS to reflect this, e.g.:
     //  text.d-text { dominant-baseline: central; text-anchor: middle; }
-    let (mut tdx, mut tdy) = element
+    let (mut tdx, mut tdy) = text_ref_element
         .bbox()?
         .ok_or_else(|| Error::MissingBBox(element.to_string()))?
         .locspec(text_anchor);
@@ -150,7 +167,10 @@ fn get_text_position(element: &mut SvgElement) -> Result<(f32, f32, bool, LocSpe
     Ok((tdx, tdy, outside, text_anchor, text_classes))
 }
 
-pub fn process_text_attr(element: &SvgElement) -> Result<(SvgElement, Vec<SvgElement>)> {
+pub fn process_text_attr(
+    element: &SvgElement,
+    ctx: &impl ElementMap,
+) -> Result<(SvgElement, Vec<SvgElement>)> {
     // Different conversions from line count to first-line offset based on whether
     // top, center, or bottom justification.
     const WRAP_DOWN: fn(usize, f32) -> f32 = |_count, _spacing| 0.;
@@ -164,7 +184,7 @@ pub fn process_text_attr(element: &SvgElement) -> Result<(SvgElement, Vec<SvgEle
 
     let text_value = get_text_value(&mut orig_elem);
 
-    let (tdx, tdy, outside, text_loc, mut text_classes) = get_text_position(&mut orig_elem)?;
+    let (tdx, tdy, outside, text_loc, mut text_classes) = get_text_position(&mut orig_elem, ctx)?;
 
     let x_str = fstr(tdx);
     let y_str = fstr(tdy);

tests/integration_tests/text_attr.rs

@@ -614,3 +614,115 @@ fn test_multiline_outside() {
         expected.trim()
     );
 }
+
+#[test]
+fn test_text_rel_centered() {
+    // text element with rel should position text at center of referenced element
+    let input = r##"
+<rect id="r" xy="10 20" wh="100 50"/>
+<text rel="#r" text="hello"/>
+"##;
+    let expected = r##"
+<rect id="r" x="10" y="20" width="100" height="50"/>
+<text x="60" y="45" class="d-text">hello</text>
+"##;
+    assert_eq!(
+        transform_str_default(input).unwrap().trim(),
+        expected.trim()
+    );
+}
+
+#[test]
+fn test_text_rel_with_text_loc() {
+    // text-loc should position text at the top of the rect bbox;
+    // since referenced element is a rect, text defaults to 'inside'
+    let input = r##"
+<rect id="r" xy="10 20" wh="100 50"/>
+<text rel="#r" text="top" text-loc="t"/>
+"##;
+    let expected = r##"
+<rect id="r" x="10" y="20" width="100" height="50"/>
+<text x="60" y="21" class="d-text d-text-top">top</text>
+"##;
+    assert_eq!(
+        transform_str_default(input).unwrap().trim(),
+        expected.trim()
+    );
+}
+
+#[test]
+fn test_text_rel_outside() {
+    // explicit d-text-outside class should push text outside the rect
+    let input = r##"
+<rect id="r" xy="10 20" wh="100 50"/>
+<text rel="#r" text="above" text-loc="t" class="d-text-outside"/>
+"##;
+    let expected = r##"
+<rect id="r" x="10" y="20" width="100" height="50"/>
+<text x="60" y="19" class="d-text d-text-bottom">above</text>
+"##;
+    assert_eq!(
+        transform_str_default(input).unwrap().trim(),
+        expected.trim()
+    );
+}
+
+#[test]
+fn test_text_rel_line_outside_default() {
+    // relative to line element should default to 'outside'
+    let input = r##"
+<line id="l1" xy1="0 0" xy2="100 0"/>
+<text rel="#l1" text="label" text-loc="t"/>
+"##;
+    let expected = r##"
+<line id="l1" x1="0" y1="0" x2="100" y2="0"/>
+<text x="50" y="-1" class="d-text d-text-bottom">label</text>
+"##;
+    assert_eq!(
+        transform_str_default(input).unwrap().trim(),
+        expected.trim()
+    );
+}
+
+#[test]
+fn test_text_rel_prev_element() {
+    // Use ^ (previous element) as rel
+    let input = r##"
+<rect xy="10 20" wh="100 50"/>
+<text rel="^" text="prev"/>
+"##;
+    let expected = r##"
+<rect x="10" y="20" width="100" height="50"/>
+<text x="60" y="45" class="d-text">prev</text>
+"##;
+    assert_eq!(
+        transform_str_default(input).unwrap().trim(),
+        expected.trim()
+    );
+}
+
+#[test]
+fn test_text_rel_nonexistent() {
+    // reference to nonexistent element should error
+    let input = r##"
+<text rel="#nonexistent" text="fail"/>
+"##;
+    assert!(transform_str_default(input).is_err());
+}
+
+#[test]
+fn test_text_rel_bottom_right() {
+    // Test bottom-right loc on text rel (inside default)
+    let input = r##"
+<rect id="r" xy="0" wh="100 50"/>
+<text rel="#r" text="br" text-loc="br"/>
+"##;
+    let expected = r##"
+<rect id="r" x="0" y="0" width="100" height="50"/>
+<text x="99" y="49" class="d-text d-text-bottom d-text-right">br</text>
+"##;
+    assert_eq!(
+        transform_str_default(input).unwrap().trim(),
+        expected.trim()
+    );
+}