Allow classic scripts to depend on modules

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

@@ -533,13 +533,77 @@ public function print_import_map() {
 	 * Returns the import map array.
 	 *
 	 * @since 6.5.0
+	 * @since 7.0.0 Script module dependencies ('module_dependencies') of classic scripts are now included.
+	 *
+	 * @global WP_Scripts $wp_scripts
 	 *
 	 * @return array<string, array<string, string>> Array with an `imports` key mapping to an array of script module
 	 *                                              identifiers and their respective URLs, including the version query.
 	 */
 	private function get_import_map(): array {
+		global $wp_scripts;
+
 		$imports = array();
-		foreach ( array_keys( $this->get_dependencies( $this->queue ) ) as $id ) {
+
+		// Identify script modules that are dependencies of classic scripts.
+		$classic_script_module_dependencies = array();
+		if ( $wp_scripts instanceof WP_Scripts ) {
+			$handles = array_merge(
+				$wp_scripts->queue,
+				$wp_scripts->to_do,
+				$wp_scripts->done
+			);
+
+			$processed = array();
+			while ( ! empty( $handles ) ) {
+				$handle = array_pop( $handles );
+				if ( isset( $processed[ $handle ] ) || ! isset( $wp_scripts->registered[ $handle ] ) ) {
+					continue;
+				}
+				$processed[ $handle ] = true;
+
+				$module_dependencies = $wp_scripts->get_data( $handle, 'module_dependencies' );
+				if ( is_array( $module_dependencies ) ) {
+					$missing_module_dependencies = array();
+					foreach ( $module_dependencies as $id ) {
+						if ( ! isset( $this->registered[ $id ] ) ) {
+							$missing_module_dependencies[] = $id;
+						} else {
+							$classic_script_module_dependencies[] = $id;
+						}
+					}
+
+					if ( count( $missing_module_dependencies ) > 0 ) {
+						_doing_it_wrong(
+							'WP_Scripts::add_data',
+							sprintf(
+								/* translators: 1: Script handle, 2: 'module_dependencies', 3: List of missing dependency IDs. */
+								__( 'The script with the handle "%1$s" was enqueued with script module dependencies ("%2$s") that are not registered: %3$s.' ),
+								$handle,
+								'module_dependencies',
+								implode( wp_get_list_item_separator(), $missing_module_dependencies )
+							),
+							'7.0.0'
+						);
+					}
+				}
+
+				foreach ( $wp_scripts->registered[ $handle ]->deps as $dep ) {
+					if ( ! isset( $processed[ $dep ] ) ) {
+						$handles[] = $dep;
+					}
+				}
+			}
+		}
+
+		// Note: the script modules in $this->queue are not included in the importmap because they get printed as scripts.
+		$ids = array_unique(
+			array_merge(
+				$classic_script_module_dependencies,
+				array_keys( $this->get_dependencies( array_merge( $this->queue, $classic_script_module_dependencies ) ) )
+			)
+		);
+		foreach ( $ids as $id ) {
 			$src = $this->get_src( $id );
 			if ( '' !== $src ) {
 				$imports[ $id ] = $src;

src/wp-includes/class-wp-scripts.php

@@ -920,6 +920,45 @@ public function add_data( $handle, $key, $value ) {
 				);
 				return false;
 			}
+		} elseif ( 'module_dependencies' === $key ) {
+			if ( ! is_array( $value ) ) {
+				_doing_it_wrong(
+					__METHOD__,
+					sprintf(
+						/* translators: 1: 'module_dependencies', 2: Script handle. */
+						__( 'The value for "%1$s" must be an array for the "%2$s" script.' ),
+						'module_dependencies',
+						$handle
+					),
+					'7.0.0'
+				);
+				return false;
+			}
+
+			$sanitized_value = array();
+			$has_invalid_ids = false;
+			foreach ( $value as $id ) {
+				if ( ! is_string( $id ) ) {
+					$has_invalid_ids = true;
+				} else {
+					$sanitized_value[] = $id;
+				}
+			}
+
+			if ( $has_invalid_ids ) {
+				_doing_it_wrong(
+					__METHOD__,
+					sprintf(
+						/* translators: 1: Script handle, 2: 'module_dependencies' */
+						__( 'The script handle "%1$s" has one or more of its script module dependencies ("%2$s") which are not strings.' ),
+						$handle,
+						'module_dependencies'
+					),
+					'7.0.0'
+				);
+			}
+
+			$value = $sanitized_value;
 		}
 		return parent::add_data( $handle, $key, $value );
 	}

src/wp-includes/functions.wp-scripts.php

@@ -68,6 +68,47 @@ function _wp_scripts_maybe_doing_it_wrong( $function_name, $handle = '' ) {
 	);
 }
 
+/**
+ * Adds the data for the recognized args and warns for unrecognized args.
+ *
+ * @ignore
+ * @since 7.0.0
+ *
+ * @param string     $function_name Function name.
+ * @param WP_Scripts $wp_scripts    WP_Scripts instance.
+ * @param string     $handle        Script handle.
+ * @param array      $args          Array of extra args for the script.
+ */
+function _wp_scripts_add_args_data( string $function_name, WP_Scripts $wp_scripts, string $handle, array $args ) {
+	$allowed_keys = array( 'strategy', 'in_footer', 'fetchpriority', 'module_dependencies' );
+	$unknown_keys = array_diff( array_keys( $args ), $allowed_keys );
+	if ( ! empty( $unknown_keys ) ) {
+		_doing_it_wrong(
+			$function_name,
+			sprintf(
+				/* translators: 1: $args, 2: List of unrecognized keys. */
+				__( 'Unrecognized keys in the %1$s array: %2$s.' ),
+				'$args',
+				implode( wp_get_list_item_separator(), $unknown_keys )
+			),
+			'7.0.0'
+		);
+	}
+
+	if ( ! empty( $args['in_footer'] ) ) {
+		$wp_scripts->add_data( $handle, 'group', 1 );
+	}
+	if ( ! empty( $args['strategy'] ) ) {
+		$wp_scripts->add_data( $handle, 'strategy', $args['strategy'] );
+	}
+	if ( ! empty( $args['fetchpriority'] ) ) {
+		$wp_scripts->add_data( $handle, 'fetchpriority', $args['fetchpriority'] );
+	}
+	if ( ! empty( $args['module_dependencies'] ) ) {
+		$wp_scripts->add_data( $handle, 'module_dependencies', $args['module_dependencies'] );
+	}
+}
+
 /**
  * Prints scripts in document head that are in the $handles queue.
  *
@@ -159,22 +200,24 @@ function wp_add_inline_script( $handle, $data, $position = 'after' ) {
  * @since 4.3.0 A return value was added.
  * @since 6.3.0 The $in_footer parameter of type boolean was overloaded to be an $args parameter of type array.
  * @since 6.9.0 The $fetchpriority parameter of type string was added to the $args parameter of type array.
- *
- * @param string                          $handle Name of the script. Should be unique.
- * @param string|false                    $src    Full URL of the script, or path of the script relative to the WordPress root directory.
- *                                                If source is set to false, script is an alias of other scripts it depends on.
- * @param string[]                        $deps   Optional. An array of registered script handles this script depends on. Default empty array.
- * @param string|bool|null                $ver    Optional. String specifying script version number, if it has one, which is added to the URL
- *                                                as a query string for cache busting purposes. If version is set to false, a version
- *                                                number is automatically added equal to current installed WordPress version.
- *                                                If set to null, no version is added.
- * @param array<string, string|bool>|bool $args   {
- *     Optional. An array of additional script loading strategies. Default empty array.
+ * @since 7.0.0 The $module_dependencies parameter of type string[] was added to the $args parameter of type array.
+ *
+ * @param string                                   $handle Name of the script. Should be unique.
+ * @param string|false                             $src    Full URL of the script, or path of the script relative to the WordPress root directory.
+ *                                                         If source is set to false, script is an alias of other scripts it depends on.
+ * @param string[]                                 $deps   Optional. An array of registered script handles this script depends on. Default empty array.
+ * @param string|bool|null                         $ver    Optional. String specifying script version number, if it has one, which is added to the URL
+ *                                                         as a query string for cache busting purposes. If version is set to false, a version
+ *                                                         number is automatically added equal to current installed WordPress version.
+ *                                                         If set to null, no version is added.
+ * @param array<string, string|bool|string[]>|bool $args   {
+ *     Optional. An array of extra args for the script. Default empty array.
  *     Otherwise, it may be a boolean in which case it determines whether the script is printed in the footer. Default false.
  *
- *     @type string    $strategy      Optional. If provided, may be either 'defer' or 'async'.
- *     @type bool      $in_footer     Optional. Whether to print the script in the footer. Default 'false'.
- *     @type string    $fetchpriority Optional. The fetch priority for the script. Default 'auto'.
+ *     @type string   $strategy            Optional. If provided, may be either 'defer' or 'async'.
+ *     @type bool     $in_footer           Optional. Whether to print the script in the footer. Default 'false'.
+ *     @type string   $fetchpriority       Optional. The fetch priority for the script. Default 'auto'.
+ *     @type string[] $module_dependencies Optional. IDs for module dependencies loaded via dynamic import. Default empty array.
  * }
  * @return bool Whether the script has been registered. True on success, false on failure.
  */
@@ -189,15 +232,8 @@ function wp_register_script( $handle, $src, $deps = array(), $ver = false, $args
 	$wp_scripts = wp_scripts();
 
 	$registered = $wp_scripts->add( $handle, $src, $deps, $ver );
-	if ( ! empty( $args['in_footer'] ) ) {
-		$wp_scripts->add_data( $handle, 'group', 1 );
-	}
-	if ( ! empty( $args['strategy'] ) ) {
-		$wp_scripts->add_data( $handle, 'strategy', $args['strategy'] );
-	}
-	if ( ! empty( $args['fetchpriority'] ) ) {
-		$wp_scripts->add_data( $handle, 'fetchpriority', $args['fetchpriority'] );
-	}
+	_wp_scripts_add_args_data( __FUNCTION__, $wp_scripts, $handle, $args );
+
 	return $registered;
 }
 
@@ -345,22 +381,24 @@ function wp_deregister_script( $handle ) {
  * @since 2.1.0
  * @since 6.3.0 The $in_footer parameter of type boolean was overloaded to be an $args parameter of type array.
  * @since 6.9.0 The $fetchpriority parameter of type string was added to the $args parameter of type array.
- *
- * @param string                          $handle Name of the script. Should be unique.
- * @param string                          $src    Full URL of the script, or path of the script relative to the WordPress root directory.
- *                                                Default empty.
- * @param string[]                        $deps   Optional. An array of registered script handles this script depends on. Default empty array.
- * @param string|bool|null                $ver    Optional. String specifying script version number, if it has one, which is added to the URL
- *                                                as a query string for cache busting purposes. If version is set to false, a version
- *                                                number is automatically added equal to current installed WordPress version.
- *                                                If set to null, no version is added.
- * @param array<string, string|bool>|bool $args   {
- *     Optional. An array of additional script loading strategies. Default empty array.
+ * @since 7.0.0 The $module_dependencies parameter of type string[] was added to the $args parameter of type array.
+ *
+ * @param string                                   $handle Name of the script. Should be unique.
+ * @param string                                   $src    Full URL of the script, or path of the script relative to the WordPress root directory.
+ *                                                         Default empty.
+ * @param string[]                                 $deps   Optional. An array of registered script handles this script depends on. Default empty array.
+ * @param string|bool|null                         $ver    Optional. String specifying script version number, if it has one, which is added to the URL
+ *                                                         as a query string for cache busting purposes. If version is set to false, a version
+ *                                                         number is automatically added equal to current installed WordPress version.
+ *                                                         If set to null, no version is added.
+ * @param array<string, string|bool|string[]>|bool $args   {
+ *     Optional. An array of extra args for the script. Default empty array.
  *     Otherwise, it may be a boolean in which case it determines whether the script is printed in the footer. Default false.
  *
- *     @type string    $strategy      Optional. If provided, may be either 'defer' or 'async'.
- *     @type bool      $in_footer     Optional. Whether to print the script in the footer. Default 'false'.
- *     @type string    $fetchpriority Optional. The fetch priority for the script. Default 'auto'.
+ *     @type string   $strategy            Optional. If provided, may be either 'defer' or 'async'.
+ *     @type bool     $in_footer           Optional. Whether to print the script in the footer. Default 'false'.
+ *     @type string   $fetchpriority       Optional. The fetch priority for the script. Default 'auto'.
+ *     @type string[] $module_dependencies Optional. IDs for module dependencies loaded via dynamic import. Default empty array.
  * }
  */
 function wp_enqueue_script( $handle, $src = '', $deps = array(), $ver = false, $args = array() ) {
@@ -379,14 +417,8 @@ function wp_enqueue_script( $handle, $src = '', $deps = array(), $ver = false, $
 		if ( $src ) {
 			$wp_scripts->add( $_handle[0], $src, $deps, $ver );
 		}
-		if ( ! empty( $args['in_footer'] ) ) {
-			$wp_scripts->add_data( $_handle[0], 'group', 1 );
-		}
-		if ( ! empty( $args['strategy'] ) ) {
-			$wp_scripts->add_data( $_handle[0], 'strategy', $args['strategy'] );
-		}
-		if ( ! empty( $args['fetchpriority'] ) ) {
-			$wp_scripts->add_data( $_handle[0], 'fetchpriority', $args['fetchpriority'] );
+		if ( ! empty( $args ) ) {
+			_wp_scripts_add_args_data( __FUNCTION__, $wp_scripts, $_handle[0], $args );
 		}
 	}