@ramstack/alpinegear-bound 1.0.0-preview.1

package/README.md

@@ -0,0 +1,259 @@
+# @ramstack/alpinegear-bound
+
+`@ramstack/alpinegear-bound` is a plugin for [Alpine.js](https://alpinejs.dev/) that provides the `x-bound` directive.
+
+This directive allows for two-way binding between input elements and their associated data properties. It works similarly to the binding provided by [Svelte](https://svelte.dev/docs/element-directives#bind-property) and also supports synchronizing values between two `Alpine.js` data properties.
+
+## 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-bound@1/alpinegear-bound.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-bound
+```
+
+Then initialize it in your bundle:
+
+```js
+import Alpine from "alpinejs";
+import bound from "@ramstack/alpinegear-bound";
+
+Alpine.plugin(bound);
+Alpine.start();
+```
+
+## Usage
+
+The syntax for binding properties is `x-bound:property="dataprop"`.
+
+Let's take the following example:
+
+```html
+<div x-data="{ name: '' }">
+    <input x-bound:value="name" />
+    Hello <span x-text="name"></span>!
+
+    <button @click="name = 'John'">Change Name</button>
+</div>
+```
+
+In this example, we bind the `name` property to the `value` property of the `<input>` element. Since `x-bound` provides two-way binding, any changes to `name` will be reflected in the `<input>` element, as will occur when the `button` is clicked.
+
+### Shorthand Syntax
+The `x-bound` directive also supports shorthand syntax: `&`.
+
+So the previous example could be written as follows:
+
+```html
+<input &value="name" />
+```
+
+If the element's property name matches the bound data property, you can simplify this further:
+```html
+<input x-bound:value />
+```
+
+In this example, the repetition of the `value` in `x-bound:value="value"` is redundant, so we can simply shorten it to `<input x-bound:value>`. Since we can use `&` instead of `x-bound`, the example can be written as follows:
+
+```html
+<input &value />
+```
+
+More examples:
+
+```html
+<div x-data="{ name: '', text: '', yes: true }">
+    <input &value="name" />
+    <textarea &value="text"></textarea>
+    <input &checked="yes" type="checkbox" />
+</div>
+```
+
+### Binding Numeric Inputs
+
+For `<input>` elements with `type="number"` and `type="range"`, values are automatically coerced into numbers. If the `<input>` value is empty or invalid, the bound property will be set to `null`.
+
+```html
+<input &value="number" type="number" />
+```
+
+### Binding `<input type="file">`
+
+For `<input>` elements with `type="file"`, the binding is applied to the `files` property, resulting in a [FileList](https://developer.mozilla.org/en-US/docs/Web/API/FileList) object being assigned, containing the list of selected files.
+
+```html
+<input &files type="file" accept="image/jpeg" />
+```
+
+> [!NOTE]
+> The `files` binding is one-way.
+
+### Binding `<select>`
+
+To bind the value of a `<select>` element, use the `value` property:
+```html
+<select &value="pet">
+  <option value="cat">Cat</option>
+  <option value="goldfish">Goldfish</option>
+  <option value="parrot">Parrot</option>
+</select>
+```
+
+For a `<select multiple>` element, the data property is an array containing the values of the selected options.
+
+```html
+<div x-data="{ pets: ['goldfish', 'parrot'] }">
+    <select &value="pets" multiple>
+        <option value="cat">Cat</option>
+        <option value="goldfish">Goldfish</option>
+        <option value="parrot">Parrot</option>
+        <option value="spider">Spider</option>
+    </select>
+
+    Pets: <span x-text="pets"></span>
+</div>
+```
+
+### Binding `<details>`
+
+The directive also allows binding to the `open` property of `<details>` elements:
+
+```html
+<details &open="isOpen">
+    <summary>Details</summary>
+    <p>Something small enough to escape casual notice.</p>
+</details>
+```
+
+### Binding `<img>` sizes
+
+You can bind the `naturalWidth` and `naturalHeight` properties of an image after it loads:
+
+```html
+<img src="..." &naturalWidth="width" &naturalHeight="height" />
+```
+
+> [!TIP]
+> If you prefer using `kebab-case` for multi-word properties like `naturalWidth`, you can write it as `natural-width`. It will be automatically normalized internally:
+> ```html
+> <img src="..." &natural-width="width" &natural-height="height" />
+> ```
+
+> [!NOTE]
+> As HTML attributes are case-insensitive, corresponding properties can be written as follows:
+> ```html
+> <img src="..." &naturalwidth="width" &naturalheight="height" />
+> ```
+
+
+> [!NOTE]
+> The `naturalWidth` and `naturalHeight` properties are read-only and reflect the original image dimensions, available after the image has loaded.
+
+
+### Binding `contenteditable` elements
+
+For `contenteditable` elements, you can bind the following properties:
+- [innerHTML](https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML)
+- [innerText](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText)
+- [textContent](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent)
+
+```html
+<div &inner-html="html" contenteditable="true"></div>
+```
+
+### Binding block-level element sizes
+
+You can bind to the following properties to get the **width** and **height** of block-level elements. The values will update whenever the element's size changes:
+
+- [clientHeight](https://developer.mozilla.org/en-US/docs/Web/API/Element/clientHeight)
+- [clientWidth](https://developer.mozilla.org/en-US/docs/Web/API/Element/clientWidth)
+- [offsetHeight](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/offsetHeight)
+- [offsetWidth](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/offsetWidth)
+
+```html
+<div &client-width="width" &client-height="height"></div>
+```
+
+> [!NOTE]
+> These properties are read-only.
+
+### Binding group of `<input type="radio">` and `<input type="checkbox">`
+The group of `<input>` elements that should function together can utilize the `group` bound property.
+
+```html
+<div x-data="{ pets: ['goldfish', 'parrot'], contact: 'Email' }">
+
+    <!-- grouped checkboxes are similar to "select multiple"
+         and use an array for selected options -->
+    <input &group="pets" type="checkbox" value="cat" />
+    <input &group="pets" type="checkbox" value="goldfish" />
+    <input &group="pets" type="checkbox" value="parrot" />
+    <input &group="pets" type="checkbox" value="spider" />
+
+    <!-- grouped radio inputs are mutually exclusive -->
+    <input &group="contact" type="radio" value="Email" />
+    <input &group="contact" type="radio" value="Phone" />
+    <input &group="contact" type="radio" value="Mail" />
+
+</div>
+```
+
+### Binding `Alpine` data properties
+
+The directive also supports synchronizing values between two data properties.
+
+```html
+<div x-data="{ number: 5 }">
+    <div x-data="{ count: 0 }" &count="number">
+        <button @click="count++">Increment</button>
+    </div>
+
+    Number: <span x-text="number"></span>
+</div>
+```
+
+In this example, we bind the outer `number` property to the inner `count` property. Since `number` is initially set to `5`, the `count` property is also set to `5` when the binding occurs.
+
+By default, the binding is two-way, so changes in `count` are reflected in `number` and vice versa.
+
+But what if we want changes to propagate in one direction only? For this case, the `x-bound` directive provides three modifiers to control data flow:
+
+> [!TIP]
+> - **`inout`**: Binding works in both directions. This means that changes in one property are automatically reflected in the other and vice versa. This modifier is used by default.
+>
+>   Example: If we have the property `&count="number"`, then changing the value of `count` will also change the value of `number`, and vice versa.
+>
+> - **`in`**: Binding works in one direction only — from the source property to the target property. This means that changes in the source property are passed to the target property, but changes in the target property do not affect the source property.
+>
+>   Example: If we have `&count.in="number"`, then changes in `number` will be passed to `count`, but changes in `count` will not be reflected in `number`.
+>
+> - **`out`**: Binding works in one direction only — from the target property to the source property. This means that changes in the target property are passed to the source property, but changes in the source property do not affect the target property.
+>
+>   Example: If we have `&count.out="number"`, then changes in `count` will be passed to `number`, but changes in `number` will not be reflected in `count`.
+
+> [!NOTE]
+> The default behavior (`inout`) can also be achieved using the `x-model` and `x-modelable` directives.
+
+## Source code
+You can find the source code for this plugin on GitHub:
+
+https://github.com/rameel/ramstack.alpinegear.js/tree/main/src/plugins/bound
+
+## 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-bound.esm.js

@@ -0,0 +1,414 @@
+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 create_setter(evaluate_later, ...args) {
+    const evaluate = evaluate_later(...args);
+    args[args.length - 1] = `${ args.at(-1) } = __val`;
+    const set = evaluate_later(...args);
+
+    return value => {
+        let result;
+        evaluate(v => result = v);
+
+        if (has_setter(result)) {
+            result.set(value);
+        }
+        else {
+            set(() => { }, {
+                scope: {
+                    __val: value
+                }
+            });
+        }
+    };
+}
+
+function has_getter(value) {
+    return typeof value?.get === "function";
+}
+
+function has_setter(value) {
+    return typeof value?.set === "function";
+}
+
+const key = Symbol();
+let observable;
+
+function observe_resize(el, listener) {
+    observable ??= new ResizeObserver(entries => {
+        for (const e of entries) {
+            for (const callback of e.target[key]?.values() ?? []) {
+                callback(e);
+            }
+        }
+    });
+
+    el[key] ??= new Set();
+    el[key].add(listener);
+
+    observable.observe(el);
+
+    return () => {
+        el[key].delete(listener);
+
+        if (!el[key].size) {
+            observable.unobserve(el);
+            el[key] = null;
+        }
+    };
+}
+
+const warn = (...args) => console.warn("alpine-gear.js:", ...args);
+const is_array = Array.isArray;
+const is_nullish = value => value === null || value === undefined;
+const is_checkable_input = el => el.type === "checkbox" || el.type === "radio";
+const is_numeric_input = el => el.type === "number" || el.type === "range";
+const as_array = value => is_array(value) ? value : [value];
+const loose_equal = (a, b) => a == b;
+const loose_index_of = (array, value) => array.findIndex(v => v == value);
+const has_modifier = (modifiers, modifier) => modifiers.includes(modifier);
+
+function assert(value, message) {
+    if (!value) {
+        throw new Error(message);
+    }
+}
+
+const listen = (target, type, listener, options) => {
+    target.addEventListener(type, listener, options);
+    return () => target.removeEventListener(type, listener, options);
+};
+
+const clone = value =>
+    typeof value === "object"
+        ? JSON.parse(JSON.stringify(value))
+        : value;
+
+const closest = (el, callback) => {
+    while (el && !callback(el)) {
+        el = (el._x_teleportBack ?? el).parentElement;
+    }
+
+    return el;
+};
+
+const create_map = keys => new Map(
+    keys.split(",").map(v => [v.trim().toLowerCase(), v.trim()]));
+
+function watch(get_value, callback, options = null) {
+    assert(Alpine, "Alpine is not defined.");
+
+    const {
+        effect,
+        release
+    } = Alpine;
+
+    let new_value;
+    let old_value;
+    let initialized = false;
+
+    const handle = effect(() => {
+        new_value = get_value();
+
+        if (!initialized) {
+            options?.deep && JSON.stringify(new_value);
+            old_value = new_value;
+        }
+
+        if (initialized || (options?.immediate ?? true)) {
+            
+            setTimeout(() => {
+                callback(new_value, old_value);
+                old_value = new_value;
+            }, 0);
+        }
+
+        initialized = true;
+    });
+
+    return () => release(handle);
+}
+
+const canonical_names = create_map(
+    "value,checked,files," +
+    "innerHTML,innerText,textContent," +
+    "videoHeight,videoWidth," +
+    "naturalHeight,naturalWidth," +
+    "clientHeight,clientWidth,offsetHeight,offsetWidth," +
+    "open," +
+    "group");
+
+function plugin({ directive, entangle, evaluateLater, mapAttributes, mutateDom, prefixed }) {
+    
+    
+    
+    
+    mapAttributes(attr => ({
+        name: attr.name.replace(/^&/, prefixed("bound:")),
+        value: attr.value
+    }));
+
+    directive("bound", (el, { expression, value, modifiers }, { effect, cleanup }) => {
+        if (!value) {
+            warn("x-bound directive expects the presence of a bound property name.");
+            return;
+        }
+
+        const tag_name = el.tagName.toUpperCase();
+
+        expression = expression?.trim();
+
+        
+        
+        const property_name = canonical_names.get(value.trim().replace("-", "").toLowerCase());
+
+        // if the expression is omitted, then we assume it corresponds
+        // to the bound property name, allowing us to write expressions more concisely,
+        // and write &value instead of &value="value"
+        expression ||= property_name;
+
+        const get_value = create_getter(evaluateLater, el, expression);
+        const set_value = create_setter(evaluateLater, el, expression);
+
+        const update_property = () => loose_equal(el[property_name],  get_value()) || mutateDom(() => el[property_name] = get_value());
+        const update_variable = () => set_value(is_numeric_input(el) ? to_number(el[property_name]) : el[property_name]);
+
+        let processed;
+
+        switch (property_name) {
+            case "value":
+                process_value();
+                break;
+
+            case "checked":
+                process_checked();
+                break;
+
+            case "files":
+                process_files();
+                break;
+
+            case "innerHTML":
+            case "innerText":
+            case "textContent":
+                process_contenteditable();
+                break;
+
+            case "videoHeight":
+            case "videoWidth":
+                process_media_resize("VIDEO", "resize");
+                break;
+
+            case "naturalHeight":
+            case "naturalWidth":
+                process_media_resize("IMG", "load");
+                break;
+
+            case "clientHeight":
+            case "clientWidth":
+            case "offsetHeight":
+            case "offsetWidth":
+                process_dimensions();
+                break;
+
+            case "open":
+                process_details();
+                break;
+
+            case "group":
+                process_group();
+                break;
+        }
+
+        if (!processed) {
+            const modifier =
+                has_modifier(modifiers, "in")  ? "in"  :
+                has_modifier(modifiers, "out") ? "out" : "inout";
+
+            const source_el = expression === value
+                ? closest(el.parentNode, node => node._x_dataStack)
+                : el;
+
+            if (!el._x_dataStack) {
+                warn("x-bound directive requires the presence of the x-data directive to bind component properties.");
+                return;
+            }
+
+            if (!source_el) {
+                warn(`x-bound directive cannot find the parent scope where the '${ value }' property is defined.`);
+                return;
+            }
+
+            const source = {
+                get: create_getter(evaluateLater, source_el, expression),
+                set: create_setter(evaluateLater, source_el, expression),
+            };
+
+            const target = {
+                get: create_getter(evaluateLater, el, value),
+                set: create_setter(evaluateLater, el, value),
+            };
+
+            switch (modifier) {
+                case "in":
+                    cleanup(watch(() => source.get(), v => target.set(clone(v))));
+                    break;
+                case "out":
+                    cleanup(watch(() => target.get(), v => source.set(clone(v))));
+                    break;
+                default:
+                    cleanup(entangle(source, target));
+                    break;
+            }
+        }
+
+        function process_value() {
+            switch (tag_name) {
+                case "INPUT":
+                case "TEXTAREA":
+                    
+                    
+                    is_nullish(get_value()) && update_variable();
+
+                    effect(update_property);
+                    cleanup(listen(el, "input", update_variable));
+
+                    processed = true;
+                    break;
+
+                case "SELECT":
+                    
+                    
+                    
+                    
+                    
+                    
+                    
+                    queueMicrotask(() => {
+                        
+                        
+                        is_nullish(get_value()) && update_variable();
+
+                        effect(() => apply_select_values(el, as_array(get_value() ?? [])));
+                        cleanup(listen(el, "change", () => set_value(collect_selected_values(el))));
+                    });
+
+                    processed = true;
+                    break;
+            }
+        }
+
+        function process_checked() {
+            if (is_checkable_input(el)) {
+                effect(update_property);
+                cleanup(listen(el, "change", update_variable));
+                processed = true;
+            }
+        }
+
+        function process_files() {
+            if (el.type === "file") {
+                cleanup(listen(el, "input", update_variable));
+                processed = true;
+            }
+        }
+
+        function process_contenteditable() {
+            if (el.contentEditable === "true") {
+                is_nullish(get_value()) && update_variable();
+
+                effect(update_property);
+                cleanup(listen(el, "input", update_variable));
+                processed = true;
+            }
+        }
+
+        function process_media_resize(name, event_name) {
+            if (tag_name === name) {
+                update_variable();
+                cleanup(listen(el, event_name, update_variable));
+                processed = true;
+            }
+        }
+
+        function process_dimensions() {
+            cleanup(observe_resize(el, update_variable));
+            processed = true;
+        }
+
+        function process_details() {
+            if (tag_name === "DETAILS") {
+                
+                
+                is_nullish(get_value()) && update_variable();
+
+                effect(update_property);
+                cleanup(listen(el, "toggle", update_variable));
+                processed = true;
+            }
+        }
+
+        function process_group() {
+            if (is_checkable_input(el)) {
+                el.name || mutateDom(() => el.name = expression);
+
+                effect(() =>
+                    mutateDom(() =>
+                        apply_group_values(el, get_value() ?? [])));
+
+                cleanup(listen(el, "input", () => set_value(collect_group_values(el, get_value()))));
+                processed = true;
+            }
+        }
+    });
+}
+
+function to_number(value) {
+    return value === "" ? null : +value;
+}
+
+function apply_select_values(el, values) {
+    for (const option of el.options) {
+        option.selected = loose_index_of(values, option.value) >= 0;
+    }
+}
+
+function collect_selected_values(el) {
+    if (el.multiple) {
+        return [...el.selectedOptions].map(o => o.value);
+    }
+
+    return el.value;
+}
+
+function apply_group_values(el, values) {
+    el.checked = is_array(values)
+        ? loose_index_of(values, el.value) >= 0
+        : loose_equal(el.value, values);
+}
+
+function collect_group_values(el, values) {
+    if (el.type === "radio") {
+        return el.value;
+    }
+
+    values = as_array(values);
+    const index = loose_index_of(values, el.value);
+
+    if (el.checked) {
+        index >= 0 || values.push(el.value);
+    }
+    else {
+        index >= 0 && values.splice(index, 1);
+    }
+
+    return values;
+}
+
+export { plugin as bound };

package/alpinegear-bound.esm.min.js

@@ -0,0 +1 @@
+function e(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}}function t(e,...t){const n=e(...t);t[t.length-1]=`${t.at(-1)} = __val`;const i=e(...t);return e=>{let t;n((e=>t=e)),function(e){return"function"==typeof e?.set}(t)?t.set(e):i((()=>{}),{scope:{__val:e}})}}const n=Symbol();let i;const a=(...e)=>console.warn("alpine-gear.js:",...e),r=Array.isArray,o=e=>null==e,c=e=>"checkbox"===e.type||"radio"===e.type,s=e=>r(e)?e:[e],u=(e,t)=>e==t,l=(e,t)=>e.findIndex((e=>e==t)),d=(e,t)=>e.includes(t),f=(e,t,n,i)=>(e.addEventListener(t,n,i),()=>e.removeEventListener(t,n,i)),p=e=>"object"==typeof e?JSON.parse(JSON.stringify(e)):e;function v(e,t,n=null){const{effect:i,release:a}=Alpine;let r,o,c=!1;const s=i((()=>{r=e(),c||(n?.deep&&JSON.stringify(r),o=r),(c||(n?.immediate??1))&&setTimeout((()=>{t(r,o),o=r}),0),c=!0}));return()=>a(s)}const h=new Map("value,checked,files,innerHTML,innerText,textContent,videoHeight,videoWidth,naturalHeight,naturalWidth,clientHeight,clientWidth,offsetHeight,offsetWidth,open,group".split(",").map((e=>[e.trim().toLowerCase(),e.trim()])));function g({directive:g,entangle:b,evaluateLater:m,mapAttributes:k,mutateDom:x,prefixed:y}){k((e=>({name:e.name.replace(/^&/,y("bound:")),value:e.value}))),g("bound",((g,{expression:k,value:y,modifiers:w},{effect:E,cleanup:H})=>{if(!y)return void a("x-bound directive expects the presence of a bound property name.");const T=g.tagName.toUpperCase();k=k?.trim();const _=h.get(y.trim().replace("-","").toLowerCase());k||=_;const L=e(m,g,k),S=t(m,g,k),W=()=>u(g[_],L())||x((()=>g[_]=L())),A=()=>S((e=>"number"===e.type||"range"===e.type)(g)?function(e){return""===e?null:+e}(g[_]):g[_]);let C;switch(_){case"value":!function(){switch(T){case"INPUT":case"TEXTAREA":o(L())&&A(),E(W),H(f(g,"input",A)),C=!0;break;case"SELECT":queueMicrotask((()=>{o(L())&&A(),E((()=>function(e,t){for(const n of e.options)n.selected=l(t,n.value)>=0}(g,s(L()??[])))),H(f(g,"change",(()=>S(function(e){return e.multiple?[...e.selectedOptions].map((e=>e.value)):e.value}(g)))))})),C=!0}}();break;case"checked":c(g)&&(E(W),H(f(g,"change",A)),C=!0);break;case"files":"file"===g.type&&(H(f(g,"input",A)),C=!0);break;case"innerHTML":case"innerText":case"textContent":"true"===g.contentEditable&&(o(L())&&A(),E(W),H(f(g,"input",A)),C=!0);break;case"videoHeight":case"videoWidth":N("VIDEO","resize");break;case"naturalHeight":case"naturalWidth":N("IMG","load");break;case"clientHeight":case"clientWidth":case"offsetHeight":case"offsetWidth":H(function(e,t){return i??=new ResizeObserver((e=>{for(const t of e)for(const e of t.target[n]?.values()??[])e(t)})),e[n]??=new Set,e[n].add(t),i.observe(e),()=>{e[n].delete(t),e[n].size||(i.unobserve(e),e[n]=null)}}(g,A)),C=!0;break;case"open":"DETAILS"===T&&(o(L())&&A(),E(W),H(f(g,"toggle",A)),C=!0);break;case"group":c(g)&&(g.name||x((()=>g.name=k)),E((()=>x((()=>function(e,t){e.checked=r(t)?l(t,e.value)>=0:u(e.value,t)}(g,L()??[]))))),H(f(g,"input",(()=>S(function(e,t){if("radio"===e.type)return e.value;t=s(t);const n=l(t,e.value);return e.checked?n>=0||t.push(e.value):n>=0&&t.splice(n,1),t}(g,L()))))),C=!0)}if(!C){const n=d(w,"in")?"in":d(w,"out")?"out":"inout",i=k===y?(e=>{for(;e&&!e._x_dataStack;)e=(e._x_teleportBack??e).parentElement;return e})(g.parentNode):g;if(!g._x_dataStack)return void a("x-bound directive requires the presence of the x-data directive to bind component properties.");if(!i)return void a(`x-bound directive cannot find the parent scope where the '${y}' property is defined.`);const r={get:e(m,i,k),set:t(m,i,k)},o={get:e(m,g,y),set:t(m,g,y)};switch(n){case"in":H(v((()=>r.get()),(e=>o.set(p(e)))));break;case"out":H(v((()=>o.get()),(e=>r.set(p(e)))));break;default:H(b(r,o))}}function N(e,t){T===e&&(A(),H(f(g,t,A)),C=!0)}}))}export{g as bound};

package/alpinegear-bound.js

@@ -0,0 +1,419 @@
+(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 create_setter(evaluate_later, ...args) {
+        const evaluate = evaluate_later(...args);
+        args[args.length - 1] = `${ args.at(-1) } = __val`;
+        const set = evaluate_later(...args);
+
+        return value => {
+            let result;
+            evaluate(v => result = v);
+
+            if (has_setter(result)) {
+                result.set(value);
+            }
+            else {
+                set(() => { }, {
+                    scope: {
+                        __val: value
+                    }
+                });
+            }
+        };
+    }
+
+    function has_getter(value) {
+        return typeof value?.get === "function";
+    }
+
+    function has_setter(value) {
+        return typeof value?.set === "function";
+    }
+
+    const key = Symbol();
+    let observable;
+
+    function observe_resize(el, listener) {
+        observable ??= new ResizeObserver(entries => {
+            for (const e of entries) {
+                for (const callback of e.target[key]?.values() ?? []) {
+                    callback(e);
+                }
+            }
+        });
+
+        el[key] ??= new Set();
+        el[key].add(listener);
+
+        observable.observe(el);
+
+        return () => {
+            el[key].delete(listener);
+
+            if (!el[key].size) {
+                observable.unobserve(el);
+                el[key] = null;
+            }
+        };
+    }
+
+    const warn = (...args) => console.warn("alpine-gear.js:", ...args);
+    const is_array = Array.isArray;
+    const is_nullish = value => value === null || value === undefined;
+    const is_checkable_input = el => el.type === "checkbox" || el.type === "radio";
+    const is_numeric_input = el => el.type === "number" || el.type === "range";
+    const as_array = value => is_array(value) ? value : [value];
+    const loose_equal = (a, b) => a == b;
+    const loose_index_of = (array, value) => array.findIndex(v => v == value);
+    const has_modifier = (modifiers, modifier) => modifiers.includes(modifier);
+
+    function assert(value, message) {
+        if (!value) {
+            throw new Error(message);
+        }
+    }
+
+    const listen = (target, type, listener, options) => {
+        target.addEventListener(type, listener, options);
+        return () => target.removeEventListener(type, listener, options);
+    };
+
+    const clone = value =>
+        typeof value === "object"
+            ? JSON.parse(JSON.stringify(value))
+            : value;
+
+    const closest = (el, callback) => {
+        while (el && !callback(el)) {
+            el = (el._x_teleportBack ?? el).parentElement;
+        }
+
+        return el;
+    };
+
+    const create_map = keys => new Map(
+        keys.split(",").map(v => [v.trim().toLowerCase(), v.trim()]));
+
+    function watch(get_value, callback, options = null) {
+        assert(Alpine, "Alpine is not defined.");
+
+        const {
+            effect,
+            release
+        } = Alpine;
+
+        let new_value;
+        let old_value;
+        let initialized = false;
+
+        const handle = effect(() => {
+            new_value = get_value();
+
+            if (!initialized) {
+                options?.deep && JSON.stringify(new_value);
+                old_value = new_value;
+            }
+
+            if (initialized || (options?.immediate ?? true)) {
+                
+                setTimeout(() => {
+                    callback(new_value, old_value);
+                    old_value = new_value;
+                }, 0);
+            }
+
+            initialized = true;
+        });
+
+        return () => release(handle);
+    }
+
+    const canonical_names = create_map(
+        "value,checked,files," +
+        "innerHTML,innerText,textContent," +
+        "videoHeight,videoWidth," +
+        "naturalHeight,naturalWidth," +
+        "clientHeight,clientWidth,offsetHeight,offsetWidth," +
+        "open," +
+        "group");
+
+    function plugin({ directive, entangle, evaluateLater, mapAttributes, mutateDom, prefixed }) {
+        
+        
+        
+        
+        mapAttributes(attr => ({
+            name: attr.name.replace(/^&/, prefixed("bound:")),
+            value: attr.value
+        }));
+
+        directive("bound", (el, { expression, value, modifiers }, { effect, cleanup }) => {
+            if (!value) {
+                warn("x-bound directive expects the presence of a bound property name.");
+                return;
+            }
+
+            const tag_name = el.tagName.toUpperCase();
+
+            expression = expression?.trim();
+
+            
+            
+            const property_name = canonical_names.get(value.trim().replace("-", "").toLowerCase());
+
+            // if the expression is omitted, then we assume it corresponds
+            // to the bound property name, allowing us to write expressions more concisely,
+            // and write &value instead of &value="value"
+            expression ||= property_name;
+
+            const get_value = create_getter(evaluateLater, el, expression);
+            const set_value = create_setter(evaluateLater, el, expression);
+
+            const update_property = () => loose_equal(el[property_name],  get_value()) || mutateDom(() => el[property_name] = get_value());
+            const update_variable = () => set_value(is_numeric_input(el) ? to_number(el[property_name]) : el[property_name]);
+
+            let processed;
+
+            switch (property_name) {
+                case "value":
+                    process_value();
+                    break;
+
+                case "checked":
+                    process_checked();
+                    break;
+
+                case "files":
+                    process_files();
+                    break;
+
+                case "innerHTML":
+                case "innerText":
+                case "textContent":
+                    process_contenteditable();
+                    break;
+
+                case "videoHeight":
+                case "videoWidth":
+                    process_media_resize("VIDEO", "resize");
+                    break;
+
+                case "naturalHeight":
+                case "naturalWidth":
+                    process_media_resize("IMG", "load");
+                    break;
+
+                case "clientHeight":
+                case "clientWidth":
+                case "offsetHeight":
+                case "offsetWidth":
+                    process_dimensions();
+                    break;
+
+                case "open":
+                    process_details();
+                    break;
+
+                case "group":
+                    process_group();
+                    break;
+            }
+
+            if (!processed) {
+                const modifier =
+                    has_modifier(modifiers, "in")  ? "in"  :
+                    has_modifier(modifiers, "out") ? "out" : "inout";
+
+                const source_el = expression === value
+                    ? closest(el.parentNode, node => node._x_dataStack)
+                    : el;
+
+                if (!el._x_dataStack) {
+                    warn("x-bound directive requires the presence of the x-data directive to bind component properties.");
+                    return;
+                }
+
+                if (!source_el) {
+                    warn(`x-bound directive cannot find the parent scope where the '${ value }' property is defined.`);
+                    return;
+                }
+
+                const source = {
+                    get: create_getter(evaluateLater, source_el, expression),
+                    set: create_setter(evaluateLater, source_el, expression),
+                };
+
+                const target = {
+                    get: create_getter(evaluateLater, el, value),
+                    set: create_setter(evaluateLater, el, value),
+                };
+
+                switch (modifier) {
+                    case "in":
+                        cleanup(watch(() => source.get(), v => target.set(clone(v))));
+                        break;
+                    case "out":
+                        cleanup(watch(() => target.get(), v => source.set(clone(v))));
+                        break;
+                    default:
+                        cleanup(entangle(source, target));
+                        break;
+                }
+            }
+
+            function process_value() {
+                switch (tag_name) {
+                    case "INPUT":
+                    case "TEXTAREA":
+                        
+                        
+                        is_nullish(get_value()) && update_variable();
+
+                        effect(update_property);
+                        cleanup(listen(el, "input", update_variable));
+
+                        processed = true;
+                        break;
+
+                    case "SELECT":
+                        
+                        
+                        
+                        
+                        
+                        
+                        
+                        queueMicrotask(() => {
+                            
+                            
+                            is_nullish(get_value()) && update_variable();
+
+                            effect(() => apply_select_values(el, as_array(get_value() ?? [])));
+                            cleanup(listen(el, "change", () => set_value(collect_selected_values(el))));
+                        });
+
+                        processed = true;
+                        break;
+                }
+            }
+
+            function process_checked() {
+                if (is_checkable_input(el)) {
+                    effect(update_property);
+                    cleanup(listen(el, "change", update_variable));
+                    processed = true;
+                }
+            }
+
+            function process_files() {
+                if (el.type === "file") {
+                    cleanup(listen(el, "input", update_variable));
+                    processed = true;
+                }
+            }
+
+            function process_contenteditable() {
+                if (el.contentEditable === "true") {
+                    is_nullish(get_value()) && update_variable();
+
+                    effect(update_property);
+                    cleanup(listen(el, "input", update_variable));
+                    processed = true;
+                }
+            }
+
+            function process_media_resize(name, event_name) {
+                if (tag_name === name) {
+                    update_variable();
+                    cleanup(listen(el, event_name, update_variable));
+                    processed = true;
+                }
+            }
+
+            function process_dimensions() {
+                cleanup(observe_resize(el, update_variable));
+                processed = true;
+            }
+
+            function process_details() {
+                if (tag_name === "DETAILS") {
+                    
+                    
+                    is_nullish(get_value()) && update_variable();
+
+                    effect(update_property);
+                    cleanup(listen(el, "toggle", update_variable));
+                    processed = true;
+                }
+            }
+
+            function process_group() {
+                if (is_checkable_input(el)) {
+                    el.name || mutateDom(() => el.name = expression);
+
+                    effect(() =>
+                        mutateDom(() =>
+                            apply_group_values(el, get_value() ?? [])));
+
+                    cleanup(listen(el, "input", () => set_value(collect_group_values(el, get_value()))));
+                    processed = true;
+                }
+            }
+        });
+    }
+
+    function to_number(value) {
+        return value === "" ? null : +value;
+    }
+
+    function apply_select_values(el, values) {
+        for (const option of el.options) {
+            option.selected = loose_index_of(values, option.value) >= 0;
+        }
+    }
+
+    function collect_selected_values(el) {
+        if (el.multiple) {
+            return [...el.selectedOptions].map(o => o.value);
+        }
+
+        return el.value;
+    }
+
+    function apply_group_values(el, values) {
+        el.checked = is_array(values)
+            ? loose_index_of(values, el.value) >= 0
+            : loose_equal(el.value, values);
+    }
+
+    function collect_group_values(el, values) {
+        if (el.type === "radio") {
+            return el.value;
+        }
+
+        values = as_array(values);
+        const index = loose_index_of(values, el.value);
+
+        if (el.checked) {
+            index >= 0 || values.push(el.value);
+        }
+        else {
+            index >= 0 && values.splice(index, 1);
+        }
+
+        return values;
+    }
+
+    document.addEventListener("alpine:init", () => { Alpine.plugin(plugin); });
+
+})();

package/alpinegear-bound.min.js

@@ -0,0 +1 @@
+!function(){"use strict";function e(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}}function t(e,...t){const n=e(...t);t[t.length-1]=`${t.at(-1)} = __val`;const i=e(...t);return e=>{let t;n((e=>t=e)),function(e){return"function"==typeof e?.set}(t)?t.set(e):i((()=>{}),{scope:{__val:e}})}}const n=Symbol();let i;const a=(...e)=>console.warn("alpine-gear.js:",...e),r=Array.isArray,o=e=>null==e,c=e=>"checkbox"===e.type||"radio"===e.type,s=e=>r(e)?e:[e],u=(e,t)=>e==t,l=(e,t)=>e.findIndex((e=>e==t)),d=(e,t)=>e.includes(t),p=(e,t,n,i)=>(e.addEventListener(t,n,i),()=>e.removeEventListener(t,n,i)),f=e=>"object"==typeof e?JSON.parse(JSON.stringify(e)):e;function v(e,t,n=null){const{effect:i,release:a}=Alpine;let r,o,c=!1;const s=i((()=>{r=e(),c||(n?.deep&&JSON.stringify(r),o=r),(c||(n?.immediate??1))&&setTimeout((()=>{t(r,o),o=r}),0),c=!0}));return()=>a(s)}const h=new Map("value,checked,files,innerHTML,innerText,textContent,videoHeight,videoWidth,naturalHeight,naturalWidth,clientHeight,clientWidth,offsetHeight,offsetWidth,open,group".split(",").map((e=>[e.trim().toLowerCase(),e.trim()])));function g({directive:g,entangle:b,evaluateLater:m,mapAttributes:k,mutateDom:x,prefixed:y}){k((e=>({name:e.name.replace(/^&/,y("bound:")),value:e.value}))),g("bound",((g,{expression:k,value:y,modifiers:E},{effect:w,cleanup:H})=>{if(!y)return void a("x-bound directive expects the presence of a bound property name.");const L=g.tagName.toUpperCase();k=k?.trim();const T=h.get(y.trim().replace("-","").toLowerCase());k||=T;const _=e(m,g,k),S=t(m,g,k),A=()=>u(g[T],_())||x((()=>g[T]=_())),W=()=>S((e=>"number"===e.type||"range"===e.type)(g)?function(e){return""===e?null:+e}(g[T]):g[T]);let C;switch(T){case"value":!function(){switch(L){case"INPUT":case"TEXTAREA":o(_())&&W(),w(A),H(p(g,"input",W)),C=!0;break;case"SELECT":queueMicrotask((()=>{o(_())&&W(),w((()=>function(e,t){for(const n of e.options)n.selected=l(t,n.value)>=0}(g,s(_()??[])))),H(p(g,"change",(()=>S(function(e){return e.multiple?[...e.selectedOptions].map((e=>e.value)):e.value}(g)))))})),C=!0}}();break;case"checked":c(g)&&(w(A),H(p(g,"change",W)),C=!0);break;case"files":"file"===g.type&&(H(p(g,"input",W)),C=!0);break;case"innerHTML":case"innerText":case"textContent":"true"===g.contentEditable&&(o(_())&&W(),w(A),H(p(g,"input",W)),C=!0);break;case"videoHeight":case"videoWidth":N("VIDEO","resize");break;case"naturalHeight":case"naturalWidth":N("IMG","load");break;case"clientHeight":case"clientWidth":case"offsetHeight":case"offsetWidth":H(function(e,t){return i??=new ResizeObserver((e=>{for(const t of e)for(const e of t.target[n]?.values()??[])e(t)})),e[n]??=new Set,e[n].add(t),i.observe(e),()=>{e[n].delete(t),e[n].size||(i.unobserve(e),e[n]=null)}}(g,W)),C=!0;break;case"open":"DETAILS"===L&&(o(_())&&W(),w(A),H(p(g,"toggle",W)),C=!0);break;case"group":c(g)&&(g.name||x((()=>g.name=k)),w((()=>x((()=>function(e,t){e.checked=r(t)?l(t,e.value)>=0:u(e.value,t)}(g,_()??[]))))),H(p(g,"input",(()=>S(function(e,t){if("radio"===e.type)return e.value;t=s(t);const n=l(t,e.value);return e.checked?n>=0||t.push(e.value):n>=0&&t.splice(n,1),t}(g,_()))))),C=!0)}if(!C){const n=d(E,"in")?"in":d(E,"out")?"out":"inout",i=k===y?(e=>{for(;e&&!e._x_dataStack;)e=(e._x_teleportBack??e).parentElement;return e})(g.parentNode):g;if(!g._x_dataStack)return void a("x-bound directive requires the presence of the x-data directive to bind component properties.");if(!i)return void a(`x-bound directive cannot find the parent scope where the '${y}' property is defined.`);const r={get:e(m,i,k),set:t(m,i,k)},o={get:e(m,g,y),set:t(m,g,y)};switch(n){case"in":H(v((()=>r.get()),(e=>o.set(f(e)))));break;case"out":H(v((()=>o.get()),(e=>r.set(f(e)))));break;default:H(b(r,o))}}function N(e,t){L===e&&(W(),H(p(g,t,W)),C=!0)}}))}document.addEventListener("alpine:init",(()=>{Alpine.plugin(g)}))}();

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@ramstack/alpinegear-bound",
+  "version": "1.0.0-preview.1",
+  "description": "@ramstack/alpinegear-bound provides the 'x-bound' Alpine.js directive, which allows for two-way binding of input elements and their associated data properties.",
+  "author": "Rameel Burhan",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rameel/ramstack.alpinegear.js.git",
+    "directory": "src/plugins/bound"
+  },
+  "keywords": [
+    "alpine.js",
+    "alpinejs"
+  ],
+  "main": "alpinegear-bound.js",
+  "module": "alpinegear-bound.esm.js"
+}