@ktjs/core 0.14.6 → 0.15.1

package/README.md

@@ -12,7 +12,7 @@ Core DOM manipulation utilities for KT.js framework with built-in JSX/TSX suppor
 
 `@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
+**Current Version:** 0.14.6
 
 ## Features
 
@@ -25,7 +25,9 @@ Core DOM manipulation utilities for KT.js framework with built-in JSX/TSX suppor
   - 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
+  - `redraw()` method for controlled re-rendering
+  - **k-if directive**: Conditional element creation with `k-if` attribute
+  - Array children support for seamless list rendering
 - **KTAsync Component**: Handle async components with ease
   - Automatic handling of Promise-based components
   - Seamless integration with JSX/TSX
@@ -87,7 +89,7 @@ const button1 = h(
   {
     'on:click': () => alert('Clicked!'),
   },
-  'Button 1'
+  'Button 1',
 );
 
 // Function attribute (also treated as event listener)
@@ -97,7 +99,7 @@ const button2 = h(
     click: (e) => console.log('Event:', e),
     'data-id': '123', // Regular attribute
   },
-  'Button 2'
+  'Button 2',
 );
 
 // Both regular and event handler for same name
@@ -136,9 +138,43 @@ const Greeting = ({ name }: { name: string }) => (
 const app = <Greeting name="World" />;
 ```
 
+### Conditional Rendering with k-if (v0.14.6+)
+
+The `k-if` directive allows conditional element creation:
+
+```tsx
+import { h } from '@ktjs/core';
+
+// Element will only be created if condition is true
+const isVisible = true;
+const element = <div k-if={isVisible}>This will be rendered</div>;
+
+// Element will not be created if condition is false
+const isHidden = false;
+const hidden = <div k-if={isHidden}>This will NOT be rendered</div>;
+// hidden will be undefined/null
+
+// Practical example
+const UserProfile = ({ user, isLoggedIn }: { user: any; isLoggedIn: boolean }) => (
+  <div>
+    <h1>User Profile</h1>
+    <div k-if={isLoggedIn}>
+      <p>Welcome, {user.name}!</p>
+      <button>Logout</button>
+    </div>
+    <div k-if={!isLoggedIn}>
+      <p>Please log in to continue</p>
+      <button>Login</button>
+    </div>
+  </div>
+);
+```
+
+**Note**: `k-if` is evaluated **once** at element creation time. It's not reactive - if you need dynamic visibility, use CSS or manually recreate the element.
+
 ### Redraw Mechanism (v0.11+)
 
-The new `redraw()` method allows you to update components efficiently:
+The `redraw()` method allows you to update components efficiently:
 
 ```tsx
 import { h, KTHTMLElement } from '@ktjs/core';
@@ -164,6 +200,39 @@ const div = (<div>Old content</div>) as KTHTMLElement;
 div.redraw(undefined, 'New content');
 ```
 
+### Array Children Support (v0.14.1+)
+
+Children can now be arrays for easier list rendering:
+
+```tsx
+import { h } from '@ktjs/core';
+
+// Map arrays directly as children
+const items = ['Apple', 'Banana', 'Orange'];
+const list = (
+  <ul>
+    {items.map((item) => (
+      <li>{item}</li>
+    ))}
+  </ul>
+);
+
+// Mix mapped elements with other elements
+const TodoList = ({ todos }: { todos: string[] }) => (
+  <div>
+    <h2>Todo List</h2>
+    <ul>
+      {todos.map((todo) => (
+        <li>{todo}</li>
+      ))}
+      <li>
+        <button>Add More</button>
+      </li>
+    </ul>
+  </div>
+);
+```
+
 ### Async Components
 
 ```typescript

package/dist/index.d.ts

@@ -16,12 +16,12 @@ interface KTRef<T> {
  */
 declare function ref<T = HTMLElement>(value?: T): KTRef<T>;
 
-type KTHTMLElement = HTMLElement & {
+type KTHTMLElement<El extends HTMLElement = HTMLElement> = El & {
   /**
    * Automically generate a redraw function if it is not provided
    * @param props
    */
-  redraw: (props?: KTAttribute, children?: KTRawContent) => KTHTMLElement;
+  redraw: (props?: KTAttribute, ...args: any[]) => KTHTMLElement;
 };
 
 declare global {
@@ -153,7 +153,7 @@ type H = (<T extends HTMLTag>(tag: T, attr?: KTRawAttr, content?: KTRawContent)
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.14.6 (Last Update: 2026.01.17 11:35:33.824)
+ * @version 0.15.1 (Last Update: 2026.01.25 13:09:33.161)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -192,14 +192,29 @@ declare const jsxs: typeof jsx;
  *    let aa = 10;
  *    // ...
  *    // aa might be changed
- *    return createRedrawable(() => <div>{aa}</div>);
+ *    return createRedrawableNoref(() => <div>{aa}</div>);
  * }
  * ```
  * Then the returned element has a `redraw` method to redraw itself with new values.
- * @param creator
+ * @param creator a simple creator function that returns an element
  * @returns created element
  */
-declare function createRedrawable(creator: () => KTHTMLElement): KTHTMLElement;
+declare function createRedrawableNoref(creator: () => KTHTMLElement): KTHTMLElement;
+/**
+ * A helper to create redrawable elements
+ * ```tsx
+ * export function MyComponent() {
+ *    let aa = 10;
+ *    // ...
+ *    // aa might be changed
+ *    return createRedrawable(() => <div>{aa}</div>);
+ * }
+ * ```
+ * Then the returned element has a `redraw` method to redraw itself with new values.
+ * @param creator a simple creator function that returns an element
+ * @returns created element's ref
+ */
+declare function createRedrawable(creator: () => KTHTMLElement): KTRef<KTHTMLElement>;
 
 /**
  * Extract component props type (excluding ref and children)
@@ -212,5 +227,5 @@ declare function KTAsync<T extends KTComponent>(props: {
     children?: KTRawContent;
 } & ExtractComponentProps<T>): KTHTMLElement;
 
-export { Fragment, KTAsync, h as createElement, createRedrawable, h, jsx, jsxDEV, jsxs, ref };
+export { Fragment, KTAsync, h as createElement, createRedrawable, createRedrawableNoref, h, jsx, jsxDEV, jsxs, ref };
 export type { EventHandler, HTMLTag, KTAttribute, KTHTMLElement, KTRawAttr, KTRawContent, KTRawContents, KTRef };

package/dist/index.iife.js

@@ -56,17 +56,11 @@ var __ktjs_core__ = (function (exports) {
 
     const defaultHandler = (element, key, value) => element.setAttribute(key, value);
     function attrIsObject(element, attr) {
-        // & deal k-if first
-        if ('k-if' in attr) {
-            if (!attr['k-if']) {
-                return false;
-            }
-        }
         const classValue = attr.class;
-        const style = attr.style;
         if (classValue !== undefined) {
             element.className = classValue;
         }
+        const style = attr.style;
         if (style) {
             if (typeof style === 'string') {
                 element.setAttribute('style', style);
@@ -78,39 +72,31 @@ var __ktjs_core__ = (function (exports) {
             }
         }
         for (const key in attr) {
-            if (key === 'class' || key === 'style' || key === 'k-if') {
+            if (key === 'class' || key === 'style' || key === 'children' || key === 'k-if' || key === 'ref') {
                 continue;
             }
             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:')) {
+            // normal event handler
+            else if (key.startsWith('on:')) {
                 element.addEventListener(key.slice(3), o); // chop off the `@`
-                continue;
-            }
-            if (typeof o === 'function') {
-                (handlers[key] || defaultHandler)(element, key, o());
             }
+            // normal attributes
             else {
                 (handlers[key] || defaultHandler)(element, key, o);
             }
         }
-        return true;
     }
     function applyAttr(element, attr) {
-        if (typeof attr === 'string') {
-            element.className = attr;
-            return true;
+        if (typeof attr === 'object' && attr !== null) {
+            attrIsObject(element, attr);
         }
-        else if (typeof attr === 'object' && attr !== null) {
-            return attrIsObject(element, attr);
+        else if (typeof attr === 'string') {
+            element.className = attr;
         }
         else {
             throw new Error('kt.js: attr must be an object/string.');
@@ -218,7 +204,7 @@ var __ktjs_core__ = (function (exports) {
      * ## About
      * @package @ktjs/core
      * @author Kasukabe Tsumugi <futami16237@gmail.com>
-     * @version 0.14.6 (Last Update: 2026.01.17 11:35:33.824)
+     * @version 0.15.1 (Last Update: 2026.01.25 13:09:33.161)
      * @license MIT
      * @link https://github.com/baendlorel/kt.js
      * @link https://baendlorel.github.io/ Welcome to my site!
@@ -232,68 +218,52 @@ var __ktjs_core__ = (function (exports) {
         // * start creating the element
         const element = document.createElement(tag);
         // * Handle content
-        const kif = applyAttr(element, attr);
-        if (!kif) {
-            return document.createComment('k-if');
-        }
+        applyAttr(element, attr);
         applyContent(element, content);
         return element;
     });
 
+    /**
+     * 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 ref(value) {
+        return { value: value, isKT: true };
+    }
+
+    const dummyRef = { value: null };
+    // todo 是否进一步削减h函数的分支，比如去掉string为attr的情况
     /**
      * @param tag html tag or function component
      * @param props properties/attributes
      */
     function jsx(tag, props = {}) {
-        const ref = props.ref?.isKT ? props.ref : null;
-        if (ref) {
-            delete props.ref;
+        const ref = props.ref?.isKT ? props.ref : dummyRef;
+        let el;
+        const redraw = (newProps) => {
+            props = newProps ? { ...props, ...newProps } : props;
+            const old = el;
+            el = jsx(tag, props);
+            old.replaceWith(el);
+            return el;
+        };
+        if ('k-if' in props && !props['k-if']) {
+            el = document.createComment('k-if');
+            ref.value = el;
+            el.redraw = redraw;
+            return el;
         }
         // Handle function components
         if (typeof tag === 'function') {
-            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);
-                    return el;
-                };
-            }
-            if (ref) {
-                ref.value = el;
-            }
-            return el;
+            el = tag(props);
         }
         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;
+            el = h(tag, props, props.children);
         }
+        el.redraw ??= redraw;
+        ref.value = el;
+        return el;
     }
     /**
      * Fragment support - returns an array of children
@@ -342,33 +312,51 @@ var __ktjs_core__ = (function (exports) {
      *    let aa = 10;
      *    // ...
      *    // aa might be changed
-     *    return createRedrawable(() => <div>{aa}</div>);
+     *    return createRedrawableNoref(() => <div>{aa}</div>);
      * }
      * ```
      * Then the returned element has a `redraw` method to redraw itself with new values.
-     * @param creator
+     * @param creator a simple creator function that returns an element
      * @returns created element
      */
-    function createRedrawable(creator) {
-        let element = creator();
+    function createRedrawableNoref(creator) {
+        let el = creator();
         const redraw = () => {
-            const old = element;
-            element = creator();
-            old.replaceWith(element);
-            element.redraw = redraw;
-            return element;
+            const old = el;
+            el = creator();
+            old.replaceWith(el);
+            el.redraw = redraw;
+            return el;
         };
-        element.redraw = redraw;
-        return element;
+        el.redraw = redraw;
+        return el;
     }
-
     /**
-     * Reference to the created HTML element.
-     * - can alse be used to store normal values, but it is not reactive.
-     * @param value mostly an HTMLElement
+     * A helper to create redrawable elements
+     * ```tsx
+     * export function MyComponent() {
+     *    let aa = 10;
+     *    // ...
+     *    // aa might be changed
+     *    return createRedrawable(() => <div>{aa}</div>);
+     * }
+     * ```
+     * Then the returned element has a `redraw` method to redraw itself with new values.
+     * @param creator a simple creator function that returns an element
+     * @returns created element's ref
      */
-    function ref(value) {
-        return { value: value, isKT: true };
+    function createRedrawable(creator) {
+        const elRef = ref();
+        elRef.value = creator();
+        const redraw = () => {
+            const old = elRef.value;
+            elRef.value = creator();
+            old.replaceWith(elRef.value);
+            elRef.value.redraw = redraw;
+            return elRef.value;
+        };
+        elRef.value.redraw = redraw;
+        return elRef;
     }
 
     function KTAsync(props) {
@@ -387,6 +375,7 @@ var __ktjs_core__ = (function (exports) {
     exports.KTAsync = KTAsync;
     exports.createElement = h;
     exports.createRedrawable = createRedrawable;
+    exports.createRedrawableNoref = createRedrawableNoref;
     exports.h = h;
     exports.jsx = jsx;
     exports.jsxDEV = jsxDEV;