feat(core registry): replace option to override an already registered pattern

The first registration of a pattern name wins, so an add-on bundle
could not override a core pattern under its own name — it had to
blacklist the original and register a replacement under a different
name with the original trigger, and then bridge the original's
options by hand.

``registry.register(pattern, name, { replace: true })`` now replaces an
existing registration; ``Base.extend`` accepts ``replace: true`` as
pattern property. Together with the registry waiting for Module
Federation remotes before the initial scan, the replacement is in
place for the initial scan no matter whether the remote or the core
bundle registered first. Replacing after the registry was initialized
logs a warning: already initialized elements keep the previous
pattern, only new elements get the replacement. The blacklist still
wins over a replacement.

Also documents the new Module Federation globals in the README.

Author: petschki

README.md

@@ -135,6 +135,9 @@ global settings or access otherwise hidden objects.
 | window.\_\_patternslib_patterns_blacklist             | A list of patterns that should not be loaded.                        | []        |
 | window.\_\_patternslib_registry                       | Global access to the Patternslib registry object.                    | -         |
 | window.\_\_patternslib_registry_initialized           | True, if the registry has been initialized.                          | false     |
+| window.\_\_patternslib_registry_initializing          | True, while the registry waits for Module Federation remotes before the initial scan. | undefined |
+| window.\_\_patternslib_mf_initialized                 | Promise provided by the Module Federation helper of `@patternslib/dev`, resolved once all remote bundles are initialized. The registry waits for it before the initial scan. | undefined |
+| window.\_\_patternslib_mf_init_timeout                | Maximum time in milliseconds the registry waits for Module Federation remotes before scanning anyway. | 5000      |
 | window.\_\_patternslib_disable_modernizr (Deprecated) | Disable modernizr, but still write the js/no-js classes to the body. | undefined |
 
 ### Bundle build analyzation

src/core/base.js

@@ -141,7 +141,11 @@ Base.extend = function (patternProps) {
             `The pattern ${patternProps.name} does not have a trigger attribute, it will not be registered.`
         );
     } else if (patternProps.autoregister !== false) {
-        Registry.register(child, patternProps.name);
+        // ``replace: true`` replaces an already registered pattern with the
+        // same name, e.g. to override a core pattern from an add-on bundle.
+        Registry.register(child, patternProps.name, {
+            replace: patternProps.replace === true,
+        });
     }
     return child;
 };

src/core/basepattern.md

@@ -55,3 +55,37 @@ registry.register(Pattern);
 // Make it available
 export default Pattern;
 ```
+
+## Replacing a registered pattern
+
+The first registration of a pattern name wins — registering another pattern
+under an already used name is refused. To override a pattern, e.g. a core
+pattern from an add-on bundle, pass ``replace: true``:
+
+```javascript
+import registry from "@patternslib/patternslib/src/core/registry";
+import { Pattern as OriginalPattern } from "some-bundle/src/pat/example/example";
+
+class Pattern extends OriginalPattern {
+    // Keep the original name and trigger, so that existing markup and
+    // options (``data-pat-example``) keep working.
+    static name = "example";
+    static trigger = ".pat-example";
+
+    async init() {
+        // Customize, then let the original do the rest.
+        await super.init();
+    }
+}
+
+registry.register(Pattern, Pattern.name, { replace: true });
+```
+
+For old-style ``Base.extend`` patterns pass ``replace: true`` along with the
+pattern properties.
+
+The registry waits for Module Federation remote bundles before its initial
+DOM scan, so a replacement registered by a remote bundle is in place for the
+initial scan no matter whether the remote or the core bundle registered
+first. Elements which were already initialized with the previous pattern
+keep it; only elements initialized afterwards get the replacement.

src/core/registry.js

@@ -259,7 +259,17 @@ const registry = {
         document.body.classList.add("patterns-loaded");
     },
 
-    register(pattern, name) {
+    register(pattern, name, { replace = false } = {}) {
+        // Register a pattern under ``name`` (defaults to ``pattern.name``).
+        //
+        // By default the first registration wins: registering another
+        // pattern under an already used name is refused. With
+        // ``replace: true`` an existing registration is replaced instead —
+        // the way for add-on bundles to override a core pattern. Together
+        // with the registry waiting for Module Federation remotes before
+        // the initial scan (see ``init()``), the replacement is in place for
+        // the initial scan no matter whether the add-on or the core bundle
+        // registered first.
         name = name || pattern.name;
         if (!name) {
             log.error("Pattern lacks a name.", pattern);
@@ -277,8 +287,19 @@ const registry = {
         }
 
         if (registry.patterns[name]) {
-            log.debug(`Already have a pattern called ${name}.`);
-            return false;
+            if (!replace) {
+                log.debug(`Already have a pattern called ${name}.`);
+                return false;
+            }
+            if (window.__patternslib_registry_initialized) {
+                // Elements which were already initialized with the previous
+                // pattern keep it. Only new elements get the replacement.
+                log.warn(
+                    `Replacing pattern ${name} after the registry was initialized. Already initialized elements keep the previous pattern.`
+                );
+            } else {
+                log.debug(`Replacing pattern ${name}.`, pattern);
+            }
         }
         // register pattern to be used for scanning new content
         registry.patterns[name] = pattern;

src/core/registry.test.js

@@ -334,6 +334,107 @@ describe("pat-registry: The registry for patterns", function () {
     });
 
 
+    describe("register with replace", function () {
+        const reset = () => {
+            window.__patternslib_registry_initialized = false;
+            delete window.__patternslib_patterns_blacklist;
+        };
+
+        beforeEach(reset);
+        afterEach(function () {
+            reset();
+            jest.restoreAllMocks();
+        });
+
+        const make_pattern = (text) =>
+            class extends BasePattern {
+                static name = "example";
+                static trigger = ".pat-example";
+                init() {
+                    this.el.innerHTML = text;
+                }
+            };
+
+        it("Refuses to register a pattern under an already used name by default", function () {
+            const first = make_pattern("first");
+            const second = make_pattern("second");
+
+            expect(registry.register(first)).toBe(true);
+            expect(registry.register(second)).toBe(false);
+            expect(registry.patterns.example).toBe(first);
+        });
+
+        it("Replaces an existing pattern with replace: true", function () {
+            const first = make_pattern("first");
+            const second = make_pattern("second");
+
+            registry.register(first);
+            expect(registry.register(second, "example", { replace: true })).toBe(true);
+            expect(registry.patterns.example).toBe(second);
+        });
+
+        it("Uses the replacement when scanning", async function () {
+            registry.register(make_pattern("first"));
+            registry.register(make_pattern("second"), "example", { replace: true });
+
+            const tree = document.createElement("div");
+            tree.setAttribute("class", "pat-example");
+            registry.scan(tree);
+            await utils.timeout(1);
+
+            expect(tree.textContent).toBe("second");
+        });
+
+        it("Base.extend replaces an existing pattern with replace: true", function () {
+            const first = Base.extend({
+                name: "example",
+                trigger: ".pat-example",
+                init: function () {},
+            });
+            const second = Base.extend({
+                name: "example",
+                trigger: ".pat-example",
+                replace: true,
+                init: function () {},
+            });
+
+            expect(registry.patterns.example).not.toBe(first);
+            expect(registry.patterns.example).toBe(second);
+        });
+
+        it("Base.extend without replace keeps the first registration", function () {
+            const first = Base.extend({
+                name: "example",
+                trigger: ".pat-example",
+                init: function () {},
+            });
+            Base.extend({
+                name: "example",
+                trigger: ".pat-example",
+                init: function () {},
+            });
+
+            expect(registry.patterns.example).toBe(first);
+        });
+
+        it("Re-scans for a replaced pattern when the registry is already initialized", function () {
+            registry.register(make_pattern("first"));
+            window.__patternslib_registry_initialized = true;
+            const scan_spy = jest.spyOn(registry, "scan").mockImplementation(() => {});
+
+            registry.register(make_pattern("second"), "example", { replace: true });
+
+            expect(scan_spy).toHaveBeenCalledWith(document.body, ["example"]);
+        });
+
+        it("Does not replace a blacklisted pattern", function () {
+            registry.register(make_pattern("first"));
+            window.__patternslib_patterns_blacklist = ["example"];
+
+            expect(registry.register(make_pattern("second"), "example", { replace: true })).toBe(false);
+        });
+    });
+
     describe("init with Module Federation", function () {
         let scan_spy;