@ktjs/core 0.22.2 → 0.22.5

package/dist/index.d.ts

@@ -21,6 +21,10 @@ declare class KTRef<T> {
      */
     get value(): T;
     set value(newValue: T);
+    /**
+     * Register a callback when the value changes
+     * @param callback (newValue, oldValue) => xxx
+     */
     addOnChange(callback: RefChangeHandler<T>): void;
     removeOnChange(callback: RefChangeHandler<T>): boolean;
 }
@@ -29,9 +33,11 @@ declare const isKTRef: <T = any>(obj: any) => obj is KTRef<T>;
  * Reference to the created HTML element.
  * - **Only** respond to `ref.value` changes, not reactive to internal changes of the element.
  * - can alse be used to store normal values, but it is not reactive.
+ * - if the value is already a `KTRef`, it will be returned **directly**.
  * @param value mostly an HTMLElement
  */
-declare function ref<T = JSX.Element>(value?: T, onChange?: RefChangeHandler<T>): KTRef<T>;
+declare function ref<T = JSX.Element>(value?: T | KTRef<T>, onChange?: RefChangeHandler<T>): KTRef<T>;
+declare function deref<T = JSX.Element>(value: T | KTRef<T>): T;
 type KTSurfaceRef<T extends Object> = {
     [K in keyof T]: KTRef<T[K]>;
 } & {
@@ -45,6 +51,10 @@ type KTSurfaceRef<T extends Object> = {
  * - `obj.a.b` is not reactive
  */
 declare const surfaceRef: <T extends Object>(obj: T) => KTSurfaceRef<T>;
+/**
+ * Assert k-model to be a ref object
+ */
+declare const $modelOrRef: <T = any>(props: any, defaultValue?: T) => KTRef<T>;
 
 type HTML<T extends (HTMLTag | SVGTag | MathMLTag) & otherstring> = T extends SVGTag
   ? SVGElementTagNameMap[T]
@@ -162,7 +172,7 @@ type KTComponent = (
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.22.2 (Last Update: 2026.02.02 20:28:37.901)
+ * @version 0.22.5 (Last Update: 2026.02.03 09:07:21.411)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -1467,5 +1477,5 @@ interface KTForProps<T> {
  */
 declare function KTFor<T>(props: KTForProps<T>): KTForElement;
 
-export { Fragment, KTAsync, KTFor, KTRef, h as createElement, createRedrawable, h, isKTRef, jsx, jsxDEV, jsxs, ref, surfaceRef };
+export { $modelOrRef, Fragment, KTAsync, KTFor, KTRef, h as createElement, createRedrawable, deref, h, isKTRef, jsx, jsxDEV, jsxs, ref, surfaceRef };
 export type { EventHandler, HTMLTag, InputElementTag, KTAttribute, KTForElement, KTForProps, KTRawAttr, KTRawContent, KTRawContents, KTSurfaceRef, MathMLTag, SVGTag };

package/dist/index.iife.js

@@ -97,7 +97,14 @@ var __ktjs_core__ = (function (exports) {
                 this._onChanges[i](newValue, oldValue);
             }
         }
+        /**
+         * Register a callback when the value changes
+         * @param callback (newValue, oldValue) => xxx
+         */
         addOnChange(callback) {
+            if (typeof callback !== 'function') {
+                throw new Error('[kt.js error] KTRef.addOnChange: callback must be a function');
+            }
             this._onChanges.push(callback);
         }
         removeOnChange(callback) {
@@ -110,18 +117,26 @@ var __ktjs_core__ = (function (exports) {
             return false;
         }
     }
-    const isKTRef = (obj) => {
-        return typeof obj === 'object' && obj !== null && obj.isKT === true;
-    };
+    const isKTRef = (obj) => obj?.isKT === true;
     /**
      * Reference to the created HTML element.
      * - **Only** respond to `ref.value` changes, not reactive to internal changes of the element.
      * - can alse be used to store normal values, but it is not reactive.
+     * - if the value is already a `KTRef`, it will be returned **directly**.
      * @param value mostly an HTMLElement
      */
     function ref(value, onChange) {
+        if (isKTRef(value)) {
+            if (onChange) {
+                value.addOnChange(onChange);
+            }
+            return value;
+        }
         return new KTRef(value, onChange ? [onChange] : []);
     }
+    function deref(value) {
+        return isKTRef(value) ? value.value : value;
+    }
     function kcollect() {
         const newObj = {};
         const entries = $entries(this);
@@ -146,6 +161,21 @@ var __ktjs_core__ = (function (exports) {
         }
         return newObj;
     };
+    // # asserts
+    /**
+     * Assert k-model to be a ref object
+     */
+    const $modelOrRef = (props, defaultValue) => {
+        // & props is an object. Won't use it in any other place
+        if ('k-model' in props) {
+            const kmodel = props['k-model'];
+            if (!kmodel?.isKT) {
+                throw new Error(`[kt.js error] k-model data must be a KTRef object, please use 'ref(...)' to wrap it.`);
+            }
+            return kmodel;
+        }
+        return ref(defaultValue);
+    };
 
     const booleanHandler = (element, key, value) => {
         if (key in element) {
@@ -330,7 +360,7 @@ var __ktjs_core__ = (function (exports) {
      * ## About
      * @package @ktjs/core
      * @author Kasukabe Tsumugi <futami16237@gmail.com>
-     * @version 0.22.2 (Last Update: 2026.02.02 20:28:37.901)
+     * @version 0.22.5 (Last Update: 2026.02.03 09:07:21.411)
      * @license MIT
      * @link https://github.com/baendlorel/kt.js
      * @link https://baendlorel.github.io/ Welcome to my site!
@@ -704,12 +734,14 @@ var __ktjs_core__ = (function (exports) {
         return result;
     }
 
+    exports.$modelOrRef = $modelOrRef;
     exports.Fragment = Fragment;
     exports.KTAsync = KTAsync;
     exports.KTFor = KTFor;
     exports.KTRef = KTRef;
     exports.createElement = h;
     exports.createRedrawable = createRedrawable;
+    exports.deref = deref;
     exports.h = h;
     exports.isKTRef = isKTRef;
     exports.jsx = jsx;

package/dist/index.legacy.js

@@ -93,7 +93,14 @@ var __ktjs_core__ = (function (exports) {
             enumerable: false,
             configurable: true
         });
+        /**
+         * Register a callback when the value changes
+         * @param callback (newValue, oldValue) => xxx
+         */
         KTRef.prototype.addOnChange = function (callback) {
+            if (typeof callback !== 'function') {
+                throw new Error('[kt.js error] KTRef.addOnChange: callback must be a function');
+            }
             this._onChanges.push(callback);
         };
         KTRef.prototype.removeOnChange = function (callback) {
@@ -107,18 +114,26 @@ var __ktjs_core__ = (function (exports) {
         };
         return KTRef;
     }());
-    var isKTRef = function (obj) {
-        return typeof obj === 'object' && obj !== null && obj.isKT === true;
-    };
+    var isKTRef = function (obj) { return (obj === null || obj === void 0 ? void 0 : obj.isKT) === true; };
     /**
      * Reference to the created HTML element.
      * - **Only** respond to `ref.value` changes, not reactive to internal changes of the element.
      * - can alse be used to store normal values, but it is not reactive.
+     * - if the value is already a `KTRef`, it will be returned **directly**.
      * @param value mostly an HTMLElement
      */
     function ref(value, onChange) {
+        if (isKTRef(value)) {
+            if (onChange) {
+                value.addOnChange(onChange);
+            }
+            return value;
+        }
         return new KTRef(value, onChange ? [onChange] : []);
     }
+    function deref(value) {
+        return isKTRef(value) ? value.value : value;
+    }
     function kcollect() {
         var newObj = {};
         var entries = $entries(this);
@@ -143,6 +158,21 @@ var __ktjs_core__ = (function (exports) {
         }
         return newObj;
     };
+    // # asserts
+    /**
+     * Assert k-model to be a ref object
+     */
+    var $modelOrRef = function (props, defaultValue) {
+        // & props is an object. Won't use it in any other place
+        if ('k-model' in props) {
+            var kmodel = props['k-model'];
+            if (!(kmodel === null || kmodel === void 0 ? void 0 : kmodel.isKT)) {
+                throw new Error("[kt.js error] k-model data must be a KTRef object, please use 'ref(...)' to wrap it.");
+            }
+            return kmodel;
+        }
+        return ref(defaultValue);
+    };
 
     var booleanHandler = function (element, key, value) {
         if (key in element) {
@@ -332,7 +362,7 @@ var __ktjs_core__ = (function (exports) {
      * ## About
      * @package @ktjs/core
      * @author Kasukabe Tsumugi <futami16237@gmail.com>
-     * @version 0.22.2 (Last Update: 2026.02.02 20:28:37.901)
+     * @version 0.22.5 (Last Update: 2026.02.03 09:07:21.411)
      * @license MIT
      * @link https://github.com/baendlorel/kt.js
      * @link https://baendlorel.github.io/ Welcome to my site!
@@ -713,12 +743,14 @@ var __ktjs_core__ = (function (exports) {
         return result;
     }
 
+    exports.$modelOrRef = $modelOrRef;
     exports.Fragment = Fragment;
     exports.KTAsync = KTAsync;
     exports.KTFor = KTFor;
     exports.KTRef = KTRef;
     exports.createElement = h;
     exports.createRedrawable = createRedrawable;
+    exports.deref = deref;
     exports.h = h;
     exports.isKTRef = isKTRef;
     exports.jsx = jsx;

package/dist/index.mjs

@@ -94,7 +94,14 @@ class KTRef {
             this._onChanges[i](newValue, oldValue);
         }
     }
+    /**
+     * Register a callback when the value changes
+     * @param callback (newValue, oldValue) => xxx
+     */
     addOnChange(callback) {
+        if (typeof callback !== 'function') {
+            throw new Error('[kt.js error] KTRef.addOnChange: callback must be a function');
+        }
         this._onChanges.push(callback);
     }
     removeOnChange(callback) {
@@ -107,18 +114,26 @@ class KTRef {
         return false;
     }
 }
-const isKTRef = (obj) => {
-    return typeof obj === 'object' && obj !== null && obj.isKT === true;
-};
+const isKTRef = (obj) => obj?.isKT === true;
 /**
  * Reference to the created HTML element.
  * - **Only** respond to `ref.value` changes, not reactive to internal changes of the element.
  * - can alse be used to store normal values, but it is not reactive.
+ * - if the value is already a `KTRef`, it will be returned **directly**.
  * @param value mostly an HTMLElement
  */
 function ref(value, onChange) {
+    if (isKTRef(value)) {
+        if (onChange) {
+            value.addOnChange(onChange);
+        }
+        return value;
+    }
     return new KTRef(value, onChange ? [onChange] : []);
 }
+function deref(value) {
+    return isKTRef(value) ? value.value : value;
+}
 function kcollect() {
     const newObj = {};
     const entries = $entries(this);
@@ -143,6 +158,21 @@ const surfaceRef = (obj) => {
     }
     return newObj;
 };
+// # asserts
+/**
+ * Assert k-model to be a ref object
+ */
+const $modelOrRef = (props, defaultValue) => {
+    // & props is an object. Won't use it in any other place
+    if ('k-model' in props) {
+        const kmodel = props['k-model'];
+        if (!kmodel?.isKT) {
+            throw new Error(`[kt.js error] k-model data must be a KTRef object, please use 'ref(...)' to wrap it.`);
+        }
+        return kmodel;
+    }
+    return ref(defaultValue);
+};
 
 const booleanHandler = (element, key, value) => {
     if (key in element) {
@@ -327,7 +357,7 @@ const MATHML_ATTR_FLAG = '__kt_mathml__';
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.22.2 (Last Update: 2026.02.02 20:28:37.901)
+ * @version 0.22.5 (Last Update: 2026.02.03 09:07:21.411)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -701,4 +731,4 @@ function getSequence(arr) {
     return result;
 }
 
-export { Fragment, KTAsync, KTFor, KTRef, h as createElement, createRedrawable, h, isKTRef, jsx, jsxDEV, jsxs, ref, surfaceRef };
+export { $modelOrRef, Fragment, KTAsync, KTFor, KTRef, h as createElement, createRedrawable, deref, h, isKTRef, jsx, jsxDEV, jsxs, ref, surfaceRef };

package/dist/jsx/index.d.ts

@@ -19,6 +19,10 @@ declare class KTRef<T> {
      */
     get value(): T;
     set value(newValue: T);
+    /**
+     * Register a callback when the value changes
+     * @param callback (newValue, oldValue) => xxx
+     */
     addOnChange(callback: RefChangeHandler<T>): void;
     removeOnChange(callback: RefChangeHandler<T>): boolean;
 }
@@ -27,9 +31,11 @@ declare const isKTRef: <T = any>(obj: any) => obj is KTRef<T>;
  * Reference to the created HTML element.
  * - **Only** respond to `ref.value` changes, not reactive to internal changes of the element.
  * - can alse be used to store normal values, but it is not reactive.
+ * - if the value is already a `KTRef`, it will be returned **directly**.
  * @param value mostly an HTMLElement
  */
-declare function ref<T = JSX.Element>(value?: T, onChange?: RefChangeHandler<T>): KTRef<T>;
+declare function ref<T = JSX.Element>(value?: T | KTRef<T>, onChange?: RefChangeHandler<T>): KTRef<T>;
+declare function deref<T = JSX.Element>(value: T | KTRef<T>): T;
 type KTSurfaceRef<T extends Object> = {
     [K in keyof T]: KTRef<T[K]>;
 } & {
@@ -43,6 +49,10 @@ type KTSurfaceRef<T extends Object> = {
  * - `obj.a.b` is not reactive
  */
 declare const surfaceRef: <T extends Object>(obj: T) => KTSurfaceRef<T>;
+/**
+ * Assert k-model to be a ref object
+ */
+declare const $modelOrRef: <T = any>(props: any, defaultValue?: T) => KTRef<T>;
 
 type HTML<T extends (HTMLTag | SVGTag | MathMLTag) & otherstring> = T extends SVGTag
   ? SVGElementTagNameMap[T]
@@ -146,7 +156,7 @@ type KTAttribute = KTBaseAttribute & KTPrefixedEventHandlers;
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.22.2 (Last Update: 2026.02.02 20:28:37.901)
+ * @version 0.22.5 (Last Update: 2026.02.03 09:07:21.411)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -1425,5 +1435,5 @@ declare global {
   }
 }
 
-export { Fragment, KTRef, h as createElement, createRedrawable, isKTRef, jsx, jsxDEV, jsxs, ref, surfaceRef };
+export { $modelOrRef, Fragment, KTRef, h as createElement, createRedrawable, deref, isKTRef, jsx, jsxDEV, jsxs, ref, surfaceRef };
 export type { KTSurfaceRef };

package/dist/jsx/index.mjs

@@ -94,7 +94,14 @@ class KTRef {
             this._onChanges[i](newValue, oldValue);
         }
     }
+    /**
+     * Register a callback when the value changes
+     * @param callback (newValue, oldValue) => xxx
+     */
     addOnChange(callback) {
+        if (typeof callback !== 'function') {
+            throw new Error('[kt.js error] KTRef.addOnChange: callback must be a function');
+        }
         this._onChanges.push(callback);
     }
     removeOnChange(callback) {
@@ -107,18 +114,26 @@ class KTRef {
         return false;
     }
 }
-const isKTRef = (obj) => {
-    return typeof obj === 'object' && obj !== null && obj.isKT === true;
-};
+const isKTRef = (obj) => obj?.isKT === true;
 /**
  * Reference to the created HTML element.
  * - **Only** respond to `ref.value` changes, not reactive to internal changes of the element.
  * - can alse be used to store normal values, but it is not reactive.
+ * - if the value is already a `KTRef`, it will be returned **directly**.
  * @param value mostly an HTMLElement
  */
 function ref(value, onChange) {
+    if (isKTRef(value)) {
+        if (onChange) {
+            value.addOnChange(onChange);
+        }
+        return value;
+    }
     return new KTRef(value, onChange ? [onChange] : []);
 }
+function deref(value) {
+    return isKTRef(value) ? value.value : value;
+}
 function kcollect() {
     const newObj = {};
     const entries = $entries(this);
@@ -143,6 +158,21 @@ const surfaceRef = (obj) => {
     }
     return newObj;
 };
+// # asserts
+/**
+ * Assert k-model to be a ref object
+ */
+const $modelOrRef = (props, defaultValue) => {
+    // & props is an object. Won't use it in any other place
+    if ('k-model' in props) {
+        const kmodel = props['k-model'];
+        if (!kmodel?.isKT) {
+            throw new Error(`[kt.js error] k-model data must be a KTRef object, please use 'ref(...)' to wrap it.`);
+        }
+        return kmodel;
+    }
+    return ref(defaultValue);
+};
 
 const booleanHandler = (element, key, value) => {
     if (key in element) {
@@ -327,7 +357,7 @@ const MATHML_ATTR_FLAG = '__kt_mathml__';
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.22.2 (Last Update: 2026.02.02 20:28:37.901)
+ * @version 0.22.5 (Last Update: 2026.02.03 09:07:21.411)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -477,4 +507,4 @@ function createRedrawable(creator) {
     return elRef;
 }
 
-export { Fragment, KTRef, h as createElement, createRedrawable, isKTRef, jsx, jsxDEV, jsxs, ref, surfaceRef };
+export { $modelOrRef, Fragment, KTRef, h as createElement, createRedrawable, deref, isKTRef, jsx, jsxDEV, jsxs, ref, surfaceRef };

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

@@ -19,6 +19,10 @@ declare class KTRef<T> {
      */
     get value(): T;
     set value(newValue: T);
+    /**
+     * Register a callback when the value changes
+     * @param callback (newValue, oldValue) => xxx
+     */
     addOnChange(callback: RefChangeHandler<T>): void;
     removeOnChange(callback: RefChangeHandler<T>): boolean;
 }
@@ -125,7 +129,7 @@ type KTAttribute = KTBaseAttribute & KTPrefixedEventHandlers;
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.22.2 (Last Update: 2026.02.02 20:28:37.901)
+ * @version 0.22.5 (Last Update: 2026.02.03 09:07:21.411)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!

package/dist/jsx/jsx-runtime.mjs

@@ -93,7 +93,14 @@ class KTRef {
             this._onChanges[i](newValue, oldValue);
         }
     }
+    /**
+     * Register a callback when the value changes
+     * @param callback (newValue, oldValue) => xxx
+     */
     addOnChange(callback) {
+        if (typeof callback !== 'function') {
+            throw new Error('[kt.js error] KTRef.addOnChange: callback must be a function');
+        }
         this._onChanges.push(callback);
     }
     removeOnChange(callback) {
@@ -106,16 +113,18 @@ class KTRef {
         return false;
     }
 }
-const isKTRef = (obj) => {
-    return typeof obj === 'object' && obj !== null && obj.isKT === true;
-};
+const isKTRef = (obj) => obj?.isKT === true;
 /**
  * Reference to the created HTML element.
  * - **Only** respond to `ref.value` changes, not reactive to internal changes of the element.
  * - can alse be used to store normal values, but it is not reactive.
+ * - if the value is already a `KTRef`, it will be returned **directly**.
  * @param value mostly an HTMLElement
  */
 function ref(value, onChange) {
+    if (isKTRef(value)) {
+        return value;
+    }
     return new KTRef(value, []);
 }
 
@@ -302,7 +311,7 @@ const MATHML_ATTR_FLAG = '__kt_mathml__';
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.22.2 (Last Update: 2026.02.02 20:28:37.901)
+ * @version 0.22.5 (Last Update: 2026.02.03 09:07:21.411)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!

package/package.json

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