feature #482 [Vue] Add support for lazy-loading with Async Components (Kocal)

This PR was squashed before being merged into the 2.x branch.

Discussion
----------

[Vue] Add support for lazy-loading with Async Components

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes <!-- please update src/**/CHANGELOG.md files -->
| Tickets       | Fix #... <!-- prefix each issue number with "Fix #", no need to create an issue if none exist, explain below instead -->
| License       | MIT

I was a bit surprised when trying the Symfony UX' Vue integration, to see all Vue components/controllers to be loaded to render at least only one controllers.
This PR aims to reduce the bundle size and only load the required code and Vue controllers to render on the page.

To enable lazy-loading, add the 4th parameter `"lazy"` to `require.context()`:
```diff
- registerVueControllerComponents(require.context('./vue/controllers', true, /\.vue$/));
+ registerVueControllerComponents(require.context('./vue/controllers', true, /\.vue$/, "lazy"));
```
_Note: the sync-loading still works_

# _Real life_ example

Given 6 really simple Vue controllers which all look the same:
<img width="688" alt="image" src="https://user-images.githubusercontent.com/2103975/192136360-556dcee8-7eb7-423d-976f-7b000bf516a7.png">

If I render only two of them on a single page:
<img width="524" alt="image" src="https://user-images.githubusercontent.com/2103975/192136376-05dd75f7-b917-4732-a1dd-49a0081ecf62.png">

## Before

<img width="1033" alt="Capture d’écran 2022-09-25 à 11 03 16" src="https://user-images.githubusercontent.com/2103975/192136387-4d415c40-6960-4e46-8bc4-7458730d5301.png">

You can see the `app.js` is about 4.8 kB, it contains all of the 6 Vue controllers.

## After

<img width="1033" alt="Capture d’écran 2022-09-25 à 11 03 38" src="https://user-images.githubusercontent.com/2103975/192136390-df1274ac-dd57-45a3-a7a7-86f2659067ba.png">

You can see the `app.js` is now about 3.4 kB, and two more files have been lazy-loaded (our two Vue controllers rendered on the page).

On a real project, with a lot of Vue controllers, the difference would be very significative. I will try to post some results when migrating our main project at work.

---

Note: ~I still have to add tests and update the documentation.~ done

Commits
-------

8fa08d0 [Vue] Add support for lazy-loading with Async Components

Author: weaverryan

src/Vue/Resources/assets/dist/register_controller.js

@@ -1,15 +1,39 @@
+import { defineAsyncComponent } from 'vue';
+
 function registerVueControllerComponents(context) {
-    const vueControllers = {};
-    const importAllVueComponents = (r) => {
-        r.keys().forEach((key) => (vueControllers[key] = r(key).default));
-    };
-    importAllVueComponents(context);
-    window.resolveVueComponent = (name) => {
-        const component = vueControllers[`./${name}.vue`];
-        if (typeof component === 'undefined') {
-            throw new Error(`Vue controller "${name}" does not exist`);
+    const vueControllers = context.keys().reduce((acc, key) => {
+        acc[key] = undefined;
+        return acc;
+    }, {});
+    function loadComponent(name) {
+        const componentPath = `./${name}.vue`;
+        if (componentPath in vueControllers && typeof vueControllers[componentPath] === 'undefined') {
+            const module = context(componentPath);
+            if (module.default) {
+                vueControllers[componentPath] = module.default;
+            }
+            else if (module instanceof Promise) {
+                vueControllers[componentPath] = defineAsyncComponent(() => new Promise((resolve, reject) => {
+                    module
+                        .then((resolvedModule) => {
+                        if (resolvedModule.default) {
+                            resolve(resolvedModule.default);
+                        }
+                        else {
+                            reject(new Error(`Cannot find default export in async Vue controller "${name}".`));
+                        }
+                    })
+                        .catch(reject);
+                }));
+            }
+            else {
+                throw new Error(`Vue controller "${name}" does not exist.`);
+            }
         }
-        return component;
+        return vueControllers[componentPath];
+    }
+    window.resolveVueComponent = (name) => {
+        return loadComponent(name);
     };
 }
 

src/Vue/Resources/assets/src/register_controller.ts

@@ -10,6 +10,7 @@
 'use strict';
 
 import type { Component } from 'vue';
+import { defineAsyncComponent } from 'vue';
 
 declare global {
     function resolveVueComponent(name: string): Component;
@@ -20,21 +21,45 @@ declare global {
 }
 
 export function registerVueControllerComponents(context: __WebpackModuleApi.RequireContext) {
-    const vueControllers: { [key: string]: object } = {};
+    const vueControllers = context.keys().reduce((acc, key) => {
+        acc[key] = undefined;
+        return acc;
+    }, {} as Record<string, object | undefined>);
 
-    const importAllVueComponents = (r: __WebpackModuleApi.RequireContext) => {
-        r.keys().forEach((key) => (vueControllers[key] = r(key).default));
-    };
+    function loadComponent(name: string): object | never {
+        const componentPath = `./${name}.vue`;
+
+        if (componentPath in vueControllers && typeof vueControllers[componentPath] === 'undefined') {
+            const module = context(componentPath);
+            if (module.default) {
+                vueControllers[componentPath] = module.default;
+            } else if (module instanceof Promise) {
+                vueControllers[componentPath] = defineAsyncComponent(
+                    () =>
+                        new Promise((resolve, reject) => {
+                            module
+                                .then((resolvedModule) => {
+                                    if (resolvedModule.default) {
+                                        resolve(resolvedModule.default);
+                                    } else {
+                                        reject(
+                                            new Error(`Cannot find default export in async Vue controller "${name}".`)
+                                        );
+                                    }
+                                })
+                                .catch(reject);
+                        })
+                );
+            } else {
+                throw new Error(`Vue controller "${name}" does not exist.`);
+            }
+        }
 
-    importAllVueComponents(context);
+        return vueControllers[componentPath] as object;
+    }
 
     // Expose a global Vue loader to allow rendering from the Stimulus controller
     window.resolveVueComponent = (name: string): object => {
-        const component = vueControllers[`./${name}.vue`];
-        if (typeof component === 'undefined') {
-            throw new Error(`Vue controller "${name}" does not exist`);
-        }
-
-        return component;
+        return loadComponent(name);
     };
 }

src/Vue/Resources/assets/test/fixtures-lazy/Goodbye.vue

@@ -0,0 +1,3 @@
+<template>
+    <h1>Goodbye {{ name }}</h1>
+</template>

src/Vue/Resources/assets/test/register_controller.test.ts

@@ -12,15 +12,24 @@
 import {registerVueControllerComponents} from '../src/register_controller';
 import {createRequireContextPolyfill} from './util/require_context_poylfill';
 import Hello from './fixtures/Hello.vue'
+import Goodbye from './fixtures-lazy/Goodbye.vue'
 
 require.context = createRequireContextPolyfill(__dirname);
 
 describe('registerVueControllerComponents', () => {
-    it('test', () => {
+    it('test should resolve components synchronously', () => {
         registerVueControllerComponents(require.context('./fixtures', true, /\.vue$/));
         const resolveComponent = window.resolveVueComponent;
 
         expect(resolveComponent).not.toBeUndefined();
         expect(resolveComponent('Hello')).toBe(Hello);
     });
+
+    it('test should resolve lazy components asynchronously', () => {
+        registerVueControllerComponents(require.context('./fixtures-lazy', true, /\.vue$/, 'lazy'));
+        const resolveComponent = window.resolveVueComponent;
+
+        expect(resolveComponent).not.toBeUndefined();
+        expect(resolveComponent('Goodbye')).toBe(Goodbye);
+    });
 });

src/Vue/Resources/doc/index.rst

@@ -47,6 +47,10 @@ You also need to add the following lines at the end to your ``assets/app.js`` fi
     // they are not necessary.
     registerVueControllerComponents(require.context('./vue/controllers', true, /\.vue$/));
 
+    // If you prefer to lazy-load your Vue.js controller components, in order to reduce to keep the JavaScript bundle the smallest as possible,
+    // and improve performances, you can use the following line instead:
+    //registerVueControllerComponents(require.context('./vue/controllers', true, /\.vue$/, 'lazy'));
+
 
 Usage
 -----

ux.symfony.com/assets/app.js

@@ -14,4 +14,4 @@ import Tab from 'bootstrap/js/dist/tab';
 
 // initialize symfony/ux-react
 registerReactControllerComponents(require.context('./react/controllers', true, /\.(j|t)sx?$/));
-registerVueControllerComponents(require.context('./vue/controllers', true, /\.vue?$/));
+registerVueControllerComponents(require.context('./vue/controllers', true, /\.vue?$/, 'lazy'));