@ktjs/core 0.27.1 → 0.28.1

package/dist/index.d.ts

@@ -13,6 +13,14 @@ declare class KTComputed<T> {
      */
     get value(): T;
     set value(_newValue: T);
+    /**
+     * Force listeners to run once with the latest computed result.
+     */
+    notify(): void;
+    /**
+     * Computed values are derived from dependencies and should not be mutated manually.
+     */
+    mutate<R = void>(_mutator?: (value: T) => R): void;
     /**
      * Register a callback when the value changes
      * @param callback (newValue, oldValue) => xxx
@@ -45,8 +53,11 @@ interface KTEffectOptions {
  */
 declare function effect(effectFn: () => void, reactives: Array<KTReactive<any>>, options?: Partial<KTEffectOptions>): () => void;
 
-type KTReactive<T> = KTRef<T> | KTComputed<T>;
 declare const toReactive: <T>(value: T | KTReactive<T>, onChange?: ReactiveChangeHandler<T>) => KTReactive<T>;
+/**
+ * Extracts the value from a KTReactive, or returns the value directly if it's not reactive.
+ */
+declare function dereactive<T = JSX.Element>(value: T | KTReactive<T>): T;
 type KTReactify<T> = T extends boolean ? KTReactive<boolean> : T extends any ? KTReactive<T> : never;
 type KTReactifyObject<T extends object> = {
     [K in keyof T]: KTReactify<T[K]>;
@@ -62,8 +73,45 @@ declare const enum KTReactiveType {
 declare const isKT: <T = any>(obj: any) => obj is KTReactive<T>;
 declare const isRef: <T = any>(obj: any) => obj is KTRef<T>;
 declare const isComputed: <T = any>(obj: any) => obj is KTComputed<T>;
+
 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
@@ -76,6 +124,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
@@ -99,7 +160,6 @@ declare function ref<T = JSX.Element>(value?: T, onChange?: ReactiveChangeHandle
  * @param o value to convert
  */
 declare const toRef: <T = any>(o: any) => KTRef<T>;
-declare function deref<T = JSX.Element>(value: T | KTReactive<T>): T;
 type KTSurfaceRef<T extends Object> = {
     [K in keyof T]: KTRef<T[K]>;
 } & {
@@ -243,7 +303,7 @@ type KTComponent = (
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.27.1 (Last Update: 2026.02.10 01:30:30.991)
+ * @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!
@@ -1404,5 +1464,5 @@ interface KTForProps<T> {
  */
 declare function KTFor<T>(props: KTForProps<T>): KTForElement;
 
-export { $modelOrRef, $setRef, Fragment, KTAsync, KTComputed, KTFor, KTReactiveType, KTRef, computed, h as createElement, createRedrawable, deref, effect, h, isComputed, isKT, isRef, jsx, jsxDEV, jsxs, ref, surfaceRef, toReactive, toRef };
-export type { EventHandler, KTAttribute, KTForElement, KTForProps, KTPrefixedEventAttribute, KTRawAttr, KTRawContent, KTRawContents, KTReactify, KTReactifyObject, KTReactifyProps, KTReactive, KTSurfaceRef, ReactiveChangeHandler };
+export { $modelOrRef, $setRef, Fragment, KTAsync, KTComputed, KTFor, KTReactive, KTReactiveType, KTRef, computed, h as createElement, createRedrawable, dereactive, effect, h, isComputed, isKT, isRef, jsx, jsxDEV, jsxs, ref, surfaceRef, toReactive, toRef };
+export type { EventHandler, KTAttribute, KTForElement, KTForProps, KTPrefixedEventAttribute, KTRawAttr, KTRawContent, KTRawContents, KTReactify, KTReactifyObject, KTReactifyProps, KTSurfaceRef, ReactiveChangeHandler };

package/dist/index.iife.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' });
 
     const isKT = (obj) => obj?.isKT;
     const isRef = (obj) => obj?.ktType === 1 /* KTReactiveType.REF */;
@@ -319,6 +311,14 @@ var __ktjs_core__ = (function (exports) {
          * @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;
@@ -336,9 +336,30 @@ var __ktjs_core__ = (function (exports) {
             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
@@ -388,9 +409,6 @@ var __ktjs_core__ = (function (exports) {
             return ref(o);
         }
     };
-    function deref(value) {
-        return isKT(value) ? value.value : value;
-    }
     function kcollect() {
         const newObj = {};
         const entries = $entries(this);
@@ -462,23 +480,37 @@ var __ktjs_core__ = (function (exports) {
          * @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) {
@@ -495,6 +527,18 @@ var __ktjs_core__ = (function (exports) {
         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
@@ -587,6 +631,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)) {
@@ -626,7 +676,7 @@ var __ktjs_core__ = (function (exports) {
      * ## About
      * @package @ktjs/core
      * @author Kasukabe Tsumugi <futami16237@gmail.com>
-     * @version 0.27.1 (Last Update: 2026.02.10 01:30:30.991)
+     * @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!
@@ -661,34 +711,6 @@ var __ktjs_core__ = (function (exports) {
         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
      *
@@ -710,17 +732,44 @@ var __ktjs_core__ = (function (exports) {
      */
     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();
             }
         });
@@ -1075,7 +1124,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;