@ktjs/shortcuts 0.32.4 β 0.33.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +48 -121
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,144 +1,71 @@
|
|
|
1
|
-
#
|
|
1
|
+
# KT.js
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/kt.js)
|
|
4
|
+
[](https://www.npmjs.com/package/kt.js)
|
|
5
|
+
[](https://opensource.org/licenses/MIT)
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
<p align="center">
|
|
8
|
+
<a href="https://baendlorel.github.io/kt.js/">
|
|
9
|
+
<img src="https://raw.githubusercontent.com/baendlorel/kt.js/refs/heads/main/assets/ktjs-0.0.1.svg" width="240px" alt="KT.js logo" />
|
|
10
|
+
</a>
|
|
11
|
+
</p>
|
|
6
12
|
|
|
7
|
-
>
|
|
13
|
+
<p align="center"><strong>Visit KT.js: <a href="https://baendlorel.github.io/kt.js/">https://baendlorel.github.io/kt.js/</a></strong></p>
|
|
8
14
|
|
|
9
|
-
|
|
15
|
+
> kt.js is still under development, so there might be some breaking changes. Note the Update Log below
|
|
10
16
|
|
|
11
|
-
|
|
17
|
+
## Recent Updates
|
|
12
18
|
|
|
13
|
-
|
|
19
|
+
1. `ref.value` remains the standard read API, and it can also replace the whole outer value with `ref.value = nextValue`.
|
|
20
|
+
2. `ref.draft` is the deep-mutation entry for nested objects, arrays, `Map` / `Set`, and custom mutable objects.
|
|
21
|
+
3. `ref.draft` itself is not assignable; mutate nested fields or call mutating methods on the returned object instead.
|
|
22
|
+
4. `addOnChange((newValue, oldValue) => ...)` keeps `oldValue` as the previous reference, not a deep snapshot.
|
|
14
23
|
|
|
15
|
-
|
|
24
|
+
## Community
|
|
16
25
|
|
|
17
|
-
|
|
26
|
+
- QQ Group: `1070434849`
|
|
27
|
+
- Telegram: https://t.me/kt_js
|
|
18
28
|
|
|
19
|
-
|
|
20
|
-
- `div`, `span`, `button`, `input`, `a`, etc.
|
|
21
|
-
- Same signature as `h` function but without the tag name
|
|
22
|
-
- Full TypeScript support with proper return types
|
|
23
|
-
- **Form Helpers**: Shortcuts for form elements with better ergonomics
|
|
24
|
-
- Pre-configured form controls
|
|
25
|
-
- Input type helpers
|
|
26
|
-
- **Layout Helpers**: Common layout patterns and containers
|
|
27
|
-
- **`withDefaults`**: Create element factories with default properties
|
|
28
|
-
- Works with both `h` function and shortcut functions
|
|
29
|
-
- Supports nested defaults (defaults on top of defaults)
|
|
30
|
-
- Full type inference for all properties
|
|
29
|
+
## Introduction
|
|
31
30
|
|
|
32
|
-
|
|
31
|
+
kt.js is a simple framework with a tiny runtime that renders real DOM directly (no virtual DOM), uses explicit reactivity variables and gives you manual control over refs, bindings, and redraw timing.
|
|
33
32
|
|
|
34
|
-
|
|
33
|
+
KT.js focuses on one principle: keep direct control of the DOM and avoid unnecessary repainting.
|
|
35
34
|
|
|
36
|
-
|
|
37
|
-
pnpm add @ktjs/shortcuts @ktjs/core
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
## Basic Usage
|
|
41
|
-
|
|
42
|
-
### Element Shortcuts
|
|
35
|
+
## Reactive Contract
|
|
43
36
|
|
|
44
|
-
```
|
|
45
|
-
|
|
37
|
+
```ts
|
|
38
|
+
const user = ref({ profile: { name: 'John' }, tags: ['new'] });
|
|
46
39
|
|
|
47
|
-
//
|
|
48
|
-
const container = div({ class: 'container' }, [
|
|
49
|
-
h1({}, 'Title'),
|
|
50
|
-
p({}, 'Description'),
|
|
51
|
-
btn({ '@click': () => alert('Hi') }, 'Click me'),
|
|
52
|
-
]);
|
|
40
|
+
console.log(user.value.profile.name); // read
|
|
53
41
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
]);
|
|
42
|
+
user.value = {
|
|
43
|
+
...user.value,
|
|
44
|
+
profile: { ...user.value.profile, name: 'Jane' },
|
|
45
|
+
tags: [...user.value.tags],
|
|
46
|
+
}; // replace the whole outer value
|
|
60
47
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
const text = span('Hello World');
|
|
48
|
+
user.draft.profile.name = 'Jane'; // deep write
|
|
49
|
+
user.draft.tags.push('active'); // array / map / set / custom-object style mutation
|
|
64
50
|
```
|
|
65
51
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
The following shortcuts are exported from `common.ts`:
|
|
69
|
-
|
|
70
|
-
**Basic**: `div`, `span`, `label`, `a`, `img`
|
|
71
|
-
|
|
72
|
-
**Text**: `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `p`
|
|
73
|
-
|
|
74
|
-
**Forms**: `form`, `input`, `button`, `select`, `option`
|
|
75
|
-
|
|
76
|
-
**Lists**: `ul`, `ol`, `li`
|
|
77
|
-
|
|
78
|
-
**Tables**: `table`, `thead`, `tbody`, `tr`, `th`, `td`
|
|
79
|
-
|
|
80
|
-
Each function has the signature:
|
|
81
|
-
|
|
82
|
-
```typescript
|
|
83
|
-
function element(attributes?: KAttribute, content?: KContent): HTMLElement;
|
|
84
|
-
function element(className: string, content?: KContent): HTMLElement;
|
|
85
|
-
function element(content: KContent): HTMLElement;
|
|
86
|
-
```
|
|
87
|
-
|
|
88
|
-
## API Reference
|
|
89
|
-
|
|
90
|
-
## Common Patterns
|
|
52
|
+
Rules:
|
|
91
53
|
|
|
92
|
-
|
|
54
|
+
- Read with `.value`.
|
|
55
|
+
- Replace the whole outer value with `.value = nextValue`.
|
|
56
|
+
- Use `.draft` for deep mutations on nested objects, arrays, `Map` / `Set`, or other mutable instances.
|
|
57
|
+
- Do not assign to `.draft` itself; mutate inside it.
|
|
58
|
+
- `computed` stays read-only and is consumed through `.value`.
|
|
59
|
+
- `oldValue` in change listeners is the previous reference only, not a deep-cloned snapshot.
|
|
60
|
+
- Correctness is expected to come from the transformer and TypeScript checks; runtime hot paths stay minimal on purpose.
|
|
93
61
|
|
|
94
|
-
|
|
95
|
-
import { div, button, input } from '@ktjs/shortcuts';
|
|
62
|
+
This is an explicit contract, closer to a Rust-style model than permissive runtime magic: unclear code should fail early.
|
|
96
63
|
|
|
97
|
-
|
|
98
|
-
const createCard = (title: string, content: string) => {
|
|
99
|
-
return div('card', [div('card-title', title), div('card-content', content)]);
|
|
100
|
-
};
|
|
64
|
+
## Quick Start
|
|
101
65
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
```typescript
|
|
109
|
-
import { input, button, div } from '@ktjs/shortcuts';
|
|
110
|
-
|
|
111
|
-
const createTextInput = (placeholder: string, name: string) => {
|
|
112
|
-
return input({ type: 'text', class: 'form-control', placeholder, name });
|
|
113
|
-
};
|
|
114
|
-
|
|
115
|
-
const createSubmitButton = (text: string) => {
|
|
116
|
-
return btn({ type: 'submit', class: 'btn-primary' }, text);
|
|
117
|
-
};
|
|
118
|
-
|
|
119
|
-
const loginForm = div('login-form', [
|
|
120
|
-
createTextInput('Username', 'username'),
|
|
121
|
-
createTextInput('Password', 'password'),
|
|
122
|
-
createSubmitButton('Login'),
|
|
123
|
-
]);
|
|
66
|
+
```bash
|
|
67
|
+
pnpm create kt.js my-app
|
|
68
|
+
cd my-app
|
|
69
|
+
pnpm install
|
|
70
|
+
pnpm dev
|
|
124
71
|
```
|
|
125
|
-
|
|
126
|
-
## Type System
|
|
127
|
-
|
|
128
|
-
The package includes comprehensive TypeScript definitions with:
|
|
129
|
-
|
|
130
|
-
- Proper element type inference for all shortcuts
|
|
131
|
-
- Attribute and content type checking
|
|
132
|
-
- Event handler type hints
|
|
133
|
-
- Support for conditional types in `withDefaults`
|
|
134
|
-
|
|
135
|
-
## Performance
|
|
136
|
-
|
|
137
|
-
- All shortcut functions are thin wrappers around the `h` function
|
|
138
|
-
- Zero runtime overhead after bundling with tree-shaking
|
|
139
|
-
- `withDefaults` creates minimal closure overhead
|
|
140
|
-
- Native method caching inherited from `@ktjs/core`
|
|
141
|
-
|
|
142
|
-
## License
|
|
143
|
-
|
|
144
|
-
MIT
|
package/package.json
CHANGED