@ktjs/core 0.12.0 → 0.13.2

package/README.md

@@ -2,26 +2,39 @@
 
 <img src="https://raw.githubusercontent.com/baendlorel/kt.js/dev/.assets/ktjs-0.0.1.svg" alt="KT.js Logo" width="150"/>
 
-> 📦 Part of [KT.js](https://raw.githubusercontent.com/baendlorel/kt.js/dev/README.md) - A simple and easy-to-use web framework that never re-renders.
+[![npm version](https://img.shields.io/npm/v/@ktjs/core.svg)](https://www.npmjs.com/package/@ktjs/core)
 
-Core DOM manipulation utilities for KT.js framework.
+> 📦 Part of [KT.js](https://github.com/baendlorel/kt.js) - A simple and easy-to-use web framework that never re-renders.
+
+Core DOM manipulation utilities for KT.js framework with built-in JSX/TSX support.
 
 ## Overview
 
 `@ktjs/core` is the foundation of KT.js, providing the essential `h` function and DOM utilities for building web applications with direct DOM manipulation. It emphasizes performance, type safety, and minimal abstraction over native DOM APIs.
 
+**Current Version:** 0.13.0
+
 ## Features
 
 - **`h` Function**: Create HTMLElements with a simple, flexible API
   - Support for attributes, content, and event handlers
-  - Special `@<eventName>` syntax for event handlers
+  - `on:<eventName>` syntax for event handlers (e.g., `on:click`)
   - Function attributes automatically treated as event listeners
   - Full TypeScript support with intelligent type inference
+- **JSX/TSX Support**: Built-in JSX runtime (no separate package needed)
+  - Zero virtual DOM - JSX compiles directly to `h()` function calls
+  - Full HTML element type inference (`<button>` returns `HTMLButtonElement`)
+  - Support for function components
+  - **NEW**: `redraw()` method for controlled re-rendering
 - **KTAsync Component**: Handle async components with ease
   - Automatic handling of Promise-based components
   - Seamless integration with JSX/TSX
   - Fallback placeholder during async loading
   - Type-safe async component support
+- **Redraw Mechanism**: Fine-grained control over component updates
+  - Update props and children selectively
+  - Efficient replacement strategy
+  - Works with both native elements and function components
 - **DOM Utilities**: Helper functions for common DOM operations
   - Native method caching for performance
   - Symbol-based private properties for internal state
@@ -68,20 +81,20 @@ const card = h('div', { class: 'card' }, [
 ```typescript
 import { h } from '@ktjs/core';
 
-// Function attribute (treated as event listener)
+// on: prefixed attribute (event handler)
 const button1 = h(
   'button',
   {
-    click: () => alert('Clicked!'),
+    'on:click': () => alert('Clicked!'),
   },
   'Button 1'
 );
 
-// @-prefixed attribute (explicitly an event handler)
+// Function attribute (also treated as event listener)
 const button2 = h(
   'button',
   {
-    '@click': (e) => console.log('Event:', e),
+    click: (e) => console.log('Event:', e),
     'data-id': '123', // Regular attribute
   },
   'Button 2'
@@ -89,18 +102,75 @@ const button2 = h(
 
 // Both regular and event handler for same name
 const input = h('input', {
-  change: 'change-value', // Regular attribute
-  '@change': (e) => console.log('Changed'), // Event listener
+  value: 'initial', // Regular attribute
+  'on:change': (e) => console.log('Changed'), // Event listener
 });
 ```
 
+### JSX/TSX Support
+
+```tsx
+import { h } from '@ktjs/core';
+
+// Configure tsconfig.json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "@ktjs/core"
+  }
+}
+
+// Use JSX syntax
+const App = () => (
+  <div class="app">
+    <h1>Hello KT.js</h1>
+    <button on:click={() => alert('Hi')}>Click me</button>
+  </div>
+);
+
+// Function components
+const Greeting = ({ name }: { name: string }) => (
+  <div class="greeting">Hello, {name}!</div>
+);
+
+const app = <Greeting name="World" />;
+```
+
+### Redraw Mechanism (v0.11+)
+
+The new `redraw()` method allows you to update components efficiently:
+
+```tsx
+import { h, KTHTMLElement } from '@ktjs/core';
+
+// With JSX - get element with redraw method
+const counter = (<button on:click={() => counter.redraw({ count: count + 1 })}>Count: {0}</button>) as KTHTMLElement;
+
+// Function component with redraw
+const Counter = ({ count = 0 }: { count?: number }) => (
+  <div>
+    <div>Count: {count}</div>
+    <button on:click={() => element.redraw({ count: count + 1 })}>Increment</button>
+  </div>
+);
+
+const element = (<Counter />) as KTHTMLElement;
+
+// Update props manually
+element.redraw({ count: 10 });
+
+// Update children (for native elements)
+const div = (<div>Old content</div>) as KTHTMLElement;
+div.redraw(undefined, 'New content');
+```
+
 ### Async Components
 
 ```typescript
-import { KTAsync } from '@ktjs/core';
+import { KTAsync, h } from '@ktjs/core';
 
 // Define an async component that returns a Promise
-const AsyncComponent = function () {
+const AsyncComponent = () => {
   return new Promise<HTMLElement>((resolve) => {
     setTimeout(() => {
       const element = h('div', { class: 'loaded' }, 'Content loaded!');
@@ -122,11 +192,21 @@ const App = () => (
     <KTAsync component={AsyncComponent} />
   </div>
 );
+
+// With custom placeholder
+const AppWithSkeleton = () => (
+  <div>
+    <KTAsync
+      component={AsyncComponent}
+      skeleton={<div class="skeleton">Loading...</div>}
+    />
+  </div>
+);
 ```
 
 **How it works:**
 
-- `KTAsync` creates a placeholder comment node immediately
+- `KTAsync` creates a placeholder (comment node or custom skeleton) immediately
 - When the Promise resolves, it automatically replaces the placeholder with the actual element
 - If the component returns a non-Promise value, it's used directly
 - No manual DOM manipulation needed - just return a Promise from your component

package/dist/index.d.ts

@@ -1,14 +1,3 @@
-interface KTRuntime {
-    throws: (message: string) => never;
-    defines: <T>(o: T, properties: PropertyDescriptorMap & ThisType<any>) => T;
-    mark: (func: (...args: any[]) => any, tag: string) => void;
-}
-declare global {
-    interface Window {
-        readonly __ktjs__: KTRuntime;
-    }
-}
-
 type otherstring = string & {};
 
 /**
@@ -27,6 +16,33 @@ interface KTRef<T> {
  */
 declare function ref<T = HTMLElement>(value?: T): KTRef<T>;
 
+type KTHTMLElement = HTMLElement & {
+  /**
+   * Automically generate a redraw function if it is not provided
+   * @param props
+   */
+  redraw: (props?: KTAttribute, children?: KTRawContent) => void;
+};
+
+declare global {
+  namespace JSX {
+    type Element = KTHTMLElement;
+
+    interface IntrinsicElements {
+      [tag: string]: KTAttribute & { children?: KTRawContent };
+    }
+
+    // interface IntrinsicAttributes {
+    //   key?: string | number;
+    // }
+    type IntrinsicAttributes = KTAttribute;
+
+    interface ElementChildrenAttribute {
+      children: {};
+    }
+  }
+}
+
 type KTAvailableContent =
   | KTRef<any>
   | HTMLElement
@@ -109,15 +125,25 @@ type KTPrefixedEventHandlers = {
   [EventName in keyof HTMLElementEventMap as `on:${EventName}`]?: (ev: HTMLElementEventMap[EventName]) => void;
 };
 
-type KTAttribute = KTBaseAttribute & KTPrefixedEventHandlers;
+type KTSpecialEventHandlers = {
+  'on:ktchange'?: (value: string) => void;
+  'ontrim:ktchange'?: (value: string) => void;
+  'on:ktchangenumber'?: (value: number) => void;
+
+  'on:ktinput'?: (value: string) => void;
+  'ontrim:ktinput'?: (value: string) => void;
+  'on:ktinputnumber'?: (value: number) => void;
+};
+
+type KTAttribute = KTBaseAttribute & KTPrefixedEventHandlers & KTSpecialEventHandlers;
 
 type KTComponent = (
   props: {
-    ref?: KTRef<HTMLElement>;
+    ref?: KTRef<KTHTMLElement>;
     children?: KTRawContent;
   } & KTAttribute &
     any
-) => HTMLElement | Promise<HTMLElement>;
+) => KTHTMLElement | Promise<KTHTMLElement> | any;
 
 type HTML<T extends HTMLTag & otherstring> = T extends HTMLTag ? HTMLElementTagNameMap[T] : HTMLElement;
 type H = (<T extends HTMLTag>(tag: T, attr?: KTRawAttr, content?: KTRawContent) => HTML<T>) & {
@@ -134,7 +160,7 @@ type H = (<T extends HTMLTag>(tag: T, attr?: KTRawAttr, content?: KTRawContent)
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.12.0 (Last Update: 2026.01.14 15:48:26.320)
+ * @version 0.13.2 (Last Update: 2026.01.16 19:38:40.621)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -143,12 +169,12 @@ type H = (<T extends HTMLTag>(tag: T, attr?: KTRawAttr, content?: KTRawContent)
  */
 declare const h: H;
 
+type JSXTag = HTMLTag | ((props?: any) => HTMLElement) | ((props?: any) => Promise<HTMLElement>) | ((props?: any) => KTHTMLElement) | ((props?: any) => Promise<KTHTMLElement>);
 /**
  * @param tag html tag or function component
  * @param props properties/attributes
- * @param _metadata metadata is ignored
  */
-declare function jsx<T extends HTMLTag>(tag: T | Function, props: KTRawAttr, ..._metadata: any[]): HTMLElementTagNameMap[T] | HTMLElement;
+declare function jsx(tag: JSXTag, props?: KTAttribute): KTHTMLElement;
 /**
  * Fragment support - returns an array of children
  * Note: kt.js doesn't have a real Fragment concept,
@@ -166,35 +192,16 @@ declare const jsxDEV: typeof jsx;
  */
 declare const jsxs: typeof jsx;
 
-declare global {
-  namespace JSX {
-    type Element = HTMLElementTagNameMap[keyof HTMLElementTagNameMap];
-
-    interface IntrinsicElements {
-      [tag: string]: KTAttribute & { children?: KTRawContent };
-    }
-
-    // interface IntrinsicAttributes {
-    //   key?: string | number;
-    // }
-    type IntrinsicAttributes = KTAttribute;
-
-    interface ElementChildrenAttribute {
-      children: {};
-    }
-  }
-}
-
 /**
  * Extract component props type (excluding ref and children)
  */
 type ExtractComponentProps<T> = T extends (props: infer P) => any ? Omit<P, 'ref' | 'children'> : {};
 declare function KTAsync<T extends KTComponent>(props: {
-    ref?: KTRef<HTMLElement>;
-    skeleton?: HTMLElement;
+    ref?: KTRef<KTHTMLElement>;
+    skeleton?: KTHTMLElement;
     component: T;
     children?: KTRawContent;
-} & ExtractComponentProps<T>): HTMLElement;
+} & ExtractComponentProps<T>): KTHTMLElement;
 
 export { Fragment, KTAsync, h as createElement, h, jsx, jsxDEV, jsxs, ref };
-export type { EventHandler, HTMLTag, KTAttribute, KTRawAttr, KTRawContent, KTRawContents, KTRef, KTRuntime };
+export type { EventHandler, HTMLTag, KTAttribute, KTHTMLElement, KTRawAttr, KTRawContent, KTRawContents, KTRef };

package/dist/index.iife.js

@@ -5,33 +5,6 @@ var __ktjs_core__ = (function (exports) {
         throw new Error('kt.js: ' + message);
     };
 
-    const $isArray = Array.isArray;
-    const $keys = Object.keys;
-    const $defines = Object.defineProperties;
-    const $mark = (func, tag) => $defines(func, { __ktjs_h__: { value: tag, configurable: true } });
-    const emptyPromiseHandler = () => ({});
-    if (typeof Promise === 'undefined') {
-        window.Promise = { resolve: emptyPromiseHandler, reject: emptyPromiseHandler };
-    }
-    const $isThenable = (o) => typeof o === 'object' && o !== null && 'then' in o && typeof o.then === 'function';
-
-    (() => {
-        const runtimeKey = '__ktjs__';
-        if (runtimeKey in window) {
-            return;
-        }
-        const __ktjs__ = Object.create(null);
-        // & We can add new functions when we need more
-        const descriptor = {
-            throws: { value: $throw, enumerable: true },
-            defines: { value: $defines, enumerable: true },
-            mark: { value: $mark, enumerable: true },
-        };
-        $defines(__ktjs__, descriptor);
-        $defines(window, { [runtimeKey]: { value: __ktjs__, enumerable: true } });
-        return {};
-    })();
-
     /**
      * & Remove `bind` because it is shockingly slower than wrapper
      * & `window.document` is safe because it is not configurable and its setter is undefined
@@ -70,22 +43,30 @@ var __ktjs_core__ = (function (exports) {
             }
         };
 
-    function booleanHandler(element, key, value) {
+    const $isArray = Array.isArray;
+    const $keys = Object.keys;
+    const emptyPromiseHandler = () => ({});
+    if (typeof Promise === 'undefined') {
+        window.Promise = { resolve: emptyPromiseHandler, reject: emptyPromiseHandler };
+    }
+    const $isThenable = (o) => typeof o === 'object' && o !== null && typeof o.then === 'function';
+
+    const booleanHandler = (element, key, value) => {
         if (key in element) {
             element[key] = !!value;
         }
         else {
             element.setAttribute(key, value);
         }
-    }
-    function valueHandler(element, key, value) {
+    };
+    const valueHandler = (element, key, value) => {
         if (key in element) {
             element[key] = value;
         }
         else {
             element.setAttribute(key, value);
         }
-    }
+    };
     // Attribute handlers map for optimized lookup
     const handlers = {
         checked: booleanHandler,
@@ -108,13 +89,18 @@ var __ktjs_core__ = (function (exports) {
         muted: booleanHandler,
         defer: booleanHandler,
         async: booleanHandler,
-        hidden: function (element, _key, value) {
-            element.hidden = !!value;
-        },
+        hidden: (element, _key, value) => (element.hidden = !!value),
     };
-    const defaultHandler = function (element, key, value) {
-        return element.setAttribute(key, value);
+    const ktEventHandlers = {
+        'on:ktchange': (element, handler) => element.addEventListener('change', () => handler(element.value)),
+        'ontrim:ktchange': (element, handler) => element.addEventListener('change', () => handler(element.value.trim())),
+        'on:ktchangenumber': (element, handler) => element.addEventListener('change', () => handler(Number(element.value))),
+        'on:ktinput': (element, handler) => element.addEventListener('input', () => handler(element.value)),
+        'ontrim:ktinput': (element, handler) => element.addEventListener('input', () => handler(element.value.trim())),
+        'on:ktinputnumber': (element, handler) => element.addEventListener('input', () => handler(Number(element.value))),
     };
+
+    const defaultHandler = (element, key, value) => element.setAttribute(key, value);
     function attrIsObject(element, attr) {
         const classValue = attr.class;
         const style = attr.style;
@@ -134,11 +120,19 @@ var __ktjs_core__ = (function (exports) {
             delete attr.style;
         }
         const keys = $keys(attr);
+        // todo 这里的处理每次遍历都要if所有的情况，能否用map或者对象来优化？
         for (let i = keys.length - 1; i >= 0; i--) {
             const key = keys[i];
             const o = attr[key];
             // force register on:xxx as an event handler
             // !if o is not valid, the throwing job will be done by `on`, not kt.js
+            // # special handling for kt.js specific events
+            const ktEvent = ktEventHandlers[key];
+            if (ktEvent) {
+                ktEvent(element, o);
+                continue;
+            }
+            // # normal event handler
             if (key.startsWith('on:')) {
                 element.addEventListener(key.slice(3), o); // chop off the `@`
                 continue;
@@ -225,7 +219,7 @@ var __ktjs_core__ = (function (exports) {
      * ## About
      * @package @ktjs/core
      * @author Kasukabe Tsumugi <futami16237@gmail.com>
-     * @version 0.12.0 (Last Update: 2026.01.14 15:48:26.320)
+     * @version 0.13.2 (Last Update: 2026.01.16 19:38:40.621)
      * @license MIT
      * @link https://github.com/baendlorel/kt.js
      * @link https://baendlorel.github.io/ Welcome to my site!
@@ -243,45 +237,67 @@ var __ktjs_core__ = (function (exports) {
         applyContent(element, content);
         return element;
     });
-    $mark(h, 'h');
 
     /**
      * @param tag html tag or function component
      * @param props properties/attributes
-     * @param _metadata metadata is ignored
      */
-    function jsx(tag, props, ..._metadata) {
+    function jsx(tag, props = {}) {
+        const ref = props.ref?.isKT ? props.ref : null;
+        if (ref) {
+            delete props.ref;
+        }
         // Handle function components
         if (typeof tag === 'function') {
-            const propObj = typeof props === 'string' ? { class: props } : props || {};
-            const children = propObj.children;
-            return tag({ ...propObj, children });
-        }
-        // Handle regular HTML tags
-        const propObj = typeof props === 'string' ? { class: props } : props;
-        if (propObj === undefined || propObj === null) {
-            return h(tag);
-        }
-        const children = propObj.children;
-        delete propObj.children;
-        // deal with ref attribute
-        const ref = propObj.ref?.isKT ? propObj.ref : null;
-        if (ref) {
-            delete propObj.ref;
+            let el = tag(props);
+            if (!el.redraw) {
+                el.redraw = (newProps) => {
+                    props = newProps ? { ...props, ...newProps } : props;
+                    // $ same as below
+                    const old = el;
+                    el = tag(props);
+                    el.redraw = old.redraw; // inherit redraw
+                    if (ref) {
+                        ref.value = el;
+                    }
+                    old.replaceWith(el);
+                };
+            }
+            if (ref) {
+                ref.value = el;
+            }
+            return el;
         }
-        const el = h(tag, propObj, children);
-        if (ref) {
-            ref.value = el;
+        else {
+            // & deal children here
+            let children = props.children;
+            delete props.children;
+            let el = h(tag, props, children);
+            if (ref) {
+                ref.value = el;
+            }
+            el.redraw = (newProps, newChildren) => {
+                props = newProps ? { ...props, ...newProps } : props;
+                children = (newChildren ?? children);
+                // $ same as above
+                const old = el;
+                el = h(tag, props, children);
+                el.redraw = old.redraw; // inherit redraw
+                if (ref) {
+                    ref.value = el;
+                }
+                old.replaceWith(el);
+            };
+            return el;
         }
-        return el;
     }
     /**
      * Fragment support - returns an array of children
      * Note: kt.js doesn't have a real Fragment concept,
      */
     function Fragment(props) {
-        window.__ktjs__.throws("kt.js doesn't have a Fragment concept");
-        // const { children } = props || {};
+        throw new Error("kt.js doesn't have a Fragment concept");
+        // const { children } = props ?? {};
         // if (!children) {
         //   return ;
         // }