@ktjs/core 0.17.3 → 0.18.0

package/README.md

@@ -81,6 +81,10 @@ const card = h('div', { class: 'card' }, [
   h('p', {}, 'Description'),
   h('button', {}, 'Click me'),
 ]);
+
+// Note: attr parameter must be an object
+// String className shorthand is NOT supported:
+// h('div', 'my-class') ❌ - This will throw an error
 ```
 
 ### Event Handlers
@@ -344,7 +348,7 @@ Creates an HTMLElement with the specified tag, attributes, and content.
 **Parameters:**
 
 - `tag` (string): HTML tag name (e.g., 'div', 'span', 'button')
-- `attributes` (object, optional): Element attributes and event handlers
+- `attributes` (object, optional): Element attributes and event handlers. **Must be an object** - string className shorthand is not supported.
 - `content` (string | HTMLElement | Array, optional): Element content
 
 **Returns:** HTMLElement
@@ -354,8 +358,9 @@ Creates an HTMLElement with the specified tag, attributes, and content.
 The package includes comprehensive TypeScript definitions:
 
 - `HTMLTag`: Union type of all valid HTML tag names
-- `KAttribute`: Attribute object type with string or function values
-- `KContent`: Valid content types (string, Element, Array, etc.)
+- `KTAttribute`: Attribute object type for element attributes and event handlers
+- `KTRawAttr`: Union type for raw attribute parameter (`KTAttribute | null | undefined | '' | false`)
+- `KTRawContent`: Valid content types (string, Element, Array, Promise, etc.)
 - Event handler types with proper event object types
 
 ## Performance Considerations

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.
@@ -48,7 +54,7 @@ declare global {
 type SingleContent = KTRef<any> | HTMLElement | Element | Node | string | number | boolean | null | undefined;
 type KTAvailableContent = SingleContent | KTAvailableContent[];
 type KTRawContent = KTAvailableContent | Promise<KTAvailableContent>;
-type KTRawAttr = KTAttribute | string;
+type KTRawAttr = KTAttribute | null | undefined | '' | false;
 type KTRawContents = KTAvailableContent;
 
 /**
@@ -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.3 (Last Update: 2026.01.28 16:50:39.470)
+ * @version 0.18.0 (Last Update: 2026.01.30 21:16:15.994)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!

package/dist/index.iife.js

@@ -97,14 +97,14 @@ var __ktjs_core__ = (function (exports) {
         }
     }
     function applyAttr(element, attr) {
+        if (!attr) {
+            return;
+        }
         if (typeof attr === 'object' && attr !== null) {
             attrIsObject(element, attr);
         }
-        else if (typeof attr === 'string') {
-            element.className = attr;
-        }
         else {
-            throw new Error('kt.js: attr must be an object/string.');
+            throw new Error('kt.js: attr must be an object.');
         }
     }
 
@@ -204,8 +204,7 @@ var __ktjs_core__ = (function (exports) {
         }
     }
 
-    const defaultCreator = (tag) => document.createElement(tag);
-    let creator = defaultCreator;
+    const svgTempWrapper = document.createElement('div');
     /**
      * Create an enhanced HTMLElement.
      * - Only supports HTMLElements, **NOT** SVGElements or other Elements.
@@ -216,7 +215,7 @@ var __ktjs_core__ = (function (exports) {
      * ## About
      * @package @ktjs/core
      * @author Kasukabe Tsumugi <futami16237@gmail.com>
-     * @version 0.17.3 (Last Update: 2026.01.28 16:50:39.470)
+     * @version 0.18.0 (Last Update: 2026.01.30 21:16:15.994)
      * @license MIT
      * @link https://github.com/baendlorel/kt.js
      * @link https://baendlorel.github.io/ Welcome to my site!
@@ -228,14 +227,13 @@ var __ktjs_core__ = (function (exports) {
             $throw('tagName must be a string.');
         }
         // * start creating the element
-        const element = creator(tag);
+        const element = document.createElement(tag);
         // * Handle content
         applyAttr(element, attr);
         applyContent(element, content);
         if (tag === 'svg') {
-            const div = document.createElement('div');
-            div.innerHTML = element.outerHTML;
-            return div.firstChild;
+            svgTempWrapper.innerHTML = element.outerHTML;
+            return svgTempWrapper.firstChild;
         }
         return element;
     };
@@ -246,11 +244,44 @@ 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 };
-    // todo 是否进一步削减h函数的分支，比如去掉string为attr的情况
     /**
      * @param tag html tag or function component
      * @param props properties/attributes

package/dist/index.legacy.js

@@ -109,14 +109,14 @@ var __ktjs_core__ = (function (exports) {
         }
     }
     function applyAttr(element, attr) {
+        if (!attr) {
+            return;
+        }
         if (typeof attr === 'object' && attr !== null) {
             attrIsObject(element, attr);
         }
-        else if (typeof attr === 'string') {
-            element.className = attr;
-        }
         else {
-            throw new Error('kt.js: attr must be an object/string.');
+            throw new Error('kt.js: attr must be an object.');
         }
     }
 
@@ -229,8 +229,7 @@ var __ktjs_core__ = (function (exports) {
         }
     }
 
-    var defaultCreator = function (tag) { return document.createElement(tag); };
-    var creator = defaultCreator;
+    var svgTempWrapper = document.createElement('div');
     /**
      * Create an enhanced HTMLElement.
      * - Only supports HTMLElements, **NOT** SVGElements or other Elements.
@@ -241,7 +240,7 @@ var __ktjs_core__ = (function (exports) {
      * ## About
      * @package @ktjs/core
      * @author Kasukabe Tsumugi <futami16237@gmail.com>
-     * @version 0.17.3 (Last Update: 2026.01.28 16:50:39.470)
+     * @version 0.18.0 (Last Update: 2026.01.30 21:16:15.994)
      * @license MIT
      * @link https://github.com/baendlorel/kt.js
      * @link https://baendlorel.github.io/ Welcome to my site!
@@ -253,14 +252,13 @@ var __ktjs_core__ = (function (exports) {
             $throw('tagName must be a string.');
         }
         // * start creating the element
-        var element = creator(tag);
+        var element = document.createElement(tag);
         // * Handle content
         applyAttr(element, attr);
         applyContent(element, content);
         if (tag === 'svg') {
-            var div = document.createElement('div');
-            div.innerHTML = element.outerHTML;
-            return div.firstChild;
+            svgTempWrapper.innerHTML = element.outerHTML;
+            return svgTempWrapper.firstChild;
         }
         return element;
     };
@@ -304,11 +302,44 @@ 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 };
-    // todo 是否进一步削减h函数的分支，比如去掉string为attr的情况
     /**
      * @param tag html tag or function component
      * @param props properties/attributes

package/dist/index.mjs

@@ -94,14 +94,14 @@ function attrIsObject(element, attr) {
     }
 }
 function applyAttr(element, attr) {
+    if (!attr) {
+        return;
+    }
     if (typeof attr === 'object' && attr !== null) {
         attrIsObject(element, attr);
     }
-    else if (typeof attr === 'string') {
-        element.className = attr;
-    }
     else {
-        throw new Error('kt.js: attr must be an object/string.');
+        throw new Error('kt.js: attr must be an object.');
     }
 }
 
@@ -201,8 +201,7 @@ function applyContent(element, content) {
     }
 }
 
-const defaultCreator = (tag) => document.createElement(tag);
-let creator = defaultCreator;
+const svgTempWrapper = document.createElement('div');
 /**
  * Create an enhanced HTMLElement.
  * - Only supports HTMLElements, **NOT** SVGElements or other Elements.
@@ -213,7 +212,7 @@ let creator = defaultCreator;
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.17.3 (Last Update: 2026.01.28 16:50:39.470)
+ * @version 0.18.0 (Last Update: 2026.01.30 21:16:15.994)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -225,14 +224,13 @@ const h = (tag, attr, content) => {
         $throw('tagName must be a string.');
     }
     // * start creating the element
-    const element = creator(tag);
+    const element = document.createElement(tag);
     // * Handle content
     applyAttr(element, attr);
     applyContent(element, content);
     if (tag === 'svg') {
-        const div = document.createElement('div');
-        div.innerHTML = element.outerHTML;
-        return div.firstChild;
+        svgTempWrapper.innerHTML = element.outerHTML;
+        return svgTempWrapper.firstChild;
     }
     return element;
 };
@@ -243,11 +241,44 @@ 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 };
-// todo 是否进一步削减h函数的分支，比如去掉string为attr的情况
 /**
  * @param tag html tag or function component
  * @param props properties/attributes

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.
@@ -48,7 +54,7 @@ declare global {
 type SingleContent = KTRef<any> | HTMLElement | Element | Node | string | number | boolean | null | undefined;
 type KTAvailableContent = SingleContent | KTAvailableContent[];
 type KTRawContent = KTAvailableContent | Promise<KTAvailableContent>;
-type KTRawAttr = KTAttribute | string;
+type KTRawAttr = KTAttribute | null | undefined | '' | false;
 
 /**
  * Used to create enhanced HTML elements
@@ -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.3 (Last Update: 2026.01.28 16:50:39.470)
+ * @version 0.18.0 (Last Update: 2026.01.30 21:16:15.994)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!

package/dist/jsx/index.mjs

@@ -94,14 +94,14 @@ function attrIsObject(element, attr) {
     }
 }
 function applyAttr(element, attr) {
+    if (!attr) {
+        return;
+    }
     if (typeof attr === 'object' && attr !== null) {
         attrIsObject(element, attr);
     }
-    else if (typeof attr === 'string') {
-        element.className = attr;
-    }
     else {
-        throw new Error('kt.js: attr must be an object/string.');
+        throw new Error('kt.js: attr must be an object.');
     }
 }
 
@@ -201,8 +201,7 @@ function applyContent(element, content) {
     }
 }
 
-const defaultCreator = (tag) => document.createElement(tag);
-let creator = defaultCreator;
+const svgTempWrapper = document.createElement('div');
 /**
  * Create an enhanced HTMLElement.
  * - Only supports HTMLElements, **NOT** SVGElements or other Elements.
@@ -213,7 +212,7 @@ let creator = defaultCreator;
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.17.3 (Last Update: 2026.01.28 16:50:39.470)
+ * @version 0.18.0 (Last Update: 2026.01.30 21:16:15.994)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -225,14 +224,13 @@ const h = (tag, attr, content) => {
         $throw('tagName must be a string.');
     }
     // * start creating the element
-    const element = creator(tag);
+    const element = document.createElement(tag);
     // * Handle content
     applyAttr(element, attr);
     applyContent(element, content);
     if (tag === 'svg') {
-        const div = document.createElement('div');
-        div.innerHTML = element.outerHTML;
-        return div.firstChild;
+        svgTempWrapper.innerHTML = element.outerHTML;
+        return svgTempWrapper.firstChild;
     }
     return element;
 };
@@ -243,11 +241,44 @@ 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 };
-// todo 是否进一步削减h函数的分支，比如去掉string为attr的情况
 /**
  * @param tag html tag or function component
  * @param props properties/attributes

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;
@@ -42,7 +48,7 @@ declare global {
 type SingleContent = KTRef<any> | HTMLElement | Element | Node | string | number | boolean | null | undefined;
 type KTAvailableContent = SingleContent | KTAvailableContent[];
 type KTRawContent = KTAvailableContent | Promise<KTAvailableContent>;
-type KTRawAttr = KTAttribute | string;
+type KTRawAttr = KTAttribute | null | undefined | '' | false;
 
 /**
  * Used to create enhanced HTML elements
@@ -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.3 (Last Update: 2026.01.28 16:50:39.470)
+ * @version 0.18.0 (Last Update: 2026.01.30 21:16:15.994)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!

package/dist/jsx/jsx-runtime.mjs

@@ -94,14 +94,14 @@ function attrIsObject(element, attr) {
     }
 }
 function applyAttr(element, attr) {
+    if (!attr) {
+        return;
+    }
     if (typeof attr === 'object' && attr !== null) {
         attrIsObject(element, attr);
     }
-    else if (typeof attr === 'string') {
-        element.className = attr;
-    }
     else {
-        throw new Error('kt.js: attr must be an object/string.');
+        throw new Error('kt.js: attr must be an object.');
     }
 }
 
@@ -201,8 +201,7 @@ function applyContent(element, content) {
     }
 }
 
-const defaultCreator = (tag) => document.createElement(tag);
-let creator = defaultCreator;
+const svgTempWrapper = document.createElement('div');
 /**
  * Create an enhanced HTMLElement.
  * - Only supports HTMLElements, **NOT** SVGElements or other Elements.
@@ -213,7 +212,7 @@ let creator = defaultCreator;
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.17.3 (Last Update: 2026.01.28 16:50:39.470)
+ * @version 0.18.0 (Last Update: 2026.01.30 21:16:15.994)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -225,14 +224,13 @@ const h = (tag, attr, content) => {
         $throw('tagName must be a string.');
     }
     // * start creating the element
-    const element = creator(tag);
+    const element = document.createElement(tag);
     // * Handle content
     applyAttr(element, attr);
     applyContent(element, content);
     if (tag === 'svg') {
-        const div = document.createElement('div');
-        div.innerHTML = element.outerHTML;
-        return div.firstChild;
+        svgTempWrapper.innerHTML = element.outerHTML;
+        return svgTempWrapper.firstChild;
     }
     return element;
 };
@@ -243,11 +241,44 @@ 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 };
-// todo 是否进一步削减h函数的分支，比如去掉string为attr的情况
 /**
  * @param tag html tag or function component
  * @param props properties/attributes

package/package.json

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