kt.js 0.23.0 → 0.24.1

package/README.md

@@ -1,43 +1,54 @@
-<img src="https://raw.githubusercontent.com/baendlorel/kt.js/dev/.assets/ktjs-0.0.1.svg" alt="KT.js Logo" width="150"/>
+# KT.js
 
-[![npm version](https://img.shields.io/npm/v/kt.js.svg)](https://www.npmjs.com/package/kt.js) [![license](https://img.shields.io/github/license/baendlorel/kt.js.svg)](https://github.com/baendlorel/kt.js/blob/main/LICENSE)
+A lightweight, manual‑control web framework that creates real DOM elements with built‑in reactive state management.
 
-[CHANGLOG✨](../../CHANGELOG.md)
+[![npm version](https://img.shields.io/npm/v/kt.js.svg)](https://www.npmjs.com/package/kt.js)
+[![npm downloads](https://img.shields.io/npm/dm/kt.js.svg)](https://www.npmjs.com/package/kt.js)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-> Note: This framework is still under development. APIs, type declarations, and other parts **may change frequently**. If you use it, please watch for updates in the near future. Feel free to mail me if you have any questions!
+[Changelog](../../CHANGELOG.md)
 
-KT.js is a tiny DOM utility focused on direct DOM manipulation. It favors not forcing re-renders and aims to keep DOM updates to the absolute minimum for maximum performance.
+## Features
 
-For more awesome packages, check out [my homepage💛](https://baendlorel.github.io/?repoType=npm)
+- **Real DOM** – JSX compiles directly to `HTMLElement` creation, with zero virtual‑DOM overhead.
+- **Manual Updates** – You decide when the DOM updates; no automatic re‑renders.
+- **Reactive State** – Built‑in `ref()` and `computed()` for reactive values with change listeners.
+- **Zero Forced Re‑renders** – Update only what changes; avoid full‑component repaints.
+- **Full TypeScript Support** – Accurate type inference and JSX/TSX integration.
+- **Lightweight** – Small bundle size, no unnecessary dependencies.
 
-## Architecture
+## Quick Start
 
-KT.js is now a **monorepo** containing multiple packages:
-
-- **[kt.js](./packages/kt.js)**: Main entry package that re-exports all functionality
-- **[@ktjs/core](./packages/core)**: Core DOM manipulation utilities and the `h` function. SX/TSX support with full TypeScript integration (included in kt.js package)
-- **[@ktjs/router](./packages/router)**: Client-side routing with navigation guards (not included in kt.js package)
-- **[@ktjs/mui](./packages/mui)**: Material UI components built on top of KT.js (not included in kt.js package)
-
-You can install the full package or individual packages as needed:
+### Installation
 
 ```bash
+# Full package (includes core)
 pnpm add kt.js
 
-# Or install individual packages
-pnpm add @ktjs/router     # Client-side router (requires @ktjs/core)
-pnpm add @ktjs/mui        # Material UI components (requires @ktjs/core)
+# Individual packages
+pnpm add @ktjs/core @ktjs/router
 ```
 
-## Philosophy
+### Basic Usage
 
-As a web framework, repeatedly creating a large number of variables and objects is unacceptable. So I created KT.js.
+```tsx
+import { ref } from 'kt.js';
 
-KT.js follows one rule: **full control of DOM and avoid unnecessary repainting**.
+function Counter() {
+  const count = ref(0);
 
-## Configuration
+  const button = <button on:click={() => count.value++}>Count: {count.value}</button>;
 
-for TSX/JSX support, add this to your `tsconfig.json`:
+  return button;
+}
+
+// Mount to DOM
+document.body.appendChild(Counter());
+```
+
+### TypeScript Configuration
+
+For JSX/TSX support, set your `tsconfig.json`:
 
 ```json
 {
@@ -48,192 +59,136 @@ for TSX/JSX support, add this to your `tsconfig.json`:
 }
 ```
 
-## Core Features (@ktjs/core)
+## Core Features
 
-### JSX/TSX Support
-
-KT.js provides first-class JSX/TSX support with zero virtual DOM overhead. JSX compiles directly to `h()` function calls.
+### Reactive System
 
 ```tsx
-// Function components
-const Button = ({ onClick, children }) => (
-  <button on:click={onClick} class="btn">
-    {children}
-  </button>
-);
-
-// Conditional rendering with k-if
-const UserCard = ({ user, showDetails }) => (
-  <div class="card">
-    <h3>{user.name}</h3>
-    <div k-if={showDetails}>
-      <p>Email: {user.email}</p>
-      <p>Role: {user.role}</p>
-    </div>
-  </div>
-);
+import { ref, computed } from 'kt.js';
 
-// List rendering with KTFor
-const UserList = ({ users }) => <KTFor list={users} key={(user) => user.id} map={(user) => <UserCard user={user} />} />;
+// Reactive references
+const count = ref(0);
+const double = computed(() => count.value * 2, [count]);
 
-// Async components
-const AsyncContent = async () => {
-  const data = await fetchData();
-  return <div>{data}</div>;
-};
-```
+// Listen to changes
+count.addOnChange((newVal, oldVal) => {
+  console.log(`Count changed from ${oldVal} to ${newVal}`);
+});
 
-### Directives
+// Update triggers change listeners
+count.value = 10;
+```
 
-#### `k-if`: Conditional rendering.
+### Conditional Rendering
 
 ```tsx
-<div k-if={condition}>This will render only if condition is true.</div>
-```
+const show = ref(true);
 
-If a `ref` instance is bound, the element will automatically redraw on changes.
+const element = <div k-if={show}>This content is conditionally rendered</div>;
 
-#### `k-model`: Two-way data binding for form elements.
+// Toggle visibility
+show.value = false; // Element becomes a comment placeholder
+```
 
-Must bind to a `ref` instance.
+### List Rendering
 
 ```tsx
-import { ref } from 'kt.js';
-const name = ref('');
+import { KTFor, ref } from 'kt.js';
 
-function NameInput() {
-  return (
-    <div>
-      <input type="text" k-model={name} />
-    </div>
-  );
-}
+const items = ref([
+  { id: 1, name: 'Item 1' },
+  { id: 2, name: 'Item 2' },
+]);
 
-name.value = 'New Name'; // Updates input value
-```
+const list = <KTFor list={items.value} key={(item) => item.id} map={(item) => <div>{item.name}</div>} />;
 
-### CreateRedrawable
+// Update list
+items.value = [...items.value, { id: 3, name: 'Item 3' }];
+```
 
-Create redrawable components with `createRedrawable()`.
+### Two‑way Data Binding
 
 ```tsx
-import { createRedrawable } from '@ktjs/core';
-let text = 'aa';
-const el = createRedrawable(() => <div>{text}</div>);
-// el is now `<div>aa</div>`
-text = 'bb';
-el.redraw();
-// el is now `<div>bb</div>`
+function InputComponent() {
+  const text = ref('');
+
+  return <input k-model={text} />;
+}
 ```
 
-### Reactive References
+### Redrawable Components
 
-Create reactive values with `ref()` and listen to changes.
+```tsx
+import { createRedrawable, ref } from 'kt.js';
 
-```typescript
-import { ref } from '@ktjs/core';
+function DynamicCounter() {
+  const count = ref(0);
 
-const count = ref(0);
-count.addOnChange((newVal, oldVal) => {
-  console.log(`Count changed from ${oldVal} to ${newVal}`);
-});
+  const counter = createRedrawable(() => (
+    <div>
+      Count: {count.value}
+      <button on:click={() => count.value++}>+</button>
+    </div>
+  ));
 
-// Update triggers change listeners
-count.value = 1;
+  // Redraw when count changes
+  count.addOnChange(() => counter.redraw());
+
+  return counter;
+}
 ```
 
-#### Surface Reactive Objects
+## Package Structure
 
-Create depth-1 reactive objects with `surfaceRef()`.
-Basically a helper of wrapping each property with `ref()`.
+- **[@ktjs/core](./packages/core)** – Core framework with JSX, reactivity, and DOM utilities.
+- **[@ktjs/router](./packages/router)** – Client‑side router with navigation guards.
+- **[@ktjs/mui](./packages/mui)** – Material UI components built on top of KT.js.
 
-```tsx
-const obj = surfaceRef({ a: 1, b: 2 });
-obj.a.value = 3; // Triggers change listeners for obj.a
+## Philosophy
 
-const data = obj.kcollect(); // Deref to the original object { a: 3, b: 2 }
-```
+KT.js follows one rule: **full control of the DOM and avoid unnecessary repainting**.
+
+As a web framework, repeatedly creating a large number of variables and objects is unacceptable. That’s why KT.js was built.
 
-### Redraw Mechanism
+## Advanced Usage
 
-`<KTFor... />` elements in-place with `redraw()` for minimal DOM updates.
+### Surface References
 
 ```tsx
-const element = <KTFor list={someArray} map={(v) => 2 * v} />;
-element.redraw({ list: [1, 2, 3] });
-```
+import { surfaceRef } from 'kt.js';
 
-## Router (@ktjs/router)
-
-Client-side hash-based routing with async navigation guards.
-
-### Basic Routing
-
-```typescript
-import { createRouter } from '@ktjs/router';
-
-const router = createRouter({
-  routes: [
-    {
-      path: '/',
-      name: 'home',
-      component: () => <HomePage />
-    },
-    {
-      path: '/user/:id',
-      name: 'user',
-      component: (to) => <UserPage id={to.params.id} />
-    }
-  ],
-  beforeEach: async (to, from) => {
-    // Auth check
-    if (to.path === '/admin' && !isAdmin()) {
-      return '/login';
-    }
-  }
+const user = surfaceRef({
+  name: 'John',
+  age: 30,
 });
-```
-
-### Navigation
 
-```typescript
-// Programmatic navigation
-router.push('/user/123');
-router.push({ name: 'user', params: { id: '456' } });
+// Access reactive properties
+user.name.value = 'Jane';
 
-// Access current route
-console.log(router.current?.path, router.current?.params);
+// Get the original object
+const original = user.kcollect();
 ```
 
-## Installation
+### Event Handling
 
-```bash
-# Full package (includes core)
-pnpm add kt.js
+```tsx
+const handleClick = (event) => {
+  console.log('Clicked!', event);
+};
 
-# Individual packages
-pnpm add @ktjs/core @ktjs/router
+const button = <button on:click={handleClick}>Click me</button>;
 ```
 
-## TypeScript Configuration
-
-For JSX/TSX support, configure your `tsconfig.json`:
+## Performance Benefits
 
-```json
-{
-  "compilerOptions": {
-    "jsx": "react-jsx",
-    "jsxImportSource": "@ktjs/core"
-  }
-}
-```
+- **No Virtual DOM** – Direct DOM manipulation eliminates reconciliation overhead.
+- **Manual Updates** – Only update what you need, when you need it.
+- **Minimal Abstraction** – Close to native DOM APIs for maximum performance.
+- **Small Bundle** – Minimal runtime overhead.
 
-## Philosophy
+## Browser Support
 
-- **Direct DOM Manipulation**: No virtual DOM, minimal abstraction
-- **Zero Re-renders**: Update only what changes, avoid full component re-renders
-- **Type Safety**: Full TypeScript support with accurate type inference
-- **Lightweight**: Small bundle size, no unnecessary dependencies
+KT.js supports all modern browsers and IE11+ with appropriate polyfills.
 
 ## License
 

package/dist/jsx-runtime.mjs

@@ -1,10 +1,34 @@
+// Shared constants
+// Empty for now - can be extended with framework-wide constants
+/**
+ * Mark the attribute as SVG to handle special cases during rendering.
+ */
+const SVG_ATTR_FLAG = '__kt_svg__';
+/**
+ * Mark the attribute as MathML to handle special cases during rendering.
+ */
+const MATHML_ATTR_FLAG = '__kt_mathml__';
+
 // Cached native methods for performance optimization
 const $isArray = Array.isArray;
-const $isThenable = (o) => typeof o === 'object' && o !== null && typeof o.then === 'function';
+const $is = Object.is;
+const $random = Math.random;
+const $isThenable = (o) => typeof o?.then === 'function';
 
 // DOM manipulation utilities
 // # dom natives
 const $isNode = (x) => x?.nodeType > 0;
+/**
+ * Safe replace `oldNode` With `newNode`
+ */
+const $replaceNode = (oldNode, newNode) => {
+    if ($isNode(oldNode) && $isNode(newNode)) {
+        if (newNode.contains(oldNode)) {
+            newNode.remove();
+        }
+        oldNode.replaceWith(newNode);
+    }
+};
 /**
  * & Remove `bind` because it is shockingly slower than wrapper
  * & `window.document` is safe because it is not configurable and its setter is undefined
@@ -50,85 +74,21 @@ const applyModel = (element, valueRef, propName, eventName) => {
     element.addEventListener(eventName, () => (valueRef.value = element[propName]));
 };
 
+if (typeof Symbol === 'undefined') {
+    window.Symbol = function Symbol(description) {
+        return `@@SYMBOL_${description || ''}_${$random().toString(36).slice(2)}`;
+    };
+}
+
 // Shared utilities and cached native methods for kt.js framework
-// import './misc/symbol-polyfill.js';
-// Re-export all utilities
-Object.defineProperty(window, '__ktjs__', { value: '0.22.3' });
+Object.defineProperty(window, '__ktjs__', { value: '0.22.6' });
 
-class KTRef {
-    /**
-     * Indicates that this is a KTRef instance
-     */
-    isKT = true;
-    /**
-     * @internal
-     */
-    _value;
-    /**
-     * @internal
-     */
-    _onChanges;
-    constructor(_value, _onChanges) {
-        this._value = _value;
-        this._onChanges = _onChanges;
-    }
-    /**
-     * If new value and old value are both nodes, the old one will be replaced in the DOM
-     */
-    get value() {
-        return this._value;
-    }
-    set value(newValue) {
-        if (newValue === this._value) {
-            return;
-        }
-        // replace the old node with the new one in the DOM if both are nodes
-        if (this._value instanceof Node && newValue instanceof Node) {
-            if (newValue.contains(this._value)) {
-                this._value.remove();
-            }
-            this._value.replaceWith(newValue);
-        }
-        const oldValue = this._value;
-        this._value = newValue;
-        for (let i = 0; i < this._onChanges.length; i++) {
-            this._onChanges[i](newValue, oldValue);
-        }
-    }
-    /**
-     * Register a callback when the value changes
-     * @param callback (newValue, oldValue) => xxx
-     */
-    addOnChange(callback) {
-        if (typeof callback !== 'function') {
-            throw new Error('[kt.js error] KTRef.addOnChange: callback must be a function');
-        }
-        this._onChanges.push(callback);
-    }
-    removeOnChange(callback) {
-        for (let i = this._onChanges.length - 1; i >= 0; i--) {
-            if (this._onChanges[i] === callback) {
-                this._onChanges.splice(i, 1);
-                return true;
-            }
-        }
-        return false;
-    }
-}
-const isKTRef = (obj) => obj?.isKT === true;
-/**
- * Reference to the created HTML element.
- * - **Only** respond to `ref.value` changes, not reactive to internal changes of the element.
- * - can alse be used to store normal values, but it is not reactive.
- * - if the value is already a `KTRef`, it will be returned **directly**.
- * @param value mostly an HTMLElement
- */
-function ref(value, onChange) {
-    if (isKTRef(value)) {
-        return value;
-    }
-    return new KTRef(value, []);
-}
+// export const KT_TYPE_REF = 1 as const;
+// export const KT_TYPE_COMPUTED = 2 as const;
+// export type KTReactiveTypeEnum = typeof KT_TYPE_REF | typeof KT_TYPE_COMPUTED;
+const isKT = (obj) => obj?.isKT;
+const isRef = (obj) => obj?.ktType === 1 /* KTReactiveType.REF */;
+const isComputed = (obj) => obj?.ktType === 2 /* KTReactiveType.COMPUTED */;
 
 const booleanHandler = (element, key, value) => {
     if (key in element) {
@@ -190,7 +150,7 @@ function attrIsObject(element, attr) {
     }
     if ('k-html' in attr) {
         const html = attr['k-html'];
-        if (isKTRef(html)) {
+        if (isKT(html)) {
             element.innerHTML = html.value;
             html.addOnChange((v) => (element.innerHTML = v));
         }
@@ -199,14 +159,14 @@ function attrIsObject(element, attr) {
         }
     }
     for (const key in attr) {
-        if (key === 'class' ||
+        if (key === 'k-if' ||
+            key === 'k-model' ||
+            key === 'ref' ||
+            key === 'class' ||
             key === 'className' ||
             key === 'style' ||
             key === 'children' ||
-            key === 'k-if' ||
-            key === 'k-model' ||
-            key === 'k-html' ||
-            key === 'ref') {
+            key === 'k-html') {
             continue;
         }
         const o = attr[key];
@@ -239,7 +199,7 @@ function apdSingle(element, c) {
     if (c === false || c === undefined || c === null) {
         return;
     }
-    if (isKTRef(c)) {
+    if (isKT(c)) {
         let node = assureNode(c.value);
         $append.call(element, node);
         c.addOnChange((newValue, oldValue) => {
@@ -296,8 +256,74 @@ function applyContent(element, content) {
     }
 }
 
+class KTRef {
+    /**
+     * Indicates that this is a KTRef instance
+     */
+    isKT = true;
+    ktType = 1 /* KTReactiveType.REF */;
+    /**
+     * @internal
+     */
+    _value;
+    /**
+     * @internal
+     */
+    _onChanges;
+    constructor(_value, _onChanges) {
+        this._value = _value;
+        this._onChanges = _onChanges;
+    }
+    /**
+     * If new value and old value are both nodes, the old one will be replaced in the DOM
+     */
+    get value() {
+        return this._value;
+    }
+    set value(newValue) {
+        if ($is(newValue, this._value)) {
+            return;
+        }
+        const oldValue = this._value;
+        $replaceNode(oldValue, newValue);
+        this._value = newValue;
+        for (let i = 0; i < this._onChanges.length; i++) {
+            this._onChanges[i](newValue, oldValue);
+        }
+    }
+    /**
+     * Register a callback when the value changes
+     * @param callback (newValue, oldValue) => xxx
+     */
+    addOnChange(callback) {
+        if (typeof callback !== 'function') {
+            throw new Error('[kt.js error] KTRef.addOnChange: callback must be a function');
+        }
+        this._onChanges.push(callback);
+    }
+    removeOnChange(callback) {
+        for (let i = this._onChanges.length - 1; i >= 0; i--) {
+            if (this._onChanges[i] === callback) {
+                this._onChanges.splice(i, 1);
+                return true;
+            }
+        }
+        return false;
+    }
+}
+/**
+ * Reference to the created HTML element.
+ * - **Only** respond to `ref.value` changes, not reactive to internal changes of the element.
+ * - can alse be used to store normal values, but it is not reactive.
+ * - if the value is already a `KTRef`, it will be returned **directly**.
+ * @param value mostly an HTMLElement
+ */
+function ref(value, onChange) {
+    return new KTRef(value, []);
+}
+
 function applyKModel(element, valueRef) {
-    if (!isKTRef(valueRef)) {
+    if (!isKT(valueRef)) {
         console.warn('[kt.js warn] k-model value must be a KTRef.');
         return;
     }
@@ -324,9 +350,6 @@ const htmlCreator = (tag) => document.createElement(tag);
 const svgCreator = (tag) => document.createElementNS('http://www.w3.org/2000/svg', tag);
 const mathMLCreator = (tag) => document.createElementNS('http://www.w3.org/1998/Math/MathML', tag);
 let creator = htmlCreator;
-// # consts
-const SVG_ATTR_FLAG = '__kt_svg__';
-const MATHML_ATTR_FLAG = '__kt_mathml__';
 /**
  * Create an enhanced HTMLElement.
  * - Only supports HTMLElements, **NOT** SVGElements or other Elements.
@@ -337,7 +360,7 @@ const MATHML_ATTR_FLAG = '__kt_mathml__';
  * ## About
  * @package @ktjs/core
  * @author Kasukabe Tsumugi <futami16237@gmail.com>
- * @version 0.23.0 (Last Update: 2026.02.03 17:15:01.812)
+ * @version 0.24.1 (Last Update: 2026.02.05 12:51:38.436)
  * @license MIT
  * @link https://github.com/baendlorel/kt.js
  * @link https://baendlorel.github.io/ Welcome to my site!
@@ -367,13 +390,7 @@ const h = (tag, attr, content) => {
     applyAttr(element, attr);
     applyContent(element, content);
     if (typeof attr === 'object' && attr !== null && 'k-model' in attr) {
-        const kmodel = attr['k-model'];
-        if (isKTRef(kmodel)) {
-            applyKModel(element, kmodel);
-        }
-        else {
-            throw new Error('[kt.js error] k-model value must be a KTRef.');
-        }
+        applyKModel(element, attr['k-model']);
     }
     return element;
 };
@@ -393,20 +410,23 @@ const placeholder = () => document.createComment('k-if');
  * @param props properties/attributes
  */
 function jsx(tag, props) {
-    const maybeDummyRef = isKTRef(props.ref) ? props.ref : dummyRef;
+    if (isComputed(props.ref)) {
+        throw new Error('[kt.js error] Cannot assign a computed value to an element.');
+    }
+    const maybeDummyRef = isRef(props.ref) ? props.ref : dummyRef;
     let el;
     if ('k-if' in props) {
         const kif = props['k-if'];
         let condition = kif; // assume boolean by default
         // Handle reactive k-if
-        if (isKTRef(kif)) {
+        if (isKT(kif)) {
             kif.addOnChange((newValue, oldValue) => {
                 if (newValue === oldValue) {
                     return;
                 }
                 const oldEl = el;
                 el = newValue ? create(tag, props) : placeholder();
-                oldEl.replaceWith(el);
+                $replaceNode(oldEl, el);
                 maybeDummyRef.value = el;
             });
             condition = kif.value;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kt.js",
-  "version": "0.23.0",
+  "version": "0.24.1",
   "author": {
     "name": "Kasukabe Tsumugi",
     "email": "futami16237@gmail.com"
@@ -41,7 +41,7 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@ktjs/core": "0.23.0"
+    "@ktjs/core": "0.24.1"
   },
   "scripts": {
     "build": "rollup -c rollup.config.mjs",