@ktjs/core 0.22.5 → 0.24.0

package/dist/jsx/index.mjs

@@ -1,10 +1,34 @@
+// Shared constants
+// Empty for now - can be extended with framework-wide constants
+/**
+ * Mark the attribute as SVG to handle special cases during rendering.
+ */
+const SVG_ATTR_FLAG = '__kt_svg__';
+/**
+ * Mark the attribute as MathML to handle special cases during rendering.
+ */
+const MATHML_ATTR_FLAG = '__kt_mathml__';
+
 // 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';
+const $is = Object.is;
+const $random = Math.random;
+const $isThenable = (o) => typeof o?.then === 'function';
 
 // DOM manipulation utilities
 // # dom natives
+const $isNode = (x) => x?.nodeType > 0;
+/**
+ * Safe replace `oldNode` With `newNode`
+ */
+const $replaceNode = (oldNode, newNode) => {
+    if ($isNode(oldNode) && $isNode(newNode)) {
+        if (newNode.contains(oldNode)) {
+            newNode.remove();
+        }
+        oldNode.replaceWith(newNode);
+    }
+};
 /**
  * & Remove `bind` because it is shockingly slower than wrapper
  * & `window.document` is safe because it is not configurable and its setter is undefined
@@ -50,129 +74,21 @@ const applyModel = (element, valueRef, propName, eventName) => {
     element.addEventListener(eventName, () => (valueRef.value = element[propName]));
 };
 
+if (typeof Symbol === 'undefined') {
+    window.Symbol = function Symbol(description) {
+        return `@@SYMBOL_${description || ''}_${$random().toString(36).slice(2)}`;
+    };
+}
+
 // Shared utilities and cached native methods for kt.js framework
-// Re-export all utilities
-Object.defineProperty(window, '__ktjs__', { value: '0.22.2' });
+Object.defineProperty(window, '__ktjs__', { value: '0.22.6' });
 
-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);
-        }
-    }
-    /**
-     * 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) {
-        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) => 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);
-    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;
-};
-// # 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);
-};
+// export const KT_TYPE_REF = 1 as const;
+// export const KT_TYPE_COMPUTED = 2 as const;
+// export type KTReactiveTypeEnum = typeof KT_TYPE_REF | typeof KT_TYPE_COMPUTED;
+const isKT = (obj) => obj?.isKT;
+const isRef = (obj) => obj?.ktType === 1 /* KTReactiveType.REF */;
+const isComputed = (obj) => obj?.ktType === 2 /* KTReactiveType.COMPUTED */;
 
 const booleanHandler = (element, key, value) => {
     if (key in element) {
@@ -232,14 +148,25 @@ function attrIsObject(element, attr) {
             }
         }
     }
+    if ('k-html' in attr) {
+        const html = attr['k-html'];
+        if (isKT(html)) {
+            element.innerHTML = html.value;
+            html.addOnChange((v) => (element.innerHTML = v));
+        }
+        else {
+            element.innerHTML = html;
+        }
+    }
     for (const key in attr) {
-        if (key === 'class' ||
+        if (key === 'k-if' ||
+            key === 'k-model' ||
+            key === 'ref' ||
+            key === 'class' ||
             key === 'className' ||
             key === 'style' ||
             key === 'children' ||
-            key === 'k-if' ||
-            key.startsWith('k-model') ||
-            key === 'ref') {
+            key === 'k-html') {
             continue;
         }
         const o = attr[key];
@@ -249,6 +176,7 @@ function attrIsObject(element, attr) {
         }
         // normal attributes
         else {
+            // todo 这里也可以绑定ref的
             (handlers[key] || defaultHandler)(element, key, o);
         }
     }
@@ -265,13 +193,25 @@ function applyAttr(element, attr) {
     }
 }
 
+const assureNode = (o) => ($isNode(o) ? o : document.createTextNode(o));
 function apdSingle(element, c) {
     // & JSX should ignore false, undefined, and null
     if (c === false || c === undefined || c === null) {
         return;
     }
-    if (typeof c === 'object' && c !== null && 'isKT' in c) {
-        $append.call(element, c.value);
+    if (isKT(c)) {
+        let node = assureNode(c.value);
+        $append.call(element, node);
+        c.addOnChange((newValue, oldValue) => {
+            if ($isNode(newValue) && $isNode(oldValue)) {
+                // & this case is handled automically in `class KTRef`
+                // todo 2 cases might be able to merge into 1
+                return;
+            }
+            const oldNode = node;
+            node = assureNode(newValue);
+            oldNode.replaceWith(node);
+        });
     }
     else {
         $append.call(element, c);
@@ -316,8 +256,74 @@ function applyContent(element, content) {
     }
 }
 
+class KTRef {
+    /**
+     * Indicates that this is a KTRef instance
+     */
+    isKT = true;
+    ktType = 1 /* KTReactiveType.REF */;
+    /**
+     * @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 ($is(newValue, this._value)) {
+            return;
+        }
+        const oldValue = this._value;
+        $replaceNode(oldValue, newValue);
+        this._value = newValue;
+        for (let i = 0; i < this._onChanges.length; i++) {
+            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) {
+        for (let i = this._onChanges.length - 1; i >= 0; i--) {
+            if (this._onChanges[i] === callback) {
+                this._onChanges.splice(i, 1);
+                return true;
+            }
+        }
+        return false;
+    }
+}
+/**
+ * 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) {
+    return new KTRef(value, []);
+}
+
 function applyKModel(element, valueRef) {
-    if (!isKTRef(valueRef)) {
+    if (!isKT(valueRef)) {
         console.warn('[kt.js warn] k-model value must be a KTRef.');
         return;
     }
@@ -344,9 +350,6 @@ 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);
 let creator = htmlCreator;
-// # consts
-const SVG_ATTR_FLAG = '__kt_svg__';
-const MATHML_ATTR_FLAG = '__kt_mathml__';
 /**
  * Create an enhanced HTMLElement.
  * - Only supports HTMLElements, **NOT** SVGElements or other Elements.
@@ -357,7 +360,7 @@ const MATHML_ATTR_FLAG = '__kt_mathml__';
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.22.5 (Last Update: 2026.02.03 09:07:21.411)
+ * @version 0.24.0 (Last Update: 2026.02.05 12:08:54.164)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -387,13 +390,7 @@ const h = (tag, attr, content) => {
     applyAttr(element, attr);
     applyContent(element, content);
     if (typeof attr === 'object' && attr !== null && 'k-model' in attr) {
-        const kmodel = attr['k-model'];
-        if (isKTRef(kmodel)) {
-            applyKModel(element, kmodel);
-        }
-        else {
-            throw new Error('[kt.js error] k-model value must be a KTRef.');
-        }
+        applyKModel(element, attr['k-model']);
     }
     return element;
 };
@@ -413,20 +410,23 @@ const placeholder = () => document.createComment('k-if');
  * @param props properties/attributes
  */
 function jsx(tag, props) {
-    const maybeDummyRef = isKTRef(props.ref) ? props.ref : dummyRef;
+    if (isComputed(props.ref)) {
+        throw new Error('[kt.js error] Cannot assign a computed value to an element.');
+    }
+    const maybeDummyRef = isRef(props.ref) ? props.ref : dummyRef;
     let el;
     if ('k-if' in props) {
         const kif = props['k-if'];
         let condition = kif; // assume boolean by default
         // Handle reactive k-if
-        if (isKTRef(kif)) {
+        if (isKT(kif)) {
             kif.addOnChange((newValue, oldValue) => {
                 if (newValue === oldValue) {
                     return;
                 }
                 const oldEl = el;
                 el = newValue ? create(tag, props) : placeholder();
-                oldEl.replaceWith(el);
+                $replaceNode(oldEl, el);
                 maybeDummyRef.value = el;
             });
             condition = kif.value;
@@ -507,4 +507,4 @@ function createRedrawable(creator) {
     return elRef;
 }
 
-export { $modelOrRef, Fragment, KTRef, h as createElement, createRedrawable, deref, isKTRef, jsx, jsxDEV, jsxs, ref, surfaceRef };
+export { Fragment, h as createElement, createRedrawable, jsx, jsxDEV, jsxs };

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

@@ -7,13 +7,19 @@ type HTMLTag = keyof HTMLElementTagNameMap;
 type SVGTag = keyof SVGElementTagNameMap;
 type MathMLTag = keyof MathMLElementTagNameMap;
 
-type RefChangeHandler<T> = (newValue: T, oldValue: T) => void;
+declare const enum KTReactiveType {
+    REF = 1,
+    COMPUTED = 2
+}
+type ReactiveChangeHandler<T> = (newValue: T, oldValue: T) => void;
+
 declare class KTRef<T> {
     /**
      * Indicates that this is a KTRef instance
      */
-    isKT: boolean;
-    constructor(_value: T, _onChanges: Array<RefChangeHandler<T>>);
+    isKT: true;
+    ktType: KTReactiveType;
+    constructor(_value: T, _onChanges: Array<ReactiveChangeHandler<T>>);
     /**
      * If new value and old value are both nodes, the old one will be replaced in the DOM
      */
@@ -23,8 +29,8 @@ declare class KTRef<T> {
      * Register a callback when the value changes
      * @param callback (newValue, oldValue) => xxx
      */
-    addOnChange(callback: RefChangeHandler<T>): void;
-    removeOnChange(callback: RefChangeHandler<T>): boolean;
+    addOnChange(callback: ReactiveChangeHandler<T>): void;
+    removeOnChange(callback: ReactiveChangeHandler<T>): boolean;
 }
 
 type HTML<T extends (HTMLTag | SVGTag | MathMLTag) & otherstring> = T extends SVGTag
@@ -60,6 +66,12 @@ interface KTBaseAttribute {
    */
   'k-model'?: KTRef<any>;
 
+  /**
+   * Directly apply html string to `innerHTML`.
+   * - Would be reactive if `KTRef` instance is provided
+   */
+  'k-html'?: any;
+
   // # normal HTML attributes
   id?: string;
   class?: string;
@@ -113,11 +125,11 @@ interface KTBaseAttribute {
   method?: 'POST' | 'GET' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS' | 'CONNECT' | 'TRACE' | otherstring;
 }
 
-type KTPrefixedEventHandlers = {
+type KTPrefixedEventAttribute = {
   [EventName in keyof HTMLElementEventMap as `on:${EventName}`]?: (ev: HTMLElementEventMap[EventName]) => void;
 };
 
-type KTAttribute = KTBaseAttribute & KTPrefixedEventHandlers;
+type KTAttribute = KTBaseAttribute & KTPrefixedEventAttribute;
 
 /**
  * Create an enhanced HTMLElement.
@@ -129,7 +141,7 @@ type KTAttribute = KTBaseAttribute & KTPrefixedEventHandlers;
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.22.5 (Last Update: 2026.02.03 09:07:21.411)
+ * @version 0.24.0 (Last Update: 2026.02.05 12:08:54.164)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!