@ktjs/core 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 kasukabe tsumugi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# @ktjs/core
+
+<img src="https://raw.githubusercontent.com/baendlorel/kt.js/dev/.assets/ktjs-0.0.1.svg" alt="KT.js Logo" width="150"/>
+
+> 📦 Part of [KT.js](https://raw.githubusercontent.com/baendlorel/kt.js/dev/README.md) - A simple and easy-to-use web framework that never re-renders.
+
+Core DOM manipulation utilities for KT.js framework.
+
+## Overview
+
+`@ktjs/core` is the foundation of KT.js, providing the essential `h` function and DOM utilities for building web applications with direct DOM manipulation. It emphasizes performance, type safety, and minimal abstraction over native DOM APIs.
+
+## Features
+
+- **`h` Function**: Create HTMLElements with a simple, flexible API
+  - Support for attributes, content, and event handlers
+  - Special `@<eventName>` syntax for event handlers
+  - Function attributes automatically treated as event listeners
+  - Full TypeScript support with intelligent type inference
+- **DOM Utilities**: Helper functions for common DOM operations
+  - Native method caching for performance
+  - Symbol-based private properties for internal state
+- **Type-Safe**: Complete TypeScript definitions
+  - 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
+
+## Installation
+
+```bash
+pnpm add @ktjs/core
+```
+
+## Usage
+
+### Basic Element Creation
+
+```typescript
+import { h } from '@ktjs/core';
+
+// Simple element
+const div = h('div', { class: 'container' }, 'Hello World');
+
+// With multiple attributes
+const input = h('input', {
+  type: 'text',
+  placeholder: 'Enter text',
+  value: 'initial',
+});
+
+// Nested elements
+const card = h('div', { class: 'card' }, [
+  h('h2', {}, 'Title'),
+  h('p', {}, 'Description'),
+  h('button', {}, 'Click me'),
+]);
+```
+
+### Event Handlers
+
+```typescript
+import { h } from '@ktjs/core';
+
+// Function attribute (treated as event listener)
+const button1 = h(
+  'button',
+  {
+    click: () => alert('Clicked!'),
+  },
+  'Button 1'
+);
+
+// @-prefixed attribute (explicitly an event handler)
+const button2 = h(
+  'button',
+  {
+    '@click': (e) => console.log('Event:', e),
+    'data-id': '123', // Regular attribute
+  },
+  'Button 2'
+);
+
+// Both regular and event handler for same name
+const input = h('input', {
+  change: 'change-value', // Regular attribute
+  '@change': (e) => console.log('Changed'), // Event listener
+});
+```
+
+### Using ktnull for Conditional Rendering
+
+```typescript
+import { h, ktnull } from '@ktjs/core';
+
+const items = [1, 2, 3, 4, 5];
+
+const list = h(
+  'ul',
+  {},
+  items.map(
+    (item) => (item % 2 === 0 ? h('li', {}, `Even: ${item}`) : ktnull) // Won't create a DOM node
+  )
+);
+// Results in: <ul><li>Even: 2</li><li>Even: 4</li></ul>
+```
+
+## API Reference
+
+### `h(tag, attributes?, content?)`
+
+Creates an HTMLElement with the specified tag, attributes, and content.
+
+**Parameters:**
+
+- `tag` (string): HTML tag name (e.g., 'div', 'span', 'button')
+- `attributes` (object, optional): Element attributes and event handlers
+- `content` (string | HTMLElement | Array, optional): Element 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:
+
+- `HTMLTag`: Union type of all valid HTML tag names
+- `KAttribute`: Attribute object type with string or function values
+- `KContent`: Valid content types (string, Element, Array, etc.)
+- Event handler types with proper event object types
+
+## Performance Considerations
+
+- Native DOM methods are cached for repeated use
+- Symbol-based properties avoid prototype pollution
+- Minimal object creation in hot paths
+- Tree-shakeable - only import what you use
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,125 @@
+interface KTRuntime {
+    throws: (message: string) => never;
+    defines: <T>(o: T, properties: PropertyDescriptorMap & ThisType<any>) => T;
+    mark: (func: (...args: any[]) => any, tag: string) => void;
+}
+declare global {
+    interface Window {
+        readonly __ktjs__: KTRuntime;
+    }
+}
+
+/**
+ * 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 & {};
+
+/**
+ * Normal HTML tags like `div`, `span`, `a`, etc.
+ */
+// & 这里也要允许其他字符串
+type HTMLTag = keyof HTMLElementTagNameMap;
+
+type KTRawContent = (HTMLElement | string | undefined)[] | HTMLElement | string;
+type KTRawAttr = KTAttribute | string;
+
+/**
+ * Event handler type for DOM events
+ */
+type EventHandler<T extends Event = Event> = (this: HTMLElement, ev: T) => any;
+
+/**
+ * Used to create enhanced HTML elements
+ */
+interface KTBaseAttribute {
+  [k: string]: any;
+
+  id?: string;
+  class?: string;
+  style?: string | Partial<CSSStyleDeclaration>;
+
+  type?:
+    | 'text'
+    | 'password'
+    | 'email'
+    | 'number'
+    | 'tel'
+    | 'url'
+    | 'search'
+    | 'date'
+    | 'datetime-local'
+    | 'time'
+    | 'month'
+    | 'week'
+    | 'color'
+    | 'range'
+    | 'file'
+    | 'checkbox'
+    | 'radio'
+    | 'hidden'
+    | 'submit'
+    | 'reset'
+    | 'button'
+    | 'image'
+    | otherstring;
+  for?: string;
+
+  name?: string;
+  value?: string;
+  valueAsDate?: Date;
+  valueAsNumber?: number;
+  label?: string;
+  disabled?: string;
+
+  min?: string | number;
+  max?: string | number;
+  step?: string | number;
+
+  selected?: boolean;
+  checked?: boolean;
+
+  action?: string;
+  method?: 'POST' | 'GET' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS' | 'CONNECT' | 'TRACE' | otherstring;
+}
+
+type KTEventHandlersOrAttribute = {
+  [EventName in keyof HTMLElementEventMap]?: ((ev: HTMLElementEventMap[EventName]) => void) | string;
+};
+
+/**
+ * Event handlers with @ prefix (e.g., @click, @input)
+ * When key starts with @, it's always registered as an event handler
+ */
+type KTPrefixedEventHandlers = {
+  [EventName in keyof HTMLElementEventMap as `@${EventName}`]?: (ev: HTMLElementEventMap[EventName]) => void;
+};
+
+type KTAttribute = KTBaseAttribute & KTEventHandlersOrAttribute & KTPrefixedEventHandlers;
+
+type HTML<T extends HTMLTag & otherstring> = T extends HTMLTag ? HTMLElementTagNameMap[T] : HTMLElement;
+/**
+ * Create an enhanced HTMLElement.
+ * - Only supports HTMLElements, **NOT** SVGElements or other Elements.
+ * @param tag tag of an `HTMLElement`
+ * @param attr attribute object or className
+ * @param content a string or an array of HTMLEnhancedElement as child nodes
+ *
+ * ## About
+ * @package @ktjs/core
+ * @author Kasukabe Tsumugi <futami16237@gmail.com>
+ * @version 0.5.0 (Last Update: 2025.11.22 16:11:52.431)
+ * @license MIT
+ * @link https://github.com/baendlorel/kt.js
+ * @link https://baendlorel.github.io/ Welcome to my site!
+ * @description Core functionality for kt.js - DOM manipulation utilities
+ * @copyright Copyright (c) 2025 Kasukabe Tsumugi. All rights reserved.
+ */
+declare const h: <T extends HTMLTag>(tag: T, attr?: KTRawAttr, content?: KTRawContent) => HTML<T>;
+
+declare function notSupportTextNode(tag: HTMLTag): boolean;
+
+export { h, ktnull, notSupportTextNode };
+export type { EventHandler, KTAttribute, KTRawAttr, KTRawContent, KTRuntime };

package/dist/index.iife.js

@@ -0,0 +1 @@
+var __ktjs_core__=function(e){"use strict";const t=e=>{throw new Error("kt.js: ".concat(e))},n=Array.isArray,o=Object.keys,r=Object.defineProperties,s=(e,t)=>r(e,{t:{value:t}}),u=()=>({});"undefined"==typeof Promise&&(window.Promise={resolve:u,reject:u}),(()=>{const e=Object.create(null);r(e,{throws:{value:t,enumerable:!0},defines:{value:r,enumerable:!0},mark:{value:s,enumerable:!0}}),r(window,{o:{value:e,enumerable:!0}})})();const c=Object.create(null),i=HTMLElement.prototype.appendChild,a=HTMLElement.prototype.append,l="function"==typeof a?function(...e){const t=e.filter(e=>e!==c);return a.apply(this,t)}:function(...e){if(e.length<50)for(let t=0;t<e.length;t++){const n=e[t];"string"==typeof n?i.call(this,document.createTextNode(n)):n!==c&&i.call(this,n)}else{const t=document.createDocumentFragment();for(let n=0;n<e.length;n++){const o=e[n];"string"==typeof o?i.call(t,document.createTextNode(o)):o!==c&&i.call(t,o)}i.call(this,t)}};function f(e,t,n){t in e?e[t]=!!n:e.setAttribute(t,n)}function d(e,t,n){t in e?e[t]=n:e.setAttribute(t,n)}const m={checked:f,selected:f,value:d,valueAsDate:d,valueAsNumber:d,defaultValue:d,defaultChecked:f,defaultSelected:f,disabled:f,readOnly:f,multiple:f,required:f,autofocus:f,open:f,controls:f,autoplay:f,loop:f,muted:f,defer:f,async:f,hidden:function(e,t,n){e.hidden=!!n}},p=function(e,t,n){return e.setAttribute(t,n)};function _(e,n){"string"==typeof n?e.className=n:"object"==typeof n&&null!==n?function(e,t){const n=t.class,r=t.style;if(void 0!==n&&(e.className=n,delete t.class),r){if("string"==typeof r)e.setAttribute("style",r);else if("object"==typeof r)for(const t in r)e.style[t]=r[t];delete t.style}const s=o(t);for(let n=s.length-1;n>=0;n--){const o=s[n],r=t[o];o.startsWith("@")?e.addEventListener(o.slice(1),r):"function"!=typeof r?(m[o]||p)(e,o,r):e.addEventListener(o,r)}void 0!==n&&(t.class=n),void 0!==r&&(t.style=r)}(e,n):t("__func__ attr must be an object.")}const b=(e,o="",r="")=>{"string"!=typeof e&&t("__func__ tagName must be a string.");const s=document.createElement(e);return _(s,o),function(e,t){n(t)?l.apply(e,t):l.call(e,t)}(s,r),s};s(b,"h");const y={area:!0,audio:!0,base:!0,basefont:!0,br:!0,canvas:!0,datalist:!0,details:!0,dialog:!0,frameset:!0,head:!0,iframe:!0,img:!0,input:!0,link:!0,meta:!0,meter:!0,noembed:!0,noframes:!0,noscript:!0,optgroup:!0,param:!0,progress:!0,rp:!0,select:!0,style:!0,template:!0,textarea:!0,title:!0,video:!0,wbr:!0,embed:!0,frame:!0,keygen:!0,option:!0};return e.h=b,e.ktnull=c,e.notSupportTextNode=function(e){return y[e]},e}({});

package/dist/index.legacy.js

@@ -0,0 +1 @@
+var __ktjs_core__=function(e){"use strict";var t,n=function(e){throw new Error("kt.js: ".concat(e))},r=Array.isArray,o=Object.keys,a=Object.defineProperties,u=function(e,t){return a(e,{t:{value:t}})},i=function(){return{}};"undefined"==typeof Promise&&(window.Promise={resolve:i,reject:i}),t=Object.create(null),a(t,{throws:{value:n,enumerable:!0},defines:{value:a,enumerable:!0},mark:{value:u,enumerable:!0}}),a(window,{o:{value:t,enumerable:!0}});var f=Object.create(null),l=HTMLElement.prototype.appendChild,c=HTMLElement.prototype.append,s="function"==typeof c?function(){for(var e=[],t=0;t<arguments.length;t++)e[t]=arguments[t];var n=e.filter(function(e){return e!==f});return c.apply(this,n)}:function(){for(var e=[],t=0;t<arguments.length;t++)e[t]=arguments[t];if(e.length<50)for(var n=0;n<e.length;n++){"string"==typeof(o=e[n])?l.call(this,document.createTextNode(o)):o!==f&&l.call(this,o)}else{var r=document.createDocumentFragment();for(n=0;n<e.length;n++){var o;"string"==typeof(o=e[n])?l.call(r,document.createTextNode(o)):o!==f&&l.call(r,o)}l.call(this,r)}};function d(e,t,n){t in e?e[t]=!!n:e.setAttribute(t,n)}function v(e,t,n){t in e?e[t]=n:e.setAttribute(t,n)}var m={checked:d,selected:d,value:v,valueAsDate:v,valueAsNumber:v,defaultValue:v,defaultChecked:d,defaultSelected:d,disabled:d,readOnly:d,multiple:d,required:d,autofocus:d,open:d,controls:d,autoplay:d,loop:d,muted:d,defer:d,async:d,hidden:function(e,t,n){e.hidden=!!n}},p=function(e,t,n){return e.setAttribute(t,n)};function _(e,t){"string"==typeof t?e.className=t:"object"==typeof t&&null!==t?function(e,t){var n=t.class,r=t.style;if(void 0!==n&&(e.className=n,delete t.class),r){if("string"==typeof r)e.setAttribute("style",r);else if("object"==typeof r)for(var a in r)e.style[a]=r[a];delete t.style}for(var u=o(t),i=u.length-1;i>=0;i--){var f=t[a=u[i]];a.startsWith("@")?e.addEventListener(a.slice(1),f):"function"!=typeof f?(m[a]||p)(e,a,f):e.addEventListener(a,f)}void 0!==n&&(t.class=n),void 0!==r&&(t.style=r)}(e,t):n("__func__ attr must be an object.")}var b=function(e,t,o){void 0===t&&(t=""),void 0===o&&(o=""),"string"!=typeof e&&n("__func__ tagName must be a string.");var a=document.createElement(e);return _(a,t),function(e,t){r(t)?s.apply(e,t):s.call(e,t)}(a,o),a};u(b,"h");var y={area:!0,audio:!0,base:!0,basefont:!0,br:!0,canvas:!0,datalist:!0,details:!0,dialog:!0,frameset:!0,head:!0,iframe:!0,img:!0,input:!0,link:!0,meta:!0,meter:!0,noembed:!0,noframes:!0,noscript:!0,optgroup:!0,param:!0,progress:!0,rp:!0,select:!0,style:!0,template:!0,textarea:!0,title:!0,video:!0,wbr:!0,embed:!0,frame:!0,keygen:!0,option:!0};return e.h=b,e.ktnull=f,e.notSupportTextNode=function(e){return y[e]},e}({});

package/dist/index.mjs

@@ -0,0 +1 @@
+const e=e=>{throw new Error("kt.js: ".concat(e))},t=Array.isArray,n=Object.keys,o=Object.defineProperties,r=(e,t)=>o(e,{t:{value:t}}),s=()=>({});"undefined"==typeof Promise&&(window.Promise={resolve:s,reject:s}),(()=>{const t=Object.create(null);o(t,{throws:{value:e,enumerable:!0},defines:{value:o,enumerable:!0},mark:{value:r,enumerable:!0}}),o(window,{o:{value:t,enumerable:!0}})})();const u=Object.create(null),i=HTMLElement.prototype.appendChild,a=HTMLElement.prototype.append,c="function"==typeof a?function(...e){const t=e.filter(e=>e!==u);return a.apply(this,t)}:function(...e){if(e.length<50)for(let t=0;t<e.length;t++){const n=e[t];"string"==typeof n?i.call(this,document.createTextNode(n)):n!==u&&i.call(this,n)}else{const t=document.createDocumentFragment();for(let n=0;n<e.length;n++){const o=e[n];"string"==typeof o?i.call(t,document.createTextNode(o)):o!==u&&i.call(t,o)}i.call(this,t)}};function l(e,t,n){t in e?e[t]=!!n:e.setAttribute(t,n)}function f(e,t,n){t in e?e[t]=n:e.setAttribute(t,n)}const d={checked:l,selected:l,value:f,valueAsDate:f,valueAsNumber:f,defaultValue:f,defaultChecked:l,defaultSelected:l,disabled:l,readOnly:l,multiple:l,required:l,autofocus:l,open:l,controls:l,autoplay:l,loop:l,muted:l,defer:l,async:l,hidden:function(e,t,n){e.hidden=!!n}},m=function(e,t,n){return e.setAttribute(t,n)};function p(t,o){"string"==typeof o?t.className=o:"object"==typeof o&&null!==o?function(e,t){const o=t.class,r=t.style;if(void 0!==o&&(e.className=o,delete t.class),r){if("string"==typeof r)e.setAttribute("style",r);else if("object"==typeof r)for(const t in r)e.style[t]=r[t];delete t.style}const s=n(t);for(let n=s.length-1;n>=0;n--){const o=s[n],r=t[o];o.startsWith("@")?e.addEventListener(o.slice(1),r):"function"!=typeof r?(d[o]||m)(e,o,r):e.addEventListener(o,r)}void 0!==o&&(t.class=o),void 0!==r&&(t.style=r)}(t,o):e("__func__ attr must be an object.")}const b=(n,o="",r="")=>{"string"!=typeof n&&e("__func__ tagName must be a string.");const s=document.createElement(n);return p(s,o),function(e,n){t(n)?c.apply(e,n):c.call(e,n)}(s,r),s};r(b,"h");const y={area:!0,audio:!0,base:!0,basefont:!0,br:!0,canvas:!0,datalist:!0,details:!0,dialog:!0,frameset:!0,head:!0,iframe:!0,img:!0,input:!0,link:!0,meta:!0,meter:!0,noembed:!0,noframes:!0,noscript:!0,optgroup:!0,param:!0,progress:!0,rp:!0,select:!0,style:!0,template:!0,textarea:!0,title:!0,video:!0,wbr:!0,embed:!0,frame:!0,keygen:!0,option:!0};function _(e){return y[e]}export{b as h,u as ktnull,_ as notSupportTextNode};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@ktjs/core",
+  "version": "0.5.0",
+  "description": "Core functionality for kt.js - DOM manipulation utilities",
+  "type": "module",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "types": "./dist/index.d.ts",
+    "import": "./dist/index.mjs",
+    "default": "./dist/index.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "dom",
+    "dom-manipulation",
+    "framework",
+    "web"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Kasukabe Tsumugi",
+    "email": "futami16237@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/baendlorel/kt.js",
+    "directory": "packages/core"
+  },
+  "scripts": {
+    "build": "rollup -c rollup.config.mjs",
+    "dev": "rollup -c rollup.config.mjs -w"
+  }
+}