[StimulusBundle] Initial import + AssetMapper integration

Co-authored-by: jmsche <contact@jmsche.fr>

Author: weaverryan

.github/workflows/test.yaml

@@ -173,6 +173,15 @@ jobs:
               run: php vendor/bin/simple-phpunit
               working-directory: src/Translator
 
+            - name: StimulusBundle Dependencies
+              uses: ramsey/composer-install@v2
+              with:
+                working-directory: src/StimulusBundle
+                dependency-versions: lowest
+            - name: StimulusBundle Tests
+              working-directory: src/StimulusBundle
+              run: php vendor/bin/simple-phpunit
+
     tests-php-high-deps:
         runs-on: ubuntu-latest
         steps:

src/StimulusBundle/.gitignore

@@ -0,0 +1,5 @@
+.php-cs-fixer.cache
+.phpunit.cache
+composer.lock
+vendor/
+tests/fixtures/var

src/StimulusBundle/.symfony.bundle.yaml

@@ -0,0 +1,3 @@
+branches: ["2.x"]
+maintained_branches: ["2.x"]
+doc_dir: "doc"

src/StimulusBundle/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+Contributing
+============
+
+When contributing, you can fix some things that will be detected by CI anyway *before* sending your pull request.
+
+The following tools will be installed in the `tools` directory, so they don't share the bundle requirements.
+
+PHPStan
+-------
+
+```bash
+composer install --working-dir=tools/phpstan
+tools/phpstan/vendor/bin/phpstan analyze
+# Based on the results, you may want to update the baseline
+tools/phpstan/vendor/bin/phpstan analyze --generate-baseline
+```
+
+PHP CS Fixer
+------------
+
+```bash
+composer install --working-dir=tools/php-cs-fixer
+# Check what can be fixed
+PHP_CS_FIXER_IGNORE_ENV=1 tools/php-cs-fixer/vendor/bin/php-cs-fixer fix --dry-run --diff
+# Fix them
+PHP_CS_FIXER_IGNORE_ENV=1 tools/php-cs-fixer/vendor/bin/php-cs-fixer fix --diff
+```
+
+PHPUnit
+-------
+
+```bash
+./vendor/bin/phpunit
+```

src/StimulusBundle/README.md

@@ -0,0 +1,11 @@
+# StimulusBundle: Symfony integration with Stimulus!
+
+This bundle adds integration between Symfony, Stimulus and Symfony UX:
+
+* A) Twig `stimulus_*` functions & filters to add Stimulus controllers, actions & targets in your templates.
+* B) Integration with Symfony UX & AssetMapper
+* C) A helper service to build the Stimulus data attributes and use them in your services.
+
+[Read the documentation][1]
+
+[1]: https://symfony.com/bundles/StimulusBundle/current/index.html

src/StimulusBundle/assets/dist/controllers.js

@@ -0,0 +1,9 @@
+// This file is dynamically rewritten by StimulusBundle + AssetMapper.
+/** @type {Object<string, Controller>} */
+export const eagerControllers = {};
+/** @type {Object<string, string>} */
+
+/** @type {Object<string, () => Promise<{default: Controller}>>} */
+export const lazyControllers = {};
+
+export const isApplicationDebug = false;

src/StimulusBundle/assets/dist/loader.js

@@ -0,0 +1,80 @@
+/**
+ * Starts the Stimulus application and reads a map dump in the DOM to load controllers.
+ *
+ * Inspired by stimulus-loading.js from stimulus-rails.
+ */
+import { Application } from '@hotwired/stimulus';
+import { eagerControllers, lazyControllers, isApplicationDebug } from './controllers.js';
+
+const controllerAttribute = 'data-controller';
+
+export const loadControllers = (application) => {
+    // loop over the controllers map and require each controller
+    for (const name in eagerControllers) {
+        registerController(name, eagerControllers[name], application);
+    }
+
+    loadLazyControllers(application);
+};
+
+export const startStimulusApp = () => {
+    const application = Application.start();
+    application.debug = isApplicationDebug;
+
+    loadControllers(application);
+
+    return application;
+};
+
+function registerController(name, controller, application) {
+    if (canRegisterController(name, application)) {
+        application.register(name, controller)
+    }
+}
+
+function loadLazyControllers(application) {
+    lazyLoadExistingControllers(application, document);
+    lazyLoadNewControllers(application, document)
+}
+
+function lazyLoadExistingControllers(application, element) {
+  queryControllerNamesWithin(element).forEach(controllerName => loadController(controllerName, application))
+}
+function queryControllerNamesWithin(element) {
+  return Array.from(element.querySelectorAll(`[${controllerAttribute}]`)).map(extractControllerNamesFrom).flat()
+}
+function extractControllerNamesFrom(element) {
+  return element.getAttribute(controllerAttribute).split(/\s+/).filter(content => content.length)
+}
+function lazyLoadNewControllers(application, element) {
+  new MutationObserver((mutationsList) => {
+    for (const { attributeName, target, type } of mutationsList) {
+      switch (type) {
+        case 'attributes': {
+          if (attributeName === controllerAttribute && target.getAttribute(controllerAttribute)) {
+            extractControllerNamesFrom(target).forEach(controllerName => loadController(controllerName, application))
+          }
+        }
+
+        case 'childList': {
+          lazyLoadExistingControllers(application, target)
+        }
+      }
+    }
+  }).observe(element, { attributeFilter: [controllerAttribute], subtree: true, childList: true })
+}
+function canRegisterController(name, application){
+  return !application.router.modulesByIdentifier.has(name)
+}
+
+async function loadController(name, application) {
+    if (canRegisterController(name, application)) {
+        if (lazyControllers[name] === undefined) {
+            console.error(`Failed to autoload controller: ${name}`);
+        }
+
+        const controllerModule = await (lazyControllers[name]());
+
+        registerController(name, controllerModule.default, application);
+    }
+}

src/StimulusBundle/assets/package.json

@@ -0,0 +1,17 @@
+{
+    "name": "@symfony/stimulus-bundle",
+    "description": "Integration of @hotwired/stimulus into Symfony",
+    "version": "1.0.0",
+    "license": "MIT",
+    "symfony": {
+        "needsPackageAsADependency": false,
+        "importmap": {
+            "@hotwired/stimulus": "^3.0.0",
+            "@symfony/stimulus-bundle": "path:dist/loader.js"
+        }
+    },
+    "peerDependencies": {
+        "@hotwired/stimulus": "^3.0.0",
+        "@symfony/stimulus-bridge": "^3.2.0"
+    }
+}

src/StimulusBundle/composer.json

@@ -0,0 +1,39 @@
+{
+    "name": "symfony/stimulus-bundle",
+    "description": "Integration with your Symfony app & Stimulus!",
+    "keywords": ["symfony-ux"],
+    "license": "MIT",
+    "type": "symfony-bundle",
+    "authors": [
+        {
+            "name": "Symfony Community",
+            "homepage": "https://symfony.com/contributors"
+        }
+    ],
+    "require": {
+        "php": ">=8.1",
+        "symfony/config": "^5.4 || ^6.0",
+        "symfony/dependency-injection": "^5.4 || ^6.0",
+        "symfony/finder": "^5.4 || ^6.0",
+        "symfony/http-kernel": "^5.4 || ^6.0",
+        "twig/twig": "^2.15.3 || ^3.4.3"
+    },
+    "require-dev": {
+        "symfony/asset-mapper": "^6.3",
+        "symfony/framework-bundle": "^5.4 || ^6.0",
+        "symfony/phpunit-bridge": "^5.4 || ^6.0",
+        "symfony/twig-bundle": "^5.4 || ^6.0",
+        "zenstruck/browser": "^1.4"
+    },
+    "minimum-stability": "dev",
+    "autoload": {
+        "psr-4": {
+            "Symfony\\UX\\StimulusBundle\\": "src"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "Symfony\\UX\\StimulusBundle\\Tests\\": "tests/"
+        }
+    }
+}

src/StimulusBundle/config/services.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
+use Symfony\UX\StimulusBundle\AssetMapper\ControllersMapGenerator;
+use Symfony\UX\StimulusBundle\AssetMapper\StimulusLoaderJavaScriptCompiler;
+use Symfony\UX\StimulusBundle\Helper\StimulusHelper;
+use Symfony\UX\StimulusBundle\Twig\StimulusTwigExtension;
+use Symfony\UX\StimulusBundle\Ux\UxPackageReader;
+use Twig\Environment;
+use function Symfony\Component\DependencyInjection\Loader\Configurator\abstract_arg;
+use function Symfony\Component\DependencyInjection\Loader\Configurator\param;
+use function Symfony\Component\DependencyInjection\Loader\Configurator\service;
+
+return static function (ContainerConfigurator $container): void {
+    $container->services()
+        ->set('stimulus.helper', StimulusHelper::class)
+            ->arg('$twig', service(Environment::class)->nullOnInvalid())
+
+        ->set('stimulus.twig_extension', StimulusTwigExtension::class)
+            ->tag('twig.extension')
+
+        ->set('stimulus.asset_mapper.controllers_map_generator', ControllersMapGenerator::class)
+            ->args([
+                service('asset_mapper'),
+                service('stimulus.asset_mapper.ux_package_reader'),
+                abstract_arg('controller paths'),
+                abstract_arg('controllers_json_path'),
+            ])
+
+        ->set('stimulus.asset_mapper.ux_package_reader', UxPackageReader::class)
+            ->args([
+                param('kernel.project_dir'),
+            ])
+
+        ->set('stimulus.asset_mapper.loader_javascript_compiler', StimulusLoaderJavaScriptCompiler::class)
+            ->args([
+                service('stimulus.asset_mapper.controllers_map_generator'),
+                param('kernel.debug'),
+            ])
+            ->tag('asset_mapper.compiler', ['priority' => 100])
+    ;
+};