@ktjs/core 0.20.2 → 0.21.1

package/dist/index.iife.js

@@ -3,6 +3,7 @@ var __ktjs_core__ = (function (exports) {
 
     // Cached native methods for performance optimization
     const $isArray = Array.isArray;
+    const $entries = Object.entries;
     const $isThenable = (o) => typeof o === 'object' && o !== null && typeof o.then === 'function';
 
     // Error handling utilities
@@ -12,6 +13,7 @@ var __ktjs_core__ = (function (exports) {
 
     // DOM manipulation utilities
     // # dom natives
+    const $replaceWith = Element.prototype.replaceWith;
     /**
      * & Remove `bind` because it is shockingly slower than wrapper
      * & `window.document` is safe because it is not configurable and its setter is undefined
@@ -51,7 +53,7 @@ var __ktjs_core__ = (function (exports) {
 
     // Shared utilities and cached native methods for kt.js framework
     // Re-export all utilities
-    Object.defineProperty(window, '@ktjs/shared', { value: '0.20.0' });
+    Object.defineProperty(window, '@ktjs/shared', { value: '0.20.2' });
 
     const booleanHandler = (element, key, value) => {
         if (key in element) {
@@ -194,7 +196,6 @@ var __ktjs_core__ = (function (exports) {
         }
     }
 
-    document.createElement('div');
     const htmlCreator = (tag) => document.createElement(tag);
     const svgCreator = (tag) => document.createElementNS('http://www.w3.org/2000/svg', tag);
     const mathMLCreator = (tag) => document.createElementNS('http://www.w3.org/1998/Math/MathML', tag);
@@ -212,7 +213,7 @@ var __ktjs_core__ = (function (exports) {
      * ## About
      * @package @ktjs/core
      * @author Kasukabe Tsumugi <futami16237@gmail.com>
-     * @version 0.20.2 (Last Update: 2026.02.01 18:34:51.151)
+     * @version 0.21.1 (Last Update: 2026.02.02 09:20:07.959)
      * @license MIT
      * @link https://github.com/baendlorel/kt.js
      * @link https://baendlorel.github.io/ Welcome to my site!
@@ -241,14 +242,6 @@ var __ktjs_core__ = (function (exports) {
         // * Handle content
         applyAttr(element, attr);
         applyContent(element, content);
-        // if (tag === 'svg') {
-        //   tempWrapper.innerHTML = element.outerHTML;
-        //   return tempWrapper.firstChild as HTML<T>;
-        // }
-        // if (tag === 'math') {
-        //   tempWrapper.innerHTML = element.outerHTML;
-        //   return tempWrapper.firstChild as HTML<T>;
-        // }
         return element;
     };
 
@@ -257,7 +250,13 @@ var __ktjs_core__ = (function (exports) {
          * Indicates that this is a KTRef instance
          */
         isKT = true;
+        /**
+         * @internal
+         */
         _value;
+        /**
+         * @internal
+         */
         _onChanges;
         constructor(_value, _onChanges) {
             this._value = _value;
@@ -299,37 +298,85 @@ var __ktjs_core__ = (function (exports) {
             return false;
         }
     }
+    const isKTRef = (obj) => {
+        return typeof obj === 'object' && obj !== null && 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.
      * @param value mostly an HTMLElement
      */
     function ref(value, onChange) {
         return new KTRef(value, onChange ? [onChange] : []);
     }
+    function kcollect() {
+        const newObj = {};
+        const entries = $entries(this);
+        for (let i = 0; i < entries.length; i++) {
+            const key = entries[i][0];
+            if (key === 'kcollect') {
+                continue;
+            }
+            newObj[key] = entries[i][1].value;
+        }
+        return newObj;
+    }
+    /**
+     * Make all first-level properties of the object a `KTRef`.
+     * - `obj.a.b` is not reactive
+     */
+    const surfaceRef = (obj) => {
+        const entries = $entries(obj);
+        const newObj = { kcollect };
+        for (let i = 0; i < entries.length; i++) {
+            newObj[entries[i][0]] = ref(entries[i][1]);
+        }
+        return newObj;
+    };
 
     const dummyRef = { value: null };
+    const create = (tag, props) => {
+        if (typeof tag === 'function') {
+            return tag(props);
+        }
+        else {
+            return h(tag, props, props.children);
+        }
+    };
+    const placeholder = () => document.createComment('k-if');
     /**
      * @param tag html tag or function component
      * @param props properties/attributes
      */
     function jsx(tag, props) {
-        const ref = props.ref?.isKT ? props.ref : dummyRef;
+        const maybeDummyRef = isKTRef(props.ref) ? props.ref : dummyRef;
         let el;
-        if ('k-if' in props && !props['k-if']) {
-            // & make comment placeholder in case that ref might be redrawn later
-            el = document.createComment('k-if');
-            ref.value = el;
-            return el;
-        }
-        // Handle function components
-        if (typeof tag === 'function') {
-            el = tag(props);
-        }
-        else {
-            el = h(tag, props, props.children);
+        if ('k-if' in props) {
+            const kif = props['k-if'];
+            let condition = kif; // assume boolean by default
+            // Handle reactive k-if
+            if (isKTRef(kif)) {
+                kif.addOnChange((newValue, oldValue) => {
+                    if (newValue === oldValue) {
+                        return;
+                    }
+                    const oldEl = el;
+                    el = newValue ? create(tag, props) : placeholder();
+                    $replaceWith.call(oldEl, el);
+                    maybeDummyRef.value = el;
+                });
+                condition = kif.value;
+            }
+            if (!condition) {
+                // & make comment placeholder in case that ref might be redrawn later
+                el = placeholder();
+                maybeDummyRef.value = el;
+                return el;
+            }
         }
-        ref.value = el;
+        el = create(tag, props);
+        maybeDummyRef.value = el;
         return el;
     }
     /**
@@ -628,10 +675,12 @@ var __ktjs_core__ = (function (exports) {
     exports.createElement = h;
     exports.createRedrawable = createRedrawable;
     exports.h = h;
+    exports.isKTRef = isKTRef;
     exports.jsx = jsx;
     exports.jsxDEV = jsxDEV;
     exports.jsxs = jsxs;
     exports.ref = ref;
+    exports.surfaceRef = surfaceRef;
 
     return exports;
 

package/dist/index.legacy.js

@@ -3,6 +3,7 @@ var __ktjs_core__ = (function (exports) {
 
     // Cached native methods for performance optimization
     const $isArray = Array.isArray;
+    const $entries = Object.entries;
     const $isThenable = (o) => typeof o === 'object' && o !== null && typeof o.then === 'function';
 
     // Error handling utilities
@@ -12,6 +13,7 @@ var __ktjs_core__ = (function (exports) {
 
     // DOM manipulation utilities
     // # dom natives
+    const $replaceWith = Element.prototype.replaceWith;
     /**
      * & Remove `bind` because it is shockingly slower than wrapper
      * & `window.document` is safe because it is not configurable and its setter is undefined
@@ -51,7 +53,7 @@ var __ktjs_core__ = (function (exports) {
 
     // Shared utilities and cached native methods for kt.js framework
     // Re-export all utilities
-    Object.defineProperty(window, '@ktjs/shared', { value: '0.20.0' });
+    Object.defineProperty(window, '@ktjs/shared', { value: '0.20.2' });
 
     var booleanHandler = function (element, key, value) {
         if (key in element) {
@@ -199,7 +201,6 @@ var __ktjs_core__ = (function (exports) {
         }
     }
 
-    document.createElement('div');
     var htmlCreator = function (tag) { return document.createElement(tag); };
     var svgCreator = function (tag) { return document.createElementNS('http://www.w3.org/2000/svg', tag); };
     var mathMLCreator = function (tag) { return document.createElementNS('http://www.w3.org/1998/Math/MathML', tag); };
@@ -217,7 +218,7 @@ var __ktjs_core__ = (function (exports) {
      * ## About
      * @package @ktjs/core
      * @author Kasukabe Tsumugi <futami16237@gmail.com>
-     * @version 0.20.2 (Last Update: 2026.02.01 18:34:51.151)
+     * @version 0.21.1 (Last Update: 2026.02.02 09:20:07.959)
      * @license MIT
      * @link https://github.com/baendlorel/kt.js
      * @link https://baendlorel.github.io/ Welcome to my site!
@@ -246,14 +247,6 @@ var __ktjs_core__ = (function (exports) {
         // * Handle content
         applyAttr(element, attr);
         applyContent(element, content);
-        // if (tag === 'svg') {
-        //   tempWrapper.innerHTML = element.outerHTML;
-        //   return tempWrapper.firstChild as HTML<T>;
-        // }
-        // if (tag === 'math') {
-        //   tempWrapper.innerHTML = element.outerHTML;
-        //   return tempWrapper.firstChild as HTML<T>;
-        // }
         return element;
     };
 
@@ -307,38 +300,85 @@ var __ktjs_core__ = (function (exports) {
         };
         return KTRef;
     }());
+    var isKTRef = function (obj) {
+        return typeof obj === 'object' && obj !== null && 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.
      * @param value mostly an HTMLElement
      */
     function ref(value, onChange) {
         return new KTRef(value, onChange ? [onChange] : []);
     }
+    function kcollect() {
+        var newObj = {};
+        var entries = $entries(this);
+        for (var i = 0; i < entries.length; i++) {
+            var key = entries[i][0];
+            if (key === 'kcollect') {
+                continue;
+            }
+            newObj[key] = entries[i][1].value;
+        }
+        return newObj;
+    }
+    /**
+     * Make all first-level properties of the object a `KTRef`.
+     * - `obj.a.b` is not reactive
+     */
+    var surfaceRef = function (obj) {
+        var entries = $entries(obj);
+        var newObj = { kcollect: kcollect };
+        for (var i = 0; i < entries.length; i++) {
+            newObj[entries[i][0]] = ref(entries[i][1]);
+        }
+        return newObj;
+    };
 
     var dummyRef = { value: null };
+    var create = function (tag, props) {
+        if (typeof tag === 'function') {
+            return tag(props);
+        }
+        else {
+            return h(tag, props, props.children);
+        }
+    };
+    var placeholder = function () { return document.createComment('k-if'); };
     /**
      * @param tag html tag or function component
      * @param props properties/attributes
      */
     function jsx(tag, props) {
-        var _a;
-        var ref = ((_a = props.ref) === null || _a === void 0 ? void 0 : _a.isKT) ? props.ref : dummyRef;
+        var maybeDummyRef = isKTRef(props.ref) ? props.ref : dummyRef;
         var el;
-        if ('k-if' in props && !props['k-if']) {
-            // & make comment placeholder in case that ref might be redrawn later
-            el = document.createComment('k-if');
-            ref.value = el;
-            return el;
-        }
-        // Handle function components
-        if (typeof tag === 'function') {
-            el = tag(props);
-        }
-        else {
-            el = h(tag, props, props.children);
+        if ('k-if' in props) {
+            var kif = props['k-if'];
+            var condition = kif; // assume boolean by default
+            // Handle reactive k-if
+            if (isKTRef(kif)) {
+                kif.addOnChange(function (newValue, oldValue) {
+                    if (newValue === oldValue) {
+                        return;
+                    }
+                    var oldEl = el;
+                    el = newValue ? create(tag, props) : placeholder();
+                    $replaceWith.call(oldEl, el);
+                    maybeDummyRef.value = el;
+                });
+                condition = kif.value;
+            }
+            if (!condition) {
+                // & make comment placeholder in case that ref might be redrawn later
+                el = placeholder();
+                maybeDummyRef.value = el;
+                return el;
+            }
         }
-        ref.value = el;
+        el = create(tag, props);
+        maybeDummyRef.value = el;
         return el;
     }
     /**
@@ -644,10 +684,12 @@ var __ktjs_core__ = (function (exports) {
     exports.createElement = h;
     exports.createRedrawable = createRedrawable;
     exports.h = h;
+    exports.isKTRef = isKTRef;
     exports.jsx = jsx;
     exports.jsxDEV = jsxDEV;
     exports.jsxs = jsxs;
     exports.ref = ref;
+    exports.surfaceRef = surfaceRef;
 
     return exports;
 

package/dist/index.mjs

@@ -1,5 +1,6 @@
 // Cached native methods for performance optimization
 const $isArray = Array.isArray;
+const $entries = Object.entries;
 const $isThenable = (o) => typeof o === 'object' && o !== null && typeof o.then === 'function';
 
 // Error handling utilities
@@ -9,6 +10,7 @@ const $throw = (message) => {
 
 // DOM manipulation utilities
 // # dom natives
+const $replaceWith = Element.prototype.replaceWith;
 /**
  * & Remove `bind` because it is shockingly slower than wrapper
  * & `window.document` is safe because it is not configurable and its setter is undefined
@@ -48,7 +50,7 @@ const { get: $buttonDisabledGetter, set: $buttonDisabledSetter } = Object.getOwn
 
 // Shared utilities and cached native methods for kt.js framework
 // Re-export all utilities
-Object.defineProperty(window, '@ktjs/shared', { value: '0.20.0' });
+Object.defineProperty(window, '@ktjs/shared', { value: '0.20.2' });
 
 const booleanHandler = (element, key, value) => {
     if (key in element) {
@@ -191,7 +193,6 @@ function applyContent(element, content) {
     }
 }
 
-document.createElement('div');
 const htmlCreator = (tag) => document.createElement(tag);
 const svgCreator = (tag) => document.createElementNS('http://www.w3.org/2000/svg', tag);
 const mathMLCreator = (tag) => document.createElementNS('http://www.w3.org/1998/Math/MathML', tag);
@@ -209,7 +210,7 @@ const MATHML_ATTR_FLAG = '__kt_mathml__';
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.20.2 (Last Update: 2026.02.01 18:34:51.151)
+ * @version 0.21.1 (Last Update: 2026.02.02 09:20:07.959)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -238,14 +239,6 @@ const h = (tag, attr, content) => {
     // * Handle content
     applyAttr(element, attr);
     applyContent(element, content);
-    // if (tag === 'svg') {
-    //   tempWrapper.innerHTML = element.outerHTML;
-    //   return tempWrapper.firstChild as HTML<T>;
-    // }
-    // if (tag === 'math') {
-    //   tempWrapper.innerHTML = element.outerHTML;
-    //   return tempWrapper.firstChild as HTML<T>;
-    // }
     return element;
 };
 
@@ -254,7 +247,13 @@ class KTRef {
      * Indicates that this is a KTRef instance
      */
     isKT = true;
+    /**
+     * @internal
+     */
     _value;
+    /**
+     * @internal
+     */
     _onChanges;
     constructor(_value, _onChanges) {
         this._value = _value;
@@ -296,37 +295,85 @@ class KTRef {
         return false;
     }
 }
+const isKTRef = (obj) => {
+    return typeof obj === 'object' && obj !== null && 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.
  * @param value mostly an HTMLElement
  */
 function ref(value, onChange) {
     return new KTRef(value, onChange ? [onChange] : []);
 }
+function kcollect() {
+    const newObj = {};
+    const entries = $entries(this);
+    for (let i = 0; i < entries.length; i++) {
+        const key = entries[i][0];
+        if (key === 'kcollect') {
+            continue;
+        }
+        newObj[key] = entries[i][1].value;
+    }
+    return newObj;
+}
+/**
+ * Make all first-level properties of the object a `KTRef`.
+ * - `obj.a.b` is not reactive
+ */
+const surfaceRef = (obj) => {
+    const entries = $entries(obj);
+    const newObj = { kcollect };
+    for (let i = 0; i < entries.length; i++) {
+        newObj[entries[i][0]] = ref(entries[i][1]);
+    }
+    return newObj;
+};
 
 const dummyRef = { value: null };
+const create = (tag, props) => {
+    if (typeof tag === 'function') {
+        return tag(props);
+    }
+    else {
+        return h(tag, props, props.children);
+    }
+};
+const placeholder = () => document.createComment('k-if');
 /**
  * @param tag html tag or function component
  * @param props properties/attributes
  */
 function jsx(tag, props) {
-    const ref = props.ref?.isKT ? props.ref : dummyRef;
+    const maybeDummyRef = isKTRef(props.ref) ? props.ref : dummyRef;
     let el;
-    if ('k-if' in props && !props['k-if']) {
-        // & make comment placeholder in case that ref might be redrawn later
-        el = document.createComment('k-if');
-        ref.value = el;
-        return el;
-    }
-    // Handle function components
-    if (typeof tag === 'function') {
-        el = tag(props);
-    }
-    else {
-        el = h(tag, props, props.children);
+    if ('k-if' in props) {
+        const kif = props['k-if'];
+        let condition = kif; // assume boolean by default
+        // Handle reactive k-if
+        if (isKTRef(kif)) {
+            kif.addOnChange((newValue, oldValue) => {
+                if (newValue === oldValue) {
+                    return;
+                }
+                const oldEl = el;
+                el = newValue ? create(tag, props) : placeholder();
+                $replaceWith.call(oldEl, el);
+                maybeDummyRef.value = el;
+            });
+            condition = kif.value;
+        }
+        if (!condition) {
+            // & make comment placeholder in case that ref might be redrawn later
+            el = placeholder();
+            maybeDummyRef.value = el;
+            return el;
+        }
     }
-    ref.value = el;
+    el = create(tag, props);
+    maybeDummyRef.value = el;
     return el;
 }
 /**
@@ -618,4 +665,4 @@ function getSequence(arr) {
     return result;
 }
 
-export { Fragment, KTAsync, KTFor, KTRef, h as createElement, createRedrawable, h, jsx, jsxDEV, jsxs, ref };
+export { Fragment, KTAsync, KTFor, KTRef, h as createElement, createRedrawable, h, isKTRef, jsx, jsxDEV, jsxs, ref, surfaceRef };

package/dist/jsx/index.d.ts

@@ -13,8 +13,6 @@ declare class KTRef<T> {
      * Indicates that this is a KTRef instance
      */
     isKT: boolean;
-    private _value;
-    private _onChanges;
     constructor(_value: T, _onChanges: Array<RefChangeHandler<T>>);
     /**
      * If new value and old value are both nodes, the old one will be replaced in the DOM
@@ -24,12 +22,35 @@ declare class KTRef<T> {
     addOnChange(callback: RefChangeHandler<T>): void;
     removeOnChange(callback: RefChangeHandler<T>): boolean;
 }
+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.
  * @param value mostly an HTMLElement
  */
 declare function ref<T = JSX.Element>(value?: T, onChange?: RefChangeHandler<T>): KTRef<T>;
+type KTSurfaceRef<T extends Object> = {
+    [K in keyof T]: KTRef<T[K]>;
+} & {
+    /**
+     * Get the dereferenced object like the original one
+     */
+    kcollect: () => T;
+};
+/**
+ * Make all first-level properties of the object a `KTRef`.
+ * - `obj.a.b` is not reactive
+ */
+declare const surfaceRef: <T extends Object>(obj: T) => KTSurfaceRef<T>;
+
+type HTML<T extends (HTMLTag | SVGTag | MathMLTag) & otherstring> = T extends SVGTag
+  ? SVGElementTagNameMap[T]
+  : T extends HTMLTag
+    ? HTMLElementTagNameMap[T]
+    : T extends MathMLTag
+      ? MathMLElementTagNameMap[T]
+      : HTMLElement;
 
 type SingleContent = KTRef<any> | HTMLElement | Element | Node | string | number | boolean | null | undefined;
 type KTAvailableContent = SingleContent | KTAvailableContent[];
@@ -44,7 +65,14 @@ interface KTBaseAttribute {
 
   // # kt-specific attributes
   ref?: KTRef<JSX.Element>;
+
+  // todo 是否要让k-if是KTRef的时候具备响应能力?
+  /**
+   * If a `KTRef` is bound, it will be reactive; otherwise, it will be static.
+   */
   'k-if'?: any;
+  // todo k-model如何指定value还是checked还是别的什么?
+  'k-model'?: KTRef<any>;
 
   // # normal HTML attributes
   id?: string;
@@ -105,7 +133,6 @@ type KTPrefixedEventHandlers = {
 
 type KTAttribute = KTBaseAttribute & KTPrefixedEventHandlers;
 
-type HTML<T extends (HTMLTag | SVGTag | MathMLTag) & otherstring> = T extends SVGTag ? SVGElementTagNameMap[T] : T extends HTMLTag ? HTMLElementTagNameMap[T] : T extends MathMLTag ? MathMLElementTagNameMap[T] : HTMLElement;
 /**
  * Create an enhanced HTMLElement.
  * - Only supports HTMLElements, **NOT** SVGElements or other Elements.
@@ -116,7 +143,7 @@ type HTML<T extends (HTMLTag | SVGTag | MathMLTag) & otherstring> = T extends SV
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.20.2 (Last Update: 2026.02.01 18:34:51.151)
+ * @version 0.21.1 (Last Update: 2026.02.02 09:20:07.959)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -1395,4 +1422,5 @@ declare global {
   }
 }
 
-export { Fragment, KTRef, h as createElement, createRedrawable, jsx, jsxDEV, jsxs, ref };
+export { Fragment, KTRef, h as createElement, createRedrawable, isKTRef, jsx, jsxDEV, jsxs, ref, surfaceRef };
+export type { KTSurfaceRef };