Changeset 61469

Timestamp:

01/11/2026 06:34:57 AM (5 weeks ago)

Author:

westonruter

Message:

Themes: Use WP_HTML_Tag_Processor to insert the block template skip link instead of JavaScript.

• The skip link now works when JavaScript is turned off.
• By removing the script, the amount of JavaScript sent to the client is reduced for a very marginal performance improvement.
• A new wp-block-template-skip-link stylesheet is registered, with minification and path data for inlining.
• The CSS for the skip link now has an RTL version generated, although it is not yet served when the styles are inlined. See #61625.
• The wp_enqueue_block_template_skip_link() function now exclusively enqueues the stylesheet since the script is removed.
• For backwards-compatibility, the skip link will continue to be omitted if the_block_template_skip_link() is unhooked from the wp_footer action or wp_enqueue_block_template_skip_link() is unhooked from wp_enqueue_scripts.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/10676

Follow-up to [56932], [51003].

Props rutviksavsani, westonruter, dmsnell, whiteshadow01, Slieptsov.
See #59505, #53176.
Fixes #64361.

Location:

trunk

Files:

• src/wp-includes/block-template.php (modified) (1 diff)
• src/wp-includes/css/wp-block-template-skip-link.css (added)
• src/wp-includes/script-loader.php (modified) (2 diffs)
• src/wp-includes/theme-templates.php (modified) (2 diffs)
• tests/phpunit/tests/block-template-utils.php (modified) (1 diff)
• tests/phpunit/tests/block-template.php (modified) (1 diff)
• tests/phpunit/tests/template.php (modified) (1 diff)

trunk/src/wp-includes/block-template.php

@@ -302 +302 @@
     // Wrap block template in .wp-site-blocks to allow for specific descendant styles
     // (e.g. `.wp-site-blocks > *`).
-    return '<div class="wp-site-blocks">' . $content . '</div>';
+    $template_html = '<div class="wp-site-blocks">' . $content . '</div>';
+
+    // Back-compat for plugins that disable functionality by unhooking one of these actions.
+    if (
+        ! has_action( 'wp_footer', 'the_block_template_skip_link' ) ||
+        ! has_action( 'wp_enqueue_scripts', 'wp_enqueue_block_template_skip_link' )
+    ) {
+        return $template_html;
+    }
+
+    return _block_template_add_skip_link( $template_html );
+}
+
+/**
+ * Inserts the block template skip-link into the template HTML.
+ *
+ * When a `MAIN` element exists in the template, this function will ensure
+ * that the element contains an `id` attribute, and it will insert a link to
+ * that `MAIN` element before the first `DIV.wp-site-blocks` element, which
+ * is the wrapper for all blocks in a block template as constructed by
+ * {@see get_the_block_template_html()}.
+ *
+ * Example:
+ *
+ *     // Input.
+ *     <div class="wp-site-blocks">
+ *         <nav>...</nav>
+ *         <main>
+ *             <h2>...
+ *
+ *     // Output.
+ *     <a href="#wp--skip-link--target" id="wp-skip-link" class="...">
+ *     <div class="wp-site-blocks">
+ *         <nav>...</nav>
+ *         <main id="wp--skip-link--target">
+ *             <h2>...
+ *
+ * When the `MAIN` element already contains a non-empty `id` value it will be
+ * used instead of the default skip-link id.
+ *
+ * @access private
+ * @since 7.0.0
+ *
+ * @param string $template_html Block template markup.
+ * @return string Modified markup with skip link when applicable.
+ */
+function _block_template_add_skip_link( string $template_html ): string {
+    // Anonymous subclass of WP_HTML_Tag_Processor to access protected bookmark spans.
+    $processor = new class( $template_html ) extends WP_HTML_Tag_Processor {
+        /**
+         * Inserts text before the current token.
+         *
+         * @param string $text Text to insert.
+         */
+        public function insert_before( string $text ) {
+            $this->set_bookmark( 'here' );
+            $this->lexical_updates[] = new WP_HTML_Text_Replacement( $this->bookmarks['here']->start, 0, $text );
+        }
+    };
+
+    // Find and bookmark the first DIV.wp-site-blocks.
+    if (
+        ! $processor->next_tag(
+            array(
+                'tag_name'   => 'DIV',
+                'class_name' => 'wp-site-blocks',
+            )
+        )
+    ) {
+        return $template_html;
+    }
+    $processor->set_bookmark( 'skip_link_insertion_point' );
+
+    // Ensure the MAIN element has an ID.
+    if ( ! $processor->next_tag( 'MAIN' ) ) {
+        return $template_html;
+    }
+
+    $skip_link_target_id = $processor->get_attribute( 'id' );
+    if ( ! is_string( $skip_link_target_id ) || '' === $skip_link_target_id ) {
+        $skip_link_target_id = 'wp--skip-link--target';
+        $processor->set_attribute( 'id', $skip_link_target_id );
+    }
+
+    // Seek back to the bookmarked insertion point.
+    $processor->seek( 'skip_link_insertion_point' );
+
+    $skip_link = sprintf(
+        '<a class="skip-link screen-reader-text" id="wp-skip-link" href="%s">%s</a>',
+        esc_url( '#' . $skip_link_target_id ),
+        /* translators: Hidden accessibility text. */
+        esc_html__( 'Skip to content' )
+    );
+    $processor->insert_before( $skip_link );
+
+    return $processor->get_updated_html();
 }
 

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

@@ -1606 +1606 @@
     $styles->add( 'customize-preview', "/wp-includes/css/customize-preview$suffix.css", array( 'dashicons' ) );
     $styles->add( 'wp-empty-template-alert', "/wp-includes/css/wp-empty-template-alert$suffix.css" );
+    $skip_link_style_path = WPINC . "/css/wp-block-template-skip-link$suffix.css";
+    $styles->add( 'wp-block-template-skip-link', "/$skip_link_style_path" );
+    $styles->add_data( 'wp-block-template-skip-link', 'path', ABSPATH . $skip_link_style_path );
 
     // External libraries and friends.
@@ -1801 +1804 @@
         'wp-pointer',
         'wp-jquery-ui-dialog',
+        'wp-block-template-skip-link',
         // Package styles.
         'wp-reset-editor-styles',

trunk/src/wp-includes/theme-templates.php

@@ -100 +100 @@
 
 /**
- * Enqueues the skip-link script & styles.
+ * Enqueues the skip-link styles.
  *
  * @access private
  * @since 6.4.0
+ * @since 7.0.0 A script is no longer printed in favor of being added via {@see _block_template_add_skip_link()}.
  *
  * @global string $_wp_current_template_content
@@ -126 +127 @@
     }
 
-    $skip_link_styles = '
-        .skip-link.screen-reader-text {
-            border: 0;
-            clip-path: inset(50%);
-            height: 1px;
-            margin: -1px;
-            overflow: hidden;
-            padding: 0;
-            position: absolute !important;
-            width: 1px;
-            word-wrap: normal !important;
-        }
-
-        .skip-link.screen-reader-text:focus {
-            background-color: #eee;
-            clip-path: none;
-            color: #444;
-            display: block;
-            font-size: 1em;
-            height: auto;
-            left: 5px;
-            line-height: normal;
-            padding: 15px 23px 14px;
-            text-decoration: none;
-            top: 5px;
-            width: auto;
-            z-index: 100000;
-        }';
-
-    $handle = 'wp-block-template-skip-link';
-
-    /**
-     * Print the skip-link styles.
-     */
-    wp_register_style( $handle, false );
-    wp_add_inline_style( $handle, $skip_link_styles );
-    wp_enqueue_style( $handle );
-
-    /**
-     * Enqueue the skip-link script.
-     */
-    ob_start();
-    ?>
-    <script>
-    ( function() {
-        var skipLinkTarget = document.querySelector( 'main' ),
-            sibling,
-            skipLinkTargetID,
-            skipLink;
-
-        // Early exit if a skip-link target can't be located.
-        if ( ! skipLinkTarget ) {
-            return;
-        }
-
-        /*
-         * Get the site wrapper.
-         * The skip-link will be injected in the beginning of it.
-         */
-        sibling = document.querySelector( '.wp-site-blocks' );
-
-        // Early exit if the root element was not found.
-        if ( ! sibling ) {
-            return;
-        }
-
-        // Get the skip-link target's ID, and generate one if it doesn't exist.
-        skipLinkTargetID = skipLinkTarget.id;
-        if ( ! skipLinkTargetID ) {
-            skipLinkTargetID = 'wp--skip-link--target';
-            skipLinkTarget.id = skipLinkTargetID;
-        }
-
-        // Create the skip link.
-        skipLink = document.createElement( 'a' );
-        skipLink.classList.add( 'skip-link', 'screen-reader-text' );
-        skipLink.id = 'wp-skip-link';
-        skipLink.href = '#' + skipLinkTargetID;
-        skipLink.innerText = '<?php /* translators: Hidden accessibility text. Do not use HTML entities (&nbsp;, etc.). */ esc_html_e( 'Skip to content' ); ?>';
-
-        // Inject the skip link.
-        sibling.parentElement.insertBefore( skipLink, sibling );
-    }() );
-    </script>
-    <?php
-    $skip_link_script = wp_remove_surrounding_empty_script_tags( ob_get_clean() );
-    $script_handle    = 'wp-block-template-skip-link';
-    wp_register_script( $script_handle, false, array(), false, array( 'in_footer' => true ) );
-    wp_add_inline_script( $script_handle, $skip_link_script );
-    wp_enqueue_script( $script_handle );
+    wp_enqueue_style( 'wp-block-template-skip-link' );
 }
 

trunk/tests/phpunit/tests/block-template-utils.php

@@ -299 +299 @@
 
     /**
+     * Tests that a skip link is added and a MAIN element without an ID receives the default ID.
+     *
+     * @ticket 64361
+     *
+     * @covers ::_block_template_add_skip_link
+     */
+    public function test_block_template_add_skip_link_inserts_link_and_adds_main_id_when_missing() {
+        $template_html = '<div class="wp-site-blocks"><main>Content</main></div>';
+        $expected      = '
+            <a class="skip-link screen-reader-text" id="wp-skip-link" href="#wp--skip-link--target">Skip to content</a>
+            <div class="wp-site-blocks"><main id="wp--skip-link--target">Content</main></div>
+        ';
+
+        $this->assertEqualHTML( $expected, _block_template_add_skip_link( $template_html ) );
+    }
+
+    /**
+     * Tests that an existing MAIN ID is reused for the skip link.
+     *
+     * @ticket 64361
+     *
+     * @covers ::_block_template_add_skip_link
+     */
+    public function test_block_template_add_skip_link_uses_existing_main_id() {
+        $template_html = '<div class="wp-site-blocks"><main id="custom-id">Content</main></div>';
+        $expected      = '
+            <a class="skip-link screen-reader-text" id="wp-skip-link" href="#custom-id">Skip to content</a>
+            <div class="wp-site-blocks"><main id="custom-id">Content</main></div>
+        ';
+
+        $this->assertEqualHTML( $expected, _block_template_add_skip_link( $template_html ) );
+    }
+
+    /**
+     * Tests that a boolean MAIN ID is treated as missing and replaced with the default.
+     *
+     * @ticket 64361
+     *
+     * @covers ::_block_template_add_skip_link
+     */
+    public function test_block_template_add_skip_link_handles_boolean_main_id() {
+        $template_html = '<div class="wp-site-blocks"><main id>Content</main></div>';
+        $expected      = '
+            <a class="skip-link screen-reader-text" id="wp-skip-link" href="#wp--skip-link--target">Skip to content</a>
+            <div class="wp-site-blocks"><main id="wp--skip-link--target">Content</main></div>
+        ';
+
+        $this->assertEqualHTML( $expected, _block_template_add_skip_link( $template_html ) );
+    }
+
+    /**
+     * Tests that a MAIN ID containing whitespace is preserved and used for the skip link.
+     *
+     * @ticket 64361
+     *
+     * @covers ::_block_template_add_skip_link
+     */
+    public function test_block_template_add_skip_link_preserves_whitespace_main_id() {
+        $template_html = '<div class="wp-site-blocks"><main id=" my-id ">Content</main></div>';
+        $expected      = '
+            <a class="skip-link screen-reader-text" id="wp-skip-link" href="#%20my-id%20">Skip to content</a>
+            <div class="wp-site-blocks"><main id=" my-id ">Content</main></div>
+        ';
+
+        $this->assertEqualHTML( $expected, _block_template_add_skip_link( $template_html ) );
+    }
+
+    /**
+     * Tests that no changes are made when there is no MAIN element.
+     *
+     * @ticket 64361
+     *
+     * @covers ::_block_template_add_skip_link
+     */
+    public function test_block_template_add_skip_link_does_not_modify_when_main_missing() {
+        $template_html = '<div class="wp-site-blocks"><div>Content</div></div>';
+
+        $this->assertSame( $template_html, _block_template_add_skip_link( $template_html ) );
+    }
+
+    /**
      * Should retrieve the template from the theme files.
      */

trunk/tests/phpunit/tests/block-template.php

@@ -313 +313 @@
 
     /**
+     * Tests that `get_the_block_template_html()` adds a skip link when a MAIN element is present.
+     *
+     * @ticket 64361
+     * @covers ::get_the_block_template_html
+     */
+    public function test_get_the_block_template_html_adds_skip_link_when_main_present() {
+        global $_wp_current_template_id, $_wp_current_template_content;
+
+        $_wp_current_template_id      = get_stylesheet() . '//index';
+        $_wp_current_template_content = '<main>Content</main>';
+
+        $processor = new WP_HTML_Tag_Processor( get_the_block_template_html() );
+        $this->assertTrue(
+            $processor->next_tag(
+                array(
+                    'tag_name'   => 'A',
+                    'class_name' => 'skip-link',
+                )
+            ),
+            'Expected skip link was not added to the block template HTML.'
+        );
+        $this->assertSame( 'wp-skip-link', $processor->get_attribute( 'id' ), 'Unexpected ID on skip link.' );
+        $this->assertTrue( $processor->has_class( 'screen-reader-text' ), 'Expected "screen-reader-text" class on skip link.' );
+    }
+
+    /**
+     * Tests that `get_the_block_template_html()` does not add a skip link when the skip-link action is unhooked.
+     *
+     * @ticket 64361
+     * @covers ::get_the_block_template_html
+     *
+     * @dataProvider data_provider_skip_link_actions
+     */
+    public function test_get_the_block_template_html_does_not_add_skip_link_when_action_unhooked( string $action, string $callback ) {
+        global $_wp_current_template_id, $_wp_current_template_content;
+
+        $_wp_current_template_id      = get_stylesheet() . '//index';
+        $_wp_current_template_content = '<main>Content</main>';
+
+        remove_action( $action, $callback );
+
+        $processor = new WP_HTML_Tag_Processor( get_the_block_template_html() );
+        $this->assertFalse(
+            $processor->next_tag(
+                array(
+                    'tag_name'   => 'A',
+                    'class_name' => 'skip-link',
+                )
+            ),
+            'Unexpected skip link was added to the block template HTML when the action was unhooked.'
+        );
+    }
+
+    /**
+     * Data provider for test_get_the_block_template_html_does_not_add_skip_link_when_action_unhooked.
+     *
+     * @return array<string, array<string, string>>
+     */
+    public function data_provider_skip_link_actions(): array {
+        return array(
+            'the_block_template_skip_link'        => array(
+                'action'   => 'wp_footer',
+                'callback' => 'the_block_template_skip_link',
+            ),
+            'wp_enqueue_block_template_skip_link' => array(
+                'action'   => 'wp_enqueue_scripts',
+                'callback' => 'wp_enqueue_block_template_skip_link',
+            ),
+        );
+    }
+
+    /**
      * @ticket 58319
      *

trunk/tests/phpunit/tests/template.php

@@ -1798 +1798 @@
             'core-block-supports-duotone-inline-css',
             'wp-block-library-theme-css',
+            'wp-block-template-skip-link-css',
             'wp-block-template-skip-link-inline-css',
         );