@ktjs/core 0.20.3 → 0.22.0

package/dist/index.mjs

@@ -1,14 +1,12 @@
 // 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
 const $throw = (message) => {
     throw new Error('@ktjs/shared: ' + message);
 };
-
-// DOM manipulation utilities
-// # dom natives
 /**
  * & 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 +46,97 @@ 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' });
+
+class KTRef {
+    /**
+     * Indicates that this is a KTRef instance
+     */
+    isKT = true;
+    /**
+     * @internal
+     */
+    _value;
+    /**
+     * @internal
+     */
+    _onChanges;
+    constructor(_value, _onChanges) {
+        this._value = _value;
+        this._onChanges = _onChanges;
+    }
+    /**
+     * If new value and old value are both nodes, the old one will be replaced in the DOM
+     */
+    get value() {
+        return this._value;
+    }
+    set value(newValue) {
+        if (newValue === this._value) {
+            return;
+        }
+        // replace the old node with the new one in the DOM if both are nodes
+        if (this._value instanceof Node && newValue instanceof Node) {
+            if (newValue.contains(this._value)) {
+                this._value.remove();
+            }
+            this._value.replaceWith(newValue);
+        }
+        const oldValue = this._value;
+        this._value = newValue;
+        for (let i = 0; i < this._onChanges.length; i++) {
+            this._onChanges[i](newValue, oldValue);
+        }
+    }
+    addOnChange(callback) {
+        this._onChanges.push(callback);
+    }
+    removeOnChange(callback) {
+        for (let i = this._onChanges.length - 1; i >= 0; i--) {
+            if (this._onChanges[i] === callback) {
+                this._onChanges.splice(i, 1);
+                return true;
+            }
+        }
+        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 booleanHandler = (element, key, value) => {
     if (key in element) {
@@ -114,6 +202,7 @@ function attrIsObject(element, attr) {
             key === 'style' ||
             key === 'children' ||
             key === 'k-if' ||
+            key.startsWith('k-model') ||
             key === 'ref') {
             continue;
         }
@@ -191,7 +280,29 @@ function applyContent(element, content) {
     }
 }
 
-document.createElement('div');
+function register(element, valueRef, propName, eventName) {
+    element[propName] = valueRef.value; // initialize
+    valueRef.addOnChange((newValue) => (element[propName] = newValue));
+    element.addEventListener(eventName, () => (valueRef.value = element[propName]));
+}
+function applyModel(element, valueRef) {
+    if (element instanceof HTMLInputElement) {
+        if (element.type === 'radio' || element.type === 'checkbox') {
+            register(element, valueRef, 'checked', 'change');
+        }
+        else {
+            register(element, valueRef, 'value', 'input');
+        }
+    }
+    else if (element instanceof HTMLSelectElement) {
+        register(element, valueRef, 'value', 'change');
+    }
+    else if (element instanceof HTMLTextAreaElement) {
+        register(element, valueRef, 'value', 'input');
+    }
+    console.warn('[kt.js warn] not supported element for k-model:', element.tagName);
+}
+
 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 +320,7 @@ const MATHML_ATTR_FLAG = '__kt_mathml__';
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.20.3 (Last Update: 2026.02.01 18:38:02.198)
+ * @version 0.22.0 (Last Update: 2026.02.02 17:11:04.703)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -238,101 +349,60 @@ 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;
-};
-
-class KTRef {
-    /**
-     * Indicates that this is a KTRef instance
-     */
-    isKT = true;
-    /**
-     * @internal
-     */
-    _value;
-    /**
-     * @internal
-     */
-    _onChanges;
-    constructor(_value, _onChanges) {
-        this._value = _value;
-        this._onChanges = _onChanges;
-    }
-    /**
-     * If new value and old value are both nodes, the old one will be replaced in the DOM
-     */
-    get value() {
-        return this._value;
-    }
-    set value(newValue) {
-        if (newValue === this._value) {
-            return;
-        }
-        // replace the old node with the new one in the DOM if both are nodes
-        if (this._value instanceof Node && newValue instanceof Node) {
-            if (newValue.contains(this._value)) {
-                this._value.remove();
-            }
-            this._value.replaceWith(newValue);
+    if (typeof attr === 'object' && attr !== null && 'k-model' in attr) {
+        const kmodel = attr['k-model'];
+        if (isKTRef(kmodel)) {
+            applyModel(element, kmodel);
         }
-        const oldValue = this._value;
-        this._value = newValue;
-        for (let i = 0; i < this._onChanges.length; i++) {
-            this._onChanges[i](newValue, oldValue);
-        }
-    }
-    addOnChange(callback) {
-        this._onChanges.push(callback);
-    }
-    removeOnChange(callback) {
-        for (let i = this._onChanges.length - 1; i >= 0; i--) {
-            if (this._onChanges[i] === callback) {
-                this._onChanges.splice(i, 1);
-                return true;
-            }
+        else {
+            $throw('k-model value must be a KTRef.');
         }
-        return false;
     }
-}
-/**
- * Reference to the created HTML 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] : []);
-}
+    return element;
+};
 
 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();
+                oldEl.replaceWith(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;
 }
 /**
@@ -624,4 +694,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

@@ -22,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[];
@@ -42,8 +65,18 @@ interface KTBaseAttribute {
 
   // # kt-specific attributes
   ref?: KTRef<JSX.Element>;
+
+  /**
+   * If a `KTRef` is bound, it will be reactive; otherwise, it will be static.
+   */
   'k-if'?: any;
 
+  /**
+   * Register two-way data binding between an input element and a KTRef.
+   * - Default to regist `input` event and `value` property(`checked` for checkboxes and radios).
+   */
+  'k-model'?: KTRef<any>;
+
   // # normal HTML attributes
   id?: string;
   class?: string;
@@ -103,7 +136,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.
@@ -114,7 +146,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.3 (Last Update: 2026.02.01 18:38:02.198)
+ * @version 0.22.0 (Last Update: 2026.02.02 17:11:04.703)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -1393,4 +1425,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 };

package/dist/jsx/index.mjs

@@ -1,14 +1,12 @@
 // 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
 const $throw = (message) => {
     throw new Error('@ktjs/shared: ' + message);
 };
-
-// DOM manipulation utilities
-// # dom natives
 /**
  * & 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 +46,97 @@ 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' });
+
+class KTRef {
+    /**
+     * Indicates that this is a KTRef instance
+     */
+    isKT = true;
+    /**
+     * @internal
+     */
+    _value;
+    /**
+     * @internal
+     */
+    _onChanges;
+    constructor(_value, _onChanges) {
+        this._value = _value;
+        this._onChanges = _onChanges;
+    }
+    /**
+     * If new value and old value are both nodes, the old one will be replaced in the DOM
+     */
+    get value() {
+        return this._value;
+    }
+    set value(newValue) {
+        if (newValue === this._value) {
+            return;
+        }
+        // replace the old node with the new one in the DOM if both are nodes
+        if (this._value instanceof Node && newValue instanceof Node) {
+            if (newValue.contains(this._value)) {
+                this._value.remove();
+            }
+            this._value.replaceWith(newValue);
+        }
+        const oldValue = this._value;
+        this._value = newValue;
+        for (let i = 0; i < this._onChanges.length; i++) {
+            this._onChanges[i](newValue, oldValue);
+        }
+    }
+    addOnChange(callback) {
+        this._onChanges.push(callback);
+    }
+    removeOnChange(callback) {
+        for (let i = this._onChanges.length - 1; i >= 0; i--) {
+            if (this._onChanges[i] === callback) {
+                this._onChanges.splice(i, 1);
+                return true;
+            }
+        }
+        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 booleanHandler = (element, key, value) => {
     if (key in element) {
@@ -114,6 +202,7 @@ function attrIsObject(element, attr) {
             key === 'style' ||
             key === 'children' ||
             key === 'k-if' ||
+            key.startsWith('k-model') ||
             key === 'ref') {
             continue;
         }
@@ -191,7 +280,29 @@ function applyContent(element, content) {
     }
 }
 
-document.createElement('div');
+function register(element, valueRef, propName, eventName) {
+    element[propName] = valueRef.value; // initialize
+    valueRef.addOnChange((newValue) => (element[propName] = newValue));
+    element.addEventListener(eventName, () => (valueRef.value = element[propName]));
+}
+function applyModel(element, valueRef) {
+    if (element instanceof HTMLInputElement) {
+        if (element.type === 'radio' || element.type === 'checkbox') {
+            register(element, valueRef, 'checked', 'change');
+        }
+        else {
+            register(element, valueRef, 'value', 'input');
+        }
+    }
+    else if (element instanceof HTMLSelectElement) {
+        register(element, valueRef, 'value', 'change');
+    }
+    else if (element instanceof HTMLTextAreaElement) {
+        register(element, valueRef, 'value', 'input');
+    }
+    console.warn('[kt.js warn] not supported element for k-model:', element.tagName);
+}
+
 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 +320,7 @@ const MATHML_ATTR_FLAG = '__kt_mathml__';
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.20.3 (Last Update: 2026.02.01 18:38:02.198)
+ * @version 0.22.0 (Last Update: 2026.02.02 17:11:04.703)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -238,101 +349,60 @@ 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;
-};
-
-class KTRef {
-    /**
-     * Indicates that this is a KTRef instance
-     */
-    isKT = true;
-    /**
-     * @internal
-     */
-    _value;
-    /**
-     * @internal
-     */
-    _onChanges;
-    constructor(_value, _onChanges) {
-        this._value = _value;
-        this._onChanges = _onChanges;
-    }
-    /**
-     * If new value and old value are both nodes, the old one will be replaced in the DOM
-     */
-    get value() {
-        return this._value;
-    }
-    set value(newValue) {
-        if (newValue === this._value) {
-            return;
-        }
-        // replace the old node with the new one in the DOM if both are nodes
-        if (this._value instanceof Node && newValue instanceof Node) {
-            if (newValue.contains(this._value)) {
-                this._value.remove();
-            }
-            this._value.replaceWith(newValue);
+    if (typeof attr === 'object' && attr !== null && 'k-model' in attr) {
+        const kmodel = attr['k-model'];
+        if (isKTRef(kmodel)) {
+            applyModel(element, kmodel);
         }
-        const oldValue = this._value;
-        this._value = newValue;
-        for (let i = 0; i < this._onChanges.length; i++) {
-            this._onChanges[i](newValue, oldValue);
-        }
-    }
-    addOnChange(callback) {
-        this._onChanges.push(callback);
-    }
-    removeOnChange(callback) {
-        for (let i = this._onChanges.length - 1; i >= 0; i--) {
-            if (this._onChanges[i] === callback) {
-                this._onChanges.splice(i, 1);
-                return true;
-            }
+        else {
+            $throw('k-model value must be a KTRef.');
         }
-        return false;
     }
-}
-/**
- * Reference to the created HTML 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] : []);
-}
+    return element;
+};
 
 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();
+                oldEl.replaceWith(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;
 }
 /**
@@ -400,4 +470,4 @@ function createRedrawable(creator) {
     return elRef;
 }
 
-export { Fragment, KTRef, h as createElement, createRedrawable, jsx, jsxDEV, jsxs, ref };
+export { Fragment, KTRef, h as createElement, createRedrawable, isKTRef, jsx, jsxDEV, jsxs, ref, surfaceRef };