1<?php
  2/**
  3 * Script Modules API: Script Module functions
  4 *
  5 * @since 6.5.0
  6 *
  7 * @package WordPress
  8 * @subpackage Script Modules
  9 */
 10
 11/**
 12 * Retrieves the main WP_Script_Modules instance.
 13 *
 14 * This function provides access to the WP_Script_Modules instance, creating one
 15 * if it doesn't exist yet.
 16 *
 17 * @since 6.5.0
 18 *
 19 * @global WP_Script_Modules $wp_script_modules
 20 *
 21 * @return WP_Script_Modules The main WP_Script_Modules instance.
 22 */
 23function wp_script_modules(): WP_Script_Modules {
 24	global $wp_script_modules;
 25
 26	if ( ! ( $wp_script_modules instanceof WP_Script_Modules ) ) {
 27		$wp_script_modules = new WP_Script_Modules();
 28	}
 29
 30	return $wp_script_modules;
 31}
 32
 33/**
 34 * Registers the script module if no script module with that script module
 35 * identifier has already been registered.
 36 *
 37 * @since 6.5.0
 38 * @since 6.9.0 Added the $args parameter.
 39 *
 40 * @param string            $id      The identifier of the script module. Should be unique. It will be used in the
 41 *                                   final import map.
 42 * @param string            $src     Optional. Full URL of the script module, or path of the script module relative
 43 *                                   to the WordPress root directory. If it is provided and the script module has
 44 *                                   not been registered yet, it will be registered.
 45 * @param array             $deps    {
 46 *                                       Optional. List of dependencies.
 47 *
 48 *                                       @type string|array ...$0 {
 49 *                                           An array of script module identifiers of the dependencies of this script
 50 *                                           module. The dependencies can be strings or arrays. If they are arrays,
 51 *                                           they need an `id` key with the script module identifier, and can contain
 52 *                                           an `import` key with either `static` or `dynamic`. By default,
 53 *                                           dependencies that don't contain an `import` key are considered static.
 54 *
 55 *                                           @type string $id     The script module identifier.
 56 *                                           @type string $import Optional. Import type. May be either `static` or
 57 *                                                                `dynamic`. Defaults to `static`.
 58 *                                       }
 59 *                                   }
 60 * @param string|false|null $version Optional. String specifying the script module version number. Defaults to false.
 61 *                                   It is added to the URL as a query string for cache busting purposes. If $version
 62 *                                   is set to false, the version number is the currently installed WordPress version.
 63 *                                   If $version is set to null, no version is added.
 64 * @param array             $args    {
 65 *     Optional. An array of additional args. Default empty array.
 66 *
 67 *     @type bool                $in_footer     Whether to print the script module in the footer. Only relevant to block themes. Default 'false'. Optional.
 68 *     @type 'auto'|'low'|'high' $fetchpriority Fetch priority. Default 'auto'. Optional.
 69 * }
 70 */
 71function wp_register_script_module( string $id, string $src, array $deps = array(), $version = false, array $args = array() ) {
 72	wp_script_modules()->register( $id, $src, $deps, $version, $args );
 73}
 74
 75/**
 76 * Marks the script module to be enqueued in the page.
 77 *
 78 * If a src is provided and the script module has not been registered yet, it
 79 * will be registered.
 80 *
 81 * @since 6.5.0
 82 * @since 6.9.0 Added the $args parameter.
 83 *
 84 * @param string            $id      The identifier of the script module. Should be unique. It will be used in the
 85 *                                   final import map.
 86 * @param string            $src     Optional. Full URL of the script module, or path of the script module relative
 87 *                                   to the WordPress root directory. If it is provided and the script module has
 88 *                                   not been registered yet, it will be registered.
 89 * @param array             $deps    {
 90 *                                       Optional. List of dependencies.
 91 *
 92 *                                       @type string|array ...$0 {
 93 *                                           An array of script module identifiers of the dependencies of this script
 94 *                                           module. The dependencies can be strings or arrays. If they are arrays,
 95 *                                           they need an `id` key with the script module identifier, and can contain
 96 *                                           an `import` key with either `static` or `dynamic`. By default,
 97 *                                           dependencies that don't contain an `import` key are considered static.
 98 *
 99 *                                           @type string $id     The script module identifier.
100 *                                           @type string $import Optional. Import type. May be either `static` or
101 *                                                                `dynamic`. Defaults to `static`.
102 *                                       }
103 *                                   }
104 * @param string|false|null $version Optional. String specifying the script module version number. Defaults to false.
105 *                                   It is added to the URL as a query string for cache busting purposes. If $version
106 *                                   is set to false, the version number is the currently installed WordPress version.
107 *                                   If $version is set to null, no version is added.
108 * @param array             $args    {
109 *     Optional. An array of additional args. Default empty array.
110 *
111 *     @type bool                $in_footer     Whether to print the script module in the footer. Only relevant to block themes. Default 'false'. Optional.
112 *     @type 'auto'|'low'|'high' $fetchpriority Fetch priority. Default 'auto'. Optional.
113 * }
114 */
115function wp_enqueue_script_module( string $id, string $src = '', array $deps = array(), $version = false, array $args = array() ) {
116	wp_script_modules()->enqueue( $id, $src, $deps, $version, $args );
117}
118
119/**
120 * Unmarks the script module so it is no longer enqueued in the page.
121 *
122 * @since 6.5.0
123 *
124 * @param string $id The identifier of the script module.
125 */
126function wp_dequeue_script_module( string $id ) {
127	wp_script_modules()->dequeue( $id );
128}
129
130/**
131 * Deregisters the script module.
132 *
133 * @since 6.5.0
134 *
135 * @param string $id The identifier of the script module.
136 */
137function wp_deregister_script_module( string $id ) {
138	wp_script_modules()->deregister( $id );
139}
140
141/**
142 * Registers all the default WordPress Script Modules.
143 *
144 * @since 6.7.0
145 */
146function wp_default_script_modules() {
147	$suffix = defined( 'WP_RUN_CORE_TESTS' ) ? '.min' : wp_scripts_get_suffix();
148
149	/*
150	 * Expects multidimensional array like:
151	 *
152	 *     'interactivity/index.min.js' => array('dependencies' => array(…), 'version' => '…'),
153	 *     'interactivity/debug.min.js' => array('dependencies' => array(…), 'version' => '…'),
154	 *     'interactivity-router/index.min.js' => …
155	 */
156	$assets = include ABSPATH . WPINC . "/assets/script-modules-packages{$suffix}.php";
157
158	foreach ( $assets as $file_name => $script_module_data ) {
159		/*
160		 * Build the WordPress Script Module ID from the file name.
161		 * Prepend `@wordpress/` and remove extensions and `/index` if present:
162		 *   - interactivity/index.min.js  => @wordpress/interactivity
163		 *   - interactivity/debug.min.js  => @wordpress/interactivity/debug
164		 *   - block-library/query/view.js => @wordpress/block-library/query/view
165		 */
166		$script_module_id = '@wordpress/' . preg_replace( '~(?:/index)?(?:\.min)?\.js$~D', '', $file_name, 1 );
167
168		switch ( $script_module_id ) {
169			/*
170			 * Interactivity exposes two entrypoints, "/index" and "/debug".
171			 * "/debug" should replace "/index" in development.
172			 */
173			case '@wordpress/interactivity/debug':
174				if ( ! SCRIPT_DEBUG ) {
175					continue 2;
176				}
177				$script_module_id = '@wordpress/interactivity';
178				break;
179			case '@wordpress/interactivity':
180				if ( SCRIPT_DEBUG ) {
181					continue 2;
182				}
183				break;
184		}
185
186		/*
187		 * The Interactivity API is designed with server-side rendering as its primary goal, so all of its script modules
188		 * should be loaded with low fetchpriority and printed in the footer since they should not be needed in the
189		 * critical rendering path. Also, the @wordpress/a11y script module is intended to be used as a dynamic import
190		 * dependency, in which case the fetchpriority is irrelevant. See <https://make.wordpress.org/core/2024/10/14/updates-to-script-modules-in-6-7/>.
191		 * However, in case it is added as a static import dependency, the fetchpriority is explicitly set to be 'low'
192		 * since the module should not be involved in the critical rendering path, and if it is, its fetchpriority will
193		 * be bumped to match the fetchpriority of the dependent script.
194		 */
195		$args = array();
196		if (
197			str_starts_with( $script_module_id, '@wordpress/interactivity' ) ||
198			str_starts_with( $script_module_id, '@wordpress/block-library' ) ||
199			'@wordpress/a11y' === $script_module_id
200		) {
201			$args['fetchpriority'] = 'low';
202			$args['in_footer']     = true;
203		}
204
205		// Marks all Core blocks as compatible with client-side navigation.
206		if ( str_starts_with( $script_module_id, '@wordpress/block-library' ) ) {
207			wp_interactivity()->add_client_navigation_support_to_script_module( $script_module_id );
208		}
209
210		$path = includes_url( "js/dist/script-modules/{$file_name}" );
211		wp_register_script_module( $script_module_id, $path, $script_module_data['dependencies'], $script_module_data['version'], $args );
212	}
213}
214