@snupo/jmc 1.3.0 → 1.4.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/design-guide.md +193 -193
- package/dist/base.d.ts +1 -1
- package/dist/base.js +1 -1
- package/dist/base.js.map +1 -1
- package/dist/jsx.d.ts +1 -1
- package/dist/jsx.js.map +1 -1
- package/package.json +1 -1
- package/readme.md +317 -317
- package/src/base.ts +32 -32
- package/src/jsx.ts +1 -1
package/readme.md
CHANGED
|
@@ -1,317 +1,317 @@
|
|
|
1
|
-
# jmc
|
|
2
|
-
|
|
3
|
-
A minimal JSX/TSX view library that syncs your views directly with the real DOM.
|
|
4
|
-
|
|
5
|
-
- small enough to read in one sitting: the core is a single file of about 200 lines
|
|
6
|
-
- statically typed views with TSX
|
|
7
|
-
- you decide what to update and when: one call, scoped to any element
|
|
8
|
-
- plain objects as model, plain classes as controller, nothing hidden in between
|
|
9
|
-
|
|
10
|
-
```tsx
|
|
11
|
-
import { patch, updateview } from '@snupo/jmc'
|
|
12
|
-
|
|
13
|
-
const model = { count: 0 }
|
|
14
|
-
|
|
15
|
-
const App = () =>
|
|
16
|
-
<body>
|
|
17
|
-
<button onclick={() => { model.count++; updateview() }}>+1</button>
|
|
18
|
-
<span>{model.count}</span>
|
|
19
|
-
</body>
|
|
20
|
-
|
|
21
|
-
patch(document.body, <App />)
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
Upgrading from 1.0? See [UPGRADING.md](UPGRADING.md).
|
|
25
|
-
|
|
26
|
-
## Working with Claude and other coding agents
|
|
27
|
-
|
|
28
|
-
jmc ships a [design guide](design-guide.md) that explains to coding agents how a jmc app is structured: model, view and controller, and the rules between them. To have Claude follow it in your app, reference it from your project's `CLAUDE.md`:
|
|
29
|
-
|
|
30
|
-
```md
|
|
31
|
-
This app uses jmc. Follow @node_modules/@snupo/jmc/design-guide.md
|
|
32
|
-
```
|
|
33
|
-
|
|
34
|
-
The `@` import loads the guide into every session, and it stays current when you update jmc.
|
|
35
|
-
|
|
36
|
-
## Install
|
|
37
|
-
|
|
38
|
-
```sh
|
|
39
|
-
npm install @snupo/jmc
|
|
40
|
-
```
|
|
41
|
-
|
|
42
|
-
Tell TypeScript and your bundler to take JSX from jmc. jmc supports both JSX setups that TypeScript offers.
|
|
43
|
-
|
|
44
|
-
### Automatic runtime (recommended)
|
|
45
|
-
|
|
46
|
-
The compiler imports what JSX needs by itself, so your `.tsx` files need no JSX import. In `tsconfig.json`:
|
|
47
|
-
|
|
48
|
-
```jsonc
|
|
49
|
-
{
|
|
50
|
-
"compilerOptions": {
|
|
51
|
-
"jsx": "react-jsx",
|
|
52
|
-
"jsxImportSource": "@snupo/jmc"
|
|
53
|
-
}
|
|
54
|
-
}
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
Your bundler needs the same. With Vite's oxc transformer:
|
|
58
|
-
|
|
59
|
-
```ts
|
|
60
|
-
// vite.config.ts
|
|
61
|
-
export default defineConfig({
|
|
62
|
-
oxc: {
|
|
63
|
-
jsx: { runtime: 'automatic', importSource: '@snupo/jmc' },
|
|
64
|
-
},
|
|
65
|
-
})
|
|
66
|
-
```
|
|
67
|
-
|
|
68
|
-
With esbuild, the options are `jsx: 'automatic'` and `jsxImportSource: '@snupo/jmc'`.
|
|
69
|
-
|
|
70
|
-
### Classic
|
|
71
|
-
|
|
72
|
-
Every `.tsx` file imports jmc's factory functions `jsx`, and `jsxf` if it uses fragments (`<>…</>`). In `tsconfig.json`:
|
|
73
|
-
|
|
74
|
-
```jsonc
|
|
75
|
-
{
|
|
76
|
-
"compilerOptions": {
|
|
77
|
-
"jsx": "react",
|
|
78
|
-
"jsxFactory": "jsx",
|
|
79
|
-
"jsxFragmentFactory": "jsxf"
|
|
80
|
-
}
|
|
81
|
-
}
|
|
82
|
-
```
|
|
83
|
-
|
|
84
|
-
With Vite's oxc transformer:
|
|
85
|
-
|
|
86
|
-
```ts
|
|
87
|
-
// vite.config.ts
|
|
88
|
-
export default defineConfig({
|
|
89
|
-
oxc: {
|
|
90
|
-
jsx: { runtime: 'classic', pragma: 'jsx', pragmaFrag: 'jsxf' },
|
|
91
|
-
},
|
|
92
|
-
})
|
|
93
|
-
```
|
|
94
|
-
|
|
95
|
-
With esbuild, the options are `jsxFactory: 'jsx'` and `jsxFragment: 'jsxf'`.
|
|
96
|
-
|
|
97
|
-
Both setups render the same, and the same components work in both.
|
|
98
|
-
|
|
99
|
-
## The idea
|
|
100
|
-
|
|
101
|
-
An application is split into three parts with clear responsibilities.
|
|
102
|
-
|
|
103
|
-
**Model**: a plain object. No proxies, no observables, no special setters. You change a value by assigning it. The model instance itself stays stable.
|
|
104
|
-
|
|
105
|
-
**Controller**: a plain class whose methods are the application's operations. Only the controller changes the model. Other parts, like the view, treat it as read-only. After an action, the controller updates the parts of the view that the action affected.
|
|
106
|
-
|
|
107
|
-
Deciding which parts to update is a small, explicit step for the programmer. In return, there is no hidden machinery to learn, debug or work around, and no diffing of old and new state.
|
|
108
|
-
|
|
109
|
-
**View**: the DOM, described with statically typed TSX. jmc renders it and keeps it in sync. An update can be as coarse as the whole page or as fine as a single element.
|
|
110
|
-
|
|
111
|
-
## Rendering and updating
|
|
112
|
-
|
|
113
|
-
`patch(node, h)` renders `h` in place of `node` and returns the rendered element. The usual start is to patch `document.body` with a `<body>` element:
|
|
114
|
-
|
|
115
|
-
```tsx
|
|
116
|
-
patch(document.body, <App />)
|
|
117
|
-
```
|
|
118
|
-
|
|
119
|
-
`updateview(...commands)` brings rendered parts of the page up to date. jmc remembers how each element was rendered, so it renders it again with the current model:
|
|
120
|
-
|
|
121
|
-
```tsx
|
|
122
|
-
updateview() // the whole body
|
|
123
|
-
updateview('#todos') // all elements matching a selector
|
|
124
|
-
updateview(element) // one element
|
|
125
|
-
updateview('#todos', '.badge') // several targets
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
jmc compares the new render with the existing DOM and changes only what differs. Existing elements are reused, so focus, selection and scroll positions stay intact.
|
|
129
|
-
|
|
130
|
-
Two more kinds of commands change how the targets after them are updated:
|
|
131
|
-
|
|
132
|
-
- **a number** limits the depth. `updateview(1, el)` updates only the props of `el`, not its children. `updateview(0, el)` discards the children of `el` and renders them from scratch.
|
|
133
|
-
- **an object** is passed as update context to all `update` callbacks (see below): `updateview({ resized: true })`.
|
|
134
|
-
|
|
135
|
-
Without a target, `updateview` updates `body`.
|
|
136
|
-
|
|
137
|
-
### Batching
|
|
138
|
-
|
|
139
|
-
These variants collect updates and run them together:
|
|
140
|
-
|
|
141
|
-
| function | runs the update |
|
|
142
|
-
|---|---|
|
|
143
|
-
| `updateviewmicro(...)` | at the next microtask |
|
|
144
|
-
| `updateviewaf(...)` | at the next animation frame |
|
|
145
|
-
| `updateviewsync(...)` | immediately, together with everything queued |
|
|
146
|
-
| `flush()` | runs everything queued, immediately |
|
|
147
|
-
|
|
148
|
-
An element queued several times is updated once.
|
|
149
|
-
|
|
150
|
-
## Components
|
|
151
|
-
|
|
152
|
-
### Function components
|
|
153
|
-
|
|
154
|
-
A function component receives its props and children and returns JSX:
|
|
155
|
-
|
|
156
|
-
```tsx
|
|
157
|
-
const TodoList = (p: { items: string[] }) =>
|
|
158
|
-
<ul id='todos'>{p.items.map(t => <li>{t}</li>)}</ul>
|
|
159
|
-
|
|
160
|
-
patch(document.body, <body><h1>Todos</h1><TodoList items={model.todos} /></body>)
|
|
161
|
-
|
|
162
|
-
model.todos.push('bread')
|
|
163
|
-
updateview('#todos') // runs TodoList again
|
|
164
|
-
```
|
|
165
|
-
|
|
166
|
-
When you update the root element of a function component, the function runs again. A component that returns a fragment has no single root element. It is updated through its parent.
|
|
167
|
-
|
|
168
|
-
A component gets its children in `props.children`, as an array:
|
|
169
|
-
|
|
170
|
-
```tsx
|
|
171
|
-
const Box = (p: { title: string, children?: Children }) =>
|
|
172
|
-
<section title={p.title}>{p.children}</section>
|
|
173
|
-
|
|
174
|
-
<Box title='hello'><b>world</b></Box>
|
|
175
|
-
```
|
|
176
|
-
|
|
177
|
-
### Class components
|
|
178
|
-
|
|
179
|
-
A class component keeps state between renders. Its instance is created once and reused as long as the same class is rendered at the same place:
|
|
180
|
-
|
|
181
|
-
```tsx
|
|
182
|
-
class Counter extends Component<{ start: number }> {
|
|
183
|
-
count = this.props.start
|
|
184
|
-
inc() { this.count++; this.updateview() }
|
|
185
|
-
view(): H { return <button onclick={this.inc}>{this.count}</button> }
|
|
186
|
-
}
|
|
187
|
-
|
|
188
|
-
patch(document.body, <body><Counter start={5} /></body>)
|
|
189
|
-
```
|
|
190
|
-
|
|
191
|
-
| member | |
|
|
192
|
-
|---|---|
|
|
193
|
-
| `view()` | returns the component's JSX: exactly one root element, or `null` to render nothing |
|
|
194
|
-
| `props` | the current props, updated on every render by the parent |
|
|
195
|
-
| `element` | the rendered root element |
|
|
196
|
-
| `mounted()` | called once, after the first render, when the whole tree is in the DOM |
|
|
197
|
-
| `update(uc)` | called before each re-render. Return `true` to skip the re-render, for example after updating the DOM yourself |
|
|
198
|
-
| `updateview()` | updates this component |
|
|
199
|
-
| `ismounted` | `true` once rendered |
|
|
200
|
-
|
|
201
|
-
Methods are bound to the instance, so they can be used directly as event handlers, as `onclick={this.inc}` above shows.
|
|
202
|
-
|
|
203
|
-
A component whose `view()` returns `null` keeps its state and can show itself again later.
|
|
204
|
-
|
|
205
|
-
## Elements
|
|
206
|
-
|
|
207
|
-
### Props: attributes and properties
|
|
208
|
-
|
|
209
|
-
jmc sets a prop as a DOM **property** when the value is an object or a function, or when the element has a property of that name, as `value` and `checked` do. Otherwise it sets an **attribute**. Names listed in `jmcconfig.attributes` are always set as attributes (see [Configuration](#configuration)). `style` given as a string is set as an attribute.
|
|
210
|
-
|
|
211
|
-
A prop starting with `on` whose value is a function is attached with `addEventListener`, the event name being the rest of the prop name, case kept: `onclick` listens to `click`, `onmy-event` to `my-event`. So custom events work as well as built-in ones. Replacing the function swaps the listener, removing the prop removes it.
|
|
212
|
-
|
|
213
|
-
`null`, `undefined` and `false` remove the attribute. On `aria-*` attributes, `false` is kept as the value `"false"`.
|
|
214
|
-
|
|
215
|
-
A prop whose value is wrapped in `
|
|
216
|
-
|
|
217
|
-
```tsx
|
|
218
|
-
<dd class={
|
|
219
|
-
```
|
|
220
|
-
|
|
221
|
-
### Children
|
|
222
|
-
|
|
223
|
-
Strings and numbers render as text. `null`, `undefined`, `false` and `true` render nothing, so conditions read naturally:
|
|
224
|
-
|
|
225
|
-
```tsx
|
|
226
|
-
<div>{model.error && <p class='error'>{model.error}</p>}</div>
|
|
227
|
-
```
|
|
228
|
-
|
|
229
|
-
A child that renders nothing still keeps its place, as an invisible empty text node. So when `model.error` appears or disappears, the elements after it stay the same elements, with their focus, scroll position and state.
|
|
230
|
-
|
|
231
|
-
Arrays are flattened, so `items.map(…)` works anywhere. jmc matches children by position, so elements inside a list that grows or shrinks can be reused for different items.
|
|
232
|
-
|
|
233
|
-
### Lifecycle callbacks
|
|
234
|
-
|
|
235
|
-
Elements accept two lifecycle callbacks:
|
|
236
|
-
|
|
237
|
-
```tsx
|
|
238
|
-
<canvas
|
|
239
|
-
mounted={(n) => draw(n)} // once, after the element is created
|
|
240
|
-
update={(n, uc) => { draw(n, uc); return true }} // before each update. true: skip the default update
|
|
241
|
-
/>
|
|
242
|
-
```
|
|
243
|
-
|
|
244
|
-
`mounted` callbacks, of elements and class components alike, run after the render has finished, so they see the complete DOM, connected to the document. Children run before their parents. `update` runs during the render, because its result decides whether jmc updates the element.
|
|
245
|
-
|
|
246
|
-
### Islands
|
|
247
|
-
|
|
248
|
-
Some content is managed by other code, such as a map or an editor. Mark its element with `const`: jmc renders the element and its children once, then never touches it again, neither its props nor its children. The library can take over in `mounted`, and the `update` callback passes later model changes on to it:
|
|
249
|
-
|
|
250
|
-
```tsx
|
|
251
|
-
<div class='map' const
|
|
252
|
-
mounted={(n) => map = new maplibregl.Map({ container: n })}
|
|
253
|
-
update={() => { map.setStyle(model.style) }}
|
|
254
|
-
/>
|
|
255
|
-
```
|
|
256
|
-
|
|
257
|
-
The `const` attribute stays visible in the DOM, which helps to spot islands in the dev tools.
|
|
258
|
-
|
|
259
|
-
jmc also leaves the children of web components (tags containing `-`) to the component itself.
|
|
260
|
-
|
|
261
|
-
### SVG
|
|
262
|
-
|
|
263
|
-
SVG is a different world from HTML, so entering it is explicit: `<svg>` needs its namespace, and the types require it. Its children inherit the namespace, and the children of `<foreignObject>` are HTML again:
|
|
264
|
-
|
|
265
|
-
```tsx
|
|
266
|
-
<svg xmlns='http://www.w3.org/2000/svg'><circle r={5} /></svg>
|
|
267
|
-
```
|
|
268
|
-
|
|
269
|
-
### Custom elements
|
|
270
|
-
|
|
271
|
-
jmc's element types live on the `jsx` function, not in a global `JSX` namespace. So they never clash with the JSX types of other libraries in the same project. Declare your own tags and their props by extending them:
|
|
272
|
-
|
|
273
|
-
```ts
|
|
274
|
-
import type { HtmlHTMLAttributes } from '@snupo/jmc'
|
|
275
|
-
|
|
276
|
-
declare module '@snupo/jmc' {
|
|
277
|
-
namespace jsx {
|
|
278
|
-
namespace JSX {
|
|
279
|
-
interface IntrinsicElements {
|
|
280
|
-
'my-chart': HtmlHTMLAttributes & { data: number[] }
|
|
281
|
-
}
|
|
282
|
-
}
|
|
283
|
-
}
|
|
284
|
-
}
|
|
285
|
-
```
|
|
286
|
-
|
|
287
|
-
## Configuration
|
|
288
|
-
|
|
289
|
-
`jmcconfig` holds the settings that adjust jmc:
|
|
290
|
-
|
|
291
|
-
```ts
|
|
292
|
-
import { jmcconfig } from '@snupo/jmc'
|
|
293
|
-
|
|
294
|
-
jmcconfig.debug = true // mark component roots with comp="Name"
|
|
295
|
-
jmcconfig.attributes.add('list') // always set this prop as an attribute
|
|
296
|
-
```
|
|
297
|
-
|
|
298
|
-
**`debug`**: every component root shows the component's name, as in `<section comp="Panel">`, so the dev tools reveal which component rendered what. The attribute is only set while `debug` is on. To switch it from the browser console, make the object reachable there with `mount({ jmcconfig })`, then run `jmcconfig.debug = true; updateview()`.
|
|
299
|
-
|
|
300
|
-
**`attributes`**: the prop names that jmc always sets as attributes, even where the element has a property of that name. By default `selected` and `viewBox`.
|
|
301
|
-
|
|
302
|
-
## Utilities
|
|
303
|
-
|
|
304
|
-
| | |
|
|
305
|
-
|---|---|
|
|
306
|
-
| `cc(...)` | joins class names. Objects contribute their keys with truthy values: `cc('item', { active })` |
|
|
307
|
-
| `<When cond={…}>` | renders its children only if `cond` is true |
|
|
308
|
-
| `
|
|
309
|
-
| `closestby(node, pred)` | the nearest ancestor (or the node itself) matching `pred` |
|
|
310
|
-
| `focuselement(node)` | focuses the node |
|
|
311
|
-
| `rebind(o)` | binds the prototype methods of `o` to `o` |
|
|
312
|
-
| `mount({ … })` | puts values on `globalThis`, handy for debugging in the console |
|
|
313
|
-
| `loggedmethods(o)` | logs each method call of `o` with its arguments and result |
|
|
314
|
-
|
|
315
|
-
## License
|
|
316
|
-
|
|
317
|
-
[MIT](LICENSE)
|
|
1
|
+
# jmc
|
|
2
|
+
|
|
3
|
+
A minimal JSX/TSX view library that syncs your views directly with the real DOM.
|
|
4
|
+
|
|
5
|
+
- small enough to read in one sitting: the core is a single file of about 200 lines
|
|
6
|
+
- statically typed views with TSX
|
|
7
|
+
- you decide what to update and when: one call, scoped to any element
|
|
8
|
+
- plain objects as model, plain classes as controller, nothing hidden in between
|
|
9
|
+
|
|
10
|
+
```tsx
|
|
11
|
+
import { patch, updateview } from '@snupo/jmc'
|
|
12
|
+
|
|
13
|
+
const model = { count: 0 }
|
|
14
|
+
|
|
15
|
+
const App = () =>
|
|
16
|
+
<body>
|
|
17
|
+
<button onclick={() => { model.count++; updateview() }}>+1</button>
|
|
18
|
+
<span>{model.count}</span>
|
|
19
|
+
</body>
|
|
20
|
+
|
|
21
|
+
patch(document.body, <App />)
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Upgrading from 1.0? See [UPGRADING.md](UPGRADING.md).
|
|
25
|
+
|
|
26
|
+
## Working with Claude and other coding agents
|
|
27
|
+
|
|
28
|
+
jmc ships a [design guide](design-guide.md) that explains to coding agents how a jmc app is structured: model, view and controller, and the rules between them. To have Claude follow it in your app, reference it from your project's `CLAUDE.md`:
|
|
29
|
+
|
|
30
|
+
```md
|
|
31
|
+
This app uses jmc. Follow @node_modules/@snupo/jmc/design-guide.md
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
The `@` import loads the guide into every session, and it stays current when you update jmc.
|
|
35
|
+
|
|
36
|
+
## Install
|
|
37
|
+
|
|
38
|
+
```sh
|
|
39
|
+
npm install @snupo/jmc
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Tell TypeScript and your bundler to take JSX from jmc. jmc supports both JSX setups that TypeScript offers.
|
|
43
|
+
|
|
44
|
+
### Automatic runtime (recommended)
|
|
45
|
+
|
|
46
|
+
The compiler imports what JSX needs by itself, so your `.tsx` files need no JSX import. In `tsconfig.json`:
|
|
47
|
+
|
|
48
|
+
```jsonc
|
|
49
|
+
{
|
|
50
|
+
"compilerOptions": {
|
|
51
|
+
"jsx": "react-jsx",
|
|
52
|
+
"jsxImportSource": "@snupo/jmc"
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Your bundler needs the same. With Vite's oxc transformer:
|
|
58
|
+
|
|
59
|
+
```ts
|
|
60
|
+
// vite.config.ts
|
|
61
|
+
export default defineConfig({
|
|
62
|
+
oxc: {
|
|
63
|
+
jsx: { runtime: 'automatic', importSource: '@snupo/jmc' },
|
|
64
|
+
},
|
|
65
|
+
})
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
With esbuild, the options are `jsx: 'automatic'` and `jsxImportSource: '@snupo/jmc'`.
|
|
69
|
+
|
|
70
|
+
### Classic
|
|
71
|
+
|
|
72
|
+
Every `.tsx` file imports jmc's factory functions `jsx`, and `jsxf` if it uses fragments (`<>…</>`). In `tsconfig.json`:
|
|
73
|
+
|
|
74
|
+
```jsonc
|
|
75
|
+
{
|
|
76
|
+
"compilerOptions": {
|
|
77
|
+
"jsx": "react",
|
|
78
|
+
"jsxFactory": "jsx",
|
|
79
|
+
"jsxFragmentFactory": "jsxf"
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
With Vite's oxc transformer:
|
|
85
|
+
|
|
86
|
+
```ts
|
|
87
|
+
// vite.config.ts
|
|
88
|
+
export default defineConfig({
|
|
89
|
+
oxc: {
|
|
90
|
+
jsx: { runtime: 'classic', pragma: 'jsx', pragmaFrag: 'jsxf' },
|
|
91
|
+
},
|
|
92
|
+
})
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
With esbuild, the options are `jsxFactory: 'jsx'` and `jsxFragment: 'jsxf'`.
|
|
96
|
+
|
|
97
|
+
Both setups render the same, and the same components work in both.
|
|
98
|
+
|
|
99
|
+
## The idea
|
|
100
|
+
|
|
101
|
+
An application is split into three parts with clear responsibilities.
|
|
102
|
+
|
|
103
|
+
**Model**: a plain object. No proxies, no observables, no special setters. You change a value by assigning it. The model instance itself stays stable.
|
|
104
|
+
|
|
105
|
+
**Controller**: a plain class whose methods are the application's operations. Only the controller changes the model. Other parts, like the view, treat it as read-only. After an action, the controller updates the parts of the view that the action affected.
|
|
106
|
+
|
|
107
|
+
Deciding which parts to update is a small, explicit step for the programmer. In return, there is no hidden machinery to learn, debug or work around, and no diffing of old and new state.
|
|
108
|
+
|
|
109
|
+
**View**: the DOM, described with statically typed TSX. jmc renders it and keeps it in sync. An update can be as coarse as the whole page or as fine as a single element.
|
|
110
|
+
|
|
111
|
+
## Rendering and updating
|
|
112
|
+
|
|
113
|
+
`patch(node, h)` renders `h` in place of `node` and returns the rendered element. The usual start is to patch `document.body` with a `<body>` element:
|
|
114
|
+
|
|
115
|
+
```tsx
|
|
116
|
+
patch(document.body, <App />)
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
`updateview(...commands)` brings rendered parts of the page up to date. jmc remembers how each element was rendered, so it renders it again with the current model:
|
|
120
|
+
|
|
121
|
+
```tsx
|
|
122
|
+
updateview() // the whole body
|
|
123
|
+
updateview('#todos') // all elements matching a selector
|
|
124
|
+
updateview(element) // one element
|
|
125
|
+
updateview('#todos', '.badge') // several targets
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
jmc compares the new render with the existing DOM and changes only what differs. Existing elements are reused, so focus, selection and scroll positions stay intact.
|
|
129
|
+
|
|
130
|
+
Two more kinds of commands change how the targets after them are updated:
|
|
131
|
+
|
|
132
|
+
- **a number** limits the depth. `updateview(1, el)` updates only the props of `el`, not its children. `updateview(0, el)` discards the children of `el` and renders them from scratch.
|
|
133
|
+
- **an object** is passed as update context to all `update` callbacks (see below): `updateview({ resized: true })`.
|
|
134
|
+
|
|
135
|
+
Without a target, `updateview` updates `body`.
|
|
136
|
+
|
|
137
|
+
### Batching
|
|
138
|
+
|
|
139
|
+
These variants collect updates and run them together:
|
|
140
|
+
|
|
141
|
+
| function | runs the update |
|
|
142
|
+
|---|---|
|
|
143
|
+
| `updateviewmicro(...)` | at the next microtask |
|
|
144
|
+
| `updateviewaf(...)` | at the next animation frame |
|
|
145
|
+
| `updateviewsync(...)` | immediately, together with everything queued |
|
|
146
|
+
| `flush()` | runs everything queued, immediately |
|
|
147
|
+
|
|
148
|
+
An element queued several times is updated once.
|
|
149
|
+
|
|
150
|
+
## Components
|
|
151
|
+
|
|
152
|
+
### Function components
|
|
153
|
+
|
|
154
|
+
A function component receives its props and children and returns JSX:
|
|
155
|
+
|
|
156
|
+
```tsx
|
|
157
|
+
const TodoList = (p: { items: string[] }) =>
|
|
158
|
+
<ul id='todos'>{p.items.map(t => <li>{t}</li>)}</ul>
|
|
159
|
+
|
|
160
|
+
patch(document.body, <body><h1>Todos</h1><TodoList items={model.todos} /></body>)
|
|
161
|
+
|
|
162
|
+
model.todos.push('bread')
|
|
163
|
+
updateview('#todos') // runs TodoList again
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
When you update the root element of a function component, the function runs again. A component that returns a fragment has no single root element. It is updated through its parent.
|
|
167
|
+
|
|
168
|
+
A component gets its children in `props.children`, as an array:
|
|
169
|
+
|
|
170
|
+
```tsx
|
|
171
|
+
const Box = (p: { title: string, children?: Children }) =>
|
|
172
|
+
<section title={p.title}>{p.children}</section>
|
|
173
|
+
|
|
174
|
+
<Box title='hello'><b>world</b></Box>
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
### Class components
|
|
178
|
+
|
|
179
|
+
A class component keeps state between renders. Its instance is created once and reused as long as the same class is rendered at the same place:
|
|
180
|
+
|
|
181
|
+
```tsx
|
|
182
|
+
class Counter extends Component<{ start: number }> {
|
|
183
|
+
count = this.props.start
|
|
184
|
+
inc() { this.count++; this.updateview() }
|
|
185
|
+
view(): H { return <button onclick={this.inc}>{this.count}</button> }
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
patch(document.body, <body><Counter start={5} /></body>)
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
| member | |
|
|
192
|
+
|---|---|
|
|
193
|
+
| `view()` | returns the component's JSX: exactly one root element, or `null` to render nothing |
|
|
194
|
+
| `props` | the current props, updated on every render by the parent |
|
|
195
|
+
| `element` | the rendered root element |
|
|
196
|
+
| `mounted()` | called once, after the first render, when the whole tree is in the DOM |
|
|
197
|
+
| `update(uc)` | called before each re-render. Return `true` to skip the re-render, for example after updating the DOM yourself |
|
|
198
|
+
| `updateview()` | updates this component |
|
|
199
|
+
| `ismounted` | `true` once rendered |
|
|
200
|
+
|
|
201
|
+
Methods are bound to the instance, so they can be used directly as event handlers, as `onclick={this.inc}` above shows.
|
|
202
|
+
|
|
203
|
+
A component whose `view()` returns `null` keeps its state and can show itself again later.
|
|
204
|
+
|
|
205
|
+
## Elements
|
|
206
|
+
|
|
207
|
+
### Props: attributes and properties
|
|
208
|
+
|
|
209
|
+
jmc sets a prop as a DOM **property** when the value is an object or a function, or when the element has a property of that name, as `value` and `checked` do. Otherwise it sets an **attribute**. Names listed in `jmcconfig.attributes` are always set as attributes (see [Configuration](#configuration)). `style` given as a string is set as an attribute.
|
|
210
|
+
|
|
211
|
+
A prop starting with `on` whose value is a function is attached with `addEventListener`, the event name being the rest of the prop name, case kept: `onclick` listens to `click`, `onmy-event` to `my-event`. So custom events work as well as built-in ones. Replacing the function swaps the listener, removing the prop removes it.
|
|
212
|
+
|
|
213
|
+
`null`, `undefined` and `false` remove the attribute. On `aria-*` attributes, `false` is kept as the value `"false"`.
|
|
214
|
+
|
|
215
|
+
A prop whose value is wrapped in `live` is evaluated at each render:
|
|
216
|
+
|
|
217
|
+
```tsx
|
|
218
|
+
<dd class={live(() => cc('item', { active: model.active }))} />
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
### Children
|
|
222
|
+
|
|
223
|
+
Strings and numbers render as text. `null`, `undefined`, `false` and `true` render nothing, so conditions read naturally:
|
|
224
|
+
|
|
225
|
+
```tsx
|
|
226
|
+
<div>{model.error && <p class='error'>{model.error}</p>}</div>
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
A child that renders nothing still keeps its place, as an invisible empty text node. So when `model.error` appears or disappears, the elements after it stay the same elements, with their focus, scroll position and state.
|
|
230
|
+
|
|
231
|
+
Arrays are flattened, so `items.map(…)` works anywhere. jmc matches children by position, so elements inside a list that grows or shrinks can be reused for different items.
|
|
232
|
+
|
|
233
|
+
### Lifecycle callbacks
|
|
234
|
+
|
|
235
|
+
Elements accept two lifecycle callbacks:
|
|
236
|
+
|
|
237
|
+
```tsx
|
|
238
|
+
<canvas
|
|
239
|
+
mounted={(n) => draw(n)} // once, after the element is created
|
|
240
|
+
update={(n, uc) => { draw(n, uc); return true }} // before each update. true: skip the default update
|
|
241
|
+
/>
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
`mounted` callbacks, of elements and class components alike, run after the render has finished, so they see the complete DOM, connected to the document. Children run before their parents. `update` runs during the render, because its result decides whether jmc updates the element.
|
|
245
|
+
|
|
246
|
+
### Islands
|
|
247
|
+
|
|
248
|
+
Some content is managed by other code, such as a map or an editor. Mark its element with `const`: jmc renders the element and its children once, then never touches it again, neither its props nor its children. The library can take over in `mounted`, and the `update` callback passes later model changes on to it:
|
|
249
|
+
|
|
250
|
+
```tsx
|
|
251
|
+
<div class='map' const
|
|
252
|
+
mounted={(n) => map = new maplibregl.Map({ container: n })}
|
|
253
|
+
update={() => { map.setStyle(model.style) }}
|
|
254
|
+
/>
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
The `const` attribute stays visible in the DOM, which helps to spot islands in the dev tools.
|
|
258
|
+
|
|
259
|
+
jmc also leaves the children of web components (tags containing `-`) to the component itself.
|
|
260
|
+
|
|
261
|
+
### SVG
|
|
262
|
+
|
|
263
|
+
SVG is a different world from HTML, so entering it is explicit: `<svg>` needs its namespace, and the types require it. Its children inherit the namespace, and the children of `<foreignObject>` are HTML again:
|
|
264
|
+
|
|
265
|
+
```tsx
|
|
266
|
+
<svg xmlns='http://www.w3.org/2000/svg'><circle r={5} /></svg>
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
### Custom elements
|
|
270
|
+
|
|
271
|
+
jmc's element types live on the `jsx` function, not in a global `JSX` namespace. So they never clash with the JSX types of other libraries in the same project. Declare your own tags and their props by extending them:
|
|
272
|
+
|
|
273
|
+
```ts
|
|
274
|
+
import type { HtmlHTMLAttributes } from '@snupo/jmc'
|
|
275
|
+
|
|
276
|
+
declare module '@snupo/jmc' {
|
|
277
|
+
namespace jsx {
|
|
278
|
+
namespace JSX {
|
|
279
|
+
interface IntrinsicElements {
|
|
280
|
+
'my-chart': HtmlHTMLAttributes & { data: number[] }
|
|
281
|
+
}
|
|
282
|
+
}
|
|
283
|
+
}
|
|
284
|
+
}
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
## Configuration
|
|
288
|
+
|
|
289
|
+
`jmcconfig` holds the settings that adjust jmc:
|
|
290
|
+
|
|
291
|
+
```ts
|
|
292
|
+
import { jmcconfig } from '@snupo/jmc'
|
|
293
|
+
|
|
294
|
+
jmcconfig.debug = true // mark component roots with comp="Name"
|
|
295
|
+
jmcconfig.attributes.add('list') // always set this prop as an attribute
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
**`debug`**: every component root shows the component's name, as in `<section comp="Panel">`, so the dev tools reveal which component rendered what. The attribute is only set while `debug` is on. To switch it from the browser console, make the object reachable there with `mount({ jmcconfig })`, then run `jmcconfig.debug = true; updateview()`.
|
|
299
|
+
|
|
300
|
+
**`attributes`**: the prop names that jmc always sets as attributes, even where the element has a property of that name. By default `selected` and `viewBox`.
|
|
301
|
+
|
|
302
|
+
## Utilities
|
|
303
|
+
|
|
304
|
+
| | |
|
|
305
|
+
|---|---|
|
|
306
|
+
| `cc(...)` | joins class names. Objects contribute their keys with truthy values: `cc('item', { active })` |
|
|
307
|
+
| `<When cond={…}>` | renders its children only if `cond` is true |
|
|
308
|
+
| `live(f)` | a prop value that is evaluated at each render |
|
|
309
|
+
| `closestby(node, pred)` | the nearest ancestor (or the node itself) matching `pred` |
|
|
310
|
+
| `focuselement(node)` | focuses the node |
|
|
311
|
+
| `rebind(o)` | binds the prototype methods of `o` to `o` |
|
|
312
|
+
| `mount({ … })` | puts values on `globalThis`, handy for debugging in the console |
|
|
313
|
+
| `loggedmethods(o)` | logs each method call of `o` with its arguments and result |
|
|
314
|
+
|
|
315
|
+
## License
|
|
316
|
+
|
|
317
|
+
[MIT](LICENSE)
|