General: Add opt-in <search> element support to the core search form

src/wp-content/themes/twentyseventeen/searchform.php

@@ -12,7 +12,11 @@
 
 <?php $unique_id = esc_attr( twentyseventeen_unique_id( 'search-form-' ) ); ?>
 
-<form role="search" method="get" class="search-form" action="<?php echo esc_url( home_url( '/' ) ); ?>">
+<?php $twentyseventeen_wrap_in_search = ! empty( $args['wrap_in_search'] ); ?>
+<?php if ( $twentyseventeen_wrap_in_search ) : ?>
+<search>
+<?php endif; ?>
+<form <?php echo $twentyseventeen_wrap_in_search ? '' : 'role="search" '; ?>method="get" class="search-form" action="<?php echo esc_url( home_url( '/' ) ); ?>">
 	<label for="<?php echo $unique_id; ?>">
 		<span class="screen-reader-text">
 			<?php
@@ -29,3 +33,6 @@
 		?>
 	</span></button>
 </form>
+<?php if ( $twentyseventeen_wrap_in_search ) : ?>
+</search>
+<?php endif; ?>

src/wp-content/themes/twentysixteen/searchform.php

@@ -9,7 +9,11 @@
 
 ?>
 
-<form role="search" method="get" class="search-form" action="<?php echo esc_url( home_url( '/' ) ); ?>">
+<?php $twentysixteen_wrap_in_search = ! empty( $args['wrap_in_search'] ); ?>
+<?php if ( $twentysixteen_wrap_in_search ) : ?>
+<search>
+<?php endif; ?>
+<form <?php echo $twentysixteen_wrap_in_search ? '' : 'role="search" '; ?>method="get" class="search-form" action="<?php echo esc_url( home_url( '/' ) ); ?>">
 	<label>
 		<span class="screen-reader-text">
 			<?php
@@ -26,3 +30,6 @@
 		?>
 	</span></button>
 </form>
+<?php if ( $twentysixteen_wrap_in_search ) : ?>
+</search>
+<?php endif; ?>

src/wp-content/themes/twentytwenty/searchform.php

@@ -22,8 +22,13 @@
 if ( empty( $twentytwenty_aria_label ) && ! empty( $args['label'] ) ) {
 	$twentytwenty_aria_label = 'aria-label="' . esc_attr( $args['label'] ) . '"';
 }
+
+$twentytwenty_wrap_in_search = ! empty( $args['wrap_in_search'] );
 ?>
-<form role="search" <?php echo $twentytwenty_aria_label; ?> method="get" class="search-form" action="<?php echo esc_url( home_url( '/' ) ); ?>">
+<?php if ( $twentytwenty_wrap_in_search ) : ?>
+<search<?php echo $twentytwenty_aria_label ? ' ' . $twentytwenty_aria_label : ''; ?>>
+<?php endif; ?>
+<form <?php echo $twentytwenty_wrap_in_search ? '' : 'role="search" ' . $twentytwenty_aria_label . ' '; ?>method="get" class="search-form" action="<?php echo esc_url( home_url( '/' ) ); ?>">
 	<label for="<?php echo esc_attr( $twentytwenty_unique_id ); ?>">
 		<span class="screen-reader-text">
 			<?php
@@ -35,3 +40,6 @@
 	</label>
 	<input type="submit" class="search-submit" value="<?php echo esc_attr_x( 'Search', 'submit button', 'twentytwenty' ); ?>" />
 </form>
+<?php if ( $twentytwenty_wrap_in_search ) : ?>
+</search>
+<?php endif; ?>

src/wp-content/themes/twentytwentyone/searchform.php

@@ -19,9 +19,17 @@
 $twentytwentyone_unique_id = wp_unique_id( 'search-form-' );
 
 $twentytwentyone_aria_label = ! empty( $args['aria_label'] ) ? 'aria-label="' . esc_attr( $args['aria_label'] ) . '"' : '';
+
+$twentytwentyone_wrap_in_search = ! empty( $args['wrap_in_search'] );
 ?>
-<form role="search" <?php echo $twentytwentyone_aria_label; ?> method="get" class="search-form" action="<?php echo esc_url( home_url( '/' ) ); ?>">
+<?php if ( $twentytwentyone_wrap_in_search ) : ?>
+<search<?php echo $twentytwentyone_aria_label ? ' ' . $twentytwentyone_aria_label : ''; ?>>
+<?php endif; ?>
+<form <?php echo $twentytwentyone_wrap_in_search ? '' : 'role="search" ' . $twentytwentyone_aria_label . ' '; ?>method="get" class="search-form" action="<?php echo esc_url( home_url( '/' ) ); ?>">
 	<label for="<?php echo esc_attr( $twentytwentyone_unique_id ); ?>"><?php _e( 'Search&hellip;', 'twentytwentyone' ); // phpcs:ignore: WordPress.Security.EscapeOutput.UnsafePrintingFunction -- core trusts translations ?></label>
 	<input type="search" id="<?php echo esc_attr( $twentytwentyone_unique_id ); ?>" class="search-field" value="<?php echo get_search_query(); ?>" name="s" />
 	<input type="submit" class="search-submit" value="<?php echo esc_attr_x( 'Search', 'submit button', 'twentytwentyone' ); ?>" />
 </form>
+<?php if ( $twentytwentyone_wrap_in_search ) : ?>
+</search>
+<?php endif; ?>

src/wp-includes/general-template.php

@@ -227,14 +227,21 @@ function get_template_part( $slug, $name = null, $args = array() ) {
  *
  * @since 2.7.0
  * @since 5.2.0 The `$args` array parameter was added in place of an `$echo` boolean flag.
+ * @since 7.1.0 Added the `$wrap_in_search` argument and the `search-element` theme support
+ *              feature to wrap the form in a `<search>` element.
  *
  * @param array $args {
  *     Optional. Array of display arguments.
  *
- *     @type bool   $echo       Whether to echo or return the form. Default true.
- *     @type string $aria_label ARIA label for the search form. Useful to distinguish
- *                              multiple search forms on the same page and improve
- *                              accessibility. Default empty.
+ *     @type bool   $echo           Whether to echo or return the form. Default true.
+ *     @type string $aria_label     ARIA label for the search form. Useful to distinguish
+ *                                  multiple search forms on the same page and improve
+ *                                  accessibility. Default empty.
+ *     @type bool   $wrap_in_search Whether to wrap the form in a semantic HTML `<search>`
+ *                                  landmark element and drop the now-redundant `role="search"`
+ *                                  attribute on the form. Only applies to the 'html5' format.
+ *                                  Defaults to true when the theme declares support for the
+ *                                  'search-element' feature, false otherwise.
  * }
  * @return void|string Void if 'echo' argument is true, search form HTML if 'echo' is false.
  */
@@ -269,8 +276,9 @@ function get_search_form( $args = array() ) {
 
 	// Defaults are to echo and to output no custom label on the form.
 	$defaults = array(
-		'echo'       => $echo,
-		'aria_label' => '',
+		'echo'           => $echo,
+		'aria_label'     => '',
+		'wrap_in_search' => current_theme_supports( 'search-element' ),
 	);
 
 	$args = wp_parse_args( $args, $defaults );
@@ -321,7 +329,26 @@ function get_search_form( $args = array() ) {
 			$aria_label = '';
 		}
 
-		if ( 'html5' === $format ) {
+		if ( 'html5' === $format && $args['wrap_in_search'] ) {
+			/*
+			 * Wrap the form in a <search> landmark element. The implicit ARIA role
+			 * of <search> provides the search landmark, so role="search" is omitted
+			 * from the form to avoid nesting two identical landmarks. Any aria-label
+			 * names the <search> landmark instead of the form.
+			 */
+			$search_label = $args['aria_label'] ? ' aria-label="' . esc_attr( $args['aria_label'] ) . '"' : '';
+
+			$form = '<search' . $search_label . '><form method="get" class="search-form" action="' . esc_url( home_url( '/' ) ) . '">
+				<label>
+					<span class="screen-reader-text">' .
+					/* translators: Hidden accessibility text. */
+					_x( 'Search for:', 'label' ) .
+					'</span>
+					<input type="search" class="search-field" placeholder="' . esc_attr_x( 'Search &hellip;', 'placeholder' ) . '" value="' . get_search_query() . '" name="s" />
+				</label>
+				<input type="submit" class="search-submit" value="' . esc_attr_x( 'Search', 'submit button' ) . '" />
+			</form></search>';
+		} elseif ( 'html5' === $format ) {
 			$form = '<form role="search" ' . $aria_label . 'method="get" class="search-form" action="' . esc_url( home_url( '/' ) ) . '">
 				<label>
 					<span class="screen-reader-text">' .

src/wp-includes/theme.php

@@ -2647,6 +2647,8 @@ function get_theme_starter_content() {
  *              see `WP_Theme_JSON::APPEARANCE_TOOLS_OPT_INS` for a complete list.
  * @since 6.6.0 The `editor-spacing-sizes` feature was added.
  * @since 7.0.0 The `html5` feature's 'script' and 'style' arguments are deprecated and unused.
+ * @since 7.1.0 The `search-element` feature wraps the core search form markup in the
+ *              HTML `<search>` landmark element.
  *
  * @global array $_wp_theme_features
  *
@@ -2683,6 +2685,7 @@ function get_theme_starter_content() {
  *                          - 'post-formats'
  *                          - 'post-thumbnails'
  *                          - 'responsive-embeds'
+ *                          - 'search-element'
  *                          - 'starter-content'
  *                          - 'title-tag'
  *                          - 'widgets'

tests/phpunit/tests/general/getSearchForm.php

@@ -0,0 +1,202 @@
+<?php
+/**
+ * Tests for the get_search_form() function.
+ *
+ * @since 7.1.0
+ *
+ * @group general
+ * @group template
+ *
+ * @covers ::get_search_form
+ */
+class Tests_General_GetSearchForm extends WP_UnitTestCase {
+
+	/**
+	 * Removes any theme support added during a test.
+	 */
+	public function tear_down() {
+		remove_theme_support( 'html5' );
+		remove_theme_support( 'search-element' );
+		parent::tear_down();
+	}
+
+	/**
+	 * Enables the html5 'search-form' theme support so the html5 markup is used.
+	 */
+	private function enable_html5_search_form() {
+		add_theme_support( 'html5', array( 'search-form' ) );
+	}
+
+	/**
+	 * The html5 form should keep role="search" on the <form> by default.
+	 *
+	 * @ticket 65288
+	 */
+	public function test_html5_default_uses_form_role_search() {
+		$this->enable_html5_search_form();
+
+		$form = get_search_form( array( 'echo' => false ) );
+
+		$this->assertStringContainsString( '<form role="search"', $form, 'The default html5 form should keep role="search" on the form.' );
+		$this->assertStringNotContainsString( '<search', $form, 'The default html5 form should not be wrapped in a <search> element.' );
+	}
+
+	/**
+	 * Opting in should wrap the html5 form in a <search> element and drop role="search".
+	 *
+	 * @ticket 65288
+	 */
+	public function test_wrap_in_search_wraps_form_and_drops_role() {
+		$this->enable_html5_search_form();
+
+		$form = get_search_form(
+			array(
+				'echo'           => false,
+				'wrap_in_search' => true,
+			)
+		);
+
+		$this->assertStringContainsString( '<search>', $form, 'The opted-in form should open a <search> element.' );
+		$this->assertStringContainsString( '</search>', $form, 'The opted-in form should close the <search> element.' );
+		$this->assertStringContainsString( '<form method="get" class="search-form"', $form, 'The inner form markup should be preserved.' );
+		$this->assertStringNotContainsString( 'role="search"', $form, 'role="search" should be dropped to avoid a nested duplicate landmark.' );
+	}
+
+	/**
+	 * A custom aria_label should name the <search> landmark, not the inner form.
+	 *
+	 * @ticket 65288
+	 */
+	public function test_wrap_in_search_applies_aria_label_to_search_element() {
+		$this->enable_html5_search_form();
+
+		$form = get_search_form(
+			array(
+				'echo'           => false,
+				'wrap_in_search' => true,
+				'aria_label'     => 'Search products',
+			)
+		);
+
+		$this->assertStringContainsString( '<search aria-label="Search products">', $form, 'The aria-label should be applied to the <search> element.' );
+		$this->assertStringContainsString( '<form method="get"', $form, 'The inner form should not carry the aria-label.' );
+		$this->assertStringNotContainsString( '<form method="get" aria-label', $form, 'The aria-label should not appear on the inner form.' );
+	}
+
+	/**
+	 * Without a custom aria_label, the <search> element should have no attributes.
+	 *
+	 * @ticket 65288
+	 */
+	public function test_wrap_in_search_without_aria_label_has_no_attributes() {
+		$this->enable_html5_search_form();
+
+		$form = get_search_form(
+			array(
+				'echo'           => false,
+				'wrap_in_search' => true,
+			)
+		);
+
+		$this->assertStringContainsString( '<search>', $form, 'The <search> element should have no attributes when no aria-label is set.' );
+		$this->assertStringNotContainsString( '<search >', $form, 'The <search> element should not contain a stray space.' );
+	}
+
+	/**
+	 * The default html5 form should still apply a custom aria_label to the form.
+	 *
+	 * @ticket 65288
+	 */
+	public function test_html5_default_applies_aria_label_to_form() {
+		$this->enable_html5_search_form();
+
+		$form = get_search_form(
+			array(
+				'echo'       => false,
+				'aria_label' => 'Search the site',
+			)
+		);
+
+		$this->assertStringContainsString( '<form role="search" aria-label="Search the site"', $form, 'The aria-label should be applied to the form by default.' );
+		$this->assertStringNotContainsString( '<search', $form, 'The default form should not be wrapped in a <search> element.' );
+	}
+
+	/**
+	 * The wrap_in_search argument should not affect the xhtml format.
+	 *
+	 * The <search> element does not exist in XHTML 1.x, so themes without html5
+	 * 'search-form' support should continue to receive the unchanged xhtml markup.
+	 *
+	 * @ticket 65288
+	 */
+	public function test_wrap_in_search_is_ignored_for_xhtml_format() {
+		// No html5 theme support added: the format defaults to xhtml.
+		$form = get_search_form(
+			array(
+				'echo'           => false,
+				'wrap_in_search' => true,
+			)
+		);
+
+		$this->assertStringNotContainsString( '<search', $form, 'The xhtml format should not use the <search> element.' );
+		$this->assertStringContainsString( '<form role="search"', $form, 'The xhtml format should keep role="search" on the form.' );
+		$this->assertStringContainsString( 'id="searchform"', $form, 'The xhtml markup should be unchanged.' );
+	}
+
+	/**
+	 * The wrapping should be enableable globally via the search_form_args filter.
+	 *
+	 * @ticket 65288
+	 */
+	public function test_wrap_in_search_can_be_enabled_via_filter() {
+		$this->enable_html5_search_form();
+
+		add_filter(
+			'search_form_args',
+			static function ( $args ) {
+				$args['wrap_in_search'] = true;
+				return $args;
+			}
+		);
+
+		$form = get_search_form( array( 'echo' => false ) );
+
+		$this->assertStringContainsString( '<search>', $form, 'The search_form_args filter should be able to enable wrapping.' );
+		$this->assertStringNotContainsString( 'role="search"', $form, 'role="search" should be dropped when wrapping is enabled via filter.' );
+	}
+
+	/**
+	 * Declaring 'search-element' theme support should wrap the form by default.
+	 *
+	 * @ticket 65288
+	 */
+	public function test_search_element_theme_support_enables_wrap_by_default() {
+		$this->enable_html5_search_form();
+		add_theme_support( 'search-element' );
+
+		$form = get_search_form( array( 'echo' => false ) );
+
+		$this->assertStringContainsString( '<search>', $form, 'Declaring search-element support should wrap the form by default.' );
+		$this->assertStringNotContainsString( 'role="search"', $form, 'role="search" should be dropped when search-element support is declared.' );
+	}
+
+	/**
+	 * An explicit wrap_in_search => false should override 'search-element' theme support.
+	 *
+	 * @ticket 65288
+	 */
+	public function test_wrap_in_search_false_overrides_theme_support() {
+		$this->enable_html5_search_form();
+		add_theme_support( 'search-element' );
+
+		$form = get_search_form(
+			array(
+				'echo'           => false,
+				'wrap_in_search' => false,
+			)
+		);
+
+		$this->assertStringNotContainsString( '<search', $form, 'An explicit false should override search-element theme support.' );
+		$this->assertStringContainsString( '<form role="search"', $form, 'The form should keep role="search" when wrapping is explicitly disabled.' );
+	}
+}