@ktjs/core 0.9.0 → 0.10.1

package/README.md

@@ -17,6 +17,11 @@ Core DOM manipulation utilities for KT.js framework.
   - Special `@<eventName>` syntax for event handlers
   - Function attributes automatically treated as event listeners
   - Full TypeScript support with intelligent type inference
+- **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
 - **DOM Utilities**: Helper functions for common DOM operations
   - Native method caching for performance
   - Symbol-based private properties for internal state
@@ -24,10 +29,6 @@ Core DOM manipulation utilities for KT.js framework.
   - Accurate HTMLElement type inference
   - Event handler type hints with proper event types
   - Support for custom attributes and properties
-- **`ktnull`**: Special value for filtering null/undefined in DOM operations
-  - Works as a placeholder that won't create DOM nodes
-  - Can be used in attribute or content positions
-  - Preserves native DOM behavior while enabling conditional rendering
 - **ES5 Compatible**: Transpiled to ES5 for maximum browser compatibility
 - **Zero Dependencies**: Fully self-contained implementation
 
@@ -93,23 +94,43 @@ const input = h('input', {
 });
 ```
 
-### Using ktnull for Conditional Rendering
+### Async Components
 
 ```typescript
-import { h, ktnull } from '@ktjs/core';
-
-const items = [1, 2, 3, 4, 5];
+import { KTAsync } from '@ktjs/core';
+
+// Define an async component that returns a Promise
+const AsyncComponent = function () {
+  return new Promise<HTMLElement>((resolve) => {
+    setTimeout(() => {
+      const element = h('div', { class: 'loaded' }, 'Content loaded!');
+      resolve(element);
+    }, 1000);
+  });
+};
+
+// Use KTAsync to handle the async component
+const container = h('div', {}, [
+  h('h1', {}, 'Loading...'),
+  KTAsync({ component: AsyncComponent }),
+]);
 
-const list = h(
-  'ul',
-  {},
-  items.map(
-    (item) => (item % 2 === 0 ? h('li', {}, `Even: ${item}`) : ktnull) // Won't create a DOM node
-  )
+// With JSX/TSX
+const App = () => (
+  <div>
+    <h1>Loading...</h1>
+    <KTAsync component={AsyncComponent} />
+  </div>
 );
-// Results in: <ul><li>Even: 2</li><li>Even: 4</li></ul>
 ```
 
+**How it works:**
+
+- `KTAsync` creates a placeholder comment node 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
+
 ## API Reference
 
 ### `h(tag, attributes?, content?)`
@@ -124,10 +145,6 @@ Creates an HTMLElement with the specified tag, attributes, and content.
 
 **Returns:** HTMLElement
 
-### `ktnull`
-
-A special frozen empty object used to represent "no element" in content arrays. When used in place of an element, it won't create any DOM node.
-
 ## Type System
 
 The package includes comprehensive TypeScript definitions:

package/dist/index.d.ts

@@ -9,12 +9,6 @@ declare global {
     }
 }
 
-/**
- * This is a `falsy` value used to indicate "no node" in `h` function.
- * - It's an object, so it's guaranteed to be unique and no need for polyfill of `symbol`.
- */
-declare const ktnull: any;
-
 type otherstring = string & {};
 
 /**
@@ -26,10 +20,19 @@ interface KTRef<T> {
     value: T;
     isKT: true;
 }
-declare function ref<T>(value?: T): KTRef<T>;
+/**
+ * Reference to the created HTML element.
+ * - can alse be used to store normal values, but it is not reactive.
+ * @param value mostly an HTMLElement
+ */
+declare function ktref<T = HTMLElement>(value?: T): KTRef<T>;
 
 type KTAvailableContent = KTRef<any> | HTMLElement | string | number | undefined;
-type KTRawContent = KTAvailableContent[] | KTAvailableContent;
+type KTRawContent =
+  | KTAvailableContent[]
+  | KTAvailableContent
+  | Promise<KTAvailableContent[]>
+  | Promise<KTAvailableContent>;
 type KTRawAttr = KTAttribute | string;
 type KTRawContents = (HTMLElement | string | undefined)[];
 
@@ -98,6 +101,13 @@ type KTPrefixedEventHandlers = {
 
 type KTAttribute = KTBaseAttribute & KTPrefixedEventHandlers;
 
+type KTComponent = (
+  props: {
+    ref?: KTRef<HTMLElement>;
+    children?: KTRawContent;
+  } & KTAttribute
+) => HTMLElement | Promise<HTMLElement>;
+
 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>) & {
     kDepth: number;
@@ -113,7 +123,7 @@ type H = (<T extends HTMLTag>(tag: T, attr?: KTRawAttr, content?: KTRawContent)
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.9.0 (Last Update: 2025.12.29 11:09:49.983)
+ * @version 0.10.1 (Last Update: 2025.12.30 14:45:59.803)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -131,11 +141,10 @@ declare function jsx<T extends HTMLTag>(tag: T | Function, props: KTRawAttr, ...
 /**
  * Fragment support - returns an array of children
  * Note: kt.js doesn't have a real Fragment concept,
- * so we return ktnull for empty fragments or flatten children
  */
 declare function Fragment(props: {
     children?: KTRawContent;
-}): HTMLElement | typeof ktnull;
+}): HTMLElement;
 /**
  * JSX Development runtime - same as jsx but with additional dev checks
  */
@@ -154,9 +163,10 @@ declare global {
       [tag: string]: KTAttribute & { children?: KTRawContent };
     }
 
-    interface IntrinsicAttributes {
-      key?: string | number;
-    }
+    // interface IntrinsicAttributes {
+    //   key?: string | number;
+    // }
+    type IntrinsicAttributes = KTAttribute;
 
     interface ElementChildrenAttribute {
       children: {};
@@ -164,5 +174,11 @@ declare global {
   }
 }
 
-export { Fragment, h as createElement, h, jsx, jsxDEV, jsxs, ktnull, ref };
+declare function KTAsync(props: {
+    ref?: KTRef<HTMLElement>;
+    component: KTComponent;
+    children?: KTRawContent;
+}): HTMLElement;
+
+export { Fragment, KTAsync, h as createElement, h, jsx, jsxDEV, jsxs, ktref };
 export type { EventHandler, HTMLTag, KTAttribute, KTRawAttr, KTRawContent, KTRawContents, KTRef, KTRuntime };

package/dist/index.iife.js

@@ -13,6 +13,7 @@ var __ktjs_core__ = (function (exports) {
     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__';
@@ -31,12 +32,6 @@ var __ktjs_core__ = (function (exports) {
         return {};
     })();
 
-    /**
-     * This is a `falsy` value used to indicate "no node" in `h` function.
-     * - It's an object, so it's guaranteed to be unique and no need for polyfill of `symbol`.
-     */
-    const ktnull = Object.create(null);
-
     /**
      * & Remove `bind` because it is shockingly slower than wrapper
      * & `window.document` is safe because it is not configurable and its setter is undefined
@@ -46,8 +41,7 @@ var __ktjs_core__ = (function (exports) {
     const $append = // for ie 9/10/11
      typeof originAppend === 'function'
         ? function (...args) {
-            const nodes = args.filter((a) => a !== ktnull);
-            return originAppend.apply(this, nodes);
+            return originAppend.apply(this, args);
         }
         : function (...nodes) {
             if (nodes.length < 50) {
@@ -56,7 +50,7 @@ var __ktjs_core__ = (function (exports) {
                     if (typeof node === 'string') {
                         $appendChild.call(this, document.createTextNode(node));
                     }
-                    else if (node !== ktnull) {
+                    else {
                         $appendChild.call(this, node);
                     }
                 }
@@ -68,7 +62,7 @@ var __ktjs_core__ = (function (exports) {
                     if (typeof node === 'string') {
                         $appendChild.call(fragment, document.createTextNode(node));
                     }
-                    else if (node !== ktnull) {
+                    else {
                         $appendChild.call(fragment, node);
                     }
                 }
@@ -175,12 +169,35 @@ var __ktjs_core__ = (function (exports) {
         }
     }
 
-    function apd(element, content) {
-        if (content && content.isKT) {
-            $append.call(element, content.value);
+    function apdSingle(element, c) {
+        if (typeof c === 'object' && c !== null && 'isKT' in c) {
+            $append.call(element, c.value);
+        }
+        else {
+            $append.call(element, c);
+        }
+    }
+    function apd(element, c) {
+        if ($isThenable(c)) {
+            c.then((r) => apd(element, r));
+        }
+        else if ($isArray(c)) {
+            for (let i = 0; i < c.length; i++) {
+                // & might be thenable here too
+                const ci = c[i];
+                if ($isThenable(ci)) {
+                    const comment = document.createComment('ktjs-promise-placeholder');
+                    $append.call(element, comment);
+                    ci.then((awaited) => comment.replaceWith(awaited));
+                }
+                else {
+                    apdSingle(element, ci);
+                }
+            }
         }
         else {
-            $append.call(element, content);
+            // & here is thened, so must be a simple elementj
+            apdSingle(element, c);
         }
     }
     function applyContent(element, content) {
@@ -204,7 +221,7 @@ var __ktjs_core__ = (function (exports) {
      * ## About
      * @package @ktjs/core
      * @author Kasukabe Tsumugi <futami16237@gmail.com>
-     * @version 0.9.0 (Last Update: 2025.12.29 11:09:49.983)
+     * @version 0.10.1 (Last Update: 2025.12.30 14:45:59.803)
      * @license MIT
      * @link https://github.com/baendlorel/kt.js
      * @link https://baendlorel.github.io/ Welcome to my site!
@@ -213,7 +230,7 @@ var __ktjs_core__ = (function (exports) {
      */
     const h = ((tag, attr = '', content = '') => {
         if (typeof tag !== 'string') {
-            $throw('__func__ tagName must be a string.');
+            $throw('tagName must be a string.');
         }
         // * start creating the element
         const element = document.createElement(tag);
@@ -257,13 +274,12 @@ var __ktjs_core__ = (function (exports) {
     /**
      * Fragment support - returns an array of children
      * Note: kt.js doesn't have a real Fragment concept,
-     * so we return ktnull for empty fragments or flatten children
      */
     function Fragment(props) {
         window.__ktjs__.throws("kt.js doesn't have a Fragment concept");
         // const { children } = props || {};
         // if (!children) {
-        //   return ktnull;
+        //   return ;
         // }
         // // If single child, return it directly
         // if (!Array.isArray(children)) {
@@ -274,13 +290,11 @@ var __ktjs_core__ = (function (exports) {
         // const wrapper = document.createElement('div');
         // wrapper.setAttribute('data-kt-fragment', 'true');
         // children.forEach((child) => {
-        //   if (child && child !== ktnull) {
         //     if (typeof child === 'string') {
         //       wrapper.appendChild(document.createTextNode(child));
         //     } else if (child instanceof HTMLElement) {
         //       wrapper.appendChild(child);
         //     }
-        //   }
         // });
         // return wrapper;
     }
@@ -288,8 +302,8 @@ var __ktjs_core__ = (function (exports) {
      * JSX Development runtime - same as jsx but with additional dev checks
      */
     const jsxDEV = (...args) => {
-        console.log('JSX DEV called:', ...args);
-        console.log('chilren', args[1]?.children);
+        // console.log('JSX DEV called:', ...args);
+        // console.log('children', (args[1] as any)?.children);
         return jsx(...args);
     };
     /**
@@ -298,18 +312,35 @@ var __ktjs_core__ = (function (exports) {
      */
     const jsxs = jsx;
 
-    function ref(value) {
+    /**
+     * Reference to the created HTML element.
+     * - can alse be used to store normal values, but it is not reactive.
+     * @param value mostly an HTMLElement
+     */
+    function ktref(value) {
         return { value: value, isKT: true };
     }
 
+    function KTAsync(props) {
+        const raw = props.component(props);
+        let comp = document.createComment('ktjs-suspense-placeholder');
+        if ($isThenable(raw)) {
+            raw.then((resolved) => comp.replaceWith(resolved));
+        }
+        else {
+            comp = raw;
+        }
+        return comp;
+    }
+
     exports.Fragment = Fragment;
+    exports.KTAsync = KTAsync;
     exports.createElement = h;
     exports.h = h;
     exports.jsx = jsx;
     exports.jsxDEV = jsxDEV;
     exports.jsxs = jsxs;
-    exports.ktnull = ktnull;
-    exports.ref = ref;
+    exports.ktref = ktref;
 
     return exports;
 

package/dist/index.legacy.js

@@ -15,6 +15,9 @@ var __ktjs_core__ = (function (exports) {
     if (typeof Promise === 'undefined') {
         window.Promise = { resolve: emptyPromiseHandler, reject: emptyPromiseHandler };
     }
+    var $isThenable = function (o) {
+        return typeof o === 'object' && o !== null && 'then' in o && typeof o.then === 'function';
+    };
 
     ((function () {
         var _a;
@@ -34,12 +37,6 @@ var __ktjs_core__ = (function (exports) {
         return {};
     }))();
 
-    /**
-     * This is a `falsy` value used to indicate "no node" in `h` function.
-     * - It's an object, so it's guaranteed to be unique and no need for polyfill of `symbol`.
-     */
-    var ktnull = Object.create(null);
-
     /**
      * & Remove `bind` because it is shockingly slower than wrapper
      * & `window.document` is safe because it is not configurable and its setter is undefined
@@ -53,8 +50,7 @@ var __ktjs_core__ = (function (exports) {
             for (var _i = 0; _i < arguments.length; _i++) {
                 args[_i] = arguments[_i];
             }
-            var nodes = args.filter(function (a) { return a !== ktnull; });
-            return originAppend.apply(this, nodes);
+            return originAppend.apply(this, args);
         }
         : function () {
             var nodes = [];
@@ -67,7 +63,7 @@ var __ktjs_core__ = (function (exports) {
                     if (typeof node === 'string') {
                         $appendChild.call(this, document.createTextNode(node));
                     }
-                    else if (node !== ktnull) {
+                    else {
                         $appendChild.call(this, node);
                     }
                 }
@@ -79,7 +75,7 @@ var __ktjs_core__ = (function (exports) {
                     if (typeof node === 'string') {
                         $appendChild.call(fragment, document.createTextNode(node));
                     }
-                    else if (node !== ktnull) {
+                    else {
                         $appendChild.call(fragment, node);
                     }
                 }
@@ -186,12 +182,38 @@ var __ktjs_core__ = (function (exports) {
         }
     }
 
-    function apd(element, content) {
-        if (content && content.isKT) {
-            $append.call(element, content.value);
+    function apdSingle(element, c) {
+        if (typeof c === 'object' && c !== null && 'isKT' in c) {
+            $append.call(element, c.value);
+        }
+        else {
+            $append.call(element, c);
+        }
+    }
+    function apd(element, c) {
+        if ($isThenable(c)) {
+            c.then(function (r) { return apd(element, r); });
+        }
+        else if ($isArray(c)) {
+            var _loop_1 = function (i) {
+                // & might be thenable here too
+                var ci = c[i];
+                if ($isThenable(ci)) {
+                    var comment_1 = document.createComment('ktjs-promise-placeholder');
+                    $append.call(element, comment_1);
+                    ci.then(function (awaited) { return comment_1.replaceWith(awaited); });
+                }
+                else {
+                    apdSingle(element, ci);
+                }
+            };
+            for (var i = 0; i < c.length; i++) {
+                _loop_1(i);
+            }
         }
         else {
-            $append.call(element, content);
+            // & here is thened, so must be a simple elementj
+            apdSingle(element, c);
         }
     }
     function applyContent(element, content) {
@@ -215,7 +237,7 @@ var __ktjs_core__ = (function (exports) {
      * ## About
      * @package @ktjs/core
      * @author Kasukabe Tsumugi <futami16237@gmail.com>
-     * @version 0.9.0 (Last Update: 2025.12.29 11:09:49.983)
+     * @version 0.10.1 (Last Update: 2025.12.30 14:45:59.803)
      * @license MIT
      * @link https://github.com/baendlorel/kt.js
      * @link https://baendlorel.github.io/ Welcome to my site!
@@ -226,7 +248,7 @@ var __ktjs_core__ = (function (exports) {
         if (attr === void 0) { attr = ''; }
         if (content === void 0) { content = ''; }
         if (typeof tag !== 'string') {
-            $throw('__func__ tagName must be a string.');
+            $throw('tagName must be a string.');
         }
         // * start creating the element
         var element = document.createElement(tag);
@@ -265,16 +287,6 @@ var __ktjs_core__ = (function (exports) {
         return __assign.apply(this, arguments);
     };
 
-    function __spreadArray(to, from, pack) {
-        if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
-            if (ar || !(i in from)) {
-                if (!ar) ar = Array.prototype.slice.call(from, 0, i);
-                ar[i] = from[i];
-            }
-        }
-        return to.concat(ar || Array.prototype.slice.call(from));
-    }
-
     typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
         var e = new Error(message);
         return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
@@ -314,13 +326,12 @@ var __ktjs_core__ = (function (exports) {
     /**
      * Fragment support - returns an array of children
      * Note: kt.js doesn't have a real Fragment concept,
-     * so we return ktnull for empty fragments or flatten children
      */
     function Fragment(props) {
         window.__ktjs__.throws("kt.js doesn't have a Fragment concept");
         // const { children } = props || {};
         // if (!children) {
-        //   return ktnull;
+        //   return ;
         // }
         // // If single child, return it directly
         // if (!Array.isArray(children)) {
@@ -331,13 +342,11 @@ var __ktjs_core__ = (function (exports) {
         // const wrapper = document.createElement('div');
         // wrapper.setAttribute('data-kt-fragment', 'true');
         // children.forEach((child) => {
-        //   if (child && child !== ktnull) {
         //     if (typeof child === 'string') {
         //       wrapper.appendChild(document.createTextNode(child));
         //     } else if (child instanceof HTMLElement) {
         //       wrapper.appendChild(child);
         //     }
-        //   }
         // });
         // return wrapper;
     }
@@ -345,13 +354,12 @@ var __ktjs_core__ = (function (exports) {
      * JSX Development runtime - same as jsx but with additional dev checks
      */
     var jsxDEV = function () {
-        var _a;
         var args = [];
         for (var _i = 0; _i < arguments.length; _i++) {
             args[_i] = arguments[_i];
         }
-        console.log.apply(console, __spreadArray(['JSX DEV called:'], args, false));
-        console.log('chilren', (_a = args[1]) === null || _a === void 0 ? void 0 : _a.children);
+        // console.log('JSX DEV called:', ...args);
+        // console.log('children', (args[1] as any)?.children);
         return jsx.apply(void 0, args);
     };
     /**
@@ -360,18 +368,35 @@ var __ktjs_core__ = (function (exports) {
      */
     var jsxs = jsx;
 
-    function ref(value) {
+    /**
+     * Reference to the created HTML element.
+     * - can alse be used to store normal values, but it is not reactive.
+     * @param value mostly an HTMLElement
+     */
+    function ktref(value) {
         return { value: value, isKT: true };
     }
 
+    function KTAsync(props) {
+        var raw = props.component(props);
+        var comp = document.createComment('ktjs-suspense-placeholder');
+        if ($isThenable(raw)) {
+            raw.then(function (resolved) { return comp.replaceWith(resolved); });
+        }
+        else {
+            comp = raw;
+        }
+        return comp;
+    }
+
     exports.Fragment = Fragment;
+    exports.KTAsync = KTAsync;
     exports.createElement = h;
     exports.h = h;
     exports.jsx = jsx;
     exports.jsxDEV = jsxDEV;
     exports.jsxs = jsxs;
-    exports.ktnull = ktnull;
-    exports.ref = ref;
+    exports.ktref = ktref;
 
     return exports;
 

package/dist/index.mjs

@@ -10,6 +10,7 @@ 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__';
@@ -28,12 +29,6 @@ if (typeof Promise === 'undefined') {
     return {};
 })();
 
-/**
- * This is a `falsy` value used to indicate "no node" in `h` function.
- * - It's an object, so it's guaranteed to be unique and no need for polyfill of `symbol`.
- */
-const ktnull = Object.create(null);
-
 /**
  * & Remove `bind` because it is shockingly slower than wrapper
  * & `window.document` is safe because it is not configurable and its setter is undefined
@@ -43,8 +38,7 @@ const originAppend = HTMLElement.prototype.append;
 const $append = // for ie 9/10/11
  typeof originAppend === 'function'
     ? function (...args) {
-        const nodes = args.filter((a) => a !== ktnull);
-        return originAppend.apply(this, nodes);
+        return originAppend.apply(this, args);
     }
     : function (...nodes) {
         if (nodes.length < 50) {
@@ -53,7 +47,7 @@ const $append = // for ie 9/10/11
                 if (typeof node === 'string') {
                     $appendChild.call(this, document.createTextNode(node));
                 }
-                else if (node !== ktnull) {
+                else {
                     $appendChild.call(this, node);
                 }
             }
@@ -65,7 +59,7 @@ const $append = // for ie 9/10/11
                 if (typeof node === 'string') {
                     $appendChild.call(fragment, document.createTextNode(node));
                 }
-                else if (node !== ktnull) {
+                else {
                     $appendChild.call(fragment, node);
                 }
             }
@@ -172,12 +166,35 @@ function applyAttr(element, attr) {
     }
 }
 
-function apd(element, content) {
-    if (content && content.isKT) {
-        $append.call(element, content.value);
+function apdSingle(element, c) {
+    if (typeof c === 'object' && c !== null && 'isKT' in c) {
+        $append.call(element, c.value);
+    }
+    else {
+        $append.call(element, c);
+    }
+}
+function apd(element, c) {
+    if ($isThenable(c)) {
+        c.then((r) => apd(element, r));
+    }
+    else if ($isArray(c)) {
+        for (let i = 0; i < c.length; i++) {
+            // & might be thenable here too
+            const ci = c[i];
+            if ($isThenable(ci)) {
+                const comment = document.createComment('ktjs-promise-placeholder');
+                $append.call(element, comment);
+                ci.then((awaited) => comment.replaceWith(awaited));
+            }
+            else {
+                apdSingle(element, ci);
+            }
+        }
     }
     else {
-        $append.call(element, content);
+        // & here is thened, so must be a simple elementj
+        apdSingle(element, c);
     }
 }
 function applyContent(element, content) {
@@ -201,7 +218,7 @@ function applyContent(element, content) {
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.9.0 (Last Update: 2025.12.29 11:09:49.983)
+ * @version 0.10.1 (Last Update: 2025.12.30 14:45:59.803)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -210,7 +227,7 @@ function applyContent(element, content) {
  */
 const h = ((tag, attr = '', content = '') => {
     if (typeof tag !== 'string') {
-        $throw('__func__ tagName must be a string.');
+        $throw('tagName must be a string.');
     }
     // * start creating the element
     const element = document.createElement(tag);
@@ -254,13 +271,12 @@ function jsx(tag, props, ..._metadata) {
 /**
  * Fragment support - returns an array of children
  * Note: kt.js doesn't have a real Fragment concept,
- * so we return ktnull for empty fragments or flatten children
  */
 function Fragment(props) {
     window.__ktjs__.throws("kt.js doesn't have a Fragment concept");
     // const { children } = props || {};
     // if (!children) {
-    //   return ktnull;
+    //   return ;
     // }
     // // If single child, return it directly
     // if (!Array.isArray(children)) {
@@ -271,13 +287,11 @@ function Fragment(props) {
     // const wrapper = document.createElement('div');
     // wrapper.setAttribute('data-kt-fragment', 'true');
     // children.forEach((child) => {
-    //   if (child && child !== ktnull) {
     //     if (typeof child === 'string') {
     //       wrapper.appendChild(document.createTextNode(child));
     //     } else if (child instanceof HTMLElement) {
     //       wrapper.appendChild(child);
     //     }
-    //   }
     // });
     // return wrapper;
 }
@@ -285,8 +299,8 @@ function Fragment(props) {
  * JSX Development runtime - same as jsx but with additional dev checks
  */
 const jsxDEV = (...args) => {
-    console.log('JSX DEV called:', ...args);
-    console.log('chilren', args[1]?.children);
+    // console.log('JSX DEV called:', ...args);
+    // console.log('children', (args[1] as any)?.children);
     return jsx(...args);
 };
 /**
@@ -295,8 +309,25 @@ const jsxDEV = (...args) => {
  */
 const jsxs = jsx;
 
-function ref(value) {
+/**
+ * Reference to the created HTML element.
+ * - can alse be used to store normal values, but it is not reactive.
+ * @param value mostly an HTMLElement
+ */
+function ktref(value) {
     return { value: value, isKT: true };
 }
 
-export { Fragment, h as createElement, h, jsx, jsxDEV, jsxs, ktnull, ref };
+function KTAsync(props) {
+    const raw = props.component(props);
+    let comp = document.createComment('ktjs-suspense-placeholder');
+    if ($isThenable(raw)) {
+        raw.then((resolved) => comp.replaceWith(resolved));
+    }
+    else {
+        comp = raw;
+    }
+    return comp;
+}
+
+export { Fragment, KTAsync, h as createElement, h, jsx, jsxDEV, jsxs, ktref };

package/dist/jsx/index.d.ts

@@ -9,10 +9,19 @@ interface KTRef<T> {
     value: T;
     isKT: true;
 }
-declare function ref<T>(value?: T): KTRef<T>;
+/**
+ * Reference to the created HTML element.
+ * - can alse be used to store normal values, but it is not reactive.
+ * @param value mostly an HTMLElement
+ */
+declare function ktref<T = HTMLElement>(value?: T): KTRef<T>;
 
 type KTAvailableContent = KTRef<any> | HTMLElement | string | number | undefined;
-type KTRawContent = KTAvailableContent[] | KTAvailableContent;
+type KTRawContent =
+  | KTAvailableContent[]
+  | KTAvailableContent
+  | Promise<KTAvailableContent[]>
+  | Promise<KTAvailableContent>;
 type KTRawAttr = KTAttribute | string;
 
 /**
@@ -90,7 +99,7 @@ type H = (<T extends HTMLTag>(tag: T, attr?: KTRawAttr, content?: KTRawContent)
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.9.0 (Last Update: 2025.12.29 11:09:49.983)
+ * @version 0.10.1 (Last Update: 2025.12.30 14:45:59.803)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -99,12 +108,6 @@ type H = (<T extends HTMLTag>(tag: T, attr?: KTRawAttr, content?: KTRawContent)
  */
 declare const h: H;
 
-/**
- * This is a `falsy` value used to indicate "no node" in `h` function.
- * - It's an object, so it's guaranteed to be unique and no need for polyfill of `symbol`.
- */
-declare const ktnull: any;
-
 /**
  * @param tag html tag or function component
  * @param props properties/attributes
@@ -114,11 +117,10 @@ declare function jsx<T extends HTMLTag>(tag: T | Function, props: KTRawAttr, ...
 /**
  * Fragment support - returns an array of children
  * Note: kt.js doesn't have a real Fragment concept,
- * so we return ktnull for empty fragments or flatten children
  */
 declare function Fragment(props: {
     children?: KTRawContent;
-}): HTMLElement | typeof ktnull;
+}): HTMLElement;
 /**
  * JSX Development runtime - same as jsx but with additional dev checks
  */
@@ -137,9 +139,10 @@ declare global {
       [tag: string]: KTAttribute & { children?: KTRawContent };
     }
 
-    interface IntrinsicAttributes {
-      key?: string | number;
-    }
+    // interface IntrinsicAttributes {
+    //   key?: string | number;
+    // }
+    type IntrinsicAttributes = KTAttribute;
 
     interface ElementChildrenAttribute {
       children: {};
@@ -147,5 +150,5 @@ declare global {
   }
 }
 
-export { Fragment, h as createElement, jsx, jsxDEV, jsxs, ref };
+export { Fragment, h as createElement, jsx, jsxDEV, jsxs, ktref };
 export type { KTRef };

package/dist/jsx/index.mjs

@@ -10,12 +10,7 @@ const emptyPromiseHandler = () => ({});
 if (typeof Promise === 'undefined') {
     window.Promise = { resolve: emptyPromiseHandler, reject: emptyPromiseHandler };
 }
-
-/**
- * This is a `falsy` value used to indicate "no node" in `h` function.
- * - It's an object, so it's guaranteed to be unique and no need for polyfill of `symbol`.
- */
-const ktnull = Object.create(null);
+const $isThenable = (o) => typeof o === 'object' && o !== null && 'then' in o && typeof o.then === 'function';
 
 /**
  * & Remove `bind` because it is shockingly slower than wrapper
@@ -26,8 +21,7 @@ const originAppend = HTMLElement.prototype.append;
 const $append = // for ie 9/10/11
  typeof originAppend === 'function'
     ? function (...args) {
-        const nodes = args.filter((a) => a !== ktnull);
-        return originAppend.apply(this, nodes);
+        return originAppend.apply(this, args);
     }
     : function (...nodes) {
         if (nodes.length < 50) {
@@ -36,7 +30,7 @@ const $append = // for ie 9/10/11
                 if (typeof node === 'string') {
                     $appendChild.call(this, document.createTextNode(node));
                 }
-                else if (node !== ktnull) {
+                else {
                     $appendChild.call(this, node);
                 }
             }
@@ -48,7 +42,7 @@ const $append = // for ie 9/10/11
                 if (typeof node === 'string') {
                     $appendChild.call(fragment, document.createTextNode(node));
                 }
-                else if (node !== ktnull) {
+                else {
                     $appendChild.call(fragment, node);
                 }
             }
@@ -155,12 +149,35 @@ function applyAttr(element, attr) {
     }
 }
 
-function apd(element, content) {
-    if (content && content.isKT) {
-        $append.call(element, content.value);
+function apdSingle(element, c) {
+    if (typeof c === 'object' && c !== null && 'isKT' in c) {
+        $append.call(element, c.value);
     }
     else {
-        $append.call(element, content);
+        $append.call(element, c);
+    }
+}
+function apd(element, c) {
+    if ($isThenable(c)) {
+        c.then((r) => apd(element, r));
+    }
+    else if ($isArray(c)) {
+        for (let i = 0; i < c.length; i++) {
+            // & might be thenable here too
+            const ci = c[i];
+            if ($isThenable(ci)) {
+                const comment = document.createComment('ktjs-promise-placeholder');
+                $append.call(element, comment);
+                ci.then((awaited) => comment.replaceWith(awaited));
+            }
+            else {
+                apdSingle(element, ci);
+            }
+        }
+    }
+    else {
+        // & here is thened, so must be a simple elementj
+        apdSingle(element, c);
     }
 }
 function applyContent(element, content) {
@@ -184,7 +201,7 @@ function applyContent(element, content) {
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.9.0 (Last Update: 2025.12.29 11:09:49.983)
+ * @version 0.10.1 (Last Update: 2025.12.30 14:45:59.803)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -193,7 +210,7 @@ function applyContent(element, content) {
  */
 const h = ((tag, attr = '', content = '') => {
     if (typeof tag !== 'string') {
-        $throw('__func__ tagName must be a string.');
+        $throw('tagName must be a string.');
     }
     // * start creating the element
     const element = document.createElement(tag);
@@ -237,13 +254,12 @@ function jsx(tag, props, ..._metadata) {
 /**
  * Fragment support - returns an array of children
  * Note: kt.js doesn't have a real Fragment concept,
- * so we return ktnull for empty fragments or flatten children
  */
 function Fragment(props) {
     window.__ktjs__.throws("kt.js doesn't have a Fragment concept");
     // const { children } = props || {};
     // if (!children) {
-    //   return ktnull;
+    //   return ;
     // }
     // // If single child, return it directly
     // if (!Array.isArray(children)) {
@@ -254,13 +270,11 @@ function Fragment(props) {
     // const wrapper = document.createElement('div');
     // wrapper.setAttribute('data-kt-fragment', 'true');
     // children.forEach((child) => {
-    //   if (child && child !== ktnull) {
     //     if (typeof child === 'string') {
     //       wrapper.appendChild(document.createTextNode(child));
     //     } else if (child instanceof HTMLElement) {
     //       wrapper.appendChild(child);
     //     }
-    //   }
     // });
     // return wrapper;
 }
@@ -268,8 +282,8 @@ function Fragment(props) {
  * JSX Development runtime - same as jsx but with additional dev checks
  */
 const jsxDEV = (...args) => {
-    console.log('JSX DEV called:', ...args);
-    console.log('chilren', args[1]?.children);
+    // console.log('JSX DEV called:', ...args);
+    // console.log('children', (args[1] as any)?.children);
     return jsx(...args);
 };
 /**
@@ -278,8 +292,13 @@ const jsxDEV = (...args) => {
  */
 const jsxs = jsx;
 
-function ref(value) {
+/**
+ * Reference to the created HTML element.
+ * - can alse be used to store normal values, but it is not reactive.
+ * @param value mostly an HTMLElement
+ */
+function ktref(value) {
     return { value: value, isKT: true };
 }
 
-export { Fragment, h as createElement, jsx, jsxDEV, jsxs, ref };
+export { Fragment, h as createElement, jsx, jsxDEV, jsxs, ktref };

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

@@ -11,7 +11,11 @@ interface KTRef<T> {
 }
 
 type KTAvailableContent = KTRef<any> | HTMLElement | string | number | undefined;
-type KTRawContent = KTAvailableContent[] | KTAvailableContent;
+type KTRawContent =
+  | KTAvailableContent[]
+  | KTAvailableContent
+  | Promise<KTAvailableContent[]>
+  | Promise<KTAvailableContent>;
 type KTRawAttr = KTAttribute | string;
 
 /**
@@ -89,7 +93,7 @@ type H = (<T extends HTMLTag>(tag: T, attr?: KTRawAttr, content?: KTRawContent)
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.9.0 (Last Update: 2025.12.29 11:09:49.983)
+ * @version 0.10.1 (Last Update: 2025.12.30 14:45:59.803)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -98,12 +102,6 @@ type H = (<T extends HTMLTag>(tag: T, attr?: KTRawAttr, content?: KTRawContent)
  */
 declare const h: H;
 
-/**
- * This is a `falsy` value used to indicate "no node" in `h` function.
- * - It's an object, so it's guaranteed to be unique and no need for polyfill of `symbol`.
- */
-declare const ktnull: any;
-
 /**
  * @param tag html tag or function component
  * @param props properties/attributes
@@ -113,11 +111,10 @@ declare function jsx<T extends HTMLTag>(tag: T | Function, props: KTRawAttr, ...
 /**
  * Fragment support - returns an array of children
  * Note: kt.js doesn't have a real Fragment concept,
- * so we return ktnull for empty fragments or flatten children
  */
 declare function Fragment(props: {
     children?: KTRawContent;
-}): HTMLElement | typeof ktnull;
+}): HTMLElement;
 /**
  * JSX Development runtime - same as jsx but with additional dev checks
  */

package/dist/jsx/jsx-runtime.mjs

@@ -10,12 +10,7 @@ const emptyPromiseHandler = () => ({});
 if (typeof Promise === 'undefined') {
     window.Promise = { resolve: emptyPromiseHandler, reject: emptyPromiseHandler };
 }
-
-/**
- * This is a `falsy` value used to indicate "no node" in `h` function.
- * - It's an object, so it's guaranteed to be unique and no need for polyfill of `symbol`.
- */
-const ktnull = Object.create(null);
+const $isThenable = (o) => typeof o === 'object' && o !== null && 'then' in o && typeof o.then === 'function';
 
 /**
  * & Remove `bind` because it is shockingly slower than wrapper
@@ -26,8 +21,7 @@ const originAppend = HTMLElement.prototype.append;
 const $append = // for ie 9/10/11
  typeof originAppend === 'function'
     ? function (...args) {
-        const nodes = args.filter((a) => a !== ktnull);
-        return originAppend.apply(this, nodes);
+        return originAppend.apply(this, args);
     }
     : function (...nodes) {
         if (nodes.length < 50) {
@@ -36,7 +30,7 @@ const $append = // for ie 9/10/11
                 if (typeof node === 'string') {
                     $appendChild.call(this, document.createTextNode(node));
                 }
-                else if (node !== ktnull) {
+                else {
                     $appendChild.call(this, node);
                 }
             }
@@ -48,7 +42,7 @@ const $append = // for ie 9/10/11
                 if (typeof node === 'string') {
                     $appendChild.call(fragment, document.createTextNode(node));
                 }
-                else if (node !== ktnull) {
+                else {
                     $appendChild.call(fragment, node);
                 }
             }
@@ -155,12 +149,35 @@ function applyAttr(element, attr) {
     }
 }
 
-function apd(element, content) {
-    if (content && content.isKT) {
-        $append.call(element, content.value);
+function apdSingle(element, c) {
+    if (typeof c === 'object' && c !== null && 'isKT' in c) {
+        $append.call(element, c.value);
+    }
+    else {
+        $append.call(element, c);
+    }
+}
+function apd(element, c) {
+    if ($isThenable(c)) {
+        c.then((r) => apd(element, r));
+    }
+    else if ($isArray(c)) {
+        for (let i = 0; i < c.length; i++) {
+            // & might be thenable here too
+            const ci = c[i];
+            if ($isThenable(ci)) {
+                const comment = document.createComment('ktjs-promise-placeholder');
+                $append.call(element, comment);
+                ci.then((awaited) => comment.replaceWith(awaited));
+            }
+            else {
+                apdSingle(element, ci);
+            }
+        }
     }
     else {
-        $append.call(element, content);
+        // & here is thened, so must be a simple elementj
+        apdSingle(element, c);
     }
 }
 function applyContent(element, content) {
@@ -184,7 +201,7 @@ function applyContent(element, content) {
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.9.0 (Last Update: 2025.12.29 11:09:49.983)
+ * @version 0.10.1 (Last Update: 2025.12.30 14:45:59.803)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -193,7 +210,7 @@ function applyContent(element, content) {
  */
 const h = ((tag, attr = '', content = '') => {
     if (typeof tag !== 'string') {
-        $throw('__func__ tagName must be a string.');
+        $throw('tagName must be a string.');
     }
     // * start creating the element
     const element = document.createElement(tag);
@@ -237,13 +254,12 @@ function jsx(tag, props, ..._metadata) {
 /**
  * Fragment support - returns an array of children
  * Note: kt.js doesn't have a real Fragment concept,
- * so we return ktnull for empty fragments or flatten children
  */
 function Fragment(props) {
     window.__ktjs__.throws("kt.js doesn't have a Fragment concept");
     // const { children } = props || {};
     // if (!children) {
-    //   return ktnull;
+    //   return ;
     // }
     // // If single child, return it directly
     // if (!Array.isArray(children)) {
@@ -254,13 +270,11 @@ function Fragment(props) {
     // const wrapper = document.createElement('div');
     // wrapper.setAttribute('data-kt-fragment', 'true');
     // children.forEach((child) => {
-    //   if (child && child !== ktnull) {
     //     if (typeof child === 'string') {
     //       wrapper.appendChild(document.createTextNode(child));
     //     } else if (child instanceof HTMLElement) {
     //       wrapper.appendChild(child);
     //     }
-    //   }
     // });
     // return wrapper;
 }
@@ -268,8 +282,8 @@ function Fragment(props) {
  * JSX Development runtime - same as jsx but with additional dev checks
  */
 const jsxDEV = (...args) => {
-    console.log('JSX DEV called:', ...args);
-    console.log('chilren', args[1]?.children);
+    // console.log('JSX DEV called:', ...args);
+    // console.log('children', (args[1] as any)?.children);
     return jsx(...args);
 };
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ktjs/core",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "Core functionality for kt.js - DOM manipulation utilities with JSX/TSX support",
   "type": "module",
   "module": "./dist/index.mjs",