Merge branch 'release/0.8.75'

Author: ljonesfl

.version.json

@@ -2,6 +2,6 @@
   "strategy": "semver",
   "major": 0,
   "minor": 8,
-  "patch": 74,
+  "patch": 75,
   "build": 0
 }

src/Cms/Services/Widget/ContactFormWidget.php

@@ -154,7 +154,7 @@ private function renderField( array $field, string $idSuffix ): string
 		{
 			return '<div class="form-check mb-3">'
 				. '<input type="checkbox" class="form-check-input" id="' . $this->esc( $id ) . '" name="' . $this->esc( $name ) . '" value="1"' . $reqAttr . '>'
-				. '<label class="form-check-label" for="' . $this->esc( $id ) . '">' . $this->esc( $label ) . $reqMark . '</label>'
+				. '<label class="form-check-label" for="' . $this->esc( $id ) . '">' . $this->labelWithLink( $label, $field ) . $reqMark . '</label>'
 				. '</div>';
 		}
 
@@ -169,7 +169,7 @@ private function renderField( array $field, string $idSuffix ): string
 		}
 
 		$control = '<div class="mb-3">';
-		$control .= '<label class="form-label" for="' . $this->esc( $id ) . '">' . $this->esc( $label ) . $reqMark . '</label>';
+		$control .= '<label class="form-label" for="' . $this->esc( $id ) . '">' . $this->labelWithLink( $label, $field ) . $reqMark . '</label>';
 
 		switch( $type )
 		{
@@ -227,7 +227,7 @@ private function renderCheckboxes( array $field, string $idSuffix, string $name,
 		$groups = FieldOptions::groups( $field );
 
 		$html  = '<fieldset class="mb-3 contact-checkboxes">';
-		$html .= '<legend class="form-label fs-6">' . $this->esc( $label ) . $reqMark . '</legend>';
+		$html .= '<legend class="form-label fs-6">' . $this->labelWithLink( $label, $field ) . $reqMark . '</legend>';
 
 		foreach( $groups as $group )
 		{
@@ -274,7 +274,7 @@ private function renderRadios( array $field, string $idSuffix, string $name, str
 		$reqAttr = $required ? ' required' : '';
 
 		$html  = '<fieldset class="mb-3 contact-radios">';
-		$html .= '<legend class="form-label fs-6">' . $this->esc( $label ) . $reqMark . '</legend>';
+		$html .= '<legend class="form-label fs-6">' . $this->labelWithLink( $label, $field ) . $reqMark . '</legend>';
 
 		foreach( FieldOptions::groups( $field ) as $group )
 		{
@@ -382,6 +382,43 @@ private function session(): ?SessionManager
 		return $this->_sessionManager;
 	}
 
+	/**
+	 * Build a field's (escaped) label, optionally embedding a safe hyperlink.
+	 *
+	 * A field may declare a link via config:
+	 *
+	 *   link: { text: "Volunteer Agreement", url: "/pages/release-form" }
+	 *
+	 * Use the literal token "{link}" in the label to control placement; if the
+	 * token is absent the link is appended. Label text, link text and URL are
+	 * all escaped, so only this controlled anchor is ever injected as HTML.
+	 *
+	 * @param string $label
+	 * @param array $field
+	 * @return string
+	 */
+	private function labelWithLink( string $label, array $field ): string
+	{
+		$escaped = $this->esc( $label );
+		$link    = $field['link'] ?? null;
+
+		if( !is_array( $link ) || empty( $link['url'] ) )
+		{
+			return $escaped;
+		}
+
+		$url    = $this->esc( (string) $link['url'] );
+		$text   = $this->esc( (string) ( $link['text'] ?? $link['url'] ) );
+		$anchor = '<a href="' . $url . '" target="_blank" rel="noopener noreferrer">' . $text . '</a>';
+
+		if( str_contains( $escaped, '{link}' ) )
+		{
+			return str_replace( '{link}', $anchor, $escaped );
+		}
+
+		return $escaped . ' ' . $anchor;
+	}
+
 	/**
 	 * HTML-escape helper.
 	 *

tests/Unit/Cms/Services/Widget/ContactFormWidgetTest.php

@@ -37,7 +37,8 @@ private function widget(): ContactFormWidget
 								]
 							],
 							[ 'name' => 'contact_pref', 'label' => 'Preferred Contact', 'type' => 'radio', 'required' => true, 'options' => [ 'Email', 'Phone' ] ],
-							[ 'name' => 'start_date', 'label' => 'Start Date', 'type' => 'date', 'required' => false ]
+							[ 'name' => 'start_date', 'label' => 'Start Date', 'type' => 'date', 'required' => false ],
+							[ 'name' => 'agree', 'label' => 'I agree to the {link}', 'type' => 'checkbox', 'required' => true, 'link' => [ 'text' => 'Release Form', 'url' => '/pages/release-form' ] ]
 						]
 					]
 				]
@@ -110,6 +111,17 @@ public function testRadioAndDateFieldsRender(): void
 		$this->assertStringContainsString( 'name="start_date"', $html );
 	}
 
+	public function testCheckboxLabelEmbedsConfiguredLinkAtToken(): void
+	{
+		$html = $this->widget()->render( [] );
+
+		$this->assertStringContainsString( 'href="/pages/release-form"', $html );
+		$this->assertStringContainsString( 'target="_blank"', $html );
+		$this->assertStringContainsString( '>Release Form</a>', $html );
+		// The {link} token is replaced, not left as literal text.
+		$this->assertStringNotContainsString( '{link}', $html );
+	}
+
 	public function testTitleAndButtonCanBeOverriddenByAttributes(): void
 	{
 		$html = $this->widget()->render( [ 'title' => 'Custom Heading', 'button' => 'Go' ] );

versionlog.md

@@ -1,3 +1,5 @@
+## 0.8.75 2026-06-22
+
 ## 0.8.74 2026-06-22
 
 * Added multi select fields to forms.