@ktjs/core 0.32.5 → 0.33.0

package/README.md

@@ -12,11 +12,14 @@
 
 <p align="center"><strong>Visit KT.js: <a href="https://baendlorel.github.io/kt.js/">https://baendlorel.github.io/kt.js/</a></strong></p>
 
+> kt.js is still under development, so there might be some breaking changes. Note the Update Log below
+
 ## Recent Updates
 
-1. Special refs for `Array`, `Set`, `Map`, `WeakMap`, `WeakSet`, `Date` to better track mutations.
-   - e.g. `const a = ref.array([1, 2])`, then we can call `a.push(3)` to make a reactive change instead of `a.value.push(3)`.
-2. Fixed issues of `svg` and `mathml` elements.
+1. `ref.value` remains the standard read API, and it can also replace the whole outer value with `ref.value = nextValue`.
+2. `ref.draft` is the deep-mutation entry for nested objects, arrays, `Map` / `Set`, and custom mutable objects.
+3. `ref.draft` itself is not assignable; mutate nested fields or call mutating methods on the returned object instead.
+4. `addOnChange((newValue, oldValue) => ...)` keeps `oldValue` as the previous reference, not a deep snapshot.
 
 ## Community
 
@@ -29,6 +32,35 @@ kt.js is a simple framework with a tiny runtime that renders real DOM directly (
 
 KT.js focuses on one principle: keep direct control of the DOM and avoid unnecessary repainting.
 
+## Reactive Contract
+
+```ts
+const user = ref({ profile: { name: 'John' }, tags: ['new'] });
+
+console.log(user.value.profile.name); // read
+
+user.value = {
+  ...user.value,
+  profile: { ...user.value.profile, name: 'Jane' },
+  tags: [...user.value.tags],
+}; // replace the whole outer value
+
+user.draft.profile.name = 'Jane'; // deep write
+user.draft.tags.push('active'); // array / map / set / custom-object style mutation
+```
+
+Rules:
+
+- Read with `.value`.
+- Replace the whole outer value with `.value = nextValue`.
+- Use `.draft` for deep mutations on nested objects, arrays, `Map` / `Set`, or other mutable instances.
+- Do not assign to `.draft` itself; mutate inside it.
+- `computed` stays read-only and is consumed through `.value`.
+- `oldValue` in change listeners is the previous reference only, not a deep-cloned snapshot.
+- Correctness is expected to come from the transformer and TypeScript checks; runtime hot paths stay minimal on purpose.
+
+This is an explicit contract, closer to a Rust-style model than permissive runtime magic: unclear code should fail early.
+
 ## Quick Start
 
 ```bash

package/dist/index.d.ts

@@ -1,6 +1,75 @@
 import { otherstring, HTMLTag, SVGTag, MathMLTag, JSXTag } from '@ktjs/shared';
 export { HTMLTag, InputElementTag, MathMLTag, SVGTag } from '@ktjs/shared';
 
+interface KTEffectOptions {
+    lazy: boolean;
+    onCleanup: () => void;
+    debugName: string;
+}
+/**
+ * Register a reactive effect with options.
+ * @param effectFn The effect function to run when dependencies change
+ * @param reactives The reactive dependencies
+ * @param options Effect options: lazy, onCleanup, debugName
+ * @returns stop function to remove all listeners
+ */
+declare function effect(effectFn: () => void, reactives: Array<KTReactive<any>>, options?: Partial<KTEffectOptions>): () => void;
+
+/**
+ *
+ * @param value
+ * @returns
+ */
+declare const toReactive: <T>(value: T | KTReactive<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;
+
+declare const enum KTReactiveType {
+    Reative = 1,
+    Computed = 2,
+    Ref = 3
+}
+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>;
+
+declare class KTRef<T> extends KTReactive<T> {
+    readonly ktType = KTReactiveType.Ref;
+    get value(): T;
+    set value(newValue: T);
+    get draft(): T;
+    /**
+     * Force all listeners to run even when reference identity has not changed.
+     */
+    notify(oldValue?: T, newValue?: T, handlerKeys?: ChangeHandlerKey[]): this;
+}
+/**
+ * Create a `KTRef` object.
+ * - use `refObject.state` to get plain data
+ * - use `refObject.map(calculator)` to create a computed value based on this ref
+ * - use `refObject.mutable` to set too, but it will recalculate in the next microtask. Useful for deep objects, `Map`, `Set` or other custom objects
+ *
+ * @param value any data
+ * @param onChange event handler triggered when the value changes, with signature `(newValue, oldValue) => void`
+ * @returns
+ */
+declare const ref: <T = JSX.Element>(value?: T) => KTRef<T>;
+/**
+ * Assert k-model to be a ref object
+ */
+declare const $modelOrRef: <T = any>(props: any, defaultValue?: T) => KTRef<T>;
+type RefSetter<T> = (props: {
+    ref?: KTRef<T>;
+}, node: T) => void;
+/**
+ * Whether `props.ref` is a `KTRef` only needs to be checked in the initial render
+ */
+declare const $initRef: <T extends Node>(props: {
+    ref?: KTRef<T>;
+}, node: T) => RefSetter<T>;
+
 // Base events available to all HTML elements
 type BaseAttr = KTPrefixedEventAttribute & {
   [k: string]: KTMaybeReactive<any>;
@@ -914,8 +983,9 @@ interface SVGAttributesMap {
   view: AttributesMap['svg'] & KTMaybeReactiveProps<{ viewBox?: string; preserveAspectRatio?: string }>;
 }
 
+type AliasElement = Element;
 declare namespace JSX {
-  type Element = HTMLElementTagNameMap[keyof HTMLElementTagNameMap];
+  type Element = AliasElement;
 
   interface IntrinsicElements {
     [k: string]: AttributesMap['div']; // Allow any element with div attributes as fallback
@@ -1136,359 +1206,84 @@ declare namespace JSX {
   }
 }
 
-declare class KTArrayRef<T> extends KTRef<T[]> {
-    constructor(value: T[], onChange?: ReactiveChangeHandler<T[]>);
-    get length(): number;
-    set length(newLength: number);
-    push(...items: T[]): number;
-    /**
-     * Same as `Array.prototype.pop`, but emits change after calling it
-     */
-    pop(): T | undefined;
-    /**
-     * Same as `Array.prototype.shift`, but emits change after calling it
-     */
-    shift(): T | undefined;
-    /**
-     * Same as `Array.prototype.unshift`, but emits change after calling it
-     */
-    unshift(...items: T[]): number;
-    /**
-     * Same as `Array.prototype.splice`, but emits change after calling it
-     */
-    splice(start: number, deleteCount?: number): T[];
-    splice(start: number, deleteCount: number, ...items: T[]): T[];
-    /**
-     * Same as `Array.prototype.sort`, but emits change after calling it
-     */
-    sort(compareFn?: (a: T, b: T) => number): this;
-    /**
-     * Same as `Array.prototype.reverse`, but emits change after calling it
-     */
-    reverse(): this;
+declare class KTComputed<T> extends KTReactive<T> {
+    readonly ktType = KTReactiveType.Computed;
+    constructor(_calculator: () => T, dependencies: Array<KTReactive<unknown>>);
     /**
-     * Same as `Array.prototype.fill`, but emits change after calling it
+     * If new value and old value are both nodes, the old one will be replaced in the DOM
      */
-    fill(value: T, start?: number, end?: number): this;
+    get value(): T;
+    set value(_newValue: T);
     /**
-     * Same as `Array.prototype.copyWithin`, but emits change after calling it
+     * Force listeners to run once with the latest computed result.
      */
-    copyWithin(target: number, start: number, end?: number): this;
-}
-declare const arrayRef: (value: unknown, onChange?: ReactiveChangeHandler<any>) => KTArrayRef<any>;
-
-declare class KTDateRef extends KTRef<Date> {
-    constructor(value: Date, onChange?: ReactiveChangeHandler<Date>);
-    setTime(timeValue: number): number;
-    setMilliseconds(millisecondsValue: number): number;
-    setUTCMilliseconds(millisecondsValue: number): number;
-    setSeconds(secondsValue: number, millisecondsValue?: number): number;
-    setUTCSeconds(secondsValue: number, millisecondsValue?: number): number;
-    setMinutes(minutesValue: number, secondsValue?: number, millisecondsValue?: number): number;
-    setUTCMinutes(minutesValue: number, secondsValue?: number, millisecondsValue?: number): number;
-    setHours(hoursValue: number, minutesValue?: number, secondsValue?: number, millisecondsValue?: number): number;
-    setUTCHours(hoursValue: number, minutesValue?: number, secondsValue?: number, millisecondsValue?: number): number;
-    setDate(dateValue: number): number;
-    setUTCDate(dateValue: number): number;
-    setMonth(monthValue: number, dateValue?: number): number;
-    setUTCMonth(monthValue: number, dateValue?: number): number;
-    setFullYear(yearValue: number, monthValue?: number, dateValue?: number): number;
-    setUTCFullYear(yearValue: number, monthValue?: number, dateValue?: number): number;
-}
-declare const dateRef: (value: unknown, onChange?: ReactiveChangeHandler<any>) => KTDateRef;
-
-declare class KTMapRef<K, V> extends KTRef<Map<K, V>> {
-    constructor(value: Map<K, V>, onChange?: ReactiveChangeHandler<Map<K, V>>);
-    get size(): number;
-    has(key: K): boolean;
-    get(key: K): V | undefined;
-    set(key: K, value: V): this;
-    delete(key: K): boolean;
-    clear(): any;
-}
-declare const mapRef: (value: unknown, onChange?: ReactiveChangeHandler<any>) => KTMapRef<unknown, unknown>;
-
-declare class KTSetRef<T> extends KTRef<Set<T>> {
-    constructor(value: Set<T>, onChange?: ReactiveChangeHandler<Set<T>>);
-    get size(): number;
-    has(value: T): boolean;
-    add(value: T): this;
-    delete(value: T): boolean;
-    clear(): any;
-}
-declare const setRef: (value: unknown, onChange?: ReactiveChangeHandler<any>) => KTSetRef<unknown>;
-
-declare class KTWeakMapRef<K extends WeakKey = WeakKey, V = any> extends KTRef<WeakMap<K, V>> {
-    constructor(value: WeakMap<K, V>, onChange?: ReactiveChangeHandler<WeakMap<K, V>>);
-    has(key: K): boolean;
-    get(key: K): V | undefined;
-    set(key: K, value: V): this;
-    delete(key: K): boolean;
-}
-declare const weakMapRef: (value: unknown, onChange?: ReactiveChangeHandler<any>) => KTWeakMapRef<WeakKey, any>;
-
-declare class KTWeakSetRef<T extends WeakKey = WeakKey> extends KTRef<WeakSet<T>> {
-    constructor(value: WeakSet<T>, onChange?: ReactiveChangeHandler<WeakSet<T>>);
-    has(value: T): boolean;
-    add(value: T): this;
-    delete(value: T): boolean;
-}
-declare const weakSetRef: (value: unknown, onChange?: ReactiveChangeHandler<any>) => KTWeakSetRef<WeakKey>;
-
-type KTIsExactlyBoolean<T> = [T] extends [boolean] ? ([boolean] extends [T] ? true : false) : false;
-
-type KTAutoRef<T> =
-  KTIsExactlyBoolean<T> extends true
-    ? KTRef<boolean>
-    : T extends Array<infer A>
-      ? KTArrayRef<A>
-      : T extends Map<infer K, infer V>
-        ? KTMapRef<K, V>
-        : T extends Set<infer U>
-          ? KTSetRef<U>
-          : T extends Date
-            ? KTDateRef
-            : T extends WeakSet<infer U>
-              ? KTWeakSetRef<U>
-              : T extends WeakMap<infer K, infer V>
-                ? KTWeakMapRef<K, V>
-                : KTRef<T>;
-
-/**
- * Reference to the created HTML element or other reactive data.
- * - **Only** respond to `ref.value` changes, not reactive to internal changes of the element.
- * - Automatically wrap the value with corresponding ref type based on its type.
- *   - When wrapped, setter-like methods will be reactive. like `push` for `Array`, `set` for `Map`, `add` for `Set`, etc.
- *   - Supports: `Array`, `Map`, `Set`, `WeakMap`, `WeakSet`, `Date`.
- *   - Since there will be some cost for runtime detection, and compilation plugin might not be able to analyze all cases. It is recommended to use specific ref type directly if you already know the type of value, like `ref.array`, `ref.map`, etc.
- * @param value any data
- * @param onChange event handler triggered when the value changes, with signature `(newValue, oldValue) => void`
- */
-declare function autoRef<T>(value?: T, onChange?: ReactiveChangeHandler<T>): KTAutoRef<T>;
-type RefCreator = (<T = JSX.Element>(value?: T, onChange?: ReactiveChangeHandler<T>) => KTRef<T>) & {
-    array: typeof arrayRef;
-    date: typeof dateRef;
-    map: typeof mapRef;
-    set: typeof setRef;
-    weakMap: typeof weakMapRef;
-    weakSet: typeof weakSetRef;
-};
-/**
- * Create a plain `KTRef` object.
- *
- * If you want the value to be automatically wrapped with corresponding ref type based on its type, please use `autoRef` instead.
- *
- * @param value any data
- * @param onChange event handler triggered when the value changes, with signature `(newValue, oldValue) => void`
- * @returns
- */
-declare const ref: RefCreator;
-
-/**
- * Assert k-model to be a ref object
- */
-declare const $modelOrRef: <T = any>(props: any, defaultValue?: T) => KTRef<T>;
-type RefSetter<T> = (props: {
-    ref?: KTRef<T>;
-}, node: T) => void;
-/**
- * Whether `props.ref` is a `KTRef` only needs to be checked in the initial render
- */
-declare const $initRef: <T extends Node>(props: {
-    ref?: KTRef<T>;
-}, node: T) => RefSetter<T>;
-
-interface KTEffectOptions {
-    lazy: boolean;
-    onCleanup: () => void;
-    debugName: string;
+    notify(handlerKeys?: ChangeHandlerKey[]): this;
 }
 /**
- * Register a reactive effect with options.
- * @param effectFn The effect function to run when dependencies change
- * @param reactives The reactive dependencies
- * @param options Effect options: lazy, onCleanup, debugName
- * @returns stop function to remove all listeners
- */
-declare function effect(effectFn: () => void, reactives: Array<KTReactive<any>>, options?: Partial<KTEffectOptions>): () => void;
-
-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.
+ * Create a reactive computed value
+ * @param computeFn
+ * @param dependencies refs and computeds that this computed depends on
  */
-declare function dereactive<T = JSX.Element>(value: T | KTReactive<T>): T;
-
-declare const enum KTReactiveType {
-    Computed = 1,
-    Ref = 2,
-    ObjectRef = 3,
-    ArrayRef = 4,
-    MapRef = 5,
-    SetRef = 6,
-    WeakMapRef = 7,
-    WeakSetRef = 8,
-    DateRef = 9
-}
-declare const isKT: <T = any>(obj: any) => obj is KTReactive<T>;
-declare const isRef: <T = any>(obj: any) => obj is KTRef<T>;
-declare const isArrayRef: <T = any>(obj: any) => obj is KTRef<T[]>;
-declare const isMapRef: <K = any, V = any>(obj: any) => obj is KTRef<Map<K, V>>;
-declare const isSetRef: <T = any>(obj: any) => obj is KTRef<Set<T>>;
-declare const isWeakMapRef: <K extends WeakKey = WeakKey, V = any>(obj: any) => obj is KTRef<WeakMap<K, V>>;
-declare const isWeakSetRef: <T extends WeakKey = WeakKey>(obj: any) => obj is KTRef<WeakSet<T>>;
-declare const isDateRef: (obj: any) => obj is KTRef<Date>;
-declare const isComputed: <T = any>(obj: any) => obj is KTComputed<T>;
+declare function computed<T = JSX.Element>(computeFn: () => T, dependencies: Array<KTReactive<any>>): KTComputed<T>;
 
-declare class KTComputed<T> implements KTReactive<T> {
+type ChangeHandler<T> = (newValue: T, oldValue: T) => void;
+type ChangeHandlerKey = string | number;
+declare class KTReactive<T> {
     /**
      * Indicates that this is a KTRef instance
      */
-    isKT: true;
-    ktType: KTReactiveType;
-    constructor(_calculator: () => T, reactives: Array<KTReactive<unknown>>);
+    readonly isKT: true;
+    readonly ktType: KTReactiveType;
+    constructor(_value: T);
     /**
      * If new value and old value are both nodes, the old one will be replaced in the DOM
+     * - Use `.mutable` to modify the value.
+     * @readonly
      */
     get value(): T;
     set value(_newValue: T);
     /**
-     * Force listeners to run once with the latest computed result.
+     * Force all listeners to run even when reference identity has not changed.
+     * Useful for in-place array/object mutations.
+     * - Is implemented differently in `KTRef` and `KTComputed`
      */
-    notify(handlerKeys?: ReactiveChangeKey[]): void;
+    notify(..._args: unknown[]): this;
     /**
-     * Computed values are derived from dependencies and should not be mutated manually.
+     * Ccreate a computed value based on this `KTReactive` instance.
+     * @param calculator A function that calculates the computed value based on the current value of this `KTReactive` instance.
+     * @param dependencies Optional additional dependencies that the computed value relies on.
+     * @returns A `KTComputed` instance
+     *
+     * @see ./computed.ts implemented in `KTComputed`
      */
-    mutate<R = void>(_mutator?: (currentValue: T) => R, handlerKeys?: ReactiveChangeKey[]): R;
-    toComputed<R>(calculator: (currentValue: T) => R, dependencies?: KTReactive<any>[]): KTComputed<R>;
+    map<R>(calculator: (currentValue: T) => R, dependencies?: Array<KTReactive<any>>): KTComputed<R>;
     /**
      * Register a callback when the value changes
-     * @param callback (newValue, oldValue) => xxx
-     */
-    addOnChange<K extends ReactiveChangeKey | undefined>(callback: ReactiveChangeHandler<T>, key?: K): K extends undefined ? number : K;
-    /**
-     * Unregister a callback
-     * @param key registered listener key
+     * @param callback newValue and oldValue are references. You can use `a.draft` to make in-place mutations since `a.value` will not trigger `onChange` handers.
+     * @param key Optional key to identify the callback, allowing multiple listeners on the same ref and individual removal. If not provided, a unique ID will be generated.
      */
-    removeOnChange(key: ReactiveChangeKey): ReactiveChangeHandler<any> | undefined;
+    addOnChange(callback: ChangeHandler<T>, key?: ChangeHandlerKey): this;
+    removeOnChange(key: ChangeHandlerKey): ChangeHandler<any> | undefined;
 }
-/**
- * Create a reactive computed value
- * @param computeFn
- * @param dependencies refs and computeds that this computed depends on
- */
-declare function computed<T = JSX.Element>(computeFn: () => T, dependencies: Array<KTReactive<any>>): KTComputed<T>;
-
-type ReactiveChangeHandler<T> = (newValue: T, oldValue: T) => void;
-type ReactiveChangeKey = string | number;
-
-interface 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(handlerKeys?: ReactiveChangeKey[]): 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, handlerKeys?: ReactiveChangeKey[]): R;
-
-  /**
-   * Ccreate a computed value based on this `KTReactive` instance.
-   * @param calculator A function that calculates the computed value based on the current value of this `KTReactive` instance.
-   * @param dependencies Optional additional dependencies that the computed value relies on.
-   * @returns A `KTComputed` instance
-   */
-  toComputed<R>(calculator: (currentValue: T) => R, dependencies?: KTReactive<any>[]): KTComputed<R>;
-
-  /**
-   * Register a callback when the value changes
-   * - Value setter will check `Object.is(newValue, oldValue)`.
-   * @param callback (newValue, oldValue) => xxx
-   * @param key Optional key to identify this change handler. If not provided, a numeric id will be generated and returned.
-   */
-  addOnChange<K extends ReactiveChangeKey | undefined>(
-    callback: ReactiveChangeHandler<T>,
-    key?: K,
-  ): K extends undefined ? number : K;
-  removeOnChange(key: ReactiveChangeKey): ReactiveChangeHandler<any> | undefined;
-}
-
-// & Shockingly, If T is boolean, KTReactify<T> becomes KTReactive<true> | KTReactive<false>. It causes @ktjs/mui that disabledRefs not assignable.
 /**
  * Makes `KTReactify<'a' | 'b'> to be KTReactive<'a'> | KTReactive<'b'>`
  */
 type KTReactifySplit<T> = T extends boolean ? KTReactive<boolean> : T extends any ? KTReactive<T> : never;
-
 type KTReactifyObject<T extends object> = {
-  [K in keyof T]: KTReactifySplit<T[K]>;
+    [K in keyof T]: KTReactifySplit<T[K]>;
 };
-
 type KTReactifyProps<T extends object> = {
-  [K in keyof T]: KTReactifySplit<Exclude<T[K], undefined>> | T[K];
+    [K in keyof T]: KTReactifySplit<Exclude<T[K], undefined>> | T[K];
 };
-
 /**
  * Makes `KTReactify<'a' | 'b'>` to be `KTReactive<'a' | 'b'>`
  */
 type KTReactify<T> = [T] extends [KTReactive<infer U>] ? KTReactive<U> : KTReactive<T>;
 type KTMaybeReactive<T> = T | KTReactify<T>;
 type KTMaybeReactiveProps<T extends object> = {
-  [K in keyof T]: K extends `on:${string}` ? T[K] : KTMaybeReactive<Exclude<T[K], undefined>> | T[K];
+    [K in keyof T]: K extends `on:${string}` ? T[K] : KTMaybeReactive<Exclude<T[K], undefined>> | T[K];
 };
 
-declare class KTRef<T> implements KTReactive<T> {
-    /**
-     * Indicates that this is a KTRef instance
-     */
-    isKT: true;
-    ktType: KTReactiveType;
-    constructor(_value: T, _onChange?: ReactiveChangeHandler<T>);
-    /**
-     * 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);
-    /**
-     * Force all listeners to run even when reference identity has not changed.
-     * Useful for in-place array/object mutations.
-     */
-    notify(handlerKeys?: ReactiveChangeKey[]): 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, handlerKeys?: ReactiveChangeKey[]): R;
-    toComputed<R>(calculator: (currentValue: T) => R, dependencies?: KTReactive<any>[]): KTComputed<R>;
-    /**
-     * Register a callback when the value changes
-     * @param callback (newValue, oldValue) => xxx
-     * @param key Optional key to identify the callback, allowing multiple listeners on the same ref and individual removal. If not provided, a unique ID will be generated.
-     */
-    addOnChange<K extends ReactiveChangeKey | undefined>(callback: ReactiveChangeHandler<T>, key?: K): K extends undefined ? number : K;
-    removeOnChange(key: ReactiveChangeKey): ReactiveChangeHandler<any> | undefined;
-}
-
 type HTML<T extends (HTMLTag | SVGTag | MathMLTag) & otherstring> = T extends SVGTag
   ? SVGElementTagNameMap[T]
   : T extends HTMLTag
@@ -1653,7 +1448,7 @@ interface KTForProps<T> {
     ref?: KTRef<KTForElement>;
     list: T[] | KTReactive<T[]>;
     key?: (item: T, index: number, array: T[]) => any;
-    map?: (item: T, index: number, array: T[]) => HTMLElement;
+    map?: (item: T, index: number, array: T[]) => JSX.Element;
 }
 /**
  * KTFor - List rendering component with key-based optimization
@@ -1661,7 +1456,7 @@ interface KTForProps<T> {
  */
 declare function KTFor<T>(props: KTForProps<T>): KTForElement;
 
-declare function KTConditional(condition: any | KTReactive<any>, tagIf: JSXTag, propsIf: KTAttribute, tagElse?: JSXTag, propsElse?: KTAttribute): JSX.Element;
+declare function KTConditional(condition: any | KTReactive<any>, tagIf: JSXTag, propsIf: KTAttribute, tagElse?: JSXTag, propsElse?: KTAttribute): Element;
 
-export { $initRef, $modelOrRef, Fragment, JSX, KTArrayRef, KTAsync, KTComputed, KTConditional, KTDateRef, KTFor, KTMapRef, KTReactiveType, KTSetRef, KTWeakMapRef, KTWeakSetRef, applyAttr, autoRef, computed, h as createElement, mathml$1 as createMathMLElement, svg$1 as createSVGElement, dereactive, effect, h, isArrayRef, isComputed, isDateRef, isKT, isMapRef, isRef, isSetRef, isWeakMapRef, isWeakSetRef, jsx, jsxDEV, jsxs, mathml, mathml as mathmlRuntime, ref, svg, svg as svgRuntime, toReactive };
-export type { EventHandler, HTML, KTAttribute, KTForElement, KTForProps, KTMaybeReactive, KTMaybeReactiveProps, KTPrefixedEventAttribute, KTRawAttr, KTRawContent, KTRawContents, KTReactify, KTReactifyObject, KTReactifyProps, KTReactifySplit, KTReactive, ReactiveChangeHandler, ReactiveChangeKey };
+export { $initRef, $modelOrRef, Fragment, JSX, KTAsync, KTComputed, KTConditional, KTFor, KTReactive, KTReactiveType, KTRef, applyAttr, computed, h as createElement, mathml$1 as createMathMLElement, svg$1 as createSVGElement, dereactive, effect, h, isComputed, isKT, isRef, jsx, jsxDEV, jsxs, mathml, mathml as mathmlRuntime, ref, svg, svg as svgRuntime, toReactive };
+export type { AliasElement, ChangeHandler, ChangeHandlerKey, EventHandler, HTML, KTAttribute, KTForElement, KTForProps, KTMaybeReactive, KTMaybeReactiveProps, KTPrefixedEventAttribute, KTRawAttr, KTRawContent, KTRawContents, KTReactify, KTReactifyObject, KTReactifyProps, KTReactifySplit };