@tschk/moonshine-dom 0.0.0-stage → 0.4.4
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/LICENSE +15 -0
- package/README.md +398 -2
- package/package.json +57 -4
- package/src/attributes.ts +20 -0
- package/src/binding.ts +380 -0
- package/src/cleanup-order.ts +16 -0
- package/src/component-instance.ts +290 -0
- package/src/component.ts +176 -0
- package/src/control.ts +367 -0
- package/src/custom-element.ts +54 -0
- package/src/dom.ts +851 -0
- package/src/error.ts +59 -0
- package/src/framework-lazy.ts +20 -0
- package/src/framework-native.ts +134 -0
- package/src/framework-source.ts +28 -0
- package/src/html.ts +54 -0
- package/src/jsx-types.d.ts +19 -0
- package/src/reactive.ts +673 -0
- package/src/render-scheduler.ts +17 -0
- package/src/resource.ts +189 -0
- package/src/rotating-text.ts +38 -0
- package/src/ssr-attempt.ts +29 -0
- package/src/ssr-owner.ts +31 -0
- package/src/ssr.ts +617 -0
- package/src/store.ts +496 -0
- package/src/style.ts +30 -0
- package/src/template-retention.ts +4 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
ISC License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 The Software Company of Hong Kong
|
|
4
|
+
|
|
5
|
+
Permission to use, copy, modify, and/or distribute this software for any
|
|
6
|
+
purpose with or without fee is hereby granted, provided that the above
|
|
7
|
+
copyright notice and this permission notice appear in all copies.
|
|
8
|
+
|
|
9
|
+
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
|
|
10
|
+
REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
|
|
11
|
+
AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
|
|
12
|
+
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
|
|
13
|
+
LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
|
|
14
|
+
OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
|
|
15
|
+
PERFORMANCE OF THIS SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,399 @@
|
|
|
1
|
-
#
|
|
1
|
+
# `@tschk/moonshine-dom`
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Independent Moonshine browser and server rendering. The only runtime dependency
|
|
4
|
+
is the signal kernel; this package has no React, Solid or parser dependency.
|
|
5
|
+
|
|
6
|
+
```ts
|
|
7
|
+
import { h, render } from "@tschk/moonshine-dom";
|
|
8
|
+
import { createSignal } from "@tschk/moonshine-dom/reactive";
|
|
9
|
+
|
|
10
|
+
const dispose = render(() => {
|
|
11
|
+
const [count, setCount] = createSignal(0);
|
|
12
|
+
return h("button", { onClick: () => setCount(count() + 1) }, count);
|
|
13
|
+
}, document.getElementById("app")!);
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
- `/reactive`: signals, memos, owned computations, cleanup and batching.
|
|
17
|
+
`on(accessor, callback, { defer: true })` limits an effect or memo to explicit
|
|
18
|
+
dependencies and skips its first callback. An array of accessors supplies a
|
|
19
|
+
tuple of values. The callback receives current inputs, previous inputs and its
|
|
20
|
+
previous result; incidental callback reads do not subscribe. Omit `defer` to
|
|
21
|
+
run on the first evaluation. The same helper is available on `/ssr`.
|
|
22
|
+
- `/html`: opt-in, unsanitized markup. `rawHTML(read, namespace?)` returns an
|
|
23
|
+
accessor of cached nodes for ordinary `h` children; namespace is `html`, `svg`,
|
|
24
|
+
or `mathml`. `htmlContent(element, read)` requires a live owner and controls a
|
|
25
|
+
fresh element's entire sole-child contents (including cleanup); initialize it
|
|
26
|
+
from an `h` ref callback without ordinary children. It preserves contextual
|
|
27
|
+
table/SVG parsing. Identical raw values retain nodes; changed values replace
|
|
28
|
+
them. Both helpers assign directly to `innerHTML`, including TrustedHTML.
|
|
29
|
+
SSR's separate `rawHTML(value)` export from `/ssr` emits unescaped markup.
|
|
30
|
+
These helpers are not sanitizers: inline handlers and other active content
|
|
31
|
+
remain active, although inserted scripts are inert in the browser. Inject only
|
|
32
|
+
trusted content. Injected markup is not compiled into components or bindings;
|
|
33
|
+
this provides no hydration behavior. Default native children remain escaped.
|
|
34
|
+
- `/custom-element`: optional `setCustomElementValue(node, name, value)` preserves
|
|
35
|
+
literal object/function values for registered custom-element setters. Compiler
|
|
36
|
+
effects evaluate expressions before calling it; setters run without tracking or
|
|
37
|
+
an owner. Hyphenated HTML elements only; events use ordinary event listeners.
|
|
38
|
+
Missing setters use string attributes, nullish values remove attributes, and
|
|
39
|
+
unregistered elements receive nonnull objects as properties (upgrade does not
|
|
40
|
+
replay setters). HTML-content/prototype names and style always remain literal
|
|
41
|
+
attributes. This opt-in boundary rejects event names and preserves the ordinary
|
|
42
|
+
`h` contract; it does not supply SSR serialization or hydration.
|
|
43
|
+
- `/component`: per-instance setup scopes, inherited context and an explicit
|
|
44
|
+
component-event listener symbol. Both `h(Component, props)` factories enter an
|
|
45
|
+
attached, untracked scope and preserve live prop descriptors. Context APIs are
|
|
46
|
+
initialization-only; detached control-flow roots inherit context without
|
|
47
|
+
changing their explicit disposal contract. Render roots through `h` to enter
|
|
48
|
+
the component scope. Context-map snapshots do not provide a legacy vnode ABI.
|
|
49
|
+
- `/component-instance`: compiler-facing named exports and captured-path references.
|
|
50
|
+
`exposeComponent(exports)` preserves own descriptors in an opaque instance;
|
|
51
|
+
`componentRef` props carry `{ get, set }`. References publish after setup and
|
|
52
|
+
clear to `null` in a later microtask, only if they still refer to that instance.
|
|
53
|
+
References may opt into `cleanup: "commit"` for Svelte 5.57 teardown timing:
|
|
54
|
+
child and ancestor cleanup can still read the instance, then it clears after
|
|
55
|
+
the complete native cleanup commit and before the outer disposer returns.
|
|
56
|
+
The Svelte lifecycle queue publishes pending references before mount/effect
|
|
57
|
+
callbacks by default. `publication: "post"` requires an active rune scheduler
|
|
58
|
+
and queues publication at the registration point among child lifecycle posts,
|
|
59
|
+
before ancestor posts. Register exposure after child effects/mounts when those
|
|
60
|
+
callbacks must precede publication. SSR creates no reference callbacks. Dynamic paths may supply
|
|
61
|
+
`{ parts: () => tuple, get: (...parts) => value, set: (value, ...parts) => {} }`.
|
|
62
|
+
Only parts are tracked, after setup during reference publication. Path changes
|
|
63
|
+
publish the new target before clearing the old captured target if it still holds
|
|
64
|
+
that instance; disposal clears the last captured path using the chosen timing. Cell
|
|
65
|
+
getters/setters are untracked. Publication drains at most 1,000 successive feedback
|
|
66
|
+
waves per flush; independent references in one wave are not capped.
|
|
67
|
+
`ComponentReference<T, readonly [Key, Index]>`
|
|
68
|
+
preserves typed tuple arguments and requires parts for nonempty tuples;
|
|
69
|
+
`ComponentReference<T>` retains the fixed-cell contract. SFC `bind:this` now has bounded scalar/member source acceptance, including empty exports; loop-dependent path extraction remains compiler work.
|
|
70
|
+
- `/ssr-owner`: lightweight `scopeSSRChild(child)` captures a live owner for the
|
|
71
|
+
complete serialization of deferred children. It is also exported by `/ssr`.
|
|
72
|
+
It preserves request context, select state, SVG namespace and text escaping;
|
|
73
|
+
serializing it after owner disposal throws. This entry lets browser provider
|
|
74
|
+
modules support SSR without importing the serializer into browser bundles.
|
|
75
|
+
`isSSRRendering()` detects the synchronous serialization extent, including
|
|
76
|
+
bare callbacks and cleanup; it does not propagate across async continuations.
|
|
77
|
+
- `/render-scheduler`: internal opt-in carrier contract for native render effects,
|
|
78
|
+
structural memos and component/control ownership. The Svelte `/pre` module owns
|
|
79
|
+
the scheduling implementation. Ordinary native rendering stays synchronous;
|
|
80
|
+
the signal kernel has no scheduler dependency.
|
|
81
|
+
- `/resource`: owned client data fetching, separate from the kernel's resource API.
|
|
82
|
+
- `/control`: keyed `For`/`mapArray`, position-stable `Index`/`indexArray`, and
|
|
83
|
+
retained `Show` branches with explicit accessors. `Index({ each, children })`
|
|
84
|
+
calls `children(itemAccessor, indexNumber)` once per position; replacement and
|
|
85
|
+
reorder update `itemAccessor()` while preserving that position's DOM and owner.
|
|
86
|
+
Use it for editable primitive lists; keyed `For` follows item identity instead.
|
|
87
|
+
Removed tail positions dispose their owners; appended positions get new owners.
|
|
88
|
+
`Switch({ children: () => matches, fallback })` retains the first truthy
|
|
89
|
+
`Match({ when: accessor, children: valueAccessor => child })`. Conditions are
|
|
90
|
+
checked in order; inactive branches create no contents and selected branches
|
|
91
|
+
retain their owner until selection changes.
|
|
92
|
+
- `/dom` (also the root): direct DOM factories, reactive children/attributes,
|
|
93
|
+
events, refs, form defaults, SVG and bounded style objects.
|
|
94
|
+
- `/ssr`: escaped HTML factories and server lifecycle hooks.
|
|
95
|
+
`boundary(render, fallback)` buffers synchronous serialization, discards failed
|
|
96
|
+
output and internal scopes, then serializes the fallback in a fresh scope.
|
|
97
|
+
Deferred children, arrays, select bookkeeping and SVG context are covered.
|
|
98
|
+
Accepted scopes live until request cleanup; discarded Svelte destruction hooks
|
|
99
|
+
are suppressed. Factories can be created ahead of time and reused: ownership
|
|
100
|
+
and context come from the current serializer. Fallback failures reach an outer
|
|
101
|
+
boundary. Arbitrary state writes and `afterRender` commits are not rolled back.
|
|
102
|
+
Externally captured `scopeSSRChild` values retain their lexical owner and error
|
|
103
|
+
policy; an error already swallowed there cannot reach this boundary. This is a
|
|
104
|
+
native serialization API, with no async, reset, hydration or SFC boundary ABI.
|
|
105
|
+
- `/framework-native`: the bundled framework renderer; requires the optional
|
|
106
|
+
`@tschk/moonshine-framework` peer. Supports Bun, Node and Cloudflare SSR, static-mode rendering and
|
|
107
|
+
fresh SPA mounts with separate authored client entries.
|
|
108
|
+
- `/framework-source`: source-file SSR compatibility for Bun/Node, shared by
|
|
109
|
+
the Solid and Svelte replacements. It imports page/layout files on demand;
|
|
110
|
+
deployed bundles use `/framework-native` with their bundled module inventory.
|
|
111
|
+
|
|
112
|
+
If a root callback throws, its owned work is disposed before deferred effects start,
|
|
113
|
+
and the original callback error is rethrown even if cleanup fails.
|
|
114
|
+
|
|
115
|
+
Native SSR layouts initialize around lazy page children, so context providers
|
|
116
|
+
reach their descendants. Explicit `/ssr` `defer(() => child)` retains the live component owner;
|
|
117
|
+
reused factories attach to the current request after that owner is disposed.
|
|
118
|
+
Ordinary accessor children and attributes keep their eager construction snapshot.
|
|
119
|
+
|
|
120
|
+
Source parsing and lowering belong in Crepuscularity. These APIs do not implement
|
|
121
|
+
Solid's compiled instructions. Hydration, islands and async server components
|
|
122
|
+
are unsupported. Raw HTML uses the explicit `/html` entry. Property-only state can use refs. Style objects use
|
|
123
|
+
hyphenated CSS names and explicit units; complex declarations use CSS strings.
|
|
124
|
+
SSR cannot encode distinct live and reset values for a form control. Ambiguous
|
|
125
|
+
SVG tags need an accessor parent context or an explicit namespace.
|
|
126
|
+
|
|
127
|
+
See [the native example](../../examples/native-app/README.md),
|
|
128
|
+
[compiled TSX components](../../examples/native-template/README.md),
|
|
129
|
+
[compiler limits](../compiler/README.md), and [the design](../../DESIGN.md).
|
|
130
|
+
For reproducible scoped comparisons, run `bun scripts/benchmark-reactive.ts`,
|
|
131
|
+
`bun scripts/benchmark-ssr.ts`, or the browser `bun scripts/benchmark-dom.ts` from
|
|
132
|
+
the repository root. Current fixtures have smaller Moonshine bundles but slower
|
|
133
|
+
rendering than Solid; these are not complete framework comparisons.
|
|
134
|
+
For the authored counter comparison against React, run
|
|
135
|
+
`CREPUS_COMPILER=/path/to/crepus bun scripts/benchmark-counter.ts`. It checks
|
|
136
|
+
identical SSR markup and serial DOM commits, reports compressed bundle sizes,
|
|
137
|
+
and records versions and source hashes. Fresh-document startup measures from
|
|
138
|
+
before localhost module fetch through complete DOM commit, with HTTP caching
|
|
139
|
+
disabled, alternating order, five warmups and 25 recorded loads per runtime.
|
|
140
|
+
The browser/process stays warm; document navigation, paint, remote network and
|
|
141
|
+
hydration are excluded. This is one counter workload, not a framework ranking.
|
|
142
|
+
For the exact same authored two-component SFC counter against installed Svelte,
|
|
143
|
+
run `CREPUS_COMPILER=/path/to/crepus bun scripts/benchmark-sfc-counter.ts`.
|
|
144
|
+
It snapshots the compiler and native packages, fingerprints sources/artifacts,
|
|
145
|
+
compares production gzip/Brotli sizes and checks five clicks plus retained child
|
|
146
|
+
identity in Chromium. It also alternates five warmups and 25 fresh-document
|
|
147
|
+
startup samples per framework, plus 625 serial click-to-DOM-commit observations.
|
|
148
|
+
The browser/process stays warm and local responses disable caching. In-page
|
|
149
|
+
clocks exclude RPC time; startup includes localhost module fetch and evaluation.
|
|
150
|
+
Timer resolution can produce zero click medians, which do not mean free work.
|
|
151
|
+
A separate warm Bun process also measures fresh synchronous SSR from those same
|
|
152
|
+
authored components: five discarded warmups, 25 alternating samples of 5,000
|
|
153
|
+
renders, exact repeated markup and visible HTML equality after removing only
|
|
154
|
+
hydration comments. It reports SSR bundle sizes, median/p95 and raw samples in
|
|
155
|
+
the same fingerprinted result. Navigation, paint, cold startup, async data, remote
|
|
156
|
+
network and hydration are excluded. These results cover one workload, not a
|
|
157
|
+
framework ranking.
|
|
158
|
+
|
|
159
|
+
Events accept functions or native listener objects with `handleEvent(event)`.
|
|
160
|
+
Listener objects may include `capture`, `once`, `passive` and `signal` options;
|
|
161
|
+
`this` inside `handleEvent` is the listener object. For example,
|
|
162
|
+
`h("div", { "on:click": { capture: true, handleEvent(event) {} } })` registers
|
|
163
|
+
capture before bubbling handlers. `on:eventName` preserves event name case;
|
|
164
|
+
`onClick` continues to register `click`. Options are captured at registration,
|
|
165
|
+
and owner disposal removes the registered listener. SSR omits event props.
|
|
166
|
+
|
|
167
|
+
DOM lifecycle updates use setters and `batch` from `/reactive`: mount callbacks
|
|
168
|
+
run after the synchronous DOM updates finish. Wrap external kernel signal or store
|
|
169
|
+
writes in this native `batch` too, so newly inserted components mount after commit.
|
|
170
|
+
|
|
171
|
+
For authored TSX source checking, opt in with a declaration file containing
|
|
172
|
+
`import type {} from "@tschk/moonshine-dom/jsx-types";` and TypeScript options
|
|
173
|
+
`"jsx": "preserve", "noEmit": true`. Include that declaration and the source TSX
|
|
174
|
+
in a native-only tsconfig. This supplies no executable JSX runtime: compile source
|
|
175
|
+
with Crepus before running it. Keep React source in a separate config because this
|
|
176
|
+
opt-in namespace describes native components.
|
|
177
|
+
|
|
178
|
+
The types check component props, children, and known HTML/SVG tag names. Intrinsic
|
|
179
|
+
props match `h`'s unrestricted records; attribute names, attribute values, and event
|
|
180
|
+
parameter types are not checked or inferred.
|
|
181
|
+
|
|
182
|
+
Optional structured state lives on `/store`, using the native reactive graph:
|
|
183
|
+
|
|
184
|
+
```ts
|
|
185
|
+
import { createStore, produce, reconcile } from "@tschk/moonshine-dom/store";
|
|
186
|
+
|
|
187
|
+
const [state, setState] = createStore({ user: { name: "Ada" }, visits: 0 });
|
|
188
|
+
setState("user", "name", "Grace");
|
|
189
|
+
setState(
|
|
190
|
+
produce((draft) => {
|
|
191
|
+
draft.visits++;
|
|
192
|
+
}),
|
|
193
|
+
);
|
|
194
|
+
setState(reconcile({ user: { name: "Lin" }, visits: 3 }));
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
Property reads, membership checks and key enumeration subscribe independently.
|
|
198
|
+
Public proxies are read-only; setters batch writes through native `/reactive`.
|
|
199
|
+
Path setters support key arrays and array predicates/ranges. Object updates
|
|
200
|
+
shallow-merge; `undefined` deletes a property. `produce` supplies writable drafts;
|
|
201
|
+
`reconcile` replaces snapshots while retaining matching array items by `id`
|
|
202
|
+
(or a supplied key), with `key: null` and `merge` options.
|
|
203
|
+
|
|
204
|
+
Plain objects and arrays retain their input identity. Use setters for tracked
|
|
205
|
+
changes; external mutations of the original object do not notify observers.
|
|
206
|
+
Class instances and other non-plain values are opaque references; their own
|
|
207
|
+
mutations do not notify observers.
|
|
208
|
+
Frozen/nonextensible objects, descriptor/prototype mutation and unsafe prototype
|
|
209
|
+
paths reject explicitly. Deep setter paths have broad TypeScript types. The
|
|
210
|
+
kernel's `createStore` retains its callback-mutation API. The Solid replacement's
|
|
211
|
+
`/store` uses this same native graph; a separately installed Solid runtime does
|
|
212
|
+
not observe it.
|
|
213
|
+
|
|
214
|
+
Client resources use the same native graph:
|
|
215
|
+
|
|
216
|
+
```ts
|
|
217
|
+
import { createResource } from "@tschk/moonshine-dom/resource";
|
|
218
|
+
|
|
219
|
+
const [user, { mutate, refetch }] = createResource(userId, async (id) =>
|
|
220
|
+
(await fetch(`/api/users/${id}`)).json(),
|
|
221
|
+
);
|
|
222
|
+
// user() reads the value; user.loading, user.error and user.state are reactive.
|
|
223
|
+
// mutate(nextValue) edits locally; refetch(info) fetches the current source again.
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
Create resources inside an owned root or rendered component. A source accessor
|
|
227
|
+
refetches when its value changes; `false`, `null` and `undefined` disable fetching.
|
|
228
|
+
Fetchers receive the source plus `{ value, refetching }` and may return a value or
|
|
229
|
+
promise. Only the newest request publishes; disposal ignores later results.
|
|
230
|
+
This does not cancel the underlying operation. `mutate` changes only the value;
|
|
231
|
+
an active request may overwrite it. Reads throw terminal fetch errors. The
|
|
232
|
+
`latest` getter retains the previous value while refreshing. State is one of
|
|
233
|
+
`unresolved`, `pending`, `ready`, `refreshing` or `errored`.
|
|
234
|
+
Each explicit `refetch` starts a request; calls within one microtask are not
|
|
235
|
+
coalesced. Fetcher cleanup callbacks retain the resource's owner on refetch.
|
|
236
|
+
|
|
237
|
+
Options support `initialValue` and an informational `name`; other options reject.
|
|
238
|
+
This client API does not implement Suspense, transitions, hydration or async SSR,
|
|
239
|
+
and is not yet admitted by the Solid compiler bridge. The Solid replacement's
|
|
240
|
+
`/solid` export uses this client resource API; the kernel resource API keeps
|
|
241
|
+
its existing contract.
|
|
242
|
+
|
|
243
|
+
### Optional input bindings
|
|
244
|
+
|
|
245
|
+
`@tschk/moonshine-dom/binding` exports `bindValue(element, read, write)`. Call it
|
|
246
|
+
under a live owner after constructing a text/number/range, date, datetime-local,
|
|
247
|
+
month, week, time or color input, or textarea, and
|
|
248
|
+
installing its attributes and user event listeners. It synchronizes parent writes,
|
|
249
|
+
input events and uncancelled form resets, including externally associated forms.
|
|
250
|
+
Undefined/null initial state adopts an existing nonempty DOM value; number/range
|
|
251
|
+
events produce numbers, with empty/invalid numbers producing `undefined`. Other
|
|
252
|
+
accepted types write strings. Browser sanitization stays native: parent model
|
|
253
|
+
values are not replaced by sanitized DOM values, and resets forward raw defaults. Disposal
|
|
254
|
+
removes listeners and suppresses pending reset work. Keep the input type fixed
|
|
255
|
+
for the binding lifetime. Reset synchronization requires a form connected to the
|
|
256
|
+
control's owner document; detached forms are outside this contract. This optional primitive
|
|
257
|
+
does not implement hydration or SFC parsing/lowering.
|
|
258
|
+
|
|
259
|
+
`bindChecked(checkbox, read, write)` uses the same owner/reset contract with the
|
|
260
|
+
`change` event. Nullish initial state adopts `checked` (including false), while
|
|
261
|
+
explicit state overrides `defaultChecked`. Parent writes update checked state;
|
|
262
|
+
uncancelled resets synchronize its default back to state. Install user change
|
|
263
|
+
listeners before the binding. Keep the type fixed to checkbox.
|
|
264
|
+
|
|
265
|
+
`bindSelectValue(select, read, write)` supports single/multiple selects and owns
|
|
266
|
+
its change/reset listeners and option MutationObserver. Single values match by
|
|
267
|
+
`Object.is`; multiple values use array membership. Undefined initial state adopts
|
|
268
|
+
the DOM selection (all selected values as an array for multiple). Explicit null
|
|
269
|
+
selects a typed null option if present, otherwise clears a single select; multiple nullish values preserve selection. Invalid
|
|
270
|
+
nonarray multiple values throw. Option changes reapply the model without writing
|
|
271
|
+
a new model value. Keep `multiple` fixed for the binding lifetime.
|
|
272
|
+
|
|
273
|
+
For typed primitive/object option values, call `setOptionValue(option, value)`
|
|
274
|
+
after constructing each option; identity is preserved in a private WeakMap and
|
|
275
|
+
updates refresh its bound select even when their DOM strings are equal. Ordinary
|
|
276
|
+
`h("option", { value })` retains string semantics. The compiler must emit this
|
|
277
|
+
explicit hook and keep SSR serialization separate; this is not hydration.
|
|
278
|
+
|
|
279
|
+
The SSR factory exports optional `selectBinding` and `optionBinding` symbols for
|
|
280
|
+
compiler-created typed selections: `h("select", { [selectBinding]: { value } },
|
|
281
|
+
h("option", { [optionBinding]: { value: option } }, label))`. These boxes carry
|
|
282
|
+
literal values, including functions, without calling them. Options serialize
|
|
283
|
+
their value once with HTML escaping; nullish/function values omit the attribute.
|
|
284
|
+
Single selections compare raw values with `===`; multiple arrays use `includes`,
|
|
285
|
+
matching Svelte 5.57 SSR. All matching options receive `selected`; an unmatched
|
|
286
|
+
typed selection is allowed. Ordinary string select behavior stays unchanged.
|
|
287
|
+
These symbols provide SSR output, not hydration or client identity transport.
|
|
288
|
+
|
|
289
|
+
Intentional reference difference: Chromium probes of Svelte 5.46.4 and cached
|
|
290
|
+
5.57.1 initialize an undefined
|
|
291
|
+
multiple-select binding to only the first selected scalar. Native bindings adopt
|
|
292
|
+
all selected values as an array, consistent with the multiple-value contract.
|
|
293
|
+
This is a measured difference for those versions, not a claim about all Svelte versions.
|
|
294
|
+
|
|
295
|
+
Native lifecycle adapters can register `onBeforeDispose` and `onAfterDispose`
|
|
296
|
+
from `/reactive`. Before callbacks run parent-first while owned work is live;
|
|
297
|
+
after callbacks run child-first after outer cleanup, DOM removal and the current
|
|
298
|
+
native commit. These are final-disposal hooks, not computation-rerun hooks.
|
|
299
|
+
Disposal drains callbacks, children, cleanups and stops while preserving the first
|
|
300
|
+
error, including reentrant disposal. Before-disposal callbacks may register
|
|
301
|
+
`onAfterDispose` callbacks on their still-live owner; registering another
|
|
302
|
+
`onBeforeDispose` callback during disposal is rejected. Both registrations reject
|
|
303
|
+
ownerless or already disposed scopes.
|
|
304
|
+
|
|
305
|
+
`queuePostCommit` uses the existing native commit queue, or a microtask outside a
|
|
306
|
+
commit; generic callbacks must manage their own cancellation. `/component` also
|
|
307
|
+
provides `onComponentReady` during setup, fired once after successful setup with
|
|
308
|
+
the frame inactive. Failed or already disposed instances do not become ready.
|
|
309
|
+
|
|
310
|
+
`createInputGroup(kind, read, write)` returns `{ bind(input) }` for radio or
|
|
311
|
+
checkbox groups. Create each token under a live owner, then bind inputs under
|
|
312
|
+
their own live row/component owners after attributes and user change handlers.
|
|
313
|
+
Token disposal releases every member; row disposal unregisters only that member.
|
|
314
|
+
The compiler allocates tokens per binding target/component and nested each path;
|
|
315
|
+
there is no global name lookup or runtime ownership guessing. Browser HTML `name`
|
|
316
|
+
grouping still applies independently. Keep input types fixed.
|
|
317
|
+
|
|
318
|
+
`setInputValue(input, value)` stores typed group values privately and refreshes
|
|
319
|
+
selection on value changes. Ordinary inputs retain string values without this
|
|
320
|
+
hook. Checkbox models must be arrays or nullish; other values reject. Radios use
|
|
321
|
+
`Object.is` on native identities (no Svelte proxy unwrapping); checkbox membership uses array inclusion and change
|
|
322
|
+
collection deduplicates values in current DOM order. Unchecking a duplicate value
|
|
323
|
+
removes that value from the group. Removing a member preserves model state until
|
|
324
|
+
a subsequent change; value changes reapply the model without writing it back.
|
|
325
|
+
|
|
326
|
+
Pinned Svelte 5.46.4 Chromium behavior (also present in 5.57.1 source): group
|
|
327
|
+
undefined state does not adopt checked defaults; radio resets write `null` and
|
|
328
|
+
checkbox resets write `[]`. This differs from standalone `bindChecked` default
|
|
329
|
+
adoption. Native groups follow that protocol, respect cancelled connected-form
|
|
330
|
+
resets and suppress pending work after disposal. No SSR group serialization,
|
|
331
|
+
hydration, cross-component grouping or SFC lowering is claimed by these helpers.
|
|
332
|
+
|
|
333
|
+
New attached scopes reject disposed owners, including work created by post-disposal
|
|
334
|
+
callbacks. Explicit detached roots remain independent and require their own stop.
|
|
335
|
+
|
|
336
|
+
Both `bindSelectValue(select, read, write, equal?)` and
|
|
337
|
+
`createInputGroup(kind, read, write, equal?)` accept an optional final equality
|
|
338
|
+
predicate, defaulting to `Object.is`. It applies only to single selects and radio
|
|
339
|
+
groups; multiple selects and checkbox groups retain array membership semantics.
|
|
340
|
+
This lets compiler adapters normalize their own raw/proxy identities without
|
|
341
|
+
importing a source-language runtime into DOM. Stored values and change payloads
|
|
342
|
+
keep the original typed identity; equality never substitutes a normalized value.
|
|
343
|
+
|
|
344
|
+
Value-binding resets copy raw `defaultValue` into the model before numeric
|
|
345
|
+
conversion. The browser may clamp or sanitize its live value independently: an
|
|
346
|
+
empty range default yields native model `undefined` with a browser value of 50;
|
|
347
|
+
a range default 5 below minimum 10 yields model 5 with browser value 10. Empty
|
|
348
|
+
or invalid numeric defaults remain `undefined`. Svelte's adapter can translate
|
|
349
|
+
empty native numeric values to its version-specific null convention; invalid raw
|
|
350
|
+
numeric defaults still differ from Svelte 5.46.4/5.57.1's NaN conversion.
|
|
351
|
+
|
|
352
|
+
`bindValue` write callbacks may accept optional second argument `reset?: true`.
|
|
353
|
+
Only form-reset writes receive it; normal input and initial adoption call the
|
|
354
|
+
setter with one argument. Compiler adapters can use this metadata to translate
|
|
355
|
+
source-specific numeric reset conventions without adding listeners or changing
|
|
356
|
+
the generic native empty/invalid-to-undefined contract. Existing one-argument
|
|
357
|
+
setters remain compatible.
|
|
358
|
+
|
|
359
|
+
`bindOpen(details, read, write)` controls a details element's `open` property.
|
|
360
|
+
Install it after user `toggle` listeners under a live native owner. Nullish state
|
|
361
|
+
closes the element without adopting its initial DOM state. Native toggle events
|
|
362
|
+
write the boolean property after user listeners; browser coalescing is preserved.
|
|
363
|
+
It has no form-reset behavior. Cleanup removes the binding listener, including
|
|
364
|
+
queued events and retained detached nodes (unlike the audited Svelte 5.57 listener).
|
|
365
|
+
SSR uses the ordinary boolean `open` attribute snapshot. The Svelte `/binding`
|
|
366
|
+
entry re-exports this helper; authored `bind:open` lowering remains pending.
|
|
367
|
+
|
|
368
|
+
`/store`'s `createMutable(value, { equals })` can select property-write equality.
|
|
369
|
+
The default is strict equality (`===`); the optional comparator receives the
|
|
370
|
+
previous and next values. Nested mutable views and accessor setter receivers
|
|
371
|
+
retain that policy, and raw-object views are cached separately per comparator
|
|
372
|
+
function. The Vue adapter supplies `Object.is` for signed-zero/NaN behavior.
|
|
373
|
+
|
|
374
|
+
## Optional rotating text
|
|
375
|
+
|
|
376
|
+
`@tschk/moonshine-dom/rotating-text` exports `createRotatingText(phrases, intervalMs)`.
|
|
377
|
+
Its text accessor advances inside a live render owner and stops when that owner
|
|
378
|
+
is disposed. Reduced motion keeps the first phrase; changing the preference
|
|
379
|
+
pauses or resumes rotation. Empty and single-phrase inputs create no timers.
|
|
380
|
+
The helper is separate from the DOM root and signal-only exports.
|
|
381
|
+
|
|
382
|
+
## Compiler-owned template blocks
|
|
383
|
+
|
|
384
|
+
The `/dom` entry exposes `templateBlock(build)` for compiler-owned node trees.
|
|
385
|
+
It detaches a block before disposal callbacks while preserving its descendant
|
|
386
|
+
DOM for those callbacks; effects, listeners and owned ranges still stop. Pass
|
|
387
|
+
the supplied retention predicate to compiler-created insertion ranges. Nested
|
|
388
|
+
`h()` children and insertion ranges inherit the containing block policy; an
|
|
389
|
+
explicit range predicate overrides it. Cleanup still stops their reactive work
|
|
390
|
+
and listeners.
|
|
391
|
+
|
|
392
|
+
Compiler-owned control ranges can pass an explicit scheduling function to
|
|
393
|
+
`Show`, `For`, `mapArray` (fourth argument), or `indexArray`. Passing `read => read`
|
|
394
|
+
keeps reconciliation inside the containing range pull. The default scheduler and
|
|
395
|
+
`mapArray`'s third deferred-removal argument retain their existing behavior.
|
|
396
|
+
|
|
397
|
+
`setAttributeValue` exposes the existing native attribute setter for typed node
|
|
398
|
+
updates. It does not install event handlers or replace form-binding helpers.
|
|
399
|
+
These primitives do not by themselves implement Svelte directive source syntax.
|
package/package.json
CHANGED
|
@@ -1,6 +1,59 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tschk/moonshine-dom",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.4.4",
|
|
4
|
+
"description": "Independent Moonshine DOM, SSR and reactive rendering",
|
|
5
|
+
"license": "ISC",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"main": "./src/dom.ts",
|
|
8
|
+
"types": "./src/dom.ts",
|
|
9
|
+
"exports": {
|
|
10
|
+
".": "./src/dom.ts",
|
|
11
|
+
"./dom": "./src/dom.ts",
|
|
12
|
+
"./reactive": "./src/reactive.ts",
|
|
13
|
+
"./component": "./src/component.ts",
|
|
14
|
+
"./component-instance": "./src/component-instance.ts",
|
|
15
|
+
"./ssr": "./src/ssr.ts",
|
|
16
|
+
"./control": "./src/control.ts",
|
|
17
|
+
"./store": "./src/store.ts",
|
|
18
|
+
"./resource": "./src/resource.ts",
|
|
19
|
+
"./framework-native": "./src/framework-native.ts",
|
|
20
|
+
"./framework-source": "./src/framework-source.ts",
|
|
21
|
+
"./jsx-types": {
|
|
22
|
+
"types": "./src/jsx-types.d.ts"
|
|
23
|
+
},
|
|
24
|
+
"./binding": "./src/binding.ts",
|
|
25
|
+
"./custom-element": "./src/custom-element.ts",
|
|
26
|
+
"./ssr-owner": "./src/ssr-owner.ts",
|
|
27
|
+
"./ssr-attempt": "./src/ssr-attempt.ts",
|
|
28
|
+
"./html": "./src/html.ts",
|
|
29
|
+
"./framework-lazy": "./src/framework-lazy.ts",
|
|
30
|
+
"./render-scheduler": "./src/render-scheduler.ts",
|
|
31
|
+
"./rotating-text": "./src/rotating-text.ts"
|
|
32
|
+
},
|
|
33
|
+
"files": [
|
|
34
|
+
"src",
|
|
35
|
+
"README.md",
|
|
36
|
+
"LICENSE"
|
|
37
|
+
],
|
|
38
|
+
"scripts": {
|
|
39
|
+
"format": "bunx prettier --check .",
|
|
40
|
+
"lint": "bunx oxlint .",
|
|
41
|
+
"typecheck": "bunx tsc --noEmit",
|
|
42
|
+
"test": "bun test"
|
|
43
|
+
},
|
|
44
|
+
"dependencies": {
|
|
45
|
+
"@tschk/moonshine": "^0.4.4"
|
|
46
|
+
},
|
|
47
|
+
"peerDependencies": {
|
|
48
|
+
"@tschk/moonshine-framework": "^0.4.4"
|
|
49
|
+
},
|
|
50
|
+
"peerDependenciesMeta": {
|
|
51
|
+
"@tschk/moonshine-framework": {
|
|
52
|
+
"optional": true
|
|
53
|
+
}
|
|
54
|
+
},
|
|
55
|
+
"devDependencies": {
|
|
56
|
+
"@types/bun": "1.3.14",
|
|
57
|
+
"typescript": "7.0.2"
|
|
58
|
+
}
|
|
59
|
+
}
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
// https://html.spec.whatwg.org/multipage/indices.html#attributes-3
|
|
2
|
+
const BOOLEAN = new Set(
|
|
3
|
+
"allowfullscreen alpha async autofocus autoplay checked controls default defer disabled formnovalidate headingreset inert ismap itemscope loop multiple muted nomodule novalidate open playsinline readonly required reversed selected shadowrootclonable shadowrootcustomelementregistry shadowrootdelegatesfocus shadowrootserializable".split(
|
|
4
|
+
" ",
|
|
5
|
+
),
|
|
6
|
+
);
|
|
7
|
+
|
|
8
|
+
export function attributeValue(
|
|
9
|
+
name: string,
|
|
10
|
+
value: unknown,
|
|
11
|
+
html: boolean,
|
|
12
|
+
): string | undefined {
|
|
13
|
+
const lower = name.toLowerCase();
|
|
14
|
+
// Hidden also accepts an empty hidden state and the string 'until-found'.
|
|
15
|
+
const boolean = html && (BOOLEAN.has(lower) || lower === "hidden");
|
|
16
|
+
if (value == null || (boolean && !value && value !== "")) return undefined;
|
|
17
|
+
if (html && lower === "translate" && typeof value === "boolean")
|
|
18
|
+
return value ? "yes" : "no";
|
|
19
|
+
return boolean && value === true ? "" : String(value);
|
|
20
|
+
}
|