@ktjs/core 0.22.5 → 0.24.0

package/dist/index.mjs

@@ -1,10 +1,35 @@
+// 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 $is = Object.is;
 const $entries = Object.entries;
-const $isThenable = (o) => typeof o === 'object' && o !== null && typeof o.then === 'function';
+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 +75,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 +149,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 +177,7 @@ function attrIsObject(element, attr) {
         }
         // normal attributes
         else {
+            // todo 这里也可以绑定ref的
             (handlers[key] || defaultHandler)(element, key, o);
         }
     }
@@ -265,13 +194,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 +257,218 @@ 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, onChange ? [onChange] : []);
+}
+/**
+ * Convert a value to `KTRef`.
+ * - Returns the original value if it is already a `KTRef`.
+ * - Throws error if the value is a `KTComputed`.
+ * - Otherwise wraps the value with `ref()`.
+ * @param o value to convert
+ */
+const toRef = (o) => {
+    if (isRef(o)) {
+        return o;
+    }
+    else if (isComputed(o)) {
+        throw new Error('[kt.js error] Computed values cannot be used as KTRef.');
+    }
+    else {
+        return ref(o);
+    }
+};
+function deref(value) {
+    return isKT(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);
+};
+
+class KTComputed {
+    /**
+     * Indicates that this is a KTRef instance
+     */
+    isKT = true;
+    ktType = 2 /* KTReactiveType.COMPUTED */;
+    /**
+     * @internal
+     */
+    _calculator;
+    /**
+     * @internal
+     */
+    _value;
+    /**
+     * @internal
+     */
+    _onChanges = [];
+    _subscribe(reactives) {
+        for (let i = 0; i < reactives.length; i++) {
+            const reactive = reactives[i];
+            reactive.addOnChange(() => {
+                const oldValue = this._value;
+                this._value = this._calculator();
+                if (oldValue === this._value) {
+                    return;
+                }
+                $replaceNode(oldValue, this._value);
+                for (let i = 0; i < this._onChanges.length; i++) {
+                    this._onChanges[i](this._value, oldValue);
+                }
+            });
+        }
+    }
+    constructor(_calculator, reactives) {
+        this._calculator = _calculator;
+        this._value = _calculator();
+        this._subscribe(reactives);
+    }
+    /**
+     * 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) {
+        throw new Error('[kt.js error] KTComputed: cannot set value of a computed value');
+    }
+    /**
+     * 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);
+    }
+    /**
+     * Unregister a callback
+     * @param callback (newValue, oldValue) => xxx
+     */
+    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;
+    }
+}
+/**
+ * Create a reactive computed value
+ * @param computeFn
+ * @param reactives refs and computeds that this computed depends on
+ */
+function computed(computeFn, reactives) {
+    if (reactives.some((v) => !isKT(v))) {
+        throw new Error('[kt.js error] computed: all reactives must be KTRef or KTComputed instances');
+    }
+    return new KTComputed(computeFn, reactives);
+}
+
 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 +495,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 +505,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 +535,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 +555,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;
@@ -683,7 +828,7 @@ function KTFor(props) {
         return anchor;
     };
     // Set ref if provided
-    if (props.ref?.isKT) {
+    if (isRef(props.ref)) {
         props.ref.value = anchor;
     }
     return anchor;
@@ -731,4 +876,4 @@ function getSequence(arr) {
     return result;
 }
 
-export { $modelOrRef, Fragment, KTAsync, KTFor, KTRef, h as createElement, createRedrawable, deref, h, isKTRef, jsx, jsxDEV, jsxs, ref, surfaceRef };
+export { $modelOrRef, Fragment, KTAsync, KTComputed, KTFor, KTRef, computed, h as createElement, createRedrawable, deref, h, isComputed, isKT, isRef, jsx, jsxDEV, jsxs, ref, surfaceRef, toRef };