@ktjs/core 0.27.2 → 0.28.1

package/dist/index.legacy.js

@@ -14,29 +14,6 @@ var __ktjs_core__ = (function (exports) {
         };
     }
 
-    // String manipulation utilities
-    /**
-     * Default empty function
-     */
-    const $emptyFn = (() => true);
-    const $emptyArray = [];
-    /**
-     * Safe and quick forEach implementation that works with array-like objects and handles sparse arrays.
-     */
-    const $forEach = (array, callback) => {
-        const len = array.length;
-        for (let i = 0; i < len; i++) {
-            callback(array[i], i, array);
-        }
-    };
-
-    const $emptyChildrenRef = { value: $emptyArray };
-    // each instance shares the same empty array, but it will be replaced when used
-    Comment.prototype.kisFragmentAnchor = false;
-    Comment.prototype.kFragmentList = $emptyArray;
-    Comment.prototype.kredraw = $emptyFn;
-    Comment.prototype.kchildrenRef = $emptyChildrenRef;
-
     // Shared constants
     // Empty for now - can be extended with framework-wide constants
     /**
@@ -107,8 +84,23 @@ var __ktjs_core__ = (function (exports) {
         element.addEventListener(eventName, () => (valueRef.value = element[propName]));
     };
 
+    // String manipulation utilities
+    /**
+     * Default empty function
+     */
+    const $emptyFn = (() => true);
+    /**
+     * Safe and quick forEach implementation that works with array-like objects and handles sparse arrays.
+     */
+    const $forEach = (array, callback) => {
+        const len = array.length;
+        for (let i = 0; i < len; i++) {
+            callback(array[i], i, array);
+        }
+    };
+
     // incase that symbol is not supported
-    Object.defineProperty(window, '__ktjs__', { value: '0.23.10' });
+    Object.defineProperty(window, '__ktjs__', { value: '0.23.11' });
 
     var isKT = function (obj) { return obj === null || obj === void 0 ? void 0 : obj.isKT; };
     var isRef = function (obj) { return (obj === null || obj === void 0 ? void 0 : obj.ktType) === 1 /* KTReactiveType.REF */; };
@@ -323,6 +315,14 @@ var __ktjs_core__ = (function (exports) {
             this._value = _value;
             this._onChanges = _onChanges;
         }
+        /**
+         * @internal
+         */
+        KTRef.prototype._emit = function (newValue, oldValue) {
+            for (var i = 0; i < this._onChanges.length; i++) {
+                this._onChanges[i](newValue, oldValue);
+            }
+        };
         Object.defineProperty(KTRef.prototype, "value", {
             /**
              * If new value and old value are both nodes, the old one will be replaced in the DOM
@@ -337,13 +337,34 @@ var __ktjs_core__ = (function (exports) {
                 var oldValue = this._value;
                 $replaceNode(oldValue, newValue);
                 this._value = newValue;
-                for (var i = 0; i < this._onChanges.length; i++) {
-                    this._onChanges[i](newValue, oldValue);
-                }
+                this._emit(newValue, oldValue);
             },
             enumerable: false,
             configurable: true
         });
+        /**
+         * Force all listeners to run even when reference identity has not changed.
+         * Useful for in-place array/object mutations.
+         */
+        KTRef.prototype.notify = function () {
+            this._emit(this._value, this._value);
+        };
+        /**
+         * Mutate current value in-place and notify listeners once.
+         *
+         * @example
+         * const items = ref<number[]>([1, 2]);
+         * items.mutate((list) => list.push(3));
+         */
+        KTRef.prototype.mutate = function (mutator) {
+            if (typeof mutator !== 'function') {
+                throw new Error('[kt.js error] KTRef.mutate: mutator must be a function');
+            }
+            var oldValue = this._value;
+            var result = mutator(this._value);
+            this._emit(this._value, oldValue);
+            return result;
+        };
         /**
          * Register a callback when the value changes
          * @param callback (newValue, oldValue) => xxx
@@ -393,9 +414,6 @@ var __ktjs_core__ = (function (exports) {
             return ref(o);
         }
     };
-    function deref(value) {
-        return isKT(value) ? value.value : value;
-    }
     function kcollect() {
         var newObj = {};
         var entries = $entries(this);
@@ -464,6 +482,31 @@ var __ktjs_core__ = (function (exports) {
             this._value = _calculator();
             this._subscribe(reactives);
         }
+        /**
+         * @internal
+         */
+        KTComputed.prototype._emit = function (newValue, oldValue) {
+            for (var i = 0; i < this._onChanges.length; i++) {
+                this._onChanges[i](newValue, oldValue);
+            }
+        };
+        /**
+         * @internal
+         */
+        KTComputed.prototype._recalculate = function (forceEmit) {
+            if (forceEmit === void 0) { forceEmit = false; }
+            var oldValue = this._value;
+            var newValue = this._calculator();
+            if (oldValue === newValue) {
+                if (forceEmit) {
+                    this._emit(newValue, oldValue);
+                }
+                return;
+            }
+            this._value = newValue;
+            $replaceNode(oldValue, newValue);
+            this._emit(newValue, oldValue);
+        };
         /**
          * @internal
          */
@@ -471,17 +514,7 @@ var __ktjs_core__ = (function (exports) {
             var _this = this;
             for (var i = 0; i < reactives.length; i++) {
                 var reactive = reactives[i];
-                reactive.addOnChange(function () {
-                    var oldValue = _this._value;
-                    _this._value = _this._calculator();
-                    if (oldValue === _this._value) {
-                        return;
-                    }
-                    $replaceNode(oldValue, _this._value);
-                    for (var i_1 = 0; i_1 < _this._onChanges.length; i_1++) {
-                        _this._onChanges[i_1](_this._value, oldValue);
-                    }
-                });
+                reactive.addOnChange(function () { return _this._recalculate(); });
             }
         };
         Object.defineProperty(KTComputed.prototype, "value", {
@@ -497,6 +530,18 @@ var __ktjs_core__ = (function (exports) {
             enumerable: false,
             configurable: true
         });
+        /**
+         * Force listeners to run once with the latest computed result.
+         */
+        KTComputed.prototype.notify = function () {
+            this._recalculate(true);
+        };
+        /**
+         * Computed values are derived from dependencies and should not be mutated manually.
+         */
+        KTComputed.prototype.mutate = function (_mutator) {
+            console.warn('[kt.js warn]','KTComputed.mutate: computed is derived automatically; manual mutate is ignored. Use notify() instead');
+        };
         /**
          * Register a callback when the value changes
          * @param callback (newValue, oldValue) => xxx
@@ -590,6 +635,12 @@ var __ktjs_core__ = (function (exports) {
             return ref(value, onChange);
         }
     };
+    /**
+     * Extracts the value from a KTReactive, or returns the value directly if it's not reactive.
+     */
+    function dereactive(value) {
+        return isKT(value) ? value.value : value;
+    }
 
     function applyKModel(element, valueRef) {
         if (!isKT(valueRef)) {
@@ -629,7 +680,7 @@ var __ktjs_core__ = (function (exports) {
      * ## About
      * @package @ktjs/core
      * @author Kasukabe Tsumugi <futami16237@gmail.com>
-     * @version 0.27.2 (Last Update: 2026.02.10 07:27:25.966)
+     * @version 0.28.1 (Last Update: 2026.02.10 11:23:01.128)
      * @license MIT
      * @link https://github.com/baendlorel/kt.js
      * @link https://baendlorel.github.io/ Welcome to my site!
@@ -664,34 +715,6 @@ var __ktjs_core__ = (function (exports) {
         return element;
     };
 
-    var kredraw = function () {
-        var newElements = this.kchildrenRef.value;
-        var parent = this.parentNode;
-        if (!parent) {
-            // If anchor is not in DOM, only update internal state
-            this.kFragmentList.length = 0;
-            for (var i = 0; i < newElements.length; i++) {
-                this.kFragmentList.push(newElements[i]);
-            }
-            return;
-        }
-        // Simple replacement algorithm: remove all old elements, insert all new elements
-        // todo Future enhancement: key-based optimization
-        // 1. Remove all old elements
-        for (var i = 0; i < this.kFragmentList.length; i++) {
-            this.kFragmentList[i].remove();
-        }
-        // 2. Insert all new elements
-        var fragment = document.createDocumentFragment();
-        this.kFragmentList.length = 0;
-        for (var i = 0; i < newElements.length; i++) {
-            var element = newElements[i];
-            this.kFragmentList.push(element);
-            fragment.appendChild(element);
-        }
-        // Insert after anchor
-        parent.insertBefore(fragment, this.nextSibling);
-    };
     /**
      * Fragment - Container component for managing arrays of child elements
      *
@@ -713,17 +736,44 @@ var __ktjs_core__ = (function (exports) {
      */
     function Fragment$1(props) {
         // key parameter reserved for future enhancement, currently unused
-        props.key;
-        var childrenRef = toReactive(props.children, function () { return anchor.kredraw(); });
+        // const { key: _key } = props;
+        var redraw = function () {
+            var newElements = childrenRef.value;
+            var parent = anchor.parentNode;
+            if (!parent) {
+                // If anchor is not in DOM, only update internal state
+                elements.length = 0;
+                for (var i = 0; i < newElements.length; i++) {
+                    elements.push(newElements[i]);
+                }
+                return;
+            }
+            // Simple replacement algorithm: remove all old elements, insert all new elements
+            // todo Future enhancement: key-based optimization
+            // 1. Remove all old elements
+            for (var i = 0; i < elements.length; i++) {
+                elements[i].remove();
+            }
+            // 2. Insert all new elements
+            var fragment = document.createDocumentFragment();
+            elements.length = 0;
+            for (var i = 0; i < newElements.length; i++) {
+                var element = newElements[i];
+                elements.push(element);
+                fragment.appendChild(element);
+            }
+            // Insert after anchor
+            parent.insertBefore(fragment, anchor.nextSibling);
+        };
+        var initialized = false;
+        var childrenRef = toReactive(props.children, redraw);
+        var elements = [];
         var anchor = document.createComment('kt-fragment');
-        anchor.kredraw = kredraw;
-        anchor.kchildrenRef = childrenRef;
-        anchor.kFragmentList = [];
-        anchor.kisFragmentAnchor = true;
         // Observe DOM insertion
         var observer = new MutationObserver(function () {
-            if (anchor.isConnected) {
-                anchor.kredraw();
+            if (anchor.isConnected && !initialized) {
+                initialized = true;
+                redraw();
                 observer.disconnect();
             }
         });
@@ -1083,7 +1133,7 @@ var __ktjs_core__ = (function (exports) {
     exports.computed = computed;
     exports.createElement = h;
     exports.createRedrawable = createRedrawable;
-    exports.deref = deref;
+    exports.dereactive = dereactive;
     exports.effect = effect;
     exports.h = h;
     exports.isComputed = isComputed;

package/dist/index.mjs

@@ -11,29 +11,6 @@ if (typeof Symbol === 'undefined') {
     };
 }
 
-// String manipulation utilities
-/**
- * Default empty function
- */
-const $emptyFn = (() => true);
-const $emptyArray = [];
-/**
- * Safe and quick forEach implementation that works with array-like objects and handles sparse arrays.
- */
-const $forEach = (array, callback) => {
-    const len = array.length;
-    for (let i = 0; i < len; i++) {
-        callback(array[i], i, array);
-    }
-};
-
-const $emptyChildrenRef = { value: $emptyArray };
-// each instance shares the same empty array, but it will be replaced when used
-Comment.prototype.kisFragmentAnchor = false;
-Comment.prototype.kFragmentList = $emptyArray;
-Comment.prototype.kredraw = $emptyFn;
-Comment.prototype.kchildrenRef = $emptyChildrenRef;
-
 // Shared constants
 // Empty for now - can be extended with framework-wide constants
 /**
@@ -104,8 +81,23 @@ const $applyModel = (element, valueRef, propName, eventName) => {
     element.addEventListener(eventName, () => (valueRef.value = element[propName]));
 };
 
+// String manipulation utilities
+/**
+ * Default empty function
+ */
+const $emptyFn = (() => true);
+/**
+ * Safe and quick forEach implementation that works with array-like objects and handles sparse arrays.
+ */
+const $forEach = (array, callback) => {
+    const len = array.length;
+    for (let i = 0; i < len; i++) {
+        callback(array[i], i, array);
+    }
+};
+
 // incase that symbol is not supported
-Object.defineProperty(window, '__ktjs__', { value: '0.23.10' });
+Object.defineProperty(window, '__ktjs__', { value: '0.23.11' });
 
 const isKT = (obj) => obj?.isKT;
 const isRef = (obj) => obj?.ktType === 1 /* KTReactiveType.REF */;
@@ -316,6 +308,14 @@ class KTRef {
      * @internal
      */
     _onChanges;
+    /**
+     * @internal
+     */
+    _emit(newValue, oldValue) {
+        for (let i = 0; i < this._onChanges.length; i++) {
+            this._onChanges[i](newValue, oldValue);
+        }
+    }
     constructor(_value, _onChanges) {
         this._value = _value;
         this._onChanges = _onChanges;
@@ -333,9 +333,30 @@ class KTRef {
         const oldValue = this._value;
         $replaceNode(oldValue, newValue);
         this._value = newValue;
-        for (let i = 0; i < this._onChanges.length; i++) {
-            this._onChanges[i](newValue, oldValue);
+        this._emit(newValue, oldValue);
+    }
+    /**
+     * Force all listeners to run even when reference identity has not changed.
+     * Useful for in-place array/object mutations.
+     */
+    notify() {
+        this._emit(this._value, this._value);
+    }
+    /**
+     * Mutate current value in-place and notify listeners once.
+     *
+     * @example
+     * const items = ref<number[]>([1, 2]);
+     * items.mutate((list) => list.push(3));
+     */
+    mutate(mutator) {
+        if (typeof mutator !== 'function') {
+            throw new Error('[kt.js error] KTRef.mutate: mutator must be a function');
         }
+        const oldValue = this._value;
+        const result = mutator(this._value);
+        this._emit(this._value, oldValue);
+        return result;
     }
     /**
      * Register a callback when the value changes
@@ -385,9 +406,6 @@ const toRef = (o) => {
         return ref(o);
     }
 };
-function deref(value) {
-    return isKT(value) ? value.value : value;
-}
 function kcollect() {
     const newObj = {};
     const entries = $entries(this);
@@ -459,23 +477,37 @@ class KTComputed {
      * @internal
      */
     _onChanges = [];
+    /**
+     * @internal
+     */
+    _emit(newValue, oldValue) {
+        for (let i = 0; i < this._onChanges.length; i++) {
+            this._onChanges[i](newValue, oldValue);
+        }
+    }
+    /**
+     * @internal
+     */
+    _recalculate(forceEmit = false) {
+        const oldValue = this._value;
+        const newValue = this._calculator();
+        if (oldValue === newValue) {
+            if (forceEmit) {
+                this._emit(newValue, oldValue);
+            }
+            return;
+        }
+        this._value = newValue;
+        $replaceNode(oldValue, newValue);
+        this._emit(newValue, oldValue);
+    }
     /**
      * @internal
      */
     _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);
-                }
-            });
+            reactive.addOnChange(() => this._recalculate());
         }
     }
     constructor(_calculator, reactives) {
@@ -492,6 +524,18 @@ class KTComputed {
     set value(_newValue) {
         throw new Error('[kt.js error] KTComputed: cannot set value of a computed value');
     }
+    /**
+     * Force listeners to run once with the latest computed result.
+     */
+    notify() {
+        this._recalculate(true);
+    }
+    /**
+     * Computed values are derived from dependencies and should not be mutated manually.
+     */
+    mutate(_mutator) {
+        console.warn('[kt.js warn]','KTComputed.mutate: computed is derived automatically; manual mutate is ignored. Use notify() instead');
+    }
     /**
      * Register a callback when the value changes
      * @param callback (newValue, oldValue) => xxx
@@ -584,6 +628,12 @@ const toReactive = (value, onChange) => {
         return ref(value, onChange);
     }
 };
+/**
+ * Extracts the value from a KTReactive, or returns the value directly if it's not reactive.
+ */
+function dereactive(value) {
+    return isKT(value) ? value.value : value;
+}
 
 function applyKModel(element, valueRef) {
     if (!isKT(valueRef)) {
@@ -623,7 +673,7 @@ let creator = htmlCreator;
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.27.2 (Last Update: 2026.02.10 07:27:25.966)
+ * @version 0.28.1 (Last Update: 2026.02.10 11:23:01.128)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -658,34 +708,6 @@ const h = (tag, attr, content) => {
     return element;
 };
 
-const kredraw = function () {
-    const newElements = this.kchildrenRef.value;
-    const parent = this.parentNode;
-    if (!parent) {
-        // If anchor is not in DOM, only update internal state
-        this.kFragmentList.length = 0;
-        for (let i = 0; i < newElements.length; i++) {
-            this.kFragmentList.push(newElements[i]);
-        }
-        return;
-    }
-    // Simple replacement algorithm: remove all old elements, insert all new elements
-    // todo Future enhancement: key-based optimization
-    // 1. Remove all old elements
-    for (let i = 0; i < this.kFragmentList.length; i++) {
-        this.kFragmentList[i].remove();
-    }
-    // 2. Insert all new elements
-    const fragment = document.createDocumentFragment();
-    this.kFragmentList.length = 0;
-    for (let i = 0; i < newElements.length; i++) {
-        const element = newElements[i];
-        this.kFragmentList.push(element);
-        fragment.appendChild(element);
-    }
-    // Insert after anchor
-    parent.insertBefore(fragment, this.nextSibling);
-};
 /**
  * Fragment - Container component for managing arrays of child elements
  *
@@ -707,17 +729,44 @@ const kredraw = function () {
  */
 function Fragment$1(props) {
     // key parameter reserved for future enhancement, currently unused
-    const { key: _key } = props;
-    const childrenRef = toReactive(props.children, () => anchor.kredraw());
+    // const { key: _key } = props;
+    const redraw = () => {
+        const newElements = childrenRef.value;
+        const parent = anchor.parentNode;
+        if (!parent) {
+            // If anchor is not in DOM, only update internal state
+            elements.length = 0;
+            for (let i = 0; i < newElements.length; i++) {
+                elements.push(newElements[i]);
+            }
+            return;
+        }
+        // Simple replacement algorithm: remove all old elements, insert all new elements
+        // todo Future enhancement: key-based optimization
+        // 1. Remove all old elements
+        for (let i = 0; i < elements.length; i++) {
+            elements[i].remove();
+        }
+        // 2. Insert all new elements
+        const fragment = document.createDocumentFragment();
+        elements.length = 0;
+        for (let i = 0; i < newElements.length; i++) {
+            const element = newElements[i];
+            elements.push(element);
+            fragment.appendChild(element);
+        }
+        // Insert after anchor
+        parent.insertBefore(fragment, anchor.nextSibling);
+    };
+    let initialized = false;
+    const childrenRef = toReactive(props.children, redraw);
+    const elements = [];
     const anchor = document.createComment('kt-fragment');
-    anchor.kredraw = kredraw;
-    anchor.kchildrenRef = childrenRef;
-    anchor.kFragmentList = [];
-    anchor.kisFragmentAnchor = true;
     // Observe DOM insertion
     const observer = new MutationObserver(() => {
-        if (anchor.isConnected) {
-            anchor.kredraw();
+        if (anchor.isConnected && !initialized) {
+            initialized = true;
+            redraw();
             observer.disconnect();
         }
     });
@@ -1062,4 +1111,4 @@ function getSequence(arr) {
     return result;
 }
 
-export { $modelOrRef, $setRef, Fragment, KTAsync, KTComputed, KTFor, KTRef, computed, h as createElement, createRedrawable, deref, effect, h, isComputed, isKT, isRef, jsx, jsxDEV, jsxs, ref, surfaceRef, toReactive, toRef };
+export { $modelOrRef, $setRef, Fragment, KTAsync, KTComputed, KTFor, KTRef, computed, h as createElement, createRedrawable, dereactive, effect, h, isComputed, isKT, isRef, jsx, jsxDEV, jsxs, ref, surfaceRef, toReactive, toRef };

package/dist/jsx/index.d.ts

@@ -1,30 +1,5 @@
 import { otherstring, HTMLTag, SVGTag, MathMLTag } from '@ktjs/shared';
 
-declare class KTComputed<T> {
-    /**
-     * Indicates that this is a KTRef instance
-     */
-    isKT: true;
-    ktType: KTReactiveType;
-    constructor(_calculator: () => T, reactives: Array<KTReactive<unknown>>);
-    /**
-     * If new value and old value are both nodes, the old one will be replaced in the DOM
-     */
-    get value(): T;
-    set value(_newValue: T);
-    /**
-     * Register a callback when the value changes
-     * @param callback (newValue, oldValue) => xxx
-     */
-    addOnChange(callback: ReactiveChangeHandler<T>): void;
-    /**
-     * Unregister a callback
-     * @param callback (newValue, oldValue) => xxx
-     */
-    removeOnChange(callback: ReactiveChangeHandler<T>): boolean;
-}
-
-type KTReactive<T> = KTRef<T> | KTComputed<T>;
 type KTReactify<T> = T extends boolean ? KTReactive<boolean> : T extends any ? KTReactive<T> : never;
 type KTReactifyProps<T extends object> = {
     [K in keyof T]: KTReactify<Exclude<T[K], undefined>> | T[K];
@@ -34,8 +9,45 @@ declare const enum KTReactiveType {
     REF = 1,
     COMPUTED = 2
 }
+
 type ReactiveChangeHandler<T> = (newValue: T, oldValue: T) => void;
 
+declare class KTReactive<T> {
+  /**
+   * Indicates that this is a KTRef instance
+   */
+  isKT: boolean;
+
+  ktType: KTReactiveType;
+
+  /**
+   * If new value and old value are both nodes, the old one will be replaced in the DOM
+   */
+  get value();
+  set value(newValue: T);
+
+  /**
+   * Force all listeners to run even when reference identity has not changed.
+   * Useful for in-place array/object mutations.
+   */
+  notify(): void;
+
+  /**
+   * Mutate current value in-place and notify listeners once.
+   *
+   * @example
+   * const items = ref<number[]>([1, 2]);
+   * items.mutate((list) => list.push(3));
+   */
+  mutate<R = void>(mutator: (currentValue: T) => R): R;
+  /**
+   * Register a callback when the value changes
+   * @param callback (newValue, oldValue) => xxx
+   */
+  addOnChange(callback: ReactiveChangeHandler<T>): void;
+  removeOnChange(callback: ReactiveChangeHandler<T>): void;
+}
+
 declare class KTRef<T> {
     /**
      * Indicates that this is a KTRef instance
@@ -48,6 +60,19 @@ declare class KTRef<T> {
      */
     get value(): T;
     set value(newValue: T);
+    /**
+     * Force all listeners to run even when reference identity has not changed.
+     * Useful for in-place array/object mutations.
+     */
+    notify(): void;
+    /**
+     * Mutate current value in-place and notify listeners once.
+     *
+     * @example
+     * const items = ref<number[]>([1, 2]);
+     * items.mutate((list) => list.push(3));
+     */
+    mutate<R = void>(mutator: (currentValue: T) => R): R;
     /**
      * Register a callback when the value changes
      * @param callback (newValue, oldValue) => xxx
@@ -164,7 +189,7 @@ type KTAttribute = KTBaseAttribute & KTPrefixedEventAttribute;
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.27.2 (Last Update: 2026.02.10 07:27:25.966)
+ * @version 0.28.1 (Last Update: 2026.02.10 11:23:01.128)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!