Changeset 61019

Timestamp:

10/21/2025 11:30:43 AM (4 months ago)

Author:

luisherranz

Message:

Interactivity API: Support for loadOnClientNavigation.

Uses the wp_script_attributes filter to add a data-wp-router-options directive with a loadOnClientNavigation: true property for all the interactive blocks that are compatible with client-side navigation to let the Interactivity API router determine which modules it can safely load during client-side navigation.

Props luisherranz, westonruter.
Fixes #64122.

Location:

trunk

Files:

• src/wp-includes/blocks.php (modified) (1 diff)
• src/wp-includes/interactivity-api/class-wp-interactivity-api.php (modified) (2 diffs)
• src/wp-includes/script-modules.php (modified) (1 diff)
• tests/phpunit/tests/blocks/register.php (modified) (1 diff)
• tests/phpunit/tests/interactivity-api/wpInteractivityAPI.php (modified) (3 diffs)
• tests/phpunit/tests/script-modules/wpScriptModules.php (modified) (1 diff)

trunk/src/wp-includes/blocks.php

@@ -176 +176 @@
     $module_version      = isset( $module_asset['version'] ) ? $module_asset['version'] : $block_version;
 
-    // Blocks using the Interactivity API are server-side rendered, so they are by design not in the critical rendering path and should be deprioritized.
+    $supports_interactivity_true = isset( $metadata['supports']['interactivity'] ) && true === $metadata['supports']['interactivity'];
+    $is_interactive              = $supports_interactivity_true || ( isset( $metadata['supports']['interactivity']['interactive'] ) && true === $metadata['supports']['interactivity']['interactive'] );
+    $supports_client_navigation  = $supports_interactivity_true || ( isset( $metadata['supports']['interactivity']['clientNavigation'] ) && true === $metadata['supports']['interactivity']['clientNavigation'] );
+
     $args = array();
-    if (
-        ( isset( $metadata['supports']['interactivity'] ) && true === $metadata['supports']['interactivity'] ) ||
-        ( isset( $metadata['supports']['interactivity']['interactive'] ) && true === $metadata['supports']['interactivity']['interactive'] )
-    ) {
+
+    // Blocks using the Interactivity API are server-side rendered, so they are
+    // by design not in the critical rendering path and should be deprioritized.
+    if ( $is_interactive ) {
         $args['fetchpriority'] = 'low';
         $args['in_footer']     = true;
+    }
+
+    // Blocks using the Interactivity API that support client-side navigation
+    // must be marked as such in their script modules.
+    if ( $is_interactive && $supports_client_navigation ) {
+        wp_interactivity()->add_client_navigation_support_to_script_module( $module_id );
     }
 

trunk/src/wp-includes/interactivity-api/class-wp-interactivity-api.php

@@ -87 +87 @@
 
     /**
+     * Set of script modules that can be loaded after client-side navigation.
+     *
+     * @since 6.9.0
+     * @var array<string, true>
+     */
+    private $script_modules_that_can_load_on_client_navigation = array();
+
+    /**
      * Stack of namespaces defined by `data-wp-interactive` directives, in
      * the order they are processed.
@@ -372 +380 @@
      *
      * @since 6.5.0
+     * @since 6.9.0 Adds support for client-side navigation in script modules.
      */
     public function add_hooks() {
         add_filter( 'script_module_data_@wordpress/interactivity', array( $this, 'filter_script_module_interactivity_data' ) );
         add_filter( 'script_module_data_@wordpress/interactivity-router', array( $this, 'filter_script_module_interactivity_router_data' ) );
+        add_filter( 'wp_script_attributes', array( $this, 'add_load_on_client_navigation_attribute_to_script_modules' ), 10, 1 );
+    }
+
+    /**
+     * Adds the `data-wp-router-options` attribute to script modules that
+     * support client-side navigation.
+     *
+     * This method filters the script attributes to include loading instructions
+     * for the Interactivity API router, indicating which modules can be loaded
+     * during client-side navigation.
+     *
+     * @since 6.9.0
+     *
+     * @param array<string, string|true>|mixed $attributes The script tag attributes.
+     * @return array The modified script tag attributes.
+     */
+    public function add_load_on_client_navigation_attribute_to_script_modules( $attributes ) {
+        if (
+            is_array( $attributes ) &&
+            isset( $attributes['type'], $attributes['id'] ) &&
+            'module' === $attributes['type'] &&
+            array_key_exists(
+                preg_replace( '/-js-module$/', '', $attributes['id'] ),
+                $this->script_modules_that_can_load_on_client_navigation
+            )
+        ) {
+            $attributes['data-wp-router-options'] = wp_json_encode( array( 'loadOnClientNavigation' => true ) );
+        }
+        return $attributes;
+    }
+
+    /**
+     * Marks a script module as compatible with client-side navigation.
+     *
+     * This method registers a script module to be loaded during client-side
+     * navigation in the Interactivity API router. Script modules marked with
+     * this method will have the `loadOnClientNavigation` option enabled in the
+     * `data-wp-router-options` directive.
+     *
+     * @since 6.9.0
+     *
+     * @param string $script_module_id The script module identifier.
+     */
+    public function add_client_navigation_support_to_script_module( string $script_module_id ) {
+        $this->script_modules_that_can_load_on_client_navigation[ $script_module_id ] = true;
     }
 

trunk/src/wp-includes/script-modules.php

@@ -203 +203 @@
         }
 
+        // Marks all Core blocks as compatible with client-side navigation.
+        if ( str_starts_with( $script_module_id, '@wordpress/block-library' ) ) {
+            wp_interactivity()->add_client_navigation_support_to_script_module( $script_module_id );
+        }
+
         $path = includes_url( "js/dist/script-modules/{$file_name}" );
         wp_register_script_module( $script_module_id, $path, $script_module_data['dependencies'], $script_module_data['version'], $args );

trunk/tests/phpunit/tests/blocks/register.php

@@ -428 +428 @@
             ) === 0
         );
+    }
+
+    /**
+     * Tests that blocks with supports.interactivity have the
+     * `data-wp-router-options` directive.
+     *
+     * @ticket 64122
+     *
+     * @covers ::register_block_script_module_id
+     */
+    public function test_register_block_script_module_id_with_interactivity_true() {
+        $metadata = array(
+            'file'             => DIR_TESTDATA . '/blocks/notice/block.json',
+            'viewScriptModule' => 'file:./block.js',
+        );
+
+        $interactivity_true                    = array_merge(
+            $metadata,
+            array(
+                'name'     => 'tests/interactivity-true',
+                'supports' => array( 'interactivity' => true ),
+            )
+        );
+        $interactive_and_client_navigation     = array_merge(
+            $metadata,
+            array(
+                'name'     => 'tests/interactive-and-client-navigation',
+                'supports' => array(
+                    'interactivity' => array(
+                        'interactive'      => true,
+                        'clientNavigation' => true,
+                    ),
+                ),
+            )
+        );
+        $interactive_and_not_client_navigation = array_merge(
+            $metadata,
+            array(
+                'name'     => 'tests/interactive-and-not-client-navigation',
+                'supports' => array(
+                    'interactivity' => array(
+                        'interactive'      => true,
+                        'clientNavigation' => false,
+                    ),
+                ),
+            )
+        );
+        $not_interactive_and_client_navigation = array_merge(
+            $metadata,
+            array(
+                'name'     => 'tests/not-interactive-and-client-navigation',
+                'supports' => array(
+                    'interactivity' => array(
+                        'interactive'      => false,
+                        'clientNavigation' => true,
+                    ),
+                ),
+            )
+        );
+        $no_interactivity                      = array_merge(
+            $metadata,
+            array(
+                'name'     => 'tests/no-interactivity',
+                'supports' => array(),
+            )
+        );
+
+        $interactivity_true_module_id                    = register_block_script_module_id( $interactivity_true, 'viewScriptModule' );
+        $interactive_and_client_navigation_module_id     = register_block_script_module_id( $interactive_and_client_navigation, 'viewScriptModule' );
+        $interactive_and_not_client_navigation_module_id = register_block_script_module_id( $interactive_and_not_client_navigation, 'viewScriptModule' );
+        $not_interactive_and_client_navigation_module_id = register_block_script_module_id( $not_interactive_and_client_navigation, 'viewScriptModule' );
+        $no_interactivity_module_id                      = register_block_script_module_id( $no_interactivity, 'viewScriptModule' );
+        wp_enqueue_script_module( $interactivity_true_module_id );
+        wp_enqueue_script_module( $interactive_and_client_navigation_module_id );
+        wp_enqueue_script_module( $interactive_and_not_client_navigation_module_id );
+        wp_enqueue_script_module( $not_interactive_and_client_navigation_module_id );
+        wp_enqueue_script_module( $no_interactivity_module_id );
+
+        $output = get_echo( array( wp_script_modules(), 'print_enqueued_script_modules' ) );
+
+        $p = new WP_HTML_Tag_Processor( $output );
+
+        $this->assertTrue( $p->next_tag( array( 'tag_name' => 'SCRIPT' ) ), 'Expected there to be another SCRIPT.' );
+        $this->assertSame( 'tests-interactivity-true-view-script-module-js-module', $p->get_attribute( 'id' ) );
+        $this->assertSame( '{"loadOnClientNavigation":true}', $p->get_attribute( 'data-wp-router-options' ) );
+
+        $this->assertTrue( $p->next_tag( array( 'tag_name' => 'SCRIPT' ) ), 'Expected there to be another SCRIPT.' );
+        $this->assertSame( 'tests-interactive-and-client-navigation-view-script-module-js-module', $p->get_attribute( 'id' ) );
+        $this->assertSame( '{"loadOnClientNavigation":true}', $p->get_attribute( 'data-wp-router-options' ) );
+
+        $this->assertTrue( $p->next_tag( array( 'tag_name' => 'SCRIPT' ) ), 'Expected there to be another SCRIPT.' );
+        $this->assertSame( 'tests-interactive-and-not-client-navigation-view-script-module-js-module', $p->get_attribute( 'id' ) );
+        $this->assertNull( $p->get_attribute( 'data-wp-router-options' ) );
+
+        $this->assertTrue( $p->next_tag( array( 'tag_name' => 'SCRIPT' ) ), 'Expected there to be another SCRIPT.' );
+        $this->assertSame( 'tests-not-interactive-and-client-navigation-view-script-module-js-module', $p->get_attribute( 'id' ) );
+        $this->assertNull( $p->get_attribute( 'data-wp-router-options' ) );
+
+        $this->assertTrue( $p->next_tag( array( 'tag_name' => 'SCRIPT' ) ), 'Expected there to be another SCRIPT.' );
+        $this->assertSame( 'tests-no-interactivity-view-script-module-js-module', $p->get_attribute( 'id' ) );
+        $this->assertNull( $p->get_attribute( 'data-wp-router-options' ) );
     }
 

trunk/tests/phpunit/tests/interactivity-api/wpInteractivityAPI.php

@@ -27 +27 @@
         $this->interactivity = new WP_Interactivity_API();
         wp_default_script_modules();
+        $this->interactivity->add_hooks();
+    }
+
+    /**
+     * Tear down.
+     */
+    public function tear_down() {
+        global $wp_script_modules;
+        parent::tear_down();
+        $wp_script_modules = null;
     }
 
@@ -237 +247 @@
      */
     private function get_script_data_filter_result( ?Closure $callback = null ): MockAction {
-        $this->interactivity->add_hooks();
         wp_enqueue_script_module( '@wordpress/interactivity' );
         $filter = new MockAction();
@@ -1724 +1733 @@
         $this->assertStringNotContainsString( 'class="[disallowed]"', $processed_html );
     }
+
+    /**
+     * Tests that add_client_navigation_support_to_script_module marks a
+     * script module for client navigation.
+     *
+     * @ticket 64122
+     *
+     * @covers WP_Interactivity_API::add_client_navigation_support_to_script_module
+     * @covers WP_Interactivity_API::add_load_on_client_navigation_attribute_to_script_modules
+     */
+    public function test_add_client_navigation_support_to_script_module() {
+        $this->interactivity->add_client_navigation_support_to_script_module( 'marked-module' );
+
+        wp_register_script_module( 'marked-module', '/marked.js' );
+        wp_register_script_module( 'unmarked-module', '/unmarked.js' );
+        wp_enqueue_script_module( 'marked-module' );
+        wp_enqueue_script_module( 'unmarked-module' );
+
+        $output = get_echo( array( wp_script_modules(), 'print_enqueued_script_modules' ) );
+
+        $p = new WP_HTML_Tag_Processor( $output );
+
+        // First module: marked-module should have the attribute.
+        $p->next_tag( array( 'tag_name' => 'SCRIPT' ) );
+        $this->assertSame( 'marked-module-js-module', $p->get_attribute( 'id' ) );
+        $this->assertSame(
+            '{"loadOnClientNavigation":true}',
+            $p->get_attribute( 'data-wp-router-options' )
+        );
+
+        // Second module: unmarked-module should NOT have the attribute.
+        $p->next_tag( array( 'tag_name' => 'SCRIPT' ) );
+        $this->assertSame( 'unmarked-module-js-module', $p->get_attribute( 'id' ) );
+        $this->assertNull( $p->get_attribute( 'data-wp-router-options' ) );
+    }
 }

trunk/tests/phpunit/tests/script-modules/wpScriptModules.php

@@ -1807 +1807 @@
             '
                 <script type="module" src="/wp-includes/js/dist/script-modules/a11y/index.min.js" id="@wordpress/a11y-js-module" fetchpriority="low"></script>
-                <script type="module" src="/wp-includes/js/dist/script-modules/block-library/navigation/view.min.js" id="@wordpress/block-library/navigation/view-js-module" fetchpriority="low"></script>
+                <script type="module" src="/wp-includes/js/dist/script-modules/block-library/navigation/view.min.js" id="@wordpress/block-library/navigation/view-js-module" fetchpriority="low" data-wp-router-options="{&quot;loadOnClientNavigation&quot;:true}"></script>
             ',
             $actual_footer_script_modules,