@ktjs/core 0.22.5 → 0.24.0

package/dist/index.d.ts

@@ -9,13 +9,55 @@ type MathMLTag = keyof MathMLElementTagNameMap;
 
 type InputElementTag = 'input' | 'select' | 'textarea';
 
-type RefChangeHandler<T> = (newValue: T, oldValue: T) => void;
+declare class KTComputed<T> {
+    /**
+     * Indicates that this is a KTRef instance
+     */
+    isKT: true;
+    ktType: KTReactiveType;
+    private _subscribe;
+    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;
+}
+/**
+ * Create a reactive computed value
+ * @param computeFn
+ * @param reactives refs and computeds that this computed depends on
+ */
+declare function computed<T = JSX.Element>(computeFn: () => T, reactives: Array<KTReactive<unknown>>): KTComputed<T>;
+
+type KTReactive<T> = KTRef<T> | KTComputed<T>;
+
+declare const enum KTReactiveType {
+    REF = 1,
+    COMPUTED = 2
+}
+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 KTRef<T> {
     /**
      * Indicates that this is a KTRef instance
      */
-    isKT: boolean;
-    constructor(_value: T, _onChanges: Array<RefChangeHandler<T>>);
+    isKT: true;
+    ktType: KTReactiveType;
+    constructor(_value: T, _onChanges: Array<ReactiveChangeHandler<T>>);
     /**
      * If new value and old value are both nodes, the old one will be replaced in the DOM
      */
@@ -25,10 +67,9 @@ declare class KTRef<T> {
      * Register a callback when the value changes
      * @param callback (newValue, oldValue) => xxx
      */
-    addOnChange(callback: RefChangeHandler<T>): void;
-    removeOnChange(callback: RefChangeHandler<T>): boolean;
+    addOnChange(callback: ReactiveChangeHandler<T>): void;
+    removeOnChange(callback: ReactiveChangeHandler<T>): boolean;
 }
-declare const isKTRef: <T = any>(obj: any) => obj is KTRef<T>;
 /**
  * Reference to the created HTML element.
  * - **Only** respond to `ref.value` changes, not reactive to internal changes of the element.
@@ -36,8 +77,16 @@ declare const isKTRef: <T = any>(obj: any) => obj is KTRef<T>;
  * - if the value is already a `KTRef`, it will be returned **directly**.
  * @param value mostly an HTMLElement
  */
-declare function ref<T = JSX.Element>(value?: T | KTRef<T>, onChange?: RefChangeHandler<T>): KTRef<T>;
-declare function deref<T = JSX.Element>(value: T | KTRef<T>): T;
+declare function ref<T = JSX.Element>(value?: T, onChange?: ReactiveChangeHandler<T>): KTRef<T>;
+/**
+ * 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
+ */
+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]>;
 } & {
@@ -95,6 +144,12 @@ interface KTBaseAttribute {
    */
   'k-model'?: KTRef<any>;
 
+  /**
+   * Directly apply html string to `innerHTML`.
+   * - Would be reactive if `KTRef` instance is provided
+   */
+  'k-html'?: any;
+
   // # normal HTML attributes
   id?: string;
   class?: string;
@@ -148,11 +203,11 @@ interface KTBaseAttribute {
   method?: 'POST' | 'GET' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS' | 'CONNECT' | 'TRACE' | otherstring;
 }
 
-type KTPrefixedEventHandlers = {
+type KTPrefixedEventAttribute = {
   [EventName in keyof HTMLElementEventMap as `on:${EventName}`]?: (ev: HTMLElementEventMap[EventName]) => void;
 };
 
-type KTAttribute = KTBaseAttribute & KTPrefixedEventHandlers;
+type KTAttribute = KTBaseAttribute & KTPrefixedEventAttribute;
 
 type KTComponent = (
   props: {
@@ -172,7 +227,7 @@ type KTComponent = (
  * ## 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!
@@ -223,149 +278,14 @@ declare function createRedrawable<T>(creator: () => T): KTRef<T> & {
 };
 
 // Base events available to all HTML elements
-interface BaseAttr {
+type BaseAttr = KTPrefixedEventAttribute & {
   [k: string]: any;
 
   // # base attributes
   class?: string;
   className?: string;
   style?: string | Partial<CSSStyleDeclaration>;
-
-  // # Events
-  // Mouse events
-  'on:click'?: (ev: PointerEvent) => void;
-  'on:dblclick'?: (ev: PointerEvent) => void;
-  'on:mousedown'?: (ev: PointerEvent) => void;
-  'on:mouseup'?: (ev: MouseEvent) => void;
-  'on:mousemove'?: (ev: MouseEvent) => void;
-  'on:mouseenter'?: (ev: MouseEvent) => void;
-  'on:mouseleave'?: (ev: MouseEvent) => void;
-  'on:mouseover'?: (ev: MouseEvent) => void;
-  'on:mouseout'?: (ev: MouseEvent) => void;
-  'on:contextmenu'?: (ev: PointerEvent) => void;
-
-  // Keyboard events
-  'on:keydown'?: (ev: KeyboardEvent) => void;
-  'on:keyup'?: (ev: KeyboardEvent) => void;
-  'on:keypress'?: (ev: KeyboardEvent) => void;
-
-  // Focus events
-  'on:focus'?: (ev: FocusEvent) => void;
-  'on:blur'?: (ev: FocusEvent) => void;
-  'on:focusin'?: (ev: FocusEvent) => void;
-  'on:focusout'?: (ev: FocusEvent) => void;
-
-  // Input events
-  'on:input'?: (ev: Event) => void;
-  'on:change'?: (ev: Event) => void;
-  'on:beforeinput'?: (ev: InputEvent) => void;
-
-  // Drag events
-  'on:drag'?: (ev: DragEvent) => void;
-  'on:dragstart'?: (ev: DragEvent) => void;
-  'on:dragend'?: (ev: DragEvent) => void;
-  'on:dragenter'?: (ev: DragEvent) => void;
-  'on:dragleave'?: (ev: DragEvent) => void;
-  'on:dragover'?: (ev: DragEvent) => void;
-  'on:drop'?: (ev: DragEvent) => void;
-
-  // Clipboard events
-  'on:copy'?: (ev: ClipboardEvent) => void;
-  'on:cut'?: (ev: ClipboardEvent) => void;
-  'on:paste'?: (ev: ClipboardEvent) => void;
-
-  // Touch events
-  'on:touchstart'?: (ev: TouchEvent) => void;
-  'on:touchmove'?: (ev: TouchEvent) => void;
-  'on:touchend'?: (ev: TouchEvent) => void;
-  'on:touchcancel'?: (ev: TouchEvent) => void;
-
-  // Wheel event
-  'on:wheel'?: (ev: WheelEvent) => void;
-
-  // Animation events
-  'on:animationstart'?: (ev: AnimationEvent) => void;
-  'on:animationend'?: (ev: AnimationEvent) => void;
-  'on:animationiteration'?: (ev: AnimationEvent) => void;
-
-  // Transition events
-  'on:transitionstart'?: (ev: TransitionEvent) => void;
-  'on:transitionend'?: (ev: TransitionEvent) => void;
-  'on:transitionrun'?: (ev: TransitionEvent) => void;
-  'on:transitioncancel'?: (ev: TransitionEvent) => void;
-
-  // Pointer events
-  'on:pointerdown'?: (ev: PointerEvent) => void;
-  'on:pointerup'?: (ev: PointerEvent) => void;
-  'on:pointermove'?: (ev: PointerEvent) => void;
-  'on:pointerenter'?: (ev: PointerEvent) => void;
-  'on:pointerleave'?: (ev: PointerEvent) => void;
-  'on:pointerover'?: (ev: PointerEvent) => void;
-  'on:pointerout'?: (ev: PointerEvent) => void;
-  'on:pointercancel'?: (ev: PointerEvent) => void;
-  'on:gotpointercapture'?: (ev: PointerEvent) => void;
-  'on:lostpointercapture'?: (ev: PointerEvent) => void;
-
-  // Selection events
-  'on:select'?: (ev: Event) => void;
-  'on:selectstart'?: (ev: Event) => void;
-
-  // Scroll event
-  'on:scroll'?: (ev: Event) => void;
-
-  // Resize event
-  'on:resize'?: (ev: UIEvent) => void;
-}
-
-// Form-specific events
-interface FormElementEvents {
-  'on:submit'?: (ev: SubmitEvent) => void;
-  'on:reset'?: (ev: Event) => void;
-  'on:invalid'?: (ev: Event) => void;
-}
-
-// Media-specific events
-interface MediaElementEvents {
-  'on:play'?: (ev: Event) => void;
-  'on:pause'?: (ev: Event) => void;
-  'on:playing'?: (ev: Event) => void;
-  'on:ended'?: (ev: Event) => void;
-  'on:canplay'?: (ev: Event) => void;
-  'on:canplaythrough'?: (ev: Event) => void;
-  'on:durationchange'?: (ev: Event) => void;
-  'on:emptied'?: (ev: Event) => void;
-  'on:loadeddata'?: (ev: Event) => void;
-  'on:loadedmetadata'?: (ev: Event) => void;
-  'on:loadstart'?: (ev: Event) => void;
-  'on:progress'?: (ev: ProgressEvent) => void;
-  'on:ratechange'?: (ev: Event) => void;
-  'on:seeked'?: (ev: Event) => void;
-  'on:seeking'?: (ev: Event) => void;
-  'on:stalled'?: (ev: Event) => void;
-  'on:suspend'?: (ev: Event) => void;
-  'on:timeupdate'?: (ev: Event) => void;
-  'on:volumechange'?: (ev: Event) => void;
-  'on:waiting'?: (ev: Event) => void;
-  'on:abort'?: (ev: UIEvent) => void;
-  'on:error'?: (ev: ErrorEvent) => void;
-}
-
-// Details-specific events
-interface DetailsElementEvents {
-  'on:toggle'?: (ev: Event) => void;
-}
-
-// Dialog-specific events
-interface DialogElementEvents {
-  'on:cancel'?: (ev: Event) => void;
-  'on:close'?: (ev: Event) => void;
-}
-
-// Image-specific events
-interface ImageElementEvents {
-  'on:load'?: (ev: Event) => void;
-  'on:error'?: (ev: ErrorEvent) => void;
-}
+};
 
 interface AttributesMap {
   // Anchor element
@@ -410,16 +330,15 @@ interface AttributesMap {
   };
 
   // Audio element
-  audio: BaseAttr &
-    MediaElementEvents & {
-      autoplay?: boolean;
-      controls?: boolean;
-      crossorigin?: 'anonymous' | 'use-credentials' | '';
-      loop?: boolean;
-      muted?: boolean;
-      preload?: 'none' | 'metadata' | 'auto' | '';
-      src?: string;
-    };
+  audio: BaseAttr & {
+    autoplay?: boolean;
+    controls?: boolean;
+    crossorigin?: 'anonymous' | 'use-credentials' | '';
+    loop?: boolean;
+    muted?: boolean;
+    preload?: 'none' | 'metadata' | 'auto' | '';
+    src?: string;
+  };
 
   // Base element
   base: BaseAttr & {
@@ -481,16 +400,14 @@ interface AttributesMap {
   };
 
   // Details element
-  details: BaseAttr &
-    DetailsElementEvents & {
-      open?: boolean;
-    };
+  details: BaseAttr & {
+    open?: boolean;
+  };
 
   // Dialog element
-  dialog: BaseAttr &
-    DialogElementEvents & {
-      open?: boolean;
-    };
+  dialog: BaseAttr & {
+    open?: boolean;
+  };
 
   // Embed element
   embed: BaseAttr & {
@@ -508,18 +425,17 @@ interface AttributesMap {
   };
 
   // Form element
-  form: BaseAttr &
-    FormElementEvents & {
-      'accept-charset'?: string;
-      action?: string;
-      autocomplete?: 'on' | 'off';
-      enctype?: 'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain';
-      method?: 'POST' | 'GET' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS' | 'CONNECT' | 'TRACE' | otherstring;
-
-      name?: string;
-      novalidate?: boolean;
-      target?: '_self' | '_blank' | '_parent' | '_top' | string;
-    };
+  form: BaseAttr & {
+    'accept-charset'?: string;
+    action?: string;
+    autocomplete?: 'on' | 'off';
+    enctype?: 'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain';
+    method?: 'POST' | 'GET' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS' | 'CONNECT' | 'TRACE' | otherstring;
+
+    name?: string;
+    novalidate?: boolean;
+    target?: '_self' | '_blank' | '_parent' | '_top' | string;
+  };
 
   // Head element
   head: BaseAttr & {};
@@ -531,53 +447,51 @@ interface AttributesMap {
   html: BaseAttr & {};
 
   // IFrame element
-  iframe: BaseAttr &
-    ImageElementEvents & {
-      allow?: string;
-      allowfullscreen?: boolean;
-      allowpaymentrequest?: boolean;
-      height?: number | string;
-      loading?: 'eager' | 'lazy';
-      name?: string;
-      referrerpolicy?:
-        | 'no-referrer'
-        | 'no-referrer-when-downgrade'
-        | 'origin'
-        | 'origin-when-cross-origin'
-        | 'same-origin'
-        | 'strict-origin'
-        | 'strict-origin-when-cross-origin'
-        | 'unsafe-url';
-      sandbox?: string;
-      src?: string;
-      srcdoc?: string;
-      width?: number | string;
-    };
+  iframe: BaseAttr & {
+    allow?: string;
+    allowfullscreen?: boolean;
+    allowpaymentrequest?: boolean;
+    height?: number | string;
+    loading?: 'eager' | 'lazy';
+    name?: string;
+    referrerpolicy?:
+      | 'no-referrer'
+      | 'no-referrer-when-downgrade'
+      | 'origin'
+      | 'origin-when-cross-origin'
+      | 'same-origin'
+      | 'strict-origin'
+      | 'strict-origin-when-cross-origin'
+      | 'unsafe-url';
+    sandbox?: string;
+    src?: string;
+    srcdoc?: string;
+    width?: number | string;
+  };
 
   // Image element
-  img: BaseAttr &
-    ImageElementEvents & {
-      alt?: string;
-      crossorigin?: 'anonymous' | 'use-credentials' | '';
-      decoding?: 'sync' | 'async' | 'auto';
-      height?: number | string;
-      ismap?: boolean;
-      loading?: 'eager' | 'lazy';
-      referrerpolicy?:
-        | 'no-referrer'
-        | 'no-referrer-when-downgrade'
-        | 'origin'
-        | 'origin-when-cross-origin'
-        | 'same-origin'
-        | 'strict-origin'
-        | 'strict-origin-when-cross-origin'
-        | 'unsafe-url';
-      sizes?: string;
-      src?: string;
-      srcset?: string;
-      usemap?: string;
-      width?: number | string;
-    };
+  img: BaseAttr & {
+    alt?: string;
+    crossorigin?: 'anonymous' | 'use-credentials' | '';
+    decoding?: 'sync' | 'async' | 'auto';
+    height?: number | string;
+    ismap?: boolean;
+    loading?: 'eager' | 'lazy';
+    referrerpolicy?:
+      | 'no-referrer'
+      | 'no-referrer-when-downgrade'
+      | 'origin'
+      | 'origin-when-cross-origin'
+      | 'same-origin'
+      | 'strict-origin'
+      | 'strict-origin-when-cross-origin'
+      | 'unsafe-url';
+    sizes?: string;
+    src?: string;
+    srcset?: string;
+    usemap?: string;
+    width?: number | string;
+  };
 
   // Input element
   input: BaseAttr & {
@@ -655,30 +569,29 @@ interface AttributesMap {
   };
 
   // Link element
-  link: BaseAttr &
-    ImageElementEvents & {
-      as?: string;
-      crossorigin?: 'anonymous' | 'use-credentials' | '';
-      disabled?: boolean;
-      href?: string;
-      hreflang?: string;
-      imagesizes?: string;
-      imagesrcset?: string;
-      integrity?: string;
-      media?: string;
-      referrerpolicy?:
-        | 'no-referrer'
-        | 'no-referrer-when-downgrade'
-        | 'origin'
-        | 'origin-when-cross-origin'
-        | 'same-origin'
-        | 'strict-origin'
-        | 'strict-origin-when-cross-origin'
-        | 'unsafe-url';
-      rel?: string;
-      sizes?: string;
-      type?: string;
-    };
+  link: BaseAttr & {
+    as?: string;
+    crossorigin?: 'anonymous' | 'use-credentials' | '';
+    disabled?: boolean;
+    href?: string;
+    hreflang?: string;
+    imagesizes?: string;
+    imagesrcset?: string;
+    integrity?: string;
+    media?: string;
+    referrerpolicy?:
+      | 'no-referrer'
+      | 'no-referrer-when-downgrade'
+      | 'origin'
+      | 'origin-when-cross-origin'
+      | 'same-origin'
+      | 'strict-origin'
+      | 'strict-origin-when-cross-origin'
+      | 'unsafe-url';
+    rel?: string;
+    sizes?: string;
+    type?: string;
+  };
 
   // Map element
   map: BaseAttr & {
@@ -708,16 +621,15 @@ interface AttributesMap {
   };
 
   // Object element
-  object: BaseAttr &
-    ImageElementEvents & {
-      data?: string;
-      form?: string;
-      height?: number | string;
-      name?: string;
-      type?: string;
-      usemap?: string;
-      width?: number | string;
-    };
+  object: BaseAttr & {
+    data?: string;
+    form?: string;
+    height?: number | string;
+    name?: string;
+    type?: string;
+    usemap?: string;
+    width?: number | string;
+  };
 
   // OL element
   ol: BaseAttr & {
@@ -769,25 +681,24 @@ interface AttributesMap {
   };
 
   // Script element
-  script: BaseAttr &
-    ImageElementEvents & {
-      async?: boolean;
-      crossorigin?: 'anonymous' | 'use-credentials' | '';
-      defer?: boolean;
-      integrity?: string;
-      nomodule?: boolean;
-      referrerpolicy?:
-        | 'no-referrer'
-        | 'no-referrer-when-downgrade'
-        | 'origin'
-        | 'origin-when-cross-origin'
-        | 'same-origin'
-        | 'strict-origin'
-        | 'strict-origin-when-cross-origin'
-        | 'unsafe-url';
-      src?: string;
-      type?: string;
-    };
+  script: BaseAttr & {
+    async?: boolean;
+    crossorigin?: 'anonymous' | 'use-credentials' | '';
+    defer?: boolean;
+    integrity?: string;
+    nomodule?: boolean;
+    referrerpolicy?:
+      | 'no-referrer'
+      | 'no-referrer-when-downgrade'
+      | 'origin'
+      | 'origin-when-cross-origin'
+      | 'same-origin'
+      | 'strict-origin'
+      | 'strict-origin-when-cross-origin'
+      | 'unsafe-url';
+    src?: string;
+    type?: string;
+  };
 
   // Select element
   select: BaseAttr & {
@@ -817,10 +728,9 @@ interface AttributesMap {
   };
 
   // Style element
-  style: BaseAttr &
-    ImageElementEvents & {
-      media?: string;
-    };
+  style: BaseAttr & {
+    media?: string;
+  };
 
   // Table element
   table: BaseAttr & {};
@@ -891,20 +801,19 @@ interface AttributesMap {
   ul: BaseAttr & {};
 
   // Video element
-  video: BaseAttr &
-    MediaElementEvents & {
-      autoplay?: boolean;
-      controls?: boolean;
-      crossorigin?: 'anonymous' | 'use-credentials' | '';
-      height?: number | string;
-      loop?: boolean;
-      muted?: boolean;
-      playsinline?: boolean;
-      poster?: string;
-      preload?: 'none' | 'metadata' | 'auto' | '';
-      src?: string;
-      width?: number | string;
-    };
+  video: BaseAttr & {
+    autoplay?: boolean;
+    controls?: boolean;
+    crossorigin?: 'anonymous' | 'use-credentials' | '';
+    height?: number | string;
+    loop?: boolean;
+    muted?: boolean;
+    playsinline?: boolean;
+    poster?: string;
+    preload?: 'none' | 'metadata' | 'auto' | '';
+    src?: string;
+    width?: number | string;
+  };
 
   // Generic HTMLElement (no specific attributes beyond BaseEvent)
   abbr: BaseAttr & {};
@@ -1439,11 +1348,31 @@ declare global {
       // 'svg:view': SVGAttributesMap['view'];
     }
 
-    interface IntrinsicAttributes {
+    type IntrinsicAttributes = KTPrefixedEventAttribute & {
+      /**
+       * Make a reference to the created element
+       */
       ref?: KTRef<any>;
+
+      /**
+       * Conditional rendering
+       * - Provide a `KTRef` to make it reactive
+       */
       'k-if'?: any;
+
+      /**
+       * 2-way binding
+       * - Provide a `KTRef` to make it reactive
+       */
+      'k-model'?: KTRef<any>;
+
+      /**
+       * Raw html binding
+       * - Provide a `KTRef` to make it reactive
+       */
+      'k-html'?: any;
       children?: KTRawContent;
-    }
+    };
 
     interface ElementChildrenAttribute {
       children: {};
@@ -1477,5 +1406,5 @@ interface KTForProps<T> {
  */
 declare function KTFor<T>(props: KTForProps<T>): KTForElement;
 
-export { $modelOrRef, Fragment, KTAsync, KTFor, KTRef, h as createElement, createRedrawable, deref, h, isKTRef, jsx, jsxDEV, jsxs, ref, surfaceRef };
-export type { EventHandler, HTMLTag, InputElementTag, KTAttribute, KTForElement, KTForProps, KTRawAttr, KTRawContent, KTRawContents, KTSurfaceRef, MathMLTag, SVGTag };
+export { $modelOrRef, Fragment, KTAsync, KTComputed, KTFor, KTReactiveType, KTRef, computed, h as createElement, createRedrawable, deref, h, isComputed, isKT, isRef, jsx, jsxDEV, jsxs, ref, surfaceRef, toRef };
+export type { EventHandler, HTMLTag, InputElementTag, KTAttribute, KTForElement, KTForProps, KTPrefixedEventAttribute, KTRawAttr, KTRawContent, KTRawContents, KTReactive, KTSurfaceRef, MathMLTag, ReactiveChangeHandler, SVGTag };