Add support for sharing data in Script Modules and improve documentation

Author: widoz

docs/assets.md

@@ -69,7 +69,8 @@ $module
     ->withFilePath('/path/to/module.js')
     ->disableAutodiscoverVersion()
     ->enableAutodiscoverVersion()
-    ->withVersion('1.0');
+    ->withVersion('1.0')
+    ->withData(['key' => 'value']);
 
 $style = new Style('foo', 'www.example.com/style.css');
 $style
@@ -81,7 +82,7 @@ $style
 
 ### Enqueue conditionally
 
-You can enqueue your Assets conditionally by using following API:
+You can enqueue your Assets conditionally by using the following API:
 
 ```php
 <?php
@@ -97,7 +98,7 @@ $style->canEnqueue(function(): bool {
 });
 ```
 
-By default Assets are always enqueued.
+By default, Assets are always enqueued.
 
 ### Location
 
@@ -318,7 +319,7 @@ $script
 
 ### Translation data
 
-Scripts can also have translation data via `wp_set_script_translations()`. This can be added like following:
+Scripts can also have translation data via `wp_set_script_translations()`. This can be added like the following:
 
 ```php
 <?php
@@ -449,6 +450,20 @@ $script->withAttributes(['src' => 'another-script.js']); // Will not overwrite "
 
 WordPress 6.5 introduced Script Modules for native JavaScript ES6 modules. The `ScriptModule` class provides basic asset management with the following limitations:
 
+### Module Data
+
+Scripts Modules allow sharing data from the server to the client via a filter `"script_module_data_{$handle}"`.
+
+Assets registered as `ScriptModule` can have shared data added like following:
+
+```php
+$module = new ScriptModule('@my-plugin/main', 'assets/main.js');
+$module->withData([
+    'apiUrl' => get_rest_url(),
+    'nonce'  => wp_create_nonce('wp_rest'),
+]);
+```
+
 ### Usage Examples
 
 ```php

src/Handler/ScriptModuleHandler.php

@@ -5,11 +5,15 @@
 namespace Inpsyde\Assets\Handler;
 
 use Inpsyde\Assets\Asset;
+use Inpsyde\Assets\ScriptModule;
 
 class ScriptModuleHandler implements AssetHandler
 {
     public function enqueue(Asset $asset): bool
     {
+        if (!$asset instanceof ScriptModule) {
+            return false;
+        }
         if (!static::scriptModulesSupported()) {
             return false;
         }
@@ -27,27 +31,45 @@ public function enqueue(Asset $asset): bool
 
     public function register(Asset $asset): bool
     {
+        if (!$asset instanceof ScriptModule) {
+            return false;
+        }
         if (!static::scriptModulesSupported()) {
             return false;
         }
 
         $handle = $asset->handle();
 
+        $this->shareData($asset);
+
         wp_register_script_module(
             $handle,
             $asset->url(),
             $asset->dependencies(), // @phpstan-ignore-line
-            $asset->version()
+            $asset->version(),
         );
 
         return true;
     }
 
-    public static function scriptModulesSupported(): bool
+    protected static function scriptModulesSupported(): bool
     {
-        return function_exists('wp_register_script_module')
-            && function_exists('wp_enqueue_script_module')
-            && function_exists('wp_deregister_script_module')
-            && function_exists('wp_dequeue_script_module');
+        return class_exists('WP_Script_Modules');
+    }
+
+    protected function shareData(ScriptModule $asset): void
+    {
+        $handle = $asset->handle();
+
+        if (!$asset->data()) {
+            return;
+        }
+
+        add_filter(
+            "script_module_data_{$handle}",
+            static function (array $data) use ($asset): array {
+                return array_merge($data, $asset->data());
+            }
+        );
     }
 }

src/ScriptModule.php

@@ -10,6 +10,37 @@ class ScriptModule extends BaseAsset implements Asset
 {
     use DependencyExtractionTrait;
 
+    /**
+     * Data which will be added via ...
+     *      - WP_Script::add_data()
+     *      - WP_Style::add_data()
+     *
+     * @var array<string, mixed>
+     */
+    protected array $data = [];
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function data(): array
+    {
+        return $this->data;
+    }
+
+    /**
+     * Allows to set additional data via WP_Script::add_data() or WP_Style::add_data().
+     *
+     * @param array<string, mixed> $data
+     *
+     * @return static
+     */
+    public function withData(array $data): Asset
+    {
+        $this->data = array_merge($this->data, $data);
+
+        return $this;
+    }
+
     /**
      * {@inheritDoc}
      */

tests/phpunit/Unit/Handler/ScriptModuleHandlerTest.php

@@ -5,10 +5,10 @@
 namespace Inpsyde\Assets\Tests\Unit\Handler;
 
 use Brain\Monkey\Functions;
-use Inpsyde\Assets\Asset;
+use Brain\Monkey\Filters;
 use Inpsyde\Assets\Handler\AssetHandler;
-use Inpsyde\Assets\Handler\OutputFilterAwareAssetHandler;
 use Inpsyde\Assets\Handler\ScriptModuleHandler;
+use Inpsyde\Assets\Script;
 use Inpsyde\Assets\ScriptModule;
 use Inpsyde\Assets\Tests\Unit\AbstractTestCase;
 
@@ -29,8 +29,8 @@ public function testBasic(): void
      */
     public function testRegisterEnqueue(): void
     {
-        $handler = new class extends ScriptModuleHandler {
-            public static function scriptModulesSupported(): bool
+        $handler = new class extends ScriptModuleHandler{
+            protected static function scriptModulesSupported(): bool
             {
                 return true;
             }
@@ -68,14 +68,9 @@ static function (
     /**
      * @test
      */
-    public function testRegisterEnqueueWithoutSupport(): void
+    public function testSkipEnqueueIfScriptModulesNotSupported(): void
     {
-        $handler = new class extends ScriptModuleHandler {
-            public static function scriptModulesSupported(): bool
-            {
-                return false;
-            }
-        };
+        $handler = new ScriptModuleHandler();
 
         $scriptModule = (new ScriptModule('@my-plugin/module', 'module.js'))
             ->withVersion('1.0.0')
@@ -89,4 +84,53 @@ public static function scriptModulesSupported(): bool
         static::assertFalse($result);
     }
 
-}
+    public function testSkipRegisterIfScriptModulesNotSupported(): void
+    {
+        $handler = new ScriptModuleHandler();
+
+        $scriptModule = (new ScriptModule('@my-plugin/module', 'module.js'))
+            ->withVersion('1.0.0')
+            ->withDependencies('@wordpress/interactivity');
+
+        Functions\expect('wp_register_script_module')->never();
+        Functions\expect('wp_enqueue_script_module')->never();
+
+        $result = $handler->register($scriptModule);
+
+        static::assertFalse($result);
+    }
+
+    public function testSkipNonScriptModuleRegistration(): void
+    {
+        $handler = new ScriptModuleHandler();
+        $scriptModule = new Script('@my-plugin/script', 'script.js');
+
+        Functions\expect('wp_register_script_module')->never();
+
+        $result = $handler->register($scriptModule);
+
+        static::assertFalse($result);
+    }
+
+    public function testDataSharedViaFilter(): void
+    {
+        $handler = new class extends ScriptModuleHandler{
+            protected static function scriptModulesSupported(): bool
+            {
+                return true;
+            }
+        };
+
+        $scriptModule = (new ScriptModule('@my-plugin/module', 'module.js'))
+            ->withVersion('1.0.0')
+            ->withDependencies('@wordpress/interactivity')
+            ->withData(['key' => 'value']);
+
+        Functions\expect('wp_register_script_module')->once();
+        Filters\expectAdded("script_module_data_@my-plugin/module");
+
+        $result = $handler->register($scriptModule);
+
+        static::assertTrue($result);
+    }
+}