@ktjs/core 0.27.2 → 0.28.2

package/dist/jsx/index.d.ts

@@ -1,42 +1,56 @@
 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];
-};
-
 declare const enum KTReactiveType {
     REF = 1,
     COMPUTED = 2
 }
+
 type ReactiveChangeHandler<T> = (newValue: T, oldValue: T) => void;
 
-declare class KTRef<T> {
+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;
+}
+
+// & Shockingly, If T is boolean, KTReactify<T> becomes KTReactive<true> | KTReactive<false>. It causes @ktjs/mui that disabledRefs not assignable.
+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];
+};
+
+declare class KTRef<T> implements KTReactive<T> {
     /**
      * Indicates that this is a KTRef instance
      */
@@ -48,6 +62,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 +191,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.2 (Last Update: 2026.02.10 14:46:21.243)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -1269,7 +1296,7 @@ declare global {
       view: SVGAttributesMap['view'];
     }
 
-    type IntrinsicAttributes = {
+    interface IntrinsicAttributes {
       /**
        * Make a reference to the created element
        */
@@ -1293,7 +1320,7 @@ declare global {
        */
       'k-html'?: any;
       children?: KTRawContent;
-    };
+    }
 
     interface ElementChildrenAttribute {
       children: {};

package/dist/jsx/index.mjs

@@ -10,29 +10,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
 /**
@@ -102,9 +79,18 @@ const $applyModel = (element, valueRef, propName, eventName) => {
     valueRef.addOnChange((newValue) => (element[propName] = newValue));
     element.addEventListener(eventName, () => (valueRef.value = element[propName]));
 };
+/**
+ * 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 */;
@@ -315,6 +301,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;
@@ -332,9 +326,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
@@ -428,7 +443,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.2 (Last Update: 2026.02.10 14:46:21.243)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -463,34 +478,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
  *
@@ -512,17 +499,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();
         }
     });
@@ -537,7 +551,7 @@ function Fragment$1(props) {
 function convertChildrenToElements(children) {
     const elements = [];
     const processChild = (child) => {
-        if (child == null || child === false || child === true) {
+        if (child === undefined || child === null || child === false || child === true) {
             // Ignore null, undefined, false, true
             return;
         }

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

@@ -4,9 +4,46 @@ declare const enum KTReactiveType {
     REF = 1,
     COMPUTED = 2
 }
+
 type ReactiveChangeHandler<T> = (newValue: T, oldValue: T) => void;
 
-declare class KTRef<T> {
+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> implements KTReactive<T> {
     /**
      * Indicates that this is a KTRef instance
      */
@@ -18,6 +55,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
@@ -134,7 +184,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.2 (Last Update: 2026.02.10 14:46:21.243)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!

package/dist/jsx/jsx-runtime.mjs

@@ -10,29 +10,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
 /**
@@ -102,9 +79,18 @@ const $applyModel = (element, valueRef, propName, eventName) => {
     valueRef.addOnChange((newValue) => (element[propName] = newValue));
     element.addEventListener(eventName, () => (valueRef.value = element[propName]));
 };
+/**
+ * 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 */;
@@ -315,6 +301,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;
@@ -332,9 +326,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
@@ -428,7 +443,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.2 (Last Update: 2026.02.10 14:46:21.243)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -463,34 +478,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
  *
@@ -512,17 +499,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();
         }
     });
@@ -537,7 +551,7 @@ function Fragment$1(props) {
 function convertChildrenToElements(children) {
     const elements = [];
     const processChild = (child) => {
-        if (child == null || child === false || child === true) {
+        if (child === undefined || child === null || child === false || child === true) {
             // Ignore null, undefined, false, true
             return;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ktjs/core",
-  "version": "0.27.2",
+  "version": "0.28.2",
   "description": "Core functionality for kt.js - DOM manipulation utilities with JSX/TSX support",
   "type": "module",
   "module": "./dist/index.mjs",
@@ -44,7 +44,7 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ktjs/shared": "0.23.10"
+    "@ktjs/shared": "0.23.11"
   },
   "scripts": {
     "build": "rollup -c rollup.config.mjs",