@ramstack/alpinegear-fragment 1.0.0-preview.1

package/README.md

@@ -0,0 +1,88 @@
+# @ramstack/alpinegear-fragment
+
+`@ramstack/alpinegear-fragment` is a plugin for [Alpine.js](https://alpinejs.dev/) that provides the `x-fragment` directive.
+
+This directive allows you to use multiple root elements in your templates, similar to the `Fragment` feature found in frameworks like `Vue.js` and `React`. It is particularly useful when you want to avoid wrapping elements in unnecessary container tags.
+
+
+## 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-fragment@1/alpinegear-fragment.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-fragment
+```
+
+Then initialize it in your bundle:
+
+```js
+import Alpine from "alpinejs";
+import fragment from "@ramstack/alpinegear-fragment";
+
+Alpine.plugin(fragment);
+Alpine.start();
+```
+
+## Usage
+With the `x-fragment` directive, you can use multiple root elements in your components without needing a wrapper container:
+
+```html
+<div x-data="{ show: true, message: 'Example' }">
+    <div>
+        <button @click="show = !show">Edit Message</button>
+    </div>
+
+    <template x-if="show">
+        <template x-fragment>
+            <label>Message:</label>
+            <input x-model="message" />
+        </template>
+    </template>
+</div>
+```
+In this example, the `x-fragment` directive allows the `<label>` and `<input>` elements to exist side by side without a parent container.
+
+### Using with `x-for`
+The `x-fragment` directive can also be used with the directive `x-for`, giving you the flexibility to render multiple sibling elements for each iteration without wrapping them:
+
+```html
+<div x-data="{
+    items: [
+        { id: 1, term: 'Item 1', description: 'Description 1' },
+        { id: 2, term: 'Item 2', description: 'Description 2' },
+        { id: 3, term: 'Item 3', description: 'Description 3' } ]
+    }">
+    <dl>
+        <template x-for="item in items" :key="item.id">
+            <template x-fragment>
+                <dt x-text="item.term"></dt>
+                <dd x-text="item.description"></dd>
+            </template>
+        </template>
+    </dl>
+</div>
+```
+
+## Source code
+You can find the source code for this plugin on GitHub:
+
+https://github.com/rameel/ramstack.alpinegear.js/tree/main/src/plugins/fragment
+
+## 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-fragment.esm.js

@@ -0,0 +1,71 @@
+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 plugin({ addScopeToNode, directive, initTree, mutateDom }) {
+    directive("fragment", (el, {}, { cleanup }) => {
+        if (!is_template(el)) {
+            warn("x-fragment can only be used on a 'template' tag.");
+            return;
+        }
+
+        anchor_block(el, el, { addScopeToNode, cleanup, initTree, mutateDom });
+    });
+}
+
+export { plugin as fragment };

package/alpinegear-fragment.esm.min.js

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

package/alpinegear-fragment.js

@@ -0,0 +1,76 @@
+(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 plugin({ addScopeToNode, directive, initTree, mutateDom }) {
+        directive("fragment", (el, {}, { cleanup }) => {
+            if (!is_template(el)) {
+                warn("x-fragment can only be used on a 'template' tag.");
+                return;
+            }
+
+            anchor_block(el, el, { addScopeToNode, cleanup, initTree, mutateDom });
+        });
+    }
+
+    document.addEventListener("alpine:init", () => { Alpine.plugin(plugin); });
+
+})();

package/alpinegear-fragment.min.js

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

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@ramstack/alpinegear-fragment",
+  "version": "1.0.0-preview.1",
+  "description": "@ramstack/alpinegear-fragment provides 'x-format' Alpine.js directive, allowing for fragment-like behavior similar to what's available in frameworks like 'Vue.js' or 'React', where multiple root elements can be grouped together.",
+  "author": "Rameel Burhan",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rameel/ramstack.alpinegear.js.git",
+    "directory": "src/plugins/fragment"
+  },
+  "keywords": [
+    "alpine.js",
+    "alpinejs"
+  ],
+  "main": "alpinegear-fragment.js",
+  "module": "alpinegear-fragment.esm.js"
+}