@ktjs/core 0.17.4 → 0.18.1

package/README.md

@@ -12,7 +12,7 @@ Core DOM manipulation utilities for KT.js framework with built-in JSX/TSX suppor
 
 `@ktjs/core` is the foundation of KT.js, providing the essential `h` function and DOM utilities for building web applications with direct DOM manipulation. It emphasizes performance, type safety, and minimal abstraction over native DOM APIs.
 
-**Current Version:** 0.16.0
+**Current Version:** 0.18.1
 
 ## Features
 
@@ -42,6 +42,10 @@ Core DOM manipulation utilities for KT.js framework with built-in JSX/TSX suppor
   - Update props and children selectively
   - Efficient replacement strategy
   - Works with both native elements and function components
+- **Ref Enhancement**: Change event binding support for `ref` (v0.18.1)
+  - New methods `addOnChange` and `removeOnChange` for listening to value changes
+  - Automatically calls registered callbacks when `ref.value` is updated
+  - When both old and new values are DOM nodes, automatically replaces old node with new one in the DOM
 - **DOM Utilities**: Helper functions for common DOM operations
   - Native method caching for performance
   - Symbol-based private properties for internal state

package/dist/index.d.ts

@@ -6,9 +6,15 @@ type otherstring = string & {};
 type HTMLTag = keyof HTMLElementTagNameMap;
 type SVGTag = keyof SVGElementTagNameMap;
 
+type ChangeHandler<T> = (newValue: T, oldValue: T) => void;
 interface KTRef<T> {
+    /**
+     * If new value and old value are both nodes, the old one will be replaced in the DOM
+     */
     value: T;
     isKT: true;
+    addOnChange: (callback: ChangeHandler<T>) => void;
+    removeOnChange: (callback: ChangeHandler<T>) => void;
 }
 /**
  * Reference to the created HTML element.
@@ -172,7 +178,7 @@ type HTML<T extends (HTMLTag | SVGTag) & otherstring> = T extends SVGTag ? SVGEl
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.17.4 (Last Update: 2026.01.29 13:40:17.223)
+ * @version 0.18.1 (Last Update: 2026.01.30 21:24:36.481)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!

package/dist/index.iife.js

@@ -215,7 +215,7 @@ var __ktjs_core__ = (function (exports) {
      * ## About
      * @package @ktjs/core
      * @author Kasukabe Tsumugi <futami16237@gmail.com>
-     * @version 0.17.4 (Last Update: 2026.01.29 13:40:17.223)
+     * @version 0.18.1 (Last Update: 2026.01.30 21:24:36.481)
      * @license MIT
      * @link https://github.com/baendlorel/kt.js
      * @link https://baendlorel.github.io/ Welcome to my site!
@@ -244,7 +244,41 @@ var __ktjs_core__ = (function (exports) {
      * @param value mostly an HTMLElement
      */
     function ref(value) {
-        return { value: value, isKT: true };
+        let _value = value;
+        let _onChanges = [];
+        return {
+            isKT: true,
+            get value() {
+                return _value;
+            },
+            set value(newValue) {
+                if (newValue === _value) {
+                    return;
+                }
+                // replace the old node with the new one in the DOM if both are nodes
+                if (_value instanceof Node && newValue instanceof Node) {
+                    if (newValue.contains(_value)) {
+                        _value.remove();
+                    }
+                    _value.replaceWith(newValue);
+                }
+                const oldValue = _value;
+                _value = newValue;
+                for (let i = 0; i < _onChanges.length; i++) {
+                    _onChanges[i](newValue, oldValue);
+                }
+            },
+            addOnChange: (callback) => _onChanges.push(callback),
+            removeOnChange: (callback) => {
+                for (let i = _onChanges.length - 1; i >= 0; i--) {
+                    if (_onChanges[i] === callback) {
+                        _onChanges.splice(i, 1);
+                        return true;
+                    }
+                }
+                return false;
+            },
+        };
     }
 
     const dummyRef = { value: null };

package/dist/index.legacy.js

@@ -240,7 +240,7 @@ var __ktjs_core__ = (function (exports) {
      * ## About
      * @package @ktjs/core
      * @author Kasukabe Tsumugi <futami16237@gmail.com>
-     * @version 0.17.4 (Last Update: 2026.01.29 13:40:17.223)
+     * @version 0.18.1 (Last Update: 2026.01.30 21:24:36.481)
      * @license MIT
      * @link https://github.com/baendlorel/kt.js
      * @link https://baendlorel.github.io/ Welcome to my site!
@@ -302,7 +302,41 @@ var __ktjs_core__ = (function (exports) {
      * @param value mostly an HTMLElement
      */
     function ref(value) {
-        return { value: value, isKT: true };
+        var _value = value;
+        var _onChanges = [];
+        return {
+            isKT: true,
+            get value() {
+                return _value;
+            },
+            set value(newValue) {
+                if (newValue === _value) {
+                    return;
+                }
+                // replace the old node with the new one in the DOM if both are nodes
+                if (_value instanceof Node && newValue instanceof Node) {
+                    if (newValue.contains(_value)) {
+                        _value.remove();
+                    }
+                    _value.replaceWith(newValue);
+                }
+                var oldValue = _value;
+                _value = newValue;
+                for (var i = 0; i < _onChanges.length; i++) {
+                    _onChanges[i](newValue, oldValue);
+                }
+            },
+            addOnChange: function (callback) { return _onChanges.push(callback); },
+            removeOnChange: function (callback) {
+                for (var i = _onChanges.length - 1; i >= 0; i--) {
+                    if (_onChanges[i] === callback) {
+                        _onChanges.splice(i, 1);
+                        return true;
+                    }
+                }
+                return false;
+            },
+        };
     }
 
     var dummyRef = { value: null };

package/dist/index.mjs

@@ -212,7 +212,7 @@ const svgTempWrapper = document.createElement('div');
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.17.4 (Last Update: 2026.01.29 13:40:17.223)
+ * @version 0.18.1 (Last Update: 2026.01.30 21:24:36.481)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -241,7 +241,41 @@ const h = (tag, attr, content) => {
  * @param value mostly an HTMLElement
  */
 function ref(value) {
-    return { value: value, isKT: true };
+    let _value = value;
+    let _onChanges = [];
+    return {
+        isKT: true,
+        get value() {
+            return _value;
+        },
+        set value(newValue) {
+            if (newValue === _value) {
+                return;
+            }
+            // replace the old node with the new one in the DOM if both are nodes
+            if (_value instanceof Node && newValue instanceof Node) {
+                if (newValue.contains(_value)) {
+                    _value.remove();
+                }
+                _value.replaceWith(newValue);
+            }
+            const oldValue = _value;
+            _value = newValue;
+            for (let i = 0; i < _onChanges.length; i++) {
+                _onChanges[i](newValue, oldValue);
+            }
+        },
+        addOnChange: (callback) => _onChanges.push(callback),
+        removeOnChange: (callback) => {
+            for (let i = _onChanges.length - 1; i >= 0; i--) {
+                if (_onChanges[i] === callback) {
+                    _onChanges.splice(i, 1);
+                    return true;
+                }
+            }
+            return false;
+        },
+    };
 }
 
 const dummyRef = { value: null };

package/dist/jsx/index.d.ts

@@ -6,9 +6,15 @@ type otherstring = string & {};
 type HTMLTag = keyof HTMLElementTagNameMap;
 type SVGTag = keyof SVGElementTagNameMap;
 
+type ChangeHandler<T> = (newValue: T, oldValue: T) => void;
 interface KTRef<T> {
+    /**
+     * If new value and old value are both nodes, the old one will be replaced in the DOM
+     */
     value: T;
     isKT: true;
+    addOnChange: (callback: ChangeHandler<T>) => void;
+    removeOnChange: (callback: ChangeHandler<T>) => void;
 }
 /**
  * Reference to the created HTML element.
@@ -158,7 +164,7 @@ type HTML<T extends (HTMLTag | SVGTag) & otherstring> = T extends SVGTag ? SVGEl
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.17.4 (Last Update: 2026.01.29 13:40:17.223)
+ * @version 0.18.1 (Last Update: 2026.01.30 21:24:36.481)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!

package/dist/jsx/index.mjs

@@ -212,7 +212,7 @@ const svgTempWrapper = document.createElement('div');
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.17.4 (Last Update: 2026.01.29 13:40:17.223)
+ * @version 0.18.1 (Last Update: 2026.01.30 21:24:36.481)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -241,7 +241,41 @@ const h = (tag, attr, content) => {
  * @param value mostly an HTMLElement
  */
 function ref(value) {
-    return { value: value, isKT: true };
+    let _value = value;
+    let _onChanges = [];
+    return {
+        isKT: true,
+        get value() {
+            return _value;
+        },
+        set value(newValue) {
+            if (newValue === _value) {
+                return;
+            }
+            // replace the old node with the new one in the DOM if both are nodes
+            if (_value instanceof Node && newValue instanceof Node) {
+                if (newValue.contains(_value)) {
+                    _value.remove();
+                }
+                _value.replaceWith(newValue);
+            }
+            const oldValue = _value;
+            _value = newValue;
+            for (let i = 0; i < _onChanges.length; i++) {
+                _onChanges[i](newValue, oldValue);
+            }
+        },
+        addOnChange: (callback) => _onChanges.push(callback),
+        removeOnChange: (callback) => {
+            for (let i = _onChanges.length - 1; i >= 0; i--) {
+                if (_onChanges[i] === callback) {
+                    _onChanges.splice(i, 1);
+                    return true;
+                }
+            }
+            return false;
+        },
+    };
 }
 
 const dummyRef = { value: null };

package/dist/jsx/jsx-runtime.d.ts

@@ -6,9 +6,15 @@ type otherstring = string & {};
 type HTMLTag = keyof HTMLElementTagNameMap;
 type SVGTag = keyof SVGElementTagNameMap;
 
+type ChangeHandler<T> = (newValue: T, oldValue: T) => void;
 interface KTRef<T> {
+    /**
+     * If new value and old value are both nodes, the old one will be replaced in the DOM
+     */
     value: T;
     isKT: true;
+    addOnChange: (callback: ChangeHandler<T>) => void;
+    removeOnChange: (callback: ChangeHandler<T>) => void;
 }
 
 type Redraw = (props?: KTAttribute, ...args: any[]) => KTHTMLElement;
@@ -152,7 +158,7 @@ type HTML<T extends (HTMLTag | SVGTag) & otherstring> = T extends SVGTag ? SVGEl
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.17.4 (Last Update: 2026.01.29 13:40:17.223)
+ * @version 0.18.1 (Last Update: 2026.01.30 21:24:36.481)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!

package/dist/jsx/jsx-runtime.mjs

@@ -212,7 +212,7 @@ const svgTempWrapper = document.createElement('div');
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.17.4 (Last Update: 2026.01.29 13:40:17.223)
+ * @version 0.18.1 (Last Update: 2026.01.30 21:24:36.481)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -241,7 +241,41 @@ const h = (tag, attr, content) => {
  * @param value mostly an HTMLElement
  */
 function ref(value) {
-    return { value: value, isKT: true };
+    let _value = value;
+    let _onChanges = [];
+    return {
+        isKT: true,
+        get value() {
+            return _value;
+        },
+        set value(newValue) {
+            if (newValue === _value) {
+                return;
+            }
+            // replace the old node with the new one in the DOM if both are nodes
+            if (_value instanceof Node && newValue instanceof Node) {
+                if (newValue.contains(_value)) {
+                    _value.remove();
+                }
+                _value.replaceWith(newValue);
+            }
+            const oldValue = _value;
+            _value = newValue;
+            for (let i = 0; i < _onChanges.length; i++) {
+                _onChanges[i](newValue, oldValue);
+            }
+        },
+        addOnChange: (callback) => _onChanges.push(callback),
+        removeOnChange: (callback) => {
+            for (let i = _onChanges.length - 1; i >= 0; i--) {
+                if (_onChanges[i] === callback) {
+                    _onChanges.splice(i, 1);
+                    return true;
+                }
+            }
+            return false;
+        },
+    };
 }
 
 const dummyRef = { value: null };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ktjs/core",
-  "version": "0.17.4",
+  "version": "0.18.1",
   "description": "Core functionality for kt.js - DOM manipulation utilities with JSX/TSX support",
   "type": "module",
   "module": "./dist/index.mjs",