Commit d7f1e03ff1e for woocommerce

commit d7f1e03ff1ee52630f1703015c5c9094f375b5eb
Author: Taha Paksu <3295+tpaksu@users.noreply.github.com>
Date:   Tue Nov 17 11:33:01 2026 +0300

    Match the block fulfillment email heading to the number of items (#71030)

    * [WOOPLUG-8256] Match the block fulfillment email heading to the item count

    * Add changefile(s) from automation for the following project(s): woocommerce

    * [WOOPLUG-8256] Stop the email editor stripping the heading tag

    * [WOOPLUG-8256] Cover the block template heading wiring with a test

    * [WOOPLUG-8256] Pin the template heading test to a sentinel heading

    ---------

    Co-authored-by: woocommercebot <woocommercebot@users.noreply.github.com>

diff --git a/plugins/woocommerce/changelog/71030-wooplug-8256-block-fulfillment-heading b/plugins/woocommerce/changelog/71030-wooplug-8256-block-fulfillment-heading
new file mode 100644
index 00000000000..ab2276d051f
--- /dev/null
+++ b/plugins/woocommerce/changelog/71030-wooplug-8256-block-fulfillment-heading
@@ -0,0 +1,4 @@
+Significance: patch
+Type: fix
+
+Match the heading to the number of items sent in fulfillment emails built with the email editor.
diff --git a/plugins/woocommerce/src/Internal/EmailEditor/PersonalizationTags/OrderTagsProvider.php b/plugins/woocommerce/src/Internal/EmailEditor/PersonalizationTags/OrderTagsProvider.php
index 08c6063e064..30922e8b23e 100644
--- a/plugins/woocommerce/src/Internal/EmailEditor/PersonalizationTags/OrderTagsProvider.php
+++ b/plugins/woocommerce/src/Internal/EmailEditor/PersonalizationTags/OrderTagsProvider.php
@@ -342,5 +342,26 @@ class OrderTagsProvider extends AbstractTagProvider {
 				Personalization_Tag::VALUE_TYPE_TEXT,
 			)
 		);
+
+		$registry->register(
+			new Personalization_Tag(
+				__( 'Fulfillment Heading', 'woocommerce' ),
+				'woocommerce/fulfillment-heading',
+				__( 'Order', 'woocommerce' ),
+				function ( array $context ): string {
+					$wc_email = $context['wc_email'] ?? null;
+					// The fulfillment emails are the only consumers of this tag.
+					if ( ! $wc_email instanceof \WC_Email || ! str_starts_with( $wc_email->id, 'customer_fulfillment_' ) ) {
+						return '';
+					}
+					// get_heading() returns filtered output, so it is cast rather than trusted.
+					return (string) $wc_email->get_heading();
+				},
+				array(),
+				null,
+				array( Integration::EMAIL_POST_TYPE ),
+				Personalization_Tag::VALUE_TYPE_TEXT,
+			)
+		);
 	}
 }
diff --git a/plugins/woocommerce/templates/emails/block/customer-fulfillment-created.php b/plugins/woocommerce/templates/emails/block/customer-fulfillment-created.php
index 0d01906d7e9..53b25d5dd0c 100644
--- a/plugins/woocommerce/templates/emails/block/customer-fulfillment-created.php
+++ b/plugins/woocommerce/templates/emails/block/customer-fulfillment-created.php
@@ -24,7 +24,7 @@ defined( 'ABSPATH' ) || exit;
 ?>

 <!-- wp:heading -->
-<h2 class="wp-block-heading"> <?php echo esc_html__( 'Your item is on the way!', 'woocommerce' ); ?> </h2>
+<h2 class="wp-block-heading"> <?php echo '<!--[woocommerce/fulfillment-heading]-->&nbsp;'; // The non-breaking space is used to prevent the comment from being removed by the email editor. ?> </h2>
 <!-- /wp:heading -->

 <!-- wp:paragraph -->
diff --git a/plugins/woocommerce/tests/php/src/Internal/EmailEditor/PersonalizationTags/OrderTagsProviderTest.php b/plugins/woocommerce/tests/php/src/Internal/EmailEditor/PersonalizationTags/OrderTagsProviderTest.php
index afcc6697e0d..534a13e69e2 100644
--- a/plugins/woocommerce/tests/php/src/Internal/EmailEditor/PersonalizationTags/OrderTagsProviderTest.php
+++ b/plugins/woocommerce/tests/php/src/Internal/EmailEditor/PersonalizationTags/OrderTagsProviderTest.php
@@ -3,10 +3,12 @@ declare( strict_types = 1 );

 namespace Automattic\WooCommerce\Tests\Internal\EmailEditor\PersonalizationTags;

+use Automattic\WooCommerce\Admin\Features\Fulfillments\Fulfillment;
 use Automattic\WooCommerce\EmailEditor\Engine\Logger\Email_Editor_Logger;
 use Automattic\WooCommerce\EmailEditor\Engine\PersonalizationTags\Personalization_Tags_Registry;
 use Automattic\WooCommerce\EmailEditor\Engine\Personalizer;
 use Automattic\WooCommerce\Internal\EmailEditor\PersonalizationTags\OrderTagsProvider;
+use Automattic\WooCommerce\Internal\EmailEditor\WCTransactionalEmails\WCTransactionalEmailPostsGenerator;
 use WC_Helper_Order;
 use WC_Unit_Test_Case;

@@ -101,4 +103,130 @@ class OrderTagsProviderTest extends WC_Unit_Test_Case {

 		$this->assertSame( '<p>&lt;b&gt;Leave&lt;/b&gt; at the door</p>', $html );
 	}
+
+	/**
+	 * @testdox Registers the fulfillment heading tag.
+	 */
+	public function test_registers_fulfillment_heading_tag(): void {
+		$tag = $this->registry->get_by_token( '[woocommerce/fulfillment-heading]' );
+
+		$this->assertNotNull( $tag, 'The fulfillment heading tag should be registered.' );
+		$this->assertSame( __( 'Order', 'woocommerce' ), $tag->get_category() );
+	}
+
+	/**
+	 * @testdox The fulfillment heading tag uses the plural heading when the fulfillment has several items.
+	 */
+	public function test_fulfillment_heading_tag_uses_plural_heading(): void {
+		$email = $this->create_fulfillment_email( 2 );
+
+		$heading = $this->registry->get_by_token( '[woocommerce/fulfillment-heading]' )->execute_callback( array( 'wc_email' => $email ) );
+
+		$this->assertSame( 'Your items are on the way!', $heading );
+	}
+
+	/**
+	 * @testdox The fulfillment heading tag uses the singular heading when the fulfillment has one item.
+	 */
+	public function test_fulfillment_heading_tag_uses_singular_heading(): void {
+		$email = $this->create_fulfillment_email( 1 );
+
+		$heading = $this->registry->get_by_token( '[woocommerce/fulfillment-heading]' )->execute_callback( array( 'wc_email' => $email ) );
+
+		$this->assertSame( 'Your item is on the way!', $heading );
+	}
+
+	/**
+	 * @testdox The fulfillment heading tag returns an empty string for an email that is not about a fulfillment.
+	 */
+	public function test_fulfillment_heading_tag_for_another_email_type(): void {
+		$bootstrap = \WC_Unit_Tests_Bootstrap::instance();
+		require_once $bootstrap->plugin_dir . '/includes/emails/class-wc-email.php';
+		require_once $bootstrap->plugin_dir . '/includes/emails/class-wc-email-customer-completed-order.php';
+
+		$heading = $this->registry->get_by_token( '[woocommerce/fulfillment-heading]' )->execute_callback( array( 'wc_email' => new \WC_Email_Customer_Completed_Order() ) );
+
+		$this->assertSame( '', $heading );
+	}
+
+	/**
+	 * @testdox The fulfillment heading tag escapes the heading exactly once in HTML.
+	 */
+	public function test_fulfillment_heading_tag_escapes_the_heading_once_in_html(): void {
+		$email  = $this->create_fulfillment_email( 1 );
+		$filter = function () {
+			return 'Packed & ready';
+		};
+		add_filter( 'woocommerce_email_heading_customer_fulfillment_created', $filter );
+
+		$personalizer = new Personalizer( $this->registry );
+		$personalizer->set_context( array( 'wc_email' => $email ) );
+
+		$html = $personalizer->personalize_content( '<h2><!--[woocommerce/fulfillment-heading]--></h2>' );
+
+		remove_filter( 'woocommerce_email_heading_customer_fulfillment_created', $filter );
+
+		$this->assertSame( '<h2>Packed &amp; ready</h2>', $html );
+	}
+
+	/**
+	 * @testdox The block fulfillment created template takes its heading from the tag.
+	 */
+	public function test_block_template_heading_comes_from_the_tag(): void {
+		$email = $this->create_fulfillment_email( 2 );
+
+		// A heading no template could contain, so the assertion fails if the markup carries its own.
+		$filter = function () {
+			return 'Heading taken from the email';
+		};
+		add_filter( 'woocommerce_email_heading_customer_fulfillment_created', $filter );
+
+		$markup       = WCTransactionalEmailPostsGenerator::render_block_template_html( $email );
+		$personalizer = new Personalizer( $this->registry );
+		$personalizer->set_context( array( 'wc_email' => $email ) );
+		$html = $personalizer->personalize_content( $markup );
+
+		remove_filter( 'woocommerce_email_heading_customer_fulfillment_created', $filter );
+
+		$this->assertStringContainsString( 'Heading taken from the email', $html );
+	}
+
+	/**
+	 * @testdox The fulfillment heading tag returns an empty string without email context.
+	 */
+	public function test_fulfillment_heading_tag_without_email_context(): void {
+		$tag = $this->registry->get_by_token( '[woocommerce/fulfillment-heading]' );
+
+		$this->assertSame( '', $tag->execute_callback( array() ) );
+	}
+
+	/**
+	 * Build a triggered fulfillment created email whose fulfillment covers the order at the given quantity.
+	 *
+	 * @param int $quantity Quantity fulfilled per order item.
+	 * @return \WC_Email_Customer_Fulfillment_Created
+	 */
+	private function create_fulfillment_email( int $quantity ): \WC_Email_Customer_Fulfillment_Created {
+		$bootstrap = \WC_Unit_Tests_Bootstrap::instance();
+		require_once $bootstrap->plugin_dir . '/includes/emails/class-wc-email.php';
+		require_once $bootstrap->plugin_dir . '/includes/emails/class-wc-email-customer-fulfillment-created.php';
+
+		$order = WC_Helper_Order::create_order();
+		$items = array();
+		foreach ( array_keys( $order->get_items() ) as $item_id ) {
+			$items[] = array(
+				'item_id' => $item_id,
+				'qty'     => $quantity,
+			);
+		}
+
+		$fulfillment = new Fulfillment();
+		$fulfillment->set_items( $items );
+
+		// The fulfillment is private on the email, so triggering is the only way to attach it.
+		$email = new \WC_Email_Customer_Fulfillment_Created();
+		$email->trigger( $order->get_id(), $fulfillment, $order );
+
+		return $email;
+	}
 }