@ktjs/core 0.16.0 → 0.17.0

package/README.md

@@ -29,11 +29,10 @@ Core DOM manipulation utilities for KT.js framework with built-in JSX/TSX suppor
   - **k-if directive**: Conditional element creation with `k-if` attribute
   - Array children support for seamless list rendering
 - **KTFor Component**: Efficient list rendering with key-based optimization (v0.16.0)
-  - Key-based DOM reuse similar to Svelte's `{#each}` blocks
-  - Minimal DOM operations - only updates what changed
-  - Returns Comment anchor node for flexible positioning
+  - Returns Comment anchor with `__kt_for_list__` array storing rendered elements
+  - Auto-appends list items when anchor is added via `applyContent`
+  - Key-based DOM reuse with customizable key function (default: identity)
   - Type-safe with full TypeScript generics support
-  - `KTForStatic` variant for simple lists without key optimization
 - **KTAsync Component**: Handle async components with ease
   - Automatic handling of Promise-based components
   - Seamless integration with JSX/TSX
@@ -211,7 +210,7 @@ div.redraw(undefined, 'New content');
 The `KTFor` component provides efficient list rendering with key-based DOM reuse:
 
 ```tsx
-import { KTFor, KTForStatic, KTForAnchor } from '@ktjs/core';
+import { KTFor } from '@ktjs/core';
 
 interface Todo {
   id: number;
@@ -228,8 +227,8 @@ let todos: Todo[] = [
 const todoList = (
   <KTFor
     list={todos}
-    key={(item) => item.id} // Stable key for efficient updates
-    mapper={(item, index) => (
+    key={(item) => item.id} // Optional, defaults to identity function
+    map={(item, index) => (
       <div class={`todo ${item.done ? 'done' : ''}`}>
         <input type="checkbox" checked={item.done} />
         <span>{item.text}</span>
@@ -237,28 +236,22 @@ const todoList = (
       </div>
     )}
   />
-) as KTForAnchor;
+);
 
-// Add to DOM (anchor + all items are rendered)
+// Add to DOM - anchor comment + __kt_for_list__ items are appended
 document.body.appendChild(todoList);
 
 // Update the list - only changed items are updated
 todos = [...todos, { id: 3, text: 'New task', done: false }];
 todoList.redraw({ list: todos });
-
-// For simple static lists, use KTForStatic (no key optimization)
-const simpleList = (
-  <KTForStatic list={['Apple', 'Banana', 'Orange']} mapper={(item) => <div>{item}</div>} />
-) as KTForAnchor;
 ```
 
 **How it works:**
 
-- Returns a Comment node (`<!-- kt-for -->`) as anchor point
-- All list items are rendered as siblings after the anchor
-- Uses key-based diff algorithm to reuse DOM nodes
+- Returns Comment anchor (`<!-- kt-for -->`) with `__kt_for_list__` array property
+- When appended via `applyContent`, anchor and all list items are added to DOM
+- Uses key-based diff to reuse DOM nodes on `redraw()`
 - Only adds/removes/moves nodes that changed
-- Similar to Svelte's `{#each}` blocks
 
 ````
 

package/dist/index.d.ts

@@ -17,12 +17,13 @@ interface KTRef<T> {
  */
 declare function ref<T = HTMLElement>(value?: T): KTRef<T>;
 
-type KTHTMLElement<El extends HTMLElement = HTMLElement> = El & {
+type Redraw = (props?: KTAttribute, ...args: any[]) => KTHTMLElement;
+type KTHTMLElement<El extends HTMLElement = HTMLElement, R extends Function = Redraw> = El & {
   /**
    * Automically generate a redraw function if it is not provided
    * @param props
    */
-  redraw: (props?: KTAttribute, ...args: any[]) => KTHTMLElement;
+  redraw: R;
 };
 
 declare global {
@@ -44,7 +45,7 @@ declare global {
   }
 }
 
-type SingleContent = KTRef<any> | HTMLElement | Element | string | number | boolean | null | undefined;
+type SingleContent = KTRef<any> | HTMLElement | Element | Node | string | number | boolean | null | undefined;
 type KTAvailableContent = SingleContent | KTAvailableContent[];
 type KTRawContent = KTAvailableContent | Promise<KTAvailableContent>;
 type KTRawAttr = KTAttribute | string;
@@ -61,9 +62,11 @@ type EventHandler<T extends Event = Event> = (this: HTMLElement, ev: T) => any;
 interface KTBaseAttribute {
   [k: string]: any;
 
+  // # kt-specific attributes
   ref?: KTRef<HTMLElement>;
   'k-if'?: any;
 
+  // # normal HTML attributes
   id?: string;
   class?: string;
   style?: string | Partial<CSSStyleDeclaration>;
@@ -168,7 +171,7 @@ type HTML<T extends (HTMLTag | SVGTag) & otherstring> = T extends SVGTag ? SVGEl
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.16.0 (Last Update: 2026.01.27 17:30:39.673)
+ * @version 0.17.0 (Last Update: 2026.01.28 15:11:59.247)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -242,63 +245,21 @@ declare function KTAsync<T extends KTComponent>(props: {
     children?: KTRawContent;
 } & ExtractComponentProps<T>): KTHTMLElement;
 
+type KForElement = KTHTMLElement & {
+    __kt_for_list__: HTMLElement[];
+    redraw: (newProps?: KTAttribute) => void;
+};
 interface KTForProps<T> {
+    ref?: KTRef<KForElement>;
     list: T[];
-    /**
-     * Key function to uniquely identify each item
-     * Using stable keys enables efficient DOM reuse and updates
-     */
-    key: (item: T, index: number) => string | number;
-    /**
-     * Mapper function to render each item
-     */
-    mapper: (item: T, index: number) => HTMLElement;
-}
-/**
- * Extended Comment node with redraw capability for KTFor
- */
-interface KTForAnchor extends Comment {
-    redraw: (newProps?: {
-        list?: any[];
-        mapper?: (item: any, index: number) => HTMLElement;
-    }) => void;
+    key?: (item: T, index: number, array: T[]) => any;
+    map: (item: T, index: number, array: T[]) => HTMLElement;
 }
 /**
- * KTFor component - Efficient list rendering with key-based DOM reuse
- * Similar to Svelte's {#each} blocks, provides optimized updates
- *
- * Returns a Comment node as anchor point. All list items are rendered after this anchor.
- *
- * @example
- * ```tsx
- * const listAnchor = <KTFor
- *   list={items}
- *   key={(item) => item.id}
- *   mapper={(item) => <div>{item.name}</div>}
- * /> as KTForAnchor;
- *
- * document.body.appendChild(listAnchor); // Anchor + all items are rendered
- *
- * // Update the list
- * listAnchor.redraw({ list: newItems });
- * ```
- */
-declare function KTFor<T>(props: KTForProps<T>): KTForAnchor;
-/**
- * Simple list rendering without key optimization
- * Rebuilds the entire list on each update - use for small static lists
- *
- * Returns a Comment anchor node. All items are rendered after this anchor.
- *
- * @example
- * ```tsx
- * const listAnchor = <KTForStatic
- *   list={items}
- *   mapper={(item) => <div>{item}</div>}
- * /> as KTForAnchor;
- * ```
+ * KTFor - List rendering component with key-based optimization
+ * Returns a Comment anchor node with rendered elements in __kt_for_list__
  */
-declare function KTForStatic<T>(props: Omit<KTForProps<T>, 'key'>): KTForAnchor;
+declare function KTFor<T>(props: KTForProps<T>): KForElement;
 
-export { Fragment, KTAsync, KTFor, KTForStatic, h as createElement, createRedrawable, createRedrawableNoref, h, jsx, jsxDEV, jsxs, ref };
-export type { EventHandler, HTMLTag, KTAttribute, KTForAnchor, KTForProps, KTHTMLElement, KTRawAttr, KTRawContent, KTRawContents, KTRef };
+export { Fragment, KTAsync, KTFor, h as createElement, createRedrawable, createRedrawableNoref, h, jsx, jsxDEV, jsxs, ref };
+export type { EventHandler, HTMLTag, KTAttribute, KTForProps, KTHTMLElement, KTRawAttr, KTRawContent, KTRawContents, KTRef, Redraw };

package/dist/index.iife.js

@@ -158,6 +158,11 @@ var __ktjs_core__ = (function (exports) {
         }
         else {
             $append.call(element, c);
+            // Handle KTFor anchor
+            const list = c.__kt_for_list__;
+            if ($isArray(list)) {
+                apd(element, list);
+            }
         }
     }
     function apd(element, c) {
@@ -206,7 +211,7 @@ var __ktjs_core__ = (function (exports) {
      * ## About
      * @package @ktjs/core
      * @author Kasukabe Tsumugi <futami16237@gmail.com>
-     * @version 0.16.0 (Last Update: 2026.01.27 17:30:39.673)
+     * @version 0.17.0 (Last Update: 2026.01.28 15:11:59.247)
      * @license MIT
      * @link https://github.com/baendlorel/kt.js
      * @link https://baendlorel.github.io/ Welcome to my site!
@@ -379,205 +384,107 @@ var __ktjs_core__ = (function (exports) {
     }
 
     /**
-     * KTFor component - Efficient list rendering with key-based DOM reuse
-     * Similar to Svelte's {#each} blocks, provides optimized updates
-     *
-     * Returns a Comment node as anchor point. All list items are rendered after this anchor.
-     *
-     * @example
-     * ```tsx
-     * const listAnchor = <KTFor
-     *   list={items}
-     *   key={(item) => item.id}
-     *   mapper={(item) => <div>{item.name}</div>}
-     * /> as KTForAnchor;
-     *
-     * document.body.appendChild(listAnchor); // Anchor + all items are rendered
-     *
-     * // Update the list
-     * listAnchor.redraw({ list: newItems });
-     * ```
+     * KTFor - List rendering component with key-based optimization
+     * Returns a Comment anchor node with rendered elements in __kt_for_list__
      */
     function KTFor(props) {
-        const { list: initList, key: getKey, mapper } = props;
-        // Cache: key -> { node: HTMLElement, item: T }
-        const nodeCache = new Map();
-        // Current key order
-        let currentKeys = [];
-        // Create anchor comment node - marks the position of the list
+        const { list, map } = props;
+        const key = props.key ?? ((item) => item);
+        // Create anchor comment node
         const anchor = document.createComment('kt-for');
-        /**
-         * Get all nodes currently in the DOM that belong to this list
-         * They are all siblings after the anchor node
-         */
-        const getListNodes = () => {
-            const nodes = [];
-            if (!anchor.parentNode)
-                return nodes;
-            let current = anchor.nextSibling;
-            new Set(currentKeys);
-            // Collect nodes that belong to this list
-            while (current) {
-                const isListNode = Array.from(nodeCache.values()).some((cached) => cached.node === current);
-                if (!isListNode)
-                    break;
-                nodes.push(current);
-                current = current.nextSibling;
-            }
-            return nodes;
-        };
-        /**
-         * Initialize list - append all initial items after anchor
-         */
-        const initialize = () => {
-            for (let i = 0; i < initList.length; i++) {
-                const item = initList[i];
-                const key = getKey(item, i);
-                const node = mapper(item, i);
-                nodeCache.set(key, { node, item });
-                currentKeys.push(key);
-                // Append to parent if anchor is already in DOM
-                if (anchor.parentNode) {
-                    const lastNode = getListNodes()[getListNodes().length - 1];
-                    if (lastNode) {
-                        lastNode.after(node);
-                    }
-                    else {
-                        anchor.after(node);
-                    }
-                }
-            }
-        };
-        /**
-         * Smart update method - only modifies DOM nodes that changed
-         * Uses key-based diff algorithm to minimize DOM operations
-         */
-        const smartUpdate = (newList, newMapper) => {
-            const mapperFn = newMapper ?? mapper;
-            const newKeys = newList.map((item, index) => getKey(item, index));
-            if (!anchor.parentNode) {
-                // If anchor is not in DOM yet, just update cache
-                nodeCache.clear();
-                currentKeys = [];
-                for (let i = 0; i < newList.length; i++) {
-                    const item = newList[i];
-                    const key = newKeys[i];
-                    const node = mapperFn(item, i);
-                    nodeCache.set(key, { node, item });
-                    currentKeys.push(key);
-                }
-                return;
-            }
-            // Find keys to remove (exist in current but not in new)
-            const keysToRemove = currentKeys.filter((k) => !newKeys.includes(k));
-            for (let i = 0; i < keysToRemove.length; i++) {
-                const key = keysToRemove[i];
-                const cached = nodeCache.get(key);
-                if (cached && cached.node.parentNode) {
-                    cached.node.parentNode.removeChild(cached.node);
+        // Store current state
+        let currentList = list;
+        let currentKey = key;
+        let currentMap = map;
+        // Map to track rendered nodes by key
+        const nodeMap = new Map();
+        // Render initial list
+        const elements = [];
+        for (let index = 0; index < currentList.length; index++) {
+            const item = currentList[index];
+            const itemKey = currentKey(item, index, currentList);
+            const node = currentMap(item, index, currentList);
+            nodeMap.set(itemKey, node);
+            elements.push(node);
+        }
+        // Attach elements array to anchor
+        anchor.__kt_for_list__ = elements;
+        // Redraw function for updates
+        anchor.redraw = (newProps = props) => {
+            const newList = (newProps.list ?? currentList);
+            const newKey = (newProps.key ?? currentKey);
+            const newMap = (newProps.map ?? currentMap);
+            // Update stored values
+            currentList = newList;
+            currentKey = newKey;
+            currentMap = newMap;
+            const parent = anchor.parentNode;
+            if (!parent) {
+                // If not in DOM yet, just rebuild the list
+                const newElements = [];
+                for (let index = 0; index < currentList.length; index++) {
+                    const item = currentList[index];
+                    const itemKey = currentKey(item, index, currentList);
+                    const node = currentMap(item, index, currentList);
+                    nodeMap.set(itemKey, node);
+                    newElements.push(node);
                 }
-                nodeCache.delete(key);
+                anchor.__kt_for_list__ = newElements;
+                return anchor;
             }
-            // Update/add nodes in correct order
-            let previousNode = anchor;
-            for (let i = 0; i < newList.length; i++) {
-                const item = newList[i];
-                const key = newKeys[i];
-                let cached = nodeCache.get(key);
-                // New item: create and cache
-                if (!cached) {
-                    const node = mapperFn(item, i);
-                    cached = { node, item };
-                    nodeCache.set(key, cached);
+            // Build new key map
+            const newNodeMap = new Map();
+            const newKeys = new Set();
+            const newElements = [];
+            for (let index = 0; index < newList.length; index++) {
+                const item = newList[index];
+                const itemKey = newKey(item, index, newList);
+                newKeys.add(itemKey);
+                // Reuse existing node if key exists
+                if (nodeMap.has(itemKey)) {
+                    const existingNode = nodeMap.get(itemKey);
+                    newNodeMap.set(itemKey, existingNode);
+                    newElements.push(existingNode);
                 }
                 else {
-                    // Update cached item reference
-                    cached.item = item;
-                }
-                // Ensure node is at correct position (right after previousNode)
-                if (previousNode.nextSibling !== cached.node) {
-                    if (previousNode.nextSibling) {
-                        anchor.parentNode.insertBefore(cached.node, previousNode.nextSibling);
-                    }
-                    else {
-                        anchor.parentNode.appendChild(cached.node);
-                    }
+                    // Create new node
+                    const node = newMap(item, index, newList);
+                    newNodeMap.set(itemKey, node);
+                    newElements.push(node);
                 }
-                previousNode = cached.node;
-            }
-            currentKeys = newKeys;
-        };
-        // Mount redraw method on anchor
-        anchor.redraw = (newProps) => {
-            if (newProps?.list) {
-                smartUpdate(newProps.list, newProps.mapper);
             }
-        };
-        // Initialize the list
-        initialize();
-        return anchor;
-    }
-    /**
-     * Simple list rendering without key optimization
-     * Rebuilds the entire list on each update - use for small static lists
-     *
-     * Returns a Comment anchor node. All items are rendered after this anchor.
-     *
-     * @example
-     * ```tsx
-     * const listAnchor = <KTForStatic
-     *   list={items}
-     *   mapper={(item) => <div>{item}</div>}
-     * /> as KTForAnchor;
-     * ```
-     */
-    function KTForStatic(props) {
-        const { list: initList, mapper } = props;
-        // Create anchor comment node
-        const anchor = document.createComment('kt-for-static');
-        let nodes = [];
-        // Simple rebuild on redraw
-        const rebuild = (newList) => {
-            // Remove all old nodes
-            for (let i = 0; i < nodes.length; i++) {
-                const node = nodes[i];
-                if (node.parentNode) {
-                    node.parentNode.removeChild(node);
+            // Remove nodes that are no longer in the list
+            nodeMap.forEach((node, key) => {
+                if (!newKeys.has(key)) {
+                    node.remove();
                 }
-            }
-            nodes = [];
-            // Create new nodes
-            let previousNode = anchor;
-            for (let i = 0; i < newList.length; i++) {
-                const item = newList[i];
-                const node = mapper(item, i);
-                nodes.push(node);
-                if (anchor.parentNode) {
-                    if (previousNode.nextSibling) {
-                        anchor.parentNode.insertBefore(node, previousNode.nextSibling);
-                    }
-                    else {
-                        anchor.parentNode.appendChild(node);
-                    }
-                    previousNode = node;
+            });
+            // Insert/reorder nodes in correct order
+            let referenceNode = anchor.nextSibling;
+            for (let index = 0; index < newElements.length; index++) {
+                const node = newElements[index];
+                // If node is not in correct position, insert it
+                if (referenceNode !== node) {
+                    parent.insertBefore(node, referenceNode);
                 }
+                referenceNode = node.nextSibling;
             }
+            // Update node map and element list
+            nodeMap.clear();
+            newNodeMap.forEach((node, key) => nodeMap.set(key, node));
+            anchor.__kt_for_list__ = newElements;
+            return anchor;
         };
-        // Initial render
-        rebuild(initList);
-        // Mount redraw
-        anchor.redraw = (newProps) => {
-            if (newProps?.list) {
-                rebuild(newProps.list);
-            }
-        };
+        // Set ref if provided
+        if (props.ref?.isKT) {
+            props.ref.value = anchor;
+        }
         return anchor;
     }
 
     exports.Fragment = Fragment;
     exports.KTAsync = KTAsync;
     exports.KTFor = KTFor;
-    exports.KTForStatic = KTForStatic;
     exports.createElement = h;
     exports.createRedrawable = createRedrawable;
     exports.createRedrawableNoref = createRedrawableNoref;

package/dist/index.legacy.js

@@ -180,6 +180,11 @@ var __ktjs_core__ = (function (exports) {
         }
         else {
             $append.call(element, c);
+            // Handle KTFor anchor
+            var list = c.__kt_for_list__;
+            if ($isArray(list)) {
+                apd(element, list);
+            }
         }
     }
     function apd(element, c) {
@@ -231,7 +236,7 @@ var __ktjs_core__ = (function (exports) {
      * ## About
      * @package @ktjs/core
      * @author Kasukabe Tsumugi <futami16237@gmail.com>
-     * @version 0.16.0 (Last Update: 2026.01.27 17:30:39.673)
+     * @version 0.17.0 (Last Update: 2026.01.28 15:11:59.247)
      * @license MIT
      * @link https://github.com/baendlorel/kt.js
      * @link https://baendlorel.github.io/ Welcome to my site!
@@ -444,205 +449,110 @@ var __ktjs_core__ = (function (exports) {
     }
 
     /**
-     * KTFor component - Efficient list rendering with key-based DOM reuse
-     * Similar to Svelte's {#each} blocks, provides optimized updates
-     *
-     * Returns a Comment node as anchor point. All list items are rendered after this anchor.
-     *
-     * @example
-     * ```tsx
-     * const listAnchor = <KTFor
-     *   list={items}
-     *   key={(item) => item.id}
-     *   mapper={(item) => <div>{item.name}</div>}
-     * /> as KTForAnchor;
-     *
-     * document.body.appendChild(listAnchor); // Anchor + all items are rendered
-     *
-     * // Update the list
-     * listAnchor.redraw({ list: newItems });
-     * ```
+     * KTFor - List rendering component with key-based optimization
+     * Returns a Comment anchor node with rendered elements in __kt_for_list__
      */
     function KTFor(props) {
-        var initList = props.list, getKey = props.key, mapper = props.mapper;
-        // Cache: key -> { node: HTMLElement, item: T }
-        var nodeCache = new Map();
-        // Current key order
-        var currentKeys = [];
-        // Create anchor comment node - marks the position of the list
+        var _a, _b;
+        var list = props.list, map = props.map;
+        var key = (_a = props.key) !== null && _a !== void 0 ? _a : (function (item) { return item; });
+        // Create anchor comment node
         var anchor = document.createComment('kt-for');
-        /**
-         * Get all nodes currently in the DOM that belong to this list
-         * They are all siblings after the anchor node
-         */
-        var getListNodes = function () {
-            var nodes = [];
-            if (!anchor.parentNode)
-                return nodes;
-            var current = anchor.nextSibling;
-            new Set(currentKeys);
-            // Collect nodes that belong to this list
-            while (current) {
-                var isListNode = Array.from(nodeCache.values()).some(function (cached) { return cached.node === current; });
-                if (!isListNode)
-                    break;
-                nodes.push(current);
-                current = current.nextSibling;
-            }
-            return nodes;
-        };
-        /**
-         * Initialize list - append all initial items after anchor
-         */
-        var initialize = function () {
-            for (var i = 0; i < initList.length; i++) {
-                var item = initList[i];
-                var key = getKey(item, i);
-                var node = mapper(item, i);
-                nodeCache.set(key, { node: node, item: item });
-                currentKeys.push(key);
-                // Append to parent if anchor is already in DOM
-                if (anchor.parentNode) {
-                    var lastNode = getListNodes()[getListNodes().length - 1];
-                    if (lastNode) {
-                        lastNode.after(node);
-                    }
-                    else {
-                        anchor.after(node);
-                    }
-                }
-            }
-        };
-        /**
-         * Smart update method - only modifies DOM nodes that changed
-         * Uses key-based diff algorithm to minimize DOM operations
-         */
-        var smartUpdate = function (newList, newMapper) {
-            var mapperFn = newMapper !== null && newMapper !== void 0 ? newMapper : mapper;
-            var newKeys = newList.map(function (item, index) { return getKey(item, index); });
-            if (!anchor.parentNode) {
-                // If anchor is not in DOM yet, just update cache
-                nodeCache.clear();
-                currentKeys = [];
-                for (var i = 0; i < newList.length; i++) {
-                    var item = newList[i];
-                    var key = newKeys[i];
-                    var node = mapperFn(item, i);
-                    nodeCache.set(key, { node: node, item: item });
-                    currentKeys.push(key);
-                }
-                return;
-            }
-            // Find keys to remove (exist in current but not in new)
-            var keysToRemove = currentKeys.filter(function (k) { return !newKeys.includes(k); });
-            for (var i = 0; i < keysToRemove.length; i++) {
-                var key = keysToRemove[i];
-                var cached = nodeCache.get(key);
-                if (cached && cached.node.parentNode) {
-                    cached.node.parentNode.removeChild(cached.node);
+        // Store current state
+        var currentList = list;
+        var currentKey = key;
+        var currentMap = map;
+        // Map to track rendered nodes by key
+        var nodeMap = new Map();
+        // Render initial list
+        var elements = [];
+        for (var index = 0; index < currentList.length; index++) {
+            var item = currentList[index];
+            var itemKey = currentKey(item, index, currentList);
+            var node = currentMap(item, index, currentList);
+            nodeMap.set(itemKey, node);
+            elements.push(node);
+        }
+        // Attach elements array to anchor
+        anchor.__kt_for_list__ = elements;
+        // Redraw function for updates
+        anchor.redraw = function (newProps) {
+            var _a, _b, _c;
+            if (newProps === void 0) { newProps = props; }
+            var newList = ((_a = newProps.list) !== null && _a !== void 0 ? _a : currentList);
+            var newKey = ((_b = newProps.key) !== null && _b !== void 0 ? _b : currentKey);
+            var newMap = ((_c = newProps.map) !== null && _c !== void 0 ? _c : currentMap);
+            // Update stored values
+            currentList = newList;
+            currentKey = newKey;
+            currentMap = newMap;
+            var parent = anchor.parentNode;
+            if (!parent) {
+                // If not in DOM yet, just rebuild the list
+                var newElements_1 = [];
+                for (var index = 0; index < currentList.length; index++) {
+                    var item = currentList[index];
+                    var itemKey = currentKey(item, index, currentList);
+                    var node = currentMap(item, index, currentList);
+                    nodeMap.set(itemKey, node);
+                    newElements_1.push(node);
                 }
-                nodeCache.delete(key);
+                anchor.__kt_for_list__ = newElements_1;
+                return anchor;
             }
-            // Update/add nodes in correct order
-            var previousNode = anchor;
-            for (var i = 0; i < newList.length; i++) {
-                var item = newList[i];
-                var key = newKeys[i];
-                var cached = nodeCache.get(key);
-                // New item: create and cache
-                if (!cached) {
-                    var node = mapperFn(item, i);
-                    cached = { node: node, item: item };
-                    nodeCache.set(key, cached);
+            // Build new key map
+            var newNodeMap = new Map();
+            var newKeys = new Set();
+            var newElements = [];
+            for (var index = 0; index < newList.length; index++) {
+                var item = newList[index];
+                var itemKey = newKey(item, index, newList);
+                newKeys.add(itemKey);
+                // Reuse existing node if key exists
+                if (nodeMap.has(itemKey)) {
+                    var existingNode = nodeMap.get(itemKey);
+                    newNodeMap.set(itemKey, existingNode);
+                    newElements.push(existingNode);
                 }
                 else {
-                    // Update cached item reference
-                    cached.item = item;
+                    // Create new node
+                    var node = newMap(item, index, newList);
+                    newNodeMap.set(itemKey, node);
+                    newElements.push(node);
                 }
-                // Ensure node is at correct position (right after previousNode)
-                if (previousNode.nextSibling !== cached.node) {
-                    if (previousNode.nextSibling) {
-                        anchor.parentNode.insertBefore(cached.node, previousNode.nextSibling);
-                    }
-                    else {
-                        anchor.parentNode.appendChild(cached.node);
-                    }
-                }
-                previousNode = cached.node;
-            }
-            currentKeys = newKeys;
-        };
-        // Mount redraw method on anchor
-        anchor.redraw = function (newProps) {
-            if (newProps === null || newProps === void 0 ? void 0 : newProps.list) {
-                smartUpdate(newProps.list, newProps.mapper);
             }
-        };
-        // Initialize the list
-        initialize();
-        return anchor;
-    }
-    /**
-     * Simple list rendering without key optimization
-     * Rebuilds the entire list on each update - use for small static lists
-     *
-     * Returns a Comment anchor node. All items are rendered after this anchor.
-     *
-     * @example
-     * ```tsx
-     * const listAnchor = <KTForStatic
-     *   list={items}
-     *   mapper={(item) => <div>{item}</div>}
-     * /> as KTForAnchor;
-     * ```
-     */
-    function KTForStatic(props) {
-        var initList = props.list, mapper = props.mapper;
-        // Create anchor comment node
-        var anchor = document.createComment('kt-for-static');
-        var nodes = [];
-        // Simple rebuild on redraw
-        var rebuild = function (newList) {
-            // Remove all old nodes
-            for (var i = 0; i < nodes.length; i++) {
-                var node = nodes[i];
-                if (node.parentNode) {
-                    node.parentNode.removeChild(node);
+            // Remove nodes that are no longer in the list
+            nodeMap.forEach(function (node, key) {
+                if (!newKeys.has(key)) {
+                    node.remove();
                 }
-            }
-            nodes = [];
-            // Create new nodes
-            var previousNode = anchor;
-            for (var i = 0; i < newList.length; i++) {
-                var item = newList[i];
-                var node = mapper(item, i);
-                nodes.push(node);
-                if (anchor.parentNode) {
-                    if (previousNode.nextSibling) {
-                        anchor.parentNode.insertBefore(node, previousNode.nextSibling);
-                    }
-                    else {
-                        anchor.parentNode.appendChild(node);
-                    }
-                    previousNode = node;
+            });
+            // Insert/reorder nodes in correct order
+            var referenceNode = anchor.nextSibling;
+            for (var index = 0; index < newElements.length; index++) {
+                var node = newElements[index];
+                // If node is not in correct position, insert it
+                if (referenceNode !== node) {
+                    parent.insertBefore(node, referenceNode);
                 }
+                referenceNode = node.nextSibling;
             }
+            // Update node map and element list
+            nodeMap.clear();
+            newNodeMap.forEach(function (node, key) { return nodeMap.set(key, node); });
+            anchor.__kt_for_list__ = newElements;
+            return anchor;
         };
-        // Initial render
-        rebuild(initList);
-        // Mount redraw
-        anchor.redraw = function (newProps) {
-            if (newProps === null || newProps === void 0 ? void 0 : newProps.list) {
-                rebuild(newProps.list);
-            }
-        };
+        // Set ref if provided
+        if ((_b = props.ref) === null || _b === void 0 ? void 0 : _b.isKT) {
+            props.ref.value = anchor;
+        }
         return anchor;
     }
 
     exports.Fragment = Fragment;
     exports.KTAsync = KTAsync;
     exports.KTFor = KTFor;
-    exports.KTForStatic = KTForStatic;
     exports.createElement = h;
     exports.createRedrawable = createRedrawable;
     exports.createRedrawableNoref = createRedrawableNoref;

package/dist/index.mjs

@@ -155,6 +155,11 @@ function apdSingle(element, c) {
     }
     else {
         $append.call(element, c);
+        // Handle KTFor anchor
+        const list = c.__kt_for_list__;
+        if ($isArray(list)) {
+            apd(element, list);
+        }
     }
 }
 function apd(element, c) {
@@ -203,7 +208,7 @@ let creator = defaultCreator;
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.16.0 (Last Update: 2026.01.27 17:30:39.673)
+ * @version 0.17.0 (Last Update: 2026.01.28 15:11:59.247)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -376,199 +381,102 @@ function KTAsync(props) {
 }
 
 /**
- * KTFor component - Efficient list rendering with key-based DOM reuse
- * Similar to Svelte's {#each} blocks, provides optimized updates
- *
- * Returns a Comment node as anchor point. All list items are rendered after this anchor.
- *
- * @example
- * ```tsx
- * const listAnchor = <KTFor
- *   list={items}
- *   key={(item) => item.id}
- *   mapper={(item) => <div>{item.name}</div>}
- * /> as KTForAnchor;
- *
- * document.body.appendChild(listAnchor); // Anchor + all items are rendered
- *
- * // Update the list
- * listAnchor.redraw({ list: newItems });
- * ```
+ * KTFor - List rendering component with key-based optimization
+ * Returns a Comment anchor node with rendered elements in __kt_for_list__
  */
 function KTFor(props) {
-    const { list: initList, key: getKey, mapper } = props;
-    // Cache: key -> { node: HTMLElement, item: T }
-    const nodeCache = new Map();
-    // Current key order
-    let currentKeys = [];
-    // Create anchor comment node - marks the position of the list
+    const { list, map } = props;
+    const key = props.key ?? ((item) => item);
+    // Create anchor comment node
     const anchor = document.createComment('kt-for');
-    /**
-     * Get all nodes currently in the DOM that belong to this list
-     * They are all siblings after the anchor node
-     */
-    const getListNodes = () => {
-        const nodes = [];
-        if (!anchor.parentNode)
-            return nodes;
-        let current = anchor.nextSibling;
-        new Set(currentKeys);
-        // Collect nodes that belong to this list
-        while (current) {
-            const isListNode = Array.from(nodeCache.values()).some((cached) => cached.node === current);
-            if (!isListNode)
-                break;
-            nodes.push(current);
-            current = current.nextSibling;
-        }
-        return nodes;
-    };
-    /**
-     * Initialize list - append all initial items after anchor
-     */
-    const initialize = () => {
-        for (let i = 0; i < initList.length; i++) {
-            const item = initList[i];
-            const key = getKey(item, i);
-            const node = mapper(item, i);
-            nodeCache.set(key, { node, item });
-            currentKeys.push(key);
-            // Append to parent if anchor is already in DOM
-            if (anchor.parentNode) {
-                const lastNode = getListNodes()[getListNodes().length - 1];
-                if (lastNode) {
-                    lastNode.after(node);
-                }
-                else {
-                    anchor.after(node);
-                }
-            }
-        }
-    };
-    /**
-     * Smart update method - only modifies DOM nodes that changed
-     * Uses key-based diff algorithm to minimize DOM operations
-     */
-    const smartUpdate = (newList, newMapper) => {
-        const mapperFn = newMapper ?? mapper;
-        const newKeys = newList.map((item, index) => getKey(item, index));
-        if (!anchor.parentNode) {
-            // If anchor is not in DOM yet, just update cache
-            nodeCache.clear();
-            currentKeys = [];
-            for (let i = 0; i < newList.length; i++) {
-                const item = newList[i];
-                const key = newKeys[i];
-                const node = mapperFn(item, i);
-                nodeCache.set(key, { node, item });
-                currentKeys.push(key);
-            }
-            return;
-        }
-        // Find keys to remove (exist in current but not in new)
-        const keysToRemove = currentKeys.filter((k) => !newKeys.includes(k));
-        for (let i = 0; i < keysToRemove.length; i++) {
-            const key = keysToRemove[i];
-            const cached = nodeCache.get(key);
-            if (cached && cached.node.parentNode) {
-                cached.node.parentNode.removeChild(cached.node);
+    // Store current state
+    let currentList = list;
+    let currentKey = key;
+    let currentMap = map;
+    // Map to track rendered nodes by key
+    const nodeMap = new Map();
+    // Render initial list
+    const elements = [];
+    for (let index = 0; index < currentList.length; index++) {
+        const item = currentList[index];
+        const itemKey = currentKey(item, index, currentList);
+        const node = currentMap(item, index, currentList);
+        nodeMap.set(itemKey, node);
+        elements.push(node);
+    }
+    // Attach elements array to anchor
+    anchor.__kt_for_list__ = elements;
+    // Redraw function for updates
+    anchor.redraw = (newProps = props) => {
+        const newList = (newProps.list ?? currentList);
+        const newKey = (newProps.key ?? currentKey);
+        const newMap = (newProps.map ?? currentMap);
+        // Update stored values
+        currentList = newList;
+        currentKey = newKey;
+        currentMap = newMap;
+        const parent = anchor.parentNode;
+        if (!parent) {
+            // If not in DOM yet, just rebuild the list
+            const newElements = [];
+            for (let index = 0; index < currentList.length; index++) {
+                const item = currentList[index];
+                const itemKey = currentKey(item, index, currentList);
+                const node = currentMap(item, index, currentList);
+                nodeMap.set(itemKey, node);
+                newElements.push(node);
             }
-            nodeCache.delete(key);
+            anchor.__kt_for_list__ = newElements;
+            return anchor;
         }
-        // Update/add nodes in correct order
-        let previousNode = anchor;
-        for (let i = 0; i < newList.length; i++) {
-            const item = newList[i];
-            const key = newKeys[i];
-            let cached = nodeCache.get(key);
-            // New item: create and cache
-            if (!cached) {
-                const node = mapperFn(item, i);
-                cached = { node, item };
-                nodeCache.set(key, cached);
+        // Build new key map
+        const newNodeMap = new Map();
+        const newKeys = new Set();
+        const newElements = [];
+        for (let index = 0; index < newList.length; index++) {
+            const item = newList[index];
+            const itemKey = newKey(item, index, newList);
+            newKeys.add(itemKey);
+            // Reuse existing node if key exists
+            if (nodeMap.has(itemKey)) {
+                const existingNode = nodeMap.get(itemKey);
+                newNodeMap.set(itemKey, existingNode);
+                newElements.push(existingNode);
             }
             else {
-                // Update cached item reference
-                cached.item = item;
-            }
-            // Ensure node is at correct position (right after previousNode)
-            if (previousNode.nextSibling !== cached.node) {
-                if (previousNode.nextSibling) {
-                    anchor.parentNode.insertBefore(cached.node, previousNode.nextSibling);
-                }
-                else {
-                    anchor.parentNode.appendChild(cached.node);
-                }
+                // Create new node
+                const node = newMap(item, index, newList);
+                newNodeMap.set(itemKey, node);
+                newElements.push(node);
             }
-            previousNode = cached.node;
-        }
-        currentKeys = newKeys;
-    };
-    // Mount redraw method on anchor
-    anchor.redraw = (newProps) => {
-        if (newProps?.list) {
-            smartUpdate(newProps.list, newProps.mapper);
         }
-    };
-    // Initialize the list
-    initialize();
-    return anchor;
-}
-/**
- * Simple list rendering without key optimization
- * Rebuilds the entire list on each update - use for small static lists
- *
- * Returns a Comment anchor node. All items are rendered after this anchor.
- *
- * @example
- * ```tsx
- * const listAnchor = <KTForStatic
- *   list={items}
- *   mapper={(item) => <div>{item}</div>}
- * /> as KTForAnchor;
- * ```
- */
-function KTForStatic(props) {
-    const { list: initList, mapper } = props;
-    // Create anchor comment node
-    const anchor = document.createComment('kt-for-static');
-    let nodes = [];
-    // Simple rebuild on redraw
-    const rebuild = (newList) => {
-        // Remove all old nodes
-        for (let i = 0; i < nodes.length; i++) {
-            const node = nodes[i];
-            if (node.parentNode) {
-                node.parentNode.removeChild(node);
+        // Remove nodes that are no longer in the list
+        nodeMap.forEach((node, key) => {
+            if (!newKeys.has(key)) {
+                node.remove();
             }
-        }
-        nodes = [];
-        // Create new nodes
-        let previousNode = anchor;
-        for (let i = 0; i < newList.length; i++) {
-            const item = newList[i];
-            const node = mapper(item, i);
-            nodes.push(node);
-            if (anchor.parentNode) {
-                if (previousNode.nextSibling) {
-                    anchor.parentNode.insertBefore(node, previousNode.nextSibling);
-                }
-                else {
-                    anchor.parentNode.appendChild(node);
-                }
-                previousNode = node;
+        });
+        // Insert/reorder nodes in correct order
+        let referenceNode = anchor.nextSibling;
+        for (let index = 0; index < newElements.length; index++) {
+            const node = newElements[index];
+            // If node is not in correct position, insert it
+            if (referenceNode !== node) {
+                parent.insertBefore(node, referenceNode);
             }
+            referenceNode = node.nextSibling;
         }
+        // Update node map and element list
+        nodeMap.clear();
+        newNodeMap.forEach((node, key) => nodeMap.set(key, node));
+        anchor.__kt_for_list__ = newElements;
+        return anchor;
     };
-    // Initial render
-    rebuild(initList);
-    // Mount redraw
-    anchor.redraw = (newProps) => {
-        if (newProps?.list) {
-            rebuild(newProps.list);
-        }
-    };
+    // Set ref if provided
+    if (props.ref?.isKT) {
+        props.ref.value = anchor;
+    }
     return anchor;
 }
 
-export { Fragment, KTAsync, KTFor, KTForStatic, h as createElement, createRedrawable, createRedrawableNoref, h, jsx, jsxDEV, jsxs, ref };
+export { Fragment, KTAsync, KTFor, h as createElement, createRedrawable, createRedrawableNoref, h, jsx, jsxDEV, jsxs, ref };

package/dist/jsx/index.d.ts

@@ -17,12 +17,13 @@ interface KTRef<T> {
  */
 declare function ref<T = HTMLElement>(value?: T): KTRef<T>;
 
-type KTHTMLElement<El extends HTMLElement = HTMLElement> = El & {
+type Redraw = (props?: KTAttribute, ...args: any[]) => KTHTMLElement;
+type KTHTMLElement<El extends HTMLElement = HTMLElement, R extends Function = Redraw> = El & {
   /**
    * Automically generate a redraw function if it is not provided
    * @param props
    */
-  redraw: (props?: KTAttribute, ...args: any[]) => KTHTMLElement;
+  redraw: R;
 };
 
 declare global {
@@ -44,7 +45,7 @@ declare global {
   }
 }
 
-type SingleContent = KTRef<any> | HTMLElement | Element | string | number | boolean | null | undefined;
+type SingleContent = KTRef<any> | HTMLElement | Element | Node | string | number | boolean | null | undefined;
 type KTAvailableContent = SingleContent | KTAvailableContent[];
 type KTRawContent = KTAvailableContent | Promise<KTAvailableContent>;
 type KTRawAttr = KTAttribute | string;
@@ -55,9 +56,11 @@ type KTRawAttr = KTAttribute | string;
 interface KTBaseAttribute {
   [k: string]: any;
 
+  // # kt-specific attributes
   ref?: KTRef<HTMLElement>;
   'k-if'?: any;
 
+  // # normal HTML attributes
   id?: string;
   class?: string;
   style?: string | Partial<CSSStyleDeclaration>;
@@ -154,7 +157,7 @@ type HTML<T extends (HTMLTag | SVGTag) & otherstring> = T extends SVGTag ? SVGEl
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.16.0 (Last Update: 2026.01.27 17:30:39.673)
+ * @version 0.17.0 (Last Update: 2026.01.28 15:11:59.247)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -218,4 +221,4 @@ declare function createRedrawableNoref(creator: () => KTHTMLElement): KTHTMLElem
 declare function createRedrawable(creator: () => KTHTMLElement): KTRef<KTHTMLElement>;
 
 export { Fragment, h as createElement, createRedrawable, createRedrawableNoref, jsx, jsxDEV, jsxs, ref };
-export type { KTHTMLElement, KTRef };
+export type { KTHTMLElement, KTRef, Redraw };

package/dist/jsx/index.mjs

@@ -155,6 +155,11 @@ function apdSingle(element, c) {
     }
     else {
         $append.call(element, c);
+        // Handle KTFor anchor
+        const list = c.__kt_for_list__;
+        if ($isArray(list)) {
+            apd(element, list);
+        }
     }
 }
 function apd(element, c) {
@@ -203,7 +208,7 @@ let creator = defaultCreator;
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.16.0 (Last Update: 2026.01.27 17:30:39.673)
+ * @version 0.17.0 (Last Update: 2026.01.28 15:11:59.247)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!

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

@@ -11,12 +11,13 @@ interface KTRef<T> {
     isKT: true;
 }
 
-type KTHTMLElement<El extends HTMLElement = HTMLElement> = El & {
+type Redraw = (props?: KTAttribute, ...args: any[]) => KTHTMLElement;
+type KTHTMLElement<El extends HTMLElement = HTMLElement, R extends Function = Redraw> = El & {
   /**
    * Automically generate a redraw function if it is not provided
    * @param props
    */
-  redraw: (props?: KTAttribute, ...args: any[]) => KTHTMLElement;
+  redraw: R;
 };
 
 declare global {
@@ -38,7 +39,7 @@ declare global {
   }
 }
 
-type SingleContent = KTRef<any> | HTMLElement | Element | string | number | boolean | null | undefined;
+type SingleContent = KTRef<any> | HTMLElement | Element | Node | string | number | boolean | null | undefined;
 type KTAvailableContent = SingleContent | KTAvailableContent[];
 type KTRawContent = KTAvailableContent | Promise<KTAvailableContent>;
 type KTRawAttr = KTAttribute | string;
@@ -49,9 +50,11 @@ type KTRawAttr = KTAttribute | string;
 interface KTBaseAttribute {
   [k: string]: any;
 
+  // # kt-specific attributes
   ref?: KTRef<HTMLElement>;
   'k-if'?: any;
 
+  // # normal HTML attributes
   id?: string;
   class?: string;
   style?: string | Partial<CSSStyleDeclaration>;
@@ -148,7 +151,7 @@ type HTML<T extends (HTMLTag | SVGTag) & otherstring> = T extends SVGTag ? SVGEl
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.16.0 (Last Update: 2026.01.27 17:30:39.673)
+ * @version 0.17.0 (Last Update: 2026.01.28 15:11:59.247)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!

package/dist/jsx/jsx-runtime.mjs

@@ -155,6 +155,11 @@ function apdSingle(element, c) {
     }
     else {
         $append.call(element, c);
+        // Handle KTFor anchor
+        const list = c.__kt_for_list__;
+        if ($isArray(list)) {
+            apd(element, list);
+        }
     }
 }
 function apd(element, c) {
@@ -203,7 +208,7 @@ let creator = defaultCreator;
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.16.0 (Last Update: 2026.01.27 17:30:39.673)
+ * @version 0.17.0 (Last Update: 2026.01.28 15:11:59.247)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!

package/package.json

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