feat: Add class based base pattern.

This is a new way to define Patterns by extending the BasePattern class and instantiating it on an element.
This is additionally to the old Base pattern approach or even the very old approach of just defining a Pattern following the specs.
The BasePattern class in core/basepattern uses JavaScript classes with all the object oriented benefits.
Yes, that might be syntactic sugar, but then again not.

For usage see: src/core/basepattern.md

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);
+    });
+});