@ramstack/alpinegear-match 1.0.0-preview.1

package/README.md

@@ -0,0 +1,101 @@
+# @ramstack/alpinegear-match
+
+`@ramstack/alpinegear-match` is a plugin for [Alpine.js](https://alpinejs.dev/) that provides the `x-match` directive.
+
+This directive functions similarly to the `switch` statement in many programming languages, allowing you to conditionally render elements based on matching cases.
+
+## Installation
+
+### Using CDN
+To include the CDN version of this plugin, add the following `<script>` tag before the core `alpine.js` file:
+
+```html
+<!-- alpine.js plugin -->
+<script src="https://cdn.jsdelivr.net/npm/@ramstack/alpinegear-when@1/alpinegear-match.min.js" defer></script>
+
+<!-- alpine.js -->
+<script src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js" defer></script>
+```
+
+### Using NPM
+Alternatively, you can install the plugin via `npm`:
+
+```bash
+npm install --save @ramstack/alpinegear-match
+```
+
+Then initialize it in your bundle:
+
+```js
+import Alpine from "alpinejs";
+import match from "@ramstack/alpinegear-match";
+
+Alpine.plugin(match);
+Alpine.start();
+```
+
+## Usage
+The `x-match` directive is similar to using multiple consecutive `x-if` or `x-when` directives. However, using multiple `x-if` or `x-when` can make your markup harder to read and lead to code bloat.
+
+The `x-match` directive provides a cleaner solution by allowing you to define multiple blocks with conditions. The corresponding block will be displayed if its condition evaluates to true.
+
+Here's a simple example solving the classic **FizzBuzz** game:
+```html
+<div x-data="{ numbers: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17] }">
+    <template x-for="n in numbers">
+        <template x-match>
+            <div x-case="n % 3 == 0 && n % 5 == 0">Fizz Buzz</div>
+            <div x-case="n % 3 == 0">Fizz</div>
+            <div x-case="n % 5 == 0">Buzz</div>
+            <div x-default x-text="n"></div>
+        </template>
+    </template>
+</div>
+```
+
+While it's possible to wrap the loop's content in an additional `<div>` (since `x-for` only allows a single root element), or use a plugin like [@ramstack/alpinegear-fragment](https://github.com/rameel/ramstack.alpinegear.js/tree/main/src/plugins/fragment), to achieve similar results, the `x-match` directive provides a much cleaner and more readable approach. Additionally, it avoids introducing extra elements that are only needed to bypass these limitations.
+
+For comparison, here's how the same **FizzBuzz** game might look using `x-fragment`:
+
+```html
+<div x-data="{ numbers: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17] }">
+    <template x-for="n in numbers">
+        <div>
+            <template x-if="n % 3 == 0 && n % 5 == 0">
+                <div>Fizz Buzz</div>
+            </template>
+            <template x-if="n % 3 == 0">
+                <div>Fizz</div>
+            </template>
+            <template x-if="n % 5 == 0">
+                <div>Buzz</div>
+            </template>
+            <template x-if="n % 3 != 0 && n % 5 != 0">
+                <div x-text="n"></div>
+            </template>
+        </div>
+    </template>
+</div>
+```
+
+> [!IMPORTANT]
+> Ensure that `x-case` conditions are ordered from most specific to least specific. Otherwise, a more general case might intercept the condition, causing subsequent cases not to execute.
+
+> [!NOTE]
+> The `x-default` branch is optional and only renders if none of the `x-case` conditions evaluate to `true`.
+
+> [!TIP]
+> The `x-case` directive can be applied to regular HTML tags or `<template>` tags. When used with `<template>`, you can define multiple root elements, and all will be rendered.
+
+
+## Source code
+You can find the source code for this plugin on GitHub:
+
+https://github.com/rameel/ramstack.alpinegear.js/tree/main/src/plugins/match
+
+## Contributions
+Bug reports and contributions are welcome.
+
+## License
+This package is released as open source under the **MIT License**.
+See the [LICENSE](https://github.com/rameel/ramstack.alpinegear.js/blob/main/LICENSE) file for more details.

package/alpinegear-match.esm.js

@@ -0,0 +1,126 @@
+const warn = (...args) => console.warn("alpine-gear.js:", ...args);
+const is_template = el => el instanceof HTMLTemplateElement;
+const is_element = el => el.nodeType === Node.ELEMENT_NODE;
+
+function anchor_block(el, template, { addScopeToNode, cleanup, initTree, mutateDom, scope = {} }) {
+    if (el._r_block) {
+        return;
+    }
+
+    initialize();
+
+    let nodes = is_template(template)
+        ? [...template.content.cloneNode(true).childNodes]
+        : [template.cloneNode(true)];
+
+    mutateDom(() => {
+        for (let node of nodes) {
+            is_element(node) && addScopeToNode(node, scope, el);
+            el.parentElement.insertBefore(node, el);
+            is_element(node) && initTree(node);
+        }
+    });
+
+    el._r_block = {
+        template,
+        update() {
+            mutateDom(() => {
+                for (let node of nodes ?? []) {
+                    el.parentElement.insertBefore(node, el);
+                }
+            });
+        },
+        delete() {
+            el._r_block = null;
+            for (let node of nodes ?? []) {
+                node.remove();
+            }
+            nodes = null;
+        }
+    };
+
+    cleanup(() => el._r_block?.delete());
+}
+
+function initialize() {
+    document.body._r_block ??= (() => {
+        const observer = new MutationObserver(mutations => {
+            for (let mutation of mutations) {
+                for (let node of mutation.addedNodes) {
+                    node._r_block?.update();
+                }
+            }
+        });
+
+        observer.observe(document.body, { childList: true, subtree: true });
+        return observer;
+    })();
+}
+
+function create_getter(evaluate_later, ...args) {
+    const evaluate = evaluate_later(...args);
+    return () => {
+        let result;
+        evaluate(v => result = v);
+        return has_getter(result) ? result.get() : result;
+    };
+}
+
+function has_getter(value) {
+    return typeof value?.get === "function";
+}
+
+function plugin({ addScopeToNode, directive, initTree, mutateDom }) {
+    directive("match", (el, { }, { cleanup, effect, evaluateLater }) => {
+        if (!is_template(el)) {
+            warn("x-match can only be used on a 'template' tag.");
+            return;
+        }
+
+        const branches = [];
+        const has_default_case = () => branches.some(b => b.default);
+
+        for (let node of el.content.children) {
+            const expr = node.getAttribute("x-case");
+            if (expr !== null) {
+                has_default_case() && warn("The x-case directive cannot be appear after x-default.");
+                branches.push({ el: node, get_value: create_getter(evaluateLater, expr) });
+            }
+            else if (node.hasAttribute("x-default")) {
+                has_default_case() && warn("Only one x-default directive is allowed.");
+                branches.push({ el: node, get_value: () => true, default: true });
+            }
+            else {
+                warn("Element has no x-case or x-default directive and will be ignored.", node);
+            }
+        }
+
+        const activate = branch => {
+            if (el._r_block?.template !== branch.el) {
+                clear();
+                anchor_block(el, branch.el, {
+                    addScopeToNode,
+                    cleanup,
+                    initTree,
+                    mutateDom
+                });
+            }
+        };
+
+        const clear = () => el._r_block?.delete();
+
+        effect(() => {
+            let active;
+
+            for (let branch of branches) {
+                if (branch.get_value() && !active) {
+                    active = branch;
+                }
+            }
+
+            active ? activate(active) : clear();
+        });
+    });
+}
+
+export { plugin as match };

package/alpinegear-match.esm.min.js

@@ -0,0 +1 @@
+const e=e=>e instanceof HTMLTemplateElement,t=e=>e.nodeType===Node.ELEMENT_NODE;function o(e,...t){const o=e(...t);return()=>{let e;return o((t=>e=t)),t=e,"function"==typeof t?.get?e.get():e;var t}}function l({addScopeToNode:l,directive:n,initTree:r,mutateDom:c}){n("match",((n,{},{cleanup:a,effect:d,evaluateLater:u})=>{if(!e(n))return void console.warn("alpine-gear.js:","x-match can only be used on a 'template' tag.");const f=[];for(let e of n.content.children){const t=e.getAttribute("x-case");null!==t?f.push({el:e,get_value:o(u,t)}):e.hasAttribute("x-default")&&f.push({el:e,get_value:()=>!0,default:!0})}const i=()=>n._r_block?.delete();d((()=>{let o;for(let e of f)e.get_value()&&!o&&(o=e);var d;o?(d=o,n._r_block?.template!==d.el&&(i(),function(o,l,{addScopeToNode:n,cleanup:r,initTree:c,mutateDom:a,scope:d={}}){if(o._r_block)return;document.body._r_block??=(()=>{const e=new MutationObserver((e=>{for(let t of e)for(let e of t.addedNodes)e._r_block?.update()}));return e.observe(document.body,{childList:!0,subtree:!0}),e})();let u=e(l)?[...l.content.cloneNode(!0).childNodes]:[l.cloneNode(!0)];a((()=>{for(let e of u)t(e)&&n(e,d,o),o.parentElement.insertBefore(e,o),t(e)&&c(e)})),o._r_block={template:l,update(){a((()=>{for(let e of u??[])o.parentElement.insertBefore(e,o)}))},delete(){o._r_block=null;for(let e of u??[])e.remove();u=null}},r((()=>o._r_block?.delete()))}(n,d.el,{addScopeToNode:l,cleanup:a,initTree:r,mutateDom:c}))):i()}))}))}export{l as match};

package/alpinegear-match.js

@@ -0,0 +1,131 @@
+(function () {
+    'use strict';
+
+    const warn = (...args) => console.warn("alpine-gear.js:", ...args);
+    const is_template = el => el instanceof HTMLTemplateElement;
+    const is_element = el => el.nodeType === Node.ELEMENT_NODE;
+
+    function anchor_block(el, template, { addScopeToNode, cleanup, initTree, mutateDom, scope = {} }) {
+        if (el._r_block) {
+            return;
+        }
+
+        initialize();
+
+        let nodes = is_template(template)
+            ? [...template.content.cloneNode(true).childNodes]
+            : [template.cloneNode(true)];
+
+        mutateDom(() => {
+            for (let node of nodes) {
+                is_element(node) && addScopeToNode(node, scope, el);
+                el.parentElement.insertBefore(node, el);
+                is_element(node) && initTree(node);
+            }
+        });
+
+        el._r_block = {
+            template,
+            update() {
+                mutateDom(() => {
+                    for (let node of nodes ?? []) {
+                        el.parentElement.insertBefore(node, el);
+                    }
+                });
+            },
+            delete() {
+                el._r_block = null;
+                for (let node of nodes ?? []) {
+                    node.remove();
+                }
+                nodes = null;
+            }
+        };
+
+        cleanup(() => el._r_block?.delete());
+    }
+
+    function initialize() {
+        document.body._r_block ??= (() => {
+            const observer = new MutationObserver(mutations => {
+                for (let mutation of mutations) {
+                    for (let node of mutation.addedNodes) {
+                        node._r_block?.update();
+                    }
+                }
+            });
+
+            observer.observe(document.body, { childList: true, subtree: true });
+            return observer;
+        })();
+    }
+
+    function create_getter(evaluate_later, ...args) {
+        const evaluate = evaluate_later(...args);
+        return () => {
+            let result;
+            evaluate(v => result = v);
+            return has_getter(result) ? result.get() : result;
+        };
+    }
+
+    function has_getter(value) {
+        return typeof value?.get === "function";
+    }
+
+    function plugin({ addScopeToNode, directive, initTree, mutateDom }) {
+        directive("match", (el, { }, { cleanup, effect, evaluateLater }) => {
+            if (!is_template(el)) {
+                warn("x-match can only be used on a 'template' tag.");
+                return;
+            }
+
+            const branches = [];
+            const has_default_case = () => branches.some(b => b.default);
+
+            for (let node of el.content.children) {
+                const expr = node.getAttribute("x-case");
+                if (expr !== null) {
+                    has_default_case() && warn("The x-case directive cannot be appear after x-default.");
+                    branches.push({ el: node, get_value: create_getter(evaluateLater, expr) });
+                }
+                else if (node.hasAttribute("x-default")) {
+                    has_default_case() && warn("Only one x-default directive is allowed.");
+                    branches.push({ el: node, get_value: () => true, default: true });
+                }
+                else {
+                    warn("Element has no x-case or x-default directive and will be ignored.", node);
+                }
+            }
+
+            const activate = branch => {
+                if (el._r_block?.template !== branch.el) {
+                    clear();
+                    anchor_block(el, branch.el, {
+                        addScopeToNode,
+                        cleanup,
+                        initTree,
+                        mutateDom
+                    });
+                }
+            };
+
+            const clear = () => el._r_block?.delete();
+
+            effect(() => {
+                let active;
+
+                for (let branch of branches) {
+                    if (branch.get_value() && !active) {
+                        active = branch;
+                    }
+                }
+
+                active ? activate(active) : clear();
+            });
+        });
+    }
+
+    document.addEventListener("alpine:init", () => { Alpine.plugin(plugin); });
+
+})();

package/alpinegear-match.min.js

@@ -0,0 +1 @@
+!function(){"use strict";const e=e=>e instanceof HTMLTemplateElement,t=e=>e.nodeType===Node.ELEMENT_NODE;function o(e,...t){const o=e(...t);return()=>{let e;return o((t=>e=t)),t=e,"function"==typeof t?.get?e.get():e;var t}}function n({addScopeToNode:n,directive:l,initTree:r,mutateDom:c}){l("match",((l,{},{cleanup:a,effect:u,evaluateLater:d})=>{if(!e(l))return void console.warn("alpine-gear.js:","x-match can only be used on a 'template' tag.");const i=[];for(let e of l.content.children){const t=e.getAttribute("x-case");null!==t?i.push({el:e,get_value:o(d,t)}):e.hasAttribute("x-default")&&i.push({el:e,get_value:()=>!0,default:!0})}const f=()=>l._r_block?.delete();u((()=>{let o;for(let e of i)e.get_value()&&!o&&(o=e);var u;o?(u=o,l._r_block?.template!==u.el&&(f(),function(o,n,{addScopeToNode:l,cleanup:r,initTree:c,mutateDom:a,scope:u={}}){if(o._r_block)return;document.body._r_block??=(()=>{const e=new MutationObserver((e=>{for(let t of e)for(let e of t.addedNodes)e._r_block?.update()}));return e.observe(document.body,{childList:!0,subtree:!0}),e})();let d=e(n)?[...n.content.cloneNode(!0).childNodes]:[n.cloneNode(!0)];a((()=>{for(let e of d)t(e)&&l(e,u,o),o.parentElement.insertBefore(e,o),t(e)&&c(e)})),o._r_block={template:n,update(){a((()=>{for(let e of d??[])o.parentElement.insertBefore(e,o)}))},delete(){o._r_block=null;for(let e of d??[])e.remove();d=null}},r((()=>o._r_block?.delete()))}(l,u.el,{addScopeToNode:n,cleanup:a,initTree:r,mutateDom:c}))):f()}))}))}document.addEventListener("alpine:init",(()=>{Alpine.plugin(n)}))}();

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@ramstack/alpinegear-match",
+  "version": "1.0.0-preview.1",
+  "description": "@ramstack/alpinegear-match provides the 'x-match' Alpine.js directive, which functions similarly to the 'switch' statement in many programming languages, allowing to conditionally render elements based on matching cases.",
+  "author": "Rameel Burhan",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rameel/ramstack.alpinegear.js.git",
+    "directory": "src/plugins/match"
+  },
+  "keywords": [
+    "alpine.js",
+    "alpinejs"
+  ],
+  "main": "alpinegear-match.js",
+  "module": "alpinegear-match.esm.js"
+}