@ktjs/core 0.22.5 → 0.24.0

package/dist/jsx/index.d.ts

@@ -7,13 +7,19 @@ type HTMLTag = keyof HTMLElementTagNameMap;
 type SVGTag = keyof SVGElementTagNameMap;
 type MathMLTag = keyof MathMLElementTagNameMap;
 
-type RefChangeHandler<T> = (newValue: T, oldValue: T) => void;
+declare const enum KTReactiveType {
+    REF = 1,
+    COMPUTED = 2
+}
+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
      */
@@ -23,36 +29,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.
- * - can alse be used to store normal values, but it is not reactive.
- * - 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;
-type KTSurfaceRef<T extends Object> = {
-    [K in keyof T]: KTRef<T[K]>;
-} & {
-    /**
-     * Get the dereferenced object like the original one
-     */
-    kcollect: () => T;
-};
-/**
- * Make all first-level properties of the object a `KTRef`.
- * - `obj.a.b` is not reactive
- */
-declare const surfaceRef: <T extends Object>(obj: T) => KTSurfaceRef<T>;
-/**
- * Assert k-model to be a ref object
- */
-declare const $modelOrRef: <T = any>(props: any, defaultValue?: T) => KTRef<T>;
 
 type HTML<T extends (HTMLTag | SVGTag | MathMLTag) & otherstring> = T extends SVGTag
   ? SVGElementTagNameMap[T]
@@ -87,6 +66,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;
@@ -140,11 +125,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;
 
 /**
  * Create an enhanced HTMLElement.
@@ -156,7 +141,7 @@ type KTAttribute = KTBaseAttribute & KTPrefixedEventHandlers;
  * ## 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!
@@ -207,149 +192,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
@@ -394,16 +244,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 & {
@@ -465,16 +314,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 & {
@@ -492,18 +339,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 & {};
@@ -515,53 +361,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 & {
@@ -639,30 +483,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 & {
@@ -692,16 +535,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 & {
@@ -753,25 +595,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 & {
@@ -801,10 +642,9 @@ interface AttributesMap {
   };
 
   // Style element
-  style: BaseAttr &
-    ImageElementEvents & {
-      media?: string;
-    };
+  style: BaseAttr & {
+    media?: string;
+  };
 
   // Table element
   table: BaseAttr & {};
@@ -875,20 +715,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 & {};
@@ -1423,11 +1262,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: {};
@@ -1435,5 +1294,4 @@ declare global {
   }
 }
 
-export { $modelOrRef, Fragment, KTRef, h as createElement, createRedrawable, deref, isKTRef, jsx, jsxDEV, jsxs, ref, surfaceRef };
-export type { KTSurfaceRef };
+export { Fragment, h as createElement, createRedrawable, jsx, jsxDEV, jsxs };