@ktjs/shortcuts 0.32.5 → 0.33.1

package/README.md

@@ -12,11 +12,14 @@
 
 <p align="center"><strong>Visit KT.js: <a href="https://baendlorel.github.io/kt.js/">https://baendlorel.github.io/kt.js/</a></strong></p>
 
+> kt.js is still under development, so there might be some breaking changes. Note the Update Log below
+
 ## Recent Updates
 
-1. Special refs for `Array`, `Set`, `Map`, `WeakMap`, `WeakSet`, `Date` to better track mutations.
-   - e.g. `const a = ref.array([1, 2])`, then we can call `a.push(3)` to make a reactive change instead of `a.value.push(3)`.
-2. Fixed issues of `svg` and `mathml` elements.
+1. `ref.value` remains the standard read API, and it can also replace the whole outer value with `ref.value = nextValue`.
+2. `ref.draft` is the deep-mutation entry for nested objects, arrays, `Map` / `Set`, and custom mutable objects.
+3. `ref.draft` itself is not assignable; mutate nested fields or call mutating methods on the returned object instead.
+4. `addOnChange((newValue, oldValue) => ...)` keeps `oldValue` as the previous reference, not a deep snapshot.
 
 ## Community
 
@@ -29,6 +32,35 @@ kt.js is a simple framework with a tiny runtime that renders real DOM directly (
 
 KT.js focuses on one principle: keep direct control of the DOM and avoid unnecessary repainting.
 
+## Reactive Contract
+
+```ts
+const user = ref({ profile: { name: 'John' }, tags: ['new'] });
+
+console.log(user.value.profile.name); // read
+
+user.value = {
+  ...user.value,
+  profile: { ...user.value.profile, name: 'Jane' },
+  tags: [...user.value.tags],
+}; // replace the whole outer value
+
+user.draft.profile.name = 'Jane'; // deep write
+user.draft.tags.push('active'); // array / map / set / custom-object style mutation
+```
+
+Rules:
+
+- Read with `.value`.
+- Replace the whole outer value with `.value = nextValue`.
+- Use `.draft` for deep mutations on nested objects, arrays, `Map` / `Set`, or other mutable instances.
+- Do not assign to `.draft` itself; mutate inside it.
+- `computed` stays read-only and is consumed through `.value`.
+- `oldValue` in change listeners is the previous reference only, not a deep-cloned snapshot.
+- Correctness is expected to come from the transformer and TypeScript checks; runtime hot paths stay minimal on purpose.
+
+This is an explicit contract, closer to a Rust-style model than permissive runtime magic: unclear code should fail early.
+
 ## Quick Start
 
 ```bash

package/dist/index.mjs

@@ -1,33 +1,6 @@
-import { h } from '@ktjs/core';
+import { h } from "@ktjs/core";
 
-const aliasH = (tag) => (attr, content) => h(tag, attr, content);
-
-const div = aliasH('div');
-const span = aliasH('span');
-const label = aliasH('label');
-const p = aliasH('p');
-const h1 = aliasH('h1');
-const h2 = aliasH('h2');
-const h3 = aliasH('h3');
-const h4 = aliasH('h4');
-const h5 = aliasH('h5');
-const h6 = aliasH('h6');
-const ul = aliasH('ul');
-const ol = aliasH('ol');
-const li = aliasH('li');
-const btn = aliasH('button');
-const form = aliasH('form');
-const input = aliasH('input');
-const select = aliasH('select');
-const option = aliasH('option');
-const table = aliasH('table');
-const thead = aliasH('thead');
-const tbody = aliasH('tbody');
-const tr = aliasH('tr');
-const th = aliasH('th');
-const td = aliasH('td');
-const a = aliasH('a');
-const img = aliasH('img');
+const aliasH = tag => (attr, content) => h(tag, attr, content), div = aliasH("div"), span = aliasH("span"), label = aliasH("label"), p = aliasH("p"), h1 = aliasH("h1"), h2 = aliasH("h2"), h3 = aliasH("h3"), h4 = aliasH("h4"), h5 = aliasH("h5"), h6 = aliasH("h6"), ul = aliasH("ul"), ol = aliasH("ol"), li = aliasH("li"), btn = aliasH("button"), form = aliasH("form"), input = aliasH("input"), select = aliasH("select"), option = aliasH("option"), table = aliasH("table"), thead = aliasH("thead"), tbody = aliasH("tbody"), tr = aliasH("tr"), th = aliasH("th"), td = aliasH("td"), a = aliasH("a"), img = aliasH("img");
 
 export { a, btn, div, form, h1, h2, h3, h4, h5, h6, img, input, label, li, ol, option, p, select, span, table, tbody, td, th, thead, tr, ul };
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","sources":["../src/alias-h.ts","../src/common.ts"],"sourcesContent":["import type { KTRawAttr, KTRawContent, HTMLTag, HTML } from '@ktjs/core';\nimport { h } from '@ktjs/core';\n\nexport const aliasH: <T extends HTMLTag>(tag: T) => (attr?: KTRawAttr, content?: KTRawContent) => HTML<T> =\n  <T extends HTMLTag>(tag: T) =>\n  (attr?: KTRawAttr, content?: KTRawContent) =>\n    h(tag, attr, content);\n","import { aliasH } from './alias-h.js';\n\nexport const div = aliasH('div');\nexport const span = aliasH('span');\nexport const label = aliasH('label');\n\nexport const p = aliasH('p');\nexport const h1 = aliasH('h1');\nexport const h2 = aliasH('h2');\nexport const h3 = aliasH('h3');\nexport const h4 = aliasH('h4');\nexport const h5 = aliasH('h5');\nexport const h6 = aliasH('h6');\n\nexport const ul = aliasH('ul');\nexport const ol = aliasH('ol');\nexport const li = aliasH('li');\n\nexport const btn = aliasH('button');\nexport const form = aliasH('form');\nexport const input = aliasH('input');\nexport const select = aliasH('select');\nexport const option = aliasH('option');\n\nexport const table = aliasH('table');\nexport const thead = aliasH('thead');\nexport const tbody = aliasH('tbody');\nexport const tr = aliasH('tr');\nexport const th = aliasH('th');\nexport const td = aliasH('td');\n\nexport const a = aliasH('a');\nexport const img = aliasH('img');\n"],"names":[],"mappings":";;AAGO,MAAM,MAAM,GACjB,CAAoB,GAAM,KAC1B,CAAC,IAAgB,EAAE,OAAsB,KACvC,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC;;MCJZ,GAAG,GAAG,MAAM,CAAC,KAAK;MAClB,IAAI,GAAG,MAAM,CAAC,MAAM;MACpB,KAAK,GAAG,MAAM,CAAC,OAAO;MAEtB,CAAC,GAAG,MAAM,CAAC,GAAG;MACd,EAAE,GAAG,MAAM,CAAC,IAAI;MAChB,EAAE,GAAG,MAAM,CAAC,IAAI;MAChB,EAAE,GAAG,MAAM,CAAC,IAAI;MAChB,EAAE,GAAG,MAAM,CAAC,IAAI;MAChB,EAAE,GAAG,MAAM,CAAC,IAAI;MAChB,EAAE,GAAG,MAAM,CAAC,IAAI;MAEhB,EAAE,GAAG,MAAM,CAAC,IAAI;MAChB,EAAE,GAAG,MAAM,CAAC,IAAI;MAChB,EAAE,GAAG,MAAM,CAAC,IAAI;MAEhB,GAAG,GAAG,MAAM,CAAC,QAAQ;MACrB,IAAI,GAAG,MAAM,CAAC,MAAM;MACpB,KAAK,GAAG,MAAM,CAAC,OAAO;MACtB,MAAM,GAAG,MAAM,CAAC,QAAQ;MACxB,MAAM,GAAG,MAAM,CAAC,QAAQ;MAExB,KAAK,GAAG,MAAM,CAAC,OAAO;MACtB,KAAK,GAAG,MAAM,CAAC,OAAO;MACtB,KAAK,GAAG,MAAM,CAAC,OAAO;MACtB,EAAE,GAAG,MAAM,CAAC,IAAI;MAChB,EAAE,GAAG,MAAM,CAAC,IAAI;MAChB,EAAE,GAAG,MAAM,CAAC,IAAI;MAEhB,CAAC,GAAG,MAAM,CAAC,GAAG;MACd,GAAG,GAAG,MAAM,CAAC,KAAK;;;;"}
+{"version":3,"file":"index.mjs","sources":["../src/alias-h.ts","../src/common.ts"],"sourcesContent":["import type { KTRawAttr, KTRawContent, HTMLTag, HTML } from '@ktjs/core';\nimport { h } from '@ktjs/core';\n\nexport const aliasH: <T extends HTMLTag>(tag: T) => (attr?: KTRawAttr, content?: KTRawContent) => HTML<T> =\n  <T extends HTMLTag>(tag: T) =>\n  (attr?: KTRawAttr, content?: KTRawContent) =>\n    h(tag, attr, content);\n","import { aliasH } from './alias-h.js';\n\nexport const div = aliasH('div');\nexport const span = aliasH('span');\nexport const label = aliasH('label');\n\nexport const p = aliasH('p');\nexport const h1 = aliasH('h1');\nexport const h2 = aliasH('h2');\nexport const h3 = aliasH('h3');\nexport const h4 = aliasH('h4');\nexport const h5 = aliasH('h5');\nexport const h6 = aliasH('h6');\n\nexport const ul = aliasH('ul');\nexport const ol = aliasH('ol');\nexport const li = aliasH('li');\n\nexport const btn = aliasH('button');\nexport const form = aliasH('form');\nexport const input = aliasH('input');\nexport const select = aliasH('select');\nexport const option = aliasH('option');\n\nexport const table = aliasH('table');\nexport const thead = aliasH('thead');\nexport const tbody = aliasH('tbody');\nexport const tr = aliasH('tr');\nexport const th = aliasH('th');\nexport const td = aliasH('td');\n\nexport const a = aliasH('a');\nexport const img = aliasH('img');\n"],"names":["aliasH","tag","attr","content","h","div","span","label","p","h1","h2","h3","h4","h5","h6","ul","ol","li","btn","form","input","select","option","table","thead","tbody","tr","th","td","a","img"],"mappings":";;AAGO,MAAMA,SACSC,OACpB,CAACC,MAAkBC,YACjBC,EAAEH,KAAKC,MAAMC,UCJJE,MAAML,OAAO,QACbM,OAAON,OAAO,SACdO,QAAQP,OAAO,UAEfQ,IAAIR,OAAO,MACXS,KAAKT,OAAO,OACZU,KAAKV,OAAO,OACZW,KAAKX,OAAO,OACZY,KAAKZ,OAAO,OACZa,KAAKb,OAAO,OACZc,KAAKd,OAAO,OAEZe,KAAKf,OAAO,OACZgB,KAAKhB,OAAO,OACZiB,KAAKjB,OAAO,OAEZkB,MAAMlB,OAAO,WACbmB,OAAOnB,OAAO,SACdoB,QAAQpB,OAAO,UACfqB,SAASrB,OAAO,WAChBsB,SAAStB,OAAO,WAEhBuB,QAAQvB,OAAO,UACfwB,QAAQxB,OAAO,UACfyB,QAAQzB,OAAO,UACf0B,KAAK1B,OAAO,OACZ2B,KAAK3B,OAAO,OACZ4B,KAAK5B,OAAO,OAEZ6B,IAAI7B,OAAO,MACX8B,MAAM9B,OAAO;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ktjs/shortcuts",
-  "version": "0.32.5",
+  "version": "0.33.1",
   "description": "Shortcut functions for kt.js - common DOM operations",
   "description_zh": "kt.js 的快捷函数集合，封装常见 DOM 操作。",
   "type": "module",