Merge pull request #1061 from Patternslib/basepattern

Pattern base class / backwards compatible approach

Author: thet

src/core/basepattern.js

@@ -0,0 +1,77 @@
+/**
+ * A Base pattern for creating scoped patterns.
+ *
+ * Each instance of a pattern has its own local scope.
+ * A new instance is created for each DOM element on which a pattern applies.
+ *
+ * For usage, see basepattern.md
+ */
+import logging from "./logging";
+
+const log = logging.getLogger("Patternslib Base");
+
+class BasePattern {
+    static name; // name of pattern used in Registry.
+    static trigger; // A CSS selector to match elements that should trigger the pattern instantiation.
+    parser; // Options parser.
+
+    constructor(el, options = {}) {
+        // Make static ``name`` and ``trigger`` available on instance.
+        this.name = this.constructor.name;
+        this.trigger = this.constructor.trigger;
+
+        if (!el) {
+            log.warn(`No element given to pattern ${this.name}.`);
+            return;
+        }
+        if (el.jquery) {
+            el = el[0];
+        }
+        this.el = el;
+
+        // Initialize asynchronously.
+        //
+        // 1) We need to call the concrete implementation of ``init``, but the
+        //    inheritance chain is not yet set up and ``init`` not available.
+        //
+        // 2) We want to wait for the init() to successfuly finish and fire an
+        //    event then.
+        //    But the constructer cannot not return a Promise, thus not be
+        //    asynchronous but only return itself.
+        //
+        // Both limitations are gone in next tick.
+        //
+        window.setTimeout(async () => {
+            if (typeof this.el[`pattern-${this.name}`] !== "undefined") {
+                // Do not reinstantiate
+                log.debug(`Not reinstatiating the pattern ${this.name}.`, this.el);
+                return;
+            }
+
+            // Create the options object by parsing the element and using the
+            // optional optios as default.
+            this.options = this.parser?.parse(this.el, options) ?? options;
+
+            // Store pattern instance on element
+            this.el[`pattern-${this.name}`] = this;
+
+            // Initialize the pattern
+            await this.init();
+
+            // Notify that now ready
+            this.el.dispatchEvent(
+                new Event(`init.${this.name}.patterns`, {
+                    bubbles: true,
+                    cancelable: true,
+                })
+            );
+        }, 0);
+    }
+
+    init() {
+        // Extend this method in your pattern.
+    }
+}
+
+export default BasePattern;
+export { BasePattern };

src/core/basepattern.md

@@ -0,0 +1,46 @@
+# BasePattern base pattern class.
+
+A Base pattern for creating scoped patterns.
+
+Each instance of a pattern has its own local scope.
+A new instance is created for each DOM element on which a pattern applies.
+
+
+## Usage:
+
+Also see: https://github.com/Patternslib/pat-PATTERN_TEMPLATE
+
+
+    import { BasePattern } from "@patternslib/patternslib/src/core/basepattern";
+    import Parser from "@patternslib/patternslib/src/core/parser";
+    import registry from "@patternslib/patternslib/src/core/registry";
+
+    export const parser = new Parser("test-pattern");
+    parser.addArgument("example-option", "Stranger");
+
+    class Pattern extends BasePattern {
+        static name = "test-pattern";
+        static trigger = ".pat-test-pattern";
+        parser = parser;
+
+        async init() {
+            import("./test-pattern.scss");
+
+            // Try to avoid jQuery, but here is how to import it.
+            // eslint-disable-next-line no-unused-vars
+            const $ = (await import("jquery")).default;
+
+            // The options are automatically created, if parser is defined.
+            const example_option = this.options.exampleOption;
+            this.el.innerHTML = `
+                <p>hello, ${example_option}, this is pattern ${this.name} speaking.</p>
+            `;
+        }
+    }
+
+    // Register Pattern class in the global pattern registry
+    registry.register(Pattern);
+
+    // Make it available
+    export default Pattern;
+

src/core/basepattern.test.js

@@ -0,0 +1,146 @@
+import { BasePattern } from "./basepattern";
+import registry from "./registry";
+import utils from "./utils";
+import { jest } from "@jest/globals";
+
+describe("Basepattern class tests", function () {
+    const patterns = registry.patterns;
+
+    beforeEach(function () {
+        registry.clear();
+    });
+
+    afterEach(function () {
+        registry.patterns = patterns;
+        jest.restoreAllMocks();
+    });
+
+    it("1 - Trigger and name are statically available on the class.", async function () {
+        class Pat extends BasePattern {
+            static name = "example";
+            static trigger = ".example";
+        }
+
+        // trigger and name are static and available on the class itself
+        expect(Pat.trigger).toBe(".example");
+        expect(Pat.name).toBe("example");
+
+        const el = document.createElement("div");
+
+        const pat = new Pat(el);
+        await utils.timeout(1);
+
+        expect(pat.name).toEqual("example");
+        expect(pat.trigger).toEqual(".example");
+    });
+
+    it("2 - Base pattern is class based and does inheritance, polymorphism, encapsulation, ... pt1", async function () {
+        class Pat1 extends BasePattern {
+            some = "thing";
+        }
+        class Pat2 extends Pat1 {
+            init() {
+                this.extra();
+            }
+            extra() {
+                this.some = "other";
+            }
+        }
+
+        const el1 = document.createElement("div");
+        const el2 = document.createElement("div");
+
+        const pat1 = new Pat1(el1);
+        await utils.timeout(1);
+
+        const pat2 = new Pat2(el2);
+        await utils.timeout(1);
+
+        expect(pat1 instanceof Pat1).toBe(true);
+        expect(pat1 instanceof Pat2).toBe(false);
+        expect(pat1.el).toEqual(el1);
+        expect(pat1.some).toEqual("thing");
+
+        expect(pat2 instanceof Pat1).toBe(true);
+        expect(pat2 instanceof Pat2).toBe(true);
+        expect(pat2.el).toEqual(el2);
+        expect(pat2.some).toEqual("other");
+    });
+
+    it("3 - can be extended multiple times", async function () {
+        class Pat1 extends BasePattern {
+            static name = "example1";
+            something = "else";
+            init() {}
+        }
+        class Pat2 extends Pat1 {
+            static name = "example2";
+            some = "thing2";
+            init() {}
+        }
+        class Pat3 extends Pat2 {
+            static name = "example3";
+            some = "thing3";
+            init() {}
+        }
+
+        const el = document.createElement("div");
+        const pat1 = new Pat1(el);
+        await utils.timeout(1);
+        const pat2 = new Pat2(el);
+        await utils.timeout(1);
+        const pat3 = new Pat3(el);
+        await utils.timeout(1);
+
+        expect(pat1.name).toEqual("example1");
+        expect(pat1.something).toEqual("else");
+        expect(pat1.some).toEqual(undefined);
+        expect(pat1 instanceof BasePattern).toBeTruthy();
+        expect(pat1 instanceof Pat2).toBeFalsy();
+        expect(pat1 instanceof Pat3).toBeFalsy();
+
+        expect(pat2.name).toEqual("example2");
+        expect(pat2.something).toEqual("else");
+        expect(pat2.some).toEqual("thing2");
+        expect(pat2 instanceof BasePattern).toBeTruthy();
+        expect(pat2 instanceof Pat1).toBeTruthy();
+        expect(pat2 instanceof Pat3).toBeFalsy();
+
+        expect(pat3.name).toEqual("example3");
+        expect(pat3.something).toEqual("else");
+        expect(pat3.some).toEqual("thing3");
+        expect(pat3 instanceof BasePattern).toBeTruthy();
+        expect(pat3 instanceof Pat1).toBeTruthy();
+        expect(pat3 instanceof Pat2).toBeTruthy();
+    });
+
+    it("4 - The pattern instance is stored on the element itself.", async function () {
+        class Pat extends BasePattern {
+            static name = "example";
+        }
+
+        const el = document.createElement("div");
+        const pat = new Pat(el);
+        await utils.timeout(1);
+
+        expect(el["pattern-example"]).toEqual(pat);
+    });
+
+    it("5 - Registers with the registry.", async function () {
+        class Pat extends BasePattern {
+            static name = "example";
+            static trigger = ".example";
+        }
+
+        registry.register(Pat);
+
+        const el = document.createElement("div");
+        el.classList.add("example");
+
+        registry.scan(el);
+        await utils.timeout(1);
+
+        // gh-copilot wrote this line.
+        expect(el["pattern-example"]).toBeInstanceOf(Pat);
+    });
+});

src/core/registry.js

@@ -110,19 +110,24 @@ const registry = {
          */
         const $el = $(el);
         const pattern = registry.patterns[name];
-        if (pattern.init) {
-            const plog = logging.getLogger(`pat.${name}`);
-            if ($el.is(pattern.trigger)) {
-                plog.debug("Initialising.", $el);
-                try {
+        const plog = logging.getLogger(`pat.${name}`);
+        if (el.matches(pattern.trigger)) {
+            plog.debug("Initialising.", el);
+            try {
+                if (pattern.init) {
+                    // old style initialisation
                     pattern.init($el, null, trigger);
-                    plog.debug("done.");
-                } catch (e) {
-                    if (dont_catch) {
-                        throw e;
-                    }
-                    plog.error("Caught error:", e);
+                } else {
+                    // class based pattern initialisation
+                    new pattern($el, null, trigger);
+                }
+
+                plog.debug("done.");
+            } catch (e) {
+                if (dont_catch) {
+                    throw e;
                 }
+                plog.error("Caught error:", e);
             }
         }
     },