@ramstack/alpinegear-format 1.0.0-preview.1

package/README.md

@@ -0,0 +1,145 @@
+# @ramstack/alpinegear-format
+
+`@ramstack/alpinegear-format` is a plugin for [Alpine.js](https://alpinejs.dev/) that provides the `x-format` directive.
+
+This directive allows you to easily interpolate text using a template syntax similar to what's available in `Vue.js`.
+
+## 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-format@1/alpinegear-format.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-format
+```
+
+Then initialize it in your bundle:
+
+```js
+import Alpine from "alpinejs";
+import format from "@ramstack/alpinegear-format";
+
+Alpine.plugin(format);
+Alpine.start();
+```
+
+## Usage
+The `x-format` directive enables you to use double curly braces (`{{ ... }}`) to evaluate expressions
+and inject their values into the DOM.
+
+```html
+<div x-data="{ message: 'Hello, World!'}" x-format>
+    <span>Message: {{ message }}</span>
+</div>
+```
+
+In this example, `{{ message }}` will be replaced by the value of the `message` property,
+and the content will update whenever the `message` property changes.
+
+### Using with Attributes
+The `x-format` directive can also be used to interpolate values inside HTML attributes:
+
+```html
+<div x-data="{ message: 'Hello, World!'}" x-format>
+    <span title="Message: {{ message }}">
+        {{ message }}
+        <label>
+            Message: <input x-model="message" />
+        </label>
+    </span>
+</div>
+```
+
+Just like with text interpolation, the attribute values will be updated automatically when the data changes.
+
+> [!WARNING]
+> Keep in mind that interpolation within a `<textarea>` element may not work as you expect.
+>
+> Use `x-model` instead.
+
+### Using `once` modifier
+The `once` modifier allows you to interpolate the template only once.
+After the initial rendering, the content remains static and will not update, even if the data changes.
+
+```html
+<div x-data="{ message: 'Hello, World!'}" x-format.once>
+    <span title="Message: {{ message }}">
+        {{ message }}
+    </span>
+</div>
+```
+
+> [!IMPORTANT]
+> By default, `x-format` treats the interpolated values as plain text, not HTML.
+>
+> If you need to render HTML, you should use the `x-html` directive instead.
+
+
+## Optimization
+The `x-format` directive is optimized to update only the parts of the text that change,
+without replacing the entire DOM element. This is especially useful for large or complex DOM structures.
+
+For example:
+```html
+<div x-data="{ message: 'Hello, World!'}" x-format>
+    The 'message' value is '{{ message }}' and it updates when the property changes.
+</div>
+```
+
+In this case, the text will be split into three separate text nodes:
+1. `The 'message' value is '`
+2. `{{ message }}`
+3. `' and it updates when the property changes.`
+
+Only the `{{ message }}` text node will be updated, while the static nodes will remain unchanged.
+
+> [!NOTE]
+> This optimization does not apply to attribute values.
+
+
+## Dynamic Elements
+Since the `x-format` directive doesn't automatically track changes to the DOM,
+newly added elements (e.g., via `x-if` or `x-for`) will not automatically interpolate their templates.
+
+For instance, in the example below, the `{{ message }}` inside `x-if` remains unchanged:
+
+```html
+<div x-data="{ show: false, message: 'Hello, World!'}" x-format>
+    <template x-if="show">
+        <span>{{ message }}</span>
+    </template>
+</div>
+```
+
+To ensure proper interpolation, include the `x-format` directive in the dynamically rendered elements:
+
+```html
+<div x-data="{ show: false, message: 'Hello, World!'}">
+    <template x-if="show">
+        <span x-format>{{ message }}</span>
+    </template>
+</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/format
+
+## 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-format.esm.js

@@ -0,0 +1,100 @@
+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";
+}
+
+const is_nullish = value => value === null || value === undefined;
+const has_modifier = (modifiers, modifier) => modifiers.includes(modifier);
+
+function plugin({ directive, mutateDom }) {
+    directive("format", (el, { modifiers }, { effect, evaluateLater }) => {
+        const cache = new Map;
+        const placeholder_regex = /{{(?<expr>.+?)}}/g;
+        const is_once = has_modifier(modifiers, "once");
+
+        process(el);
+
+        function get_eval_fn(expression) {
+            let getter = cache.get(expression);
+            if (is_nullish(getter)) {
+                getter = create_getter(evaluateLater, expression);
+                cache.set(expression, getter);
+            }
+
+            return getter;
+        }
+
+        function update(callback) {
+            if (is_once) {
+                mutateDom(() => callback());
+                cache.clear();
+            }
+            else {
+                effect(() => mutateDom(() => callback()));
+            }
+        }
+
+        function process(node) {
+            switch (node.nodeType) {
+                case Node.TEXT_NODE:
+                    process_text_node(node);
+                    break;
+
+                case Node.ELEMENT_NODE:
+                    process_nodes(node);
+                    process_attributes(node);
+                    break;
+            }
+        }
+
+        function process_text_node(node) {
+            const tokens = node.textContent.split(placeholder_regex);
+
+            if (tokens.length > 1) {
+                const fragment = new DocumentFragment();
+
+                for (let i = 0; i < tokens.length; i++) {
+                    if ((i % 2) === 0) {
+                        fragment.appendChild(document.createTextNode(tokens[i]));
+                    }
+                    else {
+                        const get_value = get_eval_fn(tokens[i]);
+                        const text = document.createTextNode("");
+
+                        fragment.append(text);
+                        update(() => text.textContent = get_value());
+                    }
+                }
+
+                mutateDom(() =>
+                    node.parentElement.replaceChild(fragment, node));
+            }
+        }
+
+        function process_attributes(node) {
+            for (let attr of node.attributes) {
+                const matches = [...attr.value.matchAll(placeholder_regex)];
+                if (matches.length) {
+                    const template = attr.value;
+                    update(() => attr.value = template.replace(placeholder_regex, (_, expr) => get_eval_fn(expr)()));
+                }
+            }
+        }
+
+        function process_nodes(node) {
+            for (let child of node.childNodes) {
+                process(child);
+            }
+        }
+    });
+}
+
+export { plugin as format };

package/alpinegear-format.esm.min.js

@@ -0,0 +1 @@
+function e({directive:e,mutateDom:t}){e("format",((e,{modifiers:n},{effect:o,evaluateLater:c})=>{const a=new Map,l=/{{(?<expr>.+?)}}/g,r=(e=>e.includes("once"))(n);function f(e){let t=a.get(e);return null==t&&(t=function(e,...t){const n=e(...t);return()=>{let e;return n((t=>e=t)),t=e,"function"==typeof t?.get?e.get():e;var t}}(c,e),a.set(e,t)),t}function i(e){r?(t((()=>e())),a.clear()):o((()=>t((()=>e()))))}!function e(n){switch(n.nodeType){case Node.TEXT_NODE:!function(e){const n=e.textContent.split(l);if(n.length>1){const o=new DocumentFragment;for(let e=0;n.length>e;e++)if(e%2==0)o.appendChild(document.createTextNode(n[e]));else{const t=f(n[e]),c=document.createTextNode("");o.append(c),i((()=>c.textContent=t()))}t((()=>e.parentElement.replaceChild(o,e)))}}(n);break;case Node.ELEMENT_NODE:!function(t){for(let n of t.childNodes)e(n)}(n),function(e){for(let t of e.attributes)if([...t.value.matchAll(l)].length){const e=t.value;i((()=>t.value=e.replace(l,((e,t)=>f(t)()))))}}(n)}}(e)}))}export{e as format};

package/alpinegear-format.js

@@ -0,0 +1,105 @@
+(function () {
+    'use strict';
+
+    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";
+    }
+
+    const is_nullish = value => value === null || value === undefined;
+    const has_modifier = (modifiers, modifier) => modifiers.includes(modifier);
+
+    function plugin({ directive, mutateDom }) {
+        directive("format", (el, { modifiers }, { effect, evaluateLater }) => {
+            const cache = new Map;
+            const placeholder_regex = /{{(?<expr>.+?)}}/g;
+            const is_once = has_modifier(modifiers, "once");
+
+            process(el);
+
+            function get_eval_fn(expression) {
+                let getter = cache.get(expression);
+                if (is_nullish(getter)) {
+                    getter = create_getter(evaluateLater, expression);
+                    cache.set(expression, getter);
+                }
+
+                return getter;
+            }
+
+            function update(callback) {
+                if (is_once) {
+                    mutateDom(() => callback());
+                    cache.clear();
+                }
+                else {
+                    effect(() => mutateDom(() => callback()));
+                }
+            }
+
+            function process(node) {
+                switch (node.nodeType) {
+                    case Node.TEXT_NODE:
+                        process_text_node(node);
+                        break;
+
+                    case Node.ELEMENT_NODE:
+                        process_nodes(node);
+                        process_attributes(node);
+                        break;
+                }
+            }
+
+            function process_text_node(node) {
+                const tokens = node.textContent.split(placeholder_regex);
+
+                if (tokens.length > 1) {
+                    const fragment = new DocumentFragment();
+
+                    for (let i = 0; i < tokens.length; i++) {
+                        if ((i % 2) === 0) {
+                            fragment.appendChild(document.createTextNode(tokens[i]));
+                        }
+                        else {
+                            const get_value = get_eval_fn(tokens[i]);
+                            const text = document.createTextNode("");
+
+                            fragment.append(text);
+                            update(() => text.textContent = get_value());
+                        }
+                    }
+
+                    mutateDom(() =>
+                        node.parentElement.replaceChild(fragment, node));
+                }
+            }
+
+            function process_attributes(node) {
+                for (let attr of node.attributes) {
+                    const matches = [...attr.value.matchAll(placeholder_regex)];
+                    if (matches.length) {
+                        const template = attr.value;
+                        update(() => attr.value = template.replace(placeholder_regex, (_, expr) => get_eval_fn(expr)()));
+                    }
+                }
+            }
+
+            function process_nodes(node) {
+                for (let child of node.childNodes) {
+                    process(child);
+                }
+            }
+        });
+    }
+
+    document.addEventListener("alpine:init", () => { Alpine.plugin(plugin); });
+
+})();

package/alpinegear-format.min.js

@@ -0,0 +1 @@
+!function(){"use strict";function e({directive:e,mutateDom:t}){e("format",((e,{modifiers:n},{effect:o,evaluateLater:c})=>{const i=new Map,l=/{{(?<expr>.+?)}}/g,u=(e=>e.includes("once"))(n);function a(e){let t=i.get(e);return null==t&&(t=function(e,...t){const n=e(...t);return()=>{let e;return n((t=>e=t)),t=e,"function"==typeof t?.get?e.get():e;var t}}(c,e),i.set(e,t)),t}function r(e){u?(t((()=>e())),i.clear()):o((()=>t((()=>e()))))}!function e(n){switch(n.nodeType){case Node.TEXT_NODE:!function(e){const n=e.textContent.split(l);if(n.length>1){const o=new DocumentFragment;for(let e=0;n.length>e;e++)if(e%2==0)o.appendChild(document.createTextNode(n[e]));else{const t=a(n[e]),c=document.createTextNode("");o.append(c),r((()=>c.textContent=t()))}t((()=>e.parentElement.replaceChild(o,e)))}}(n);break;case Node.ELEMENT_NODE:!function(t){for(let n of t.childNodes)e(n)}(n),function(e){for(let t of e.attributes)if([...t.value.matchAll(l)].length){const e=t.value;r((()=>t.value=e.replace(l,((e,t)=>a(t)()))))}}(n)}}(e)}))}document.addEventListener("alpine:init",(()=>{Alpine.plugin(e)}))}();

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@ramstack/alpinegear-format",
+  "version": "1.0.0-preview.1",
+  "description": "@ramstack/alpinegear-format provides 'x-format' Alpine.js directive, which allows you to easily interpolate text using a template syntax similar to what's available in Vue.js.",
+  "author": "Rameel Burhan",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rameel/ramstack.alpinegear.js.git",
+    "directory": "src/plugins/format"
+  },
+  "keywords": [
+    "alpine.js",
+    "alpinejs"
+  ],
+  "main": "alpinegear-format.js",
+  "module": "alpinegear-format.esm.js"
+}