@verajs/renderer 0.2.2 → 0.3.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 +711 -225
- package/dist/development/vera-renderer-elements.d.ts +39 -0
- package/dist/development/vera-renderer-elements.d.ts.map +1 -0
- package/dist/development/vera-renderer-elements.js +193 -0
- package/dist/development/vera-renderer-elements.js.map +1 -0
- package/dist/development/vera-renderer-hydrate-slots.d.ts +94 -0
- package/dist/development/vera-renderer-hydrate-slots.d.ts.map +1 -0
- package/dist/development/vera-renderer-hydrate-slots.js +325 -0
- package/dist/development/vera-renderer-hydrate-slots.js.map +1 -0
- package/dist/development/vera-renderer-hydration.d.ts +332 -0
- package/dist/development/vera-renderer-hydration.d.ts.map +1 -0
- package/dist/development/vera-renderer-hydration.js +864 -0
- package/dist/development/vera-renderer-hydration.js.map +1 -0
- package/dist/development/vera-renderer-keyed.d.ts +25 -8
- package/dist/development/vera-renderer-keyed.d.ts.map +1 -1
- package/dist/development/vera-renderer-keyed.js +843 -268
- package/dist/development/vera-renderer-keyed.js.map +1 -1
- package/dist/development/vera-renderer-multi-window.d.ts +5 -0
- package/dist/development/vera-renderer-multi-window.d.ts.map +1 -0
- package/dist/development/vera-renderer-multi-window.js +40 -0
- package/dist/development/vera-renderer-multi-window.js.map +1 -0
- package/dist/development/vera-renderer-namespaces.d.ts +64 -0
- package/dist/development/vera-renderer-namespaces.d.ts.map +1 -0
- package/dist/development/vera-renderer-namespaces.js +94 -0
- package/dist/development/vera-renderer-namespaces.js.map +1 -0
- package/dist/development/vera-renderer-native-elements.d.ts +13 -0
- package/dist/development/vera-renderer-native-elements.d.ts.map +1 -0
- package/dist/development/vera-renderer-native-elements.js +231 -0
- package/dist/development/vera-renderer-native-elements.js.map +1 -0
- package/dist/development/vera-renderer-portal.d.ts +29 -0
- package/dist/development/vera-renderer-portal.d.ts.map +1 -0
- package/dist/development/vera-renderer-portal.js +167 -0
- package/dist/development/vera-renderer-portal.js.map +1 -0
- package/dist/development/vera-renderer-profiler.d.ts +48 -96
- package/dist/development/vera-renderer-profiler.d.ts.map +1 -1
- package/dist/development/vera-renderer-profiler.js +2423 -2140
- package/dist/development/vera-renderer-profiler.js.map +1 -1
- package/dist/development/vera-renderer-slots.d.ts +88 -92
- package/dist/development/vera-renderer-slots.d.ts.map +1 -1
- package/dist/development/vera-renderer-slots.js +1834 -1237
- package/dist/development/vera-renderer-slots.js.map +1 -1
- package/dist/development/vera-renderer-spread.d.ts +7 -41
- package/dist/development/vera-renderer-spread.d.ts.map +1 -1
- package/dist/development/vera-renderer-spread.js +539 -477
- package/dist/development/vera-renderer-spread.js.map +1 -1
- package/dist/development/vera-renderer-tag.d.ts +12 -3
- package/dist/development/vera-renderer-tag.d.ts.map +1 -1
- package/dist/development/vera-renderer-tag.js +671 -513
- package/dist/development/vera-renderer-tag.js.map +1 -1
- package/dist/development/vera-renderer-until.d.ts +24 -0
- package/dist/development/vera-renderer-until.d.ts.map +1 -0
- package/dist/development/vera-renderer-until.js +83 -0
- package/dist/development/vera-renderer-until.js.map +1 -0
- package/dist/development/vera-renderer.d.ts +48 -96
- package/dist/development/vera-renderer.d.ts.map +1 -1
- package/dist/development/vera-renderer.js +2400 -2104
- package/dist/development/vera-renderer.js.map +1 -1
- package/dist/vera-renderer-elements.min.js +2 -0
- package/dist/vera-renderer-elements.min.js.map +1 -0
- package/dist/vera-renderer-hydrate-slots.min.js +2 -0
- package/dist/vera-renderer-hydrate-slots.min.js.map +1 -0
- package/dist/vera-renderer-hydration.min.js +3 -0
- package/dist/vera-renderer-hydration.min.js.map +1 -0
- package/dist/vera-renderer-keyed.min.js +1 -1
- package/dist/vera-renderer-keyed.min.js.map +1 -1
- package/dist/vera-renderer-multi-window.min.js +2 -0
- package/dist/vera-renderer-multi-window.min.js.map +1 -0
- package/dist/vera-renderer-namespaces.min.js +2 -0
- package/dist/vera-renderer-namespaces.min.js.map +1 -0
- package/dist/vera-renderer-native-elements.min.js +2 -0
- package/dist/vera-renderer-native-elements.min.js.map +1 -0
- package/dist/vera-renderer-portal.min.js +2 -0
- package/dist/vera-renderer-portal.min.js.map +1 -0
- package/dist/vera-renderer-slots.min.js +1 -1
- package/dist/vera-renderer-slots.min.js.map +1 -1
- package/dist/vera-renderer-spread.min.js +1 -1
- package/dist/vera-renderer-spread.min.js.map +1 -1
- package/dist/vera-renderer-tag.min.js +1 -1
- package/dist/vera-renderer-tag.min.js.map +1 -1
- package/dist/vera-renderer-until.min.js +2 -0
- package/dist/vera-renderer-until.min.js.map +1 -0
- package/dist/vera-renderer.min.js +1 -1
- package/dist/vera-renderer.min.js.map +1 -1
- package/package.json +52 -9
- package/dist/development/vera-renderer-hydrate.d.ts +0 -147
- package/dist/development/vera-renderer-hydrate.d.ts.map +0 -1
- package/dist/development/vera-renderer-hydrate.js +0 -3136
- package/dist/development/vera-renderer-hydrate.js.map +0 -1
- package/dist/vera-renderer-hydrate.min.js +0 -2
- package/dist/vera-renderer-hydrate.min.js.map +0 -1
|
@@ -1,3 +1,324 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* **Where every diagnostic code is explained.** The URL is permanent: a released bundle is immutable, so every version
|
|
3
|
+
* published points here for ever — the domain cannot lapse and `/e/` cannot be reorganized without breaking links in
|
|
4
|
+
* code nobody can edit; the docs site redirects instead. `scripts/sync-diagnostics.mjs` imports this constant, so the
|
|
5
|
+
* pages and the bundles can never disagree about where they are.
|
|
6
|
+
*/
|
|
7
|
+
const DOCS = 'https://verajs.dev/e/';
|
|
8
|
+
/**
|
|
9
|
+
* **One shape for every diagnostic the framework prints** — the short line production keeps, the whole sentence
|
|
10
|
+
* development adds — so a package converting its messages writes a table and a call, never its own format.
|
|
11
|
+
*
|
|
12
|
+
* production `[vera] hydration: element: found <i> — https://verajs.dev/e/hydration-fallback`
|
|
13
|
+
* development `[vera] hydration: element: found <i> — fell back to a client render: … (hydration-fallback)`
|
|
14
|
+
*
|
|
15
|
+
* `subject` is the free information — what the code already has at hand, naming the problem area — the same in both
|
|
16
|
+
* builds. `prose` is development only: the package's table entry (`Prose`), called behind `true ` at the call site so
|
|
17
|
+
* the table goes unreferenced in production and rollup drops it whole. Production prints the code inside the link, so
|
|
18
|
+
* the reader is one click from the explanation, which `scripts/sync-diagnostics.mjs` publishes from the same tables.
|
|
19
|
+
*
|
|
20
|
+
* **Every production message is coded** (Brian, 2026-11-11; this supersedes "convert where smaller", 2026-10-02):
|
|
21
|
+
* consistency over a few bytes, so no package keeps a hand-written production line beside its table.
|
|
22
|
+
*/
|
|
23
|
+
/*
|
|
24
|
+
* The parameter names are deliberately unlike anything a caller holds: terser will not inline a function whose
|
|
25
|
+
* parameter shadows a name at the call site (measured 2026-10-02 — directives passes its own `code`, and a parameter
|
|
26
|
+
* called `code` left `((e,t,n)=>`…`)(0,t,n)` in its bundle, +8 B; renamed, the call folds to the bare template).
|
|
27
|
+
*/
|
|
28
|
+
/**
|
|
29
|
+
* **A misused API, named by its function** — the thrown-error twin of `diagnostic()`: `untrack: expected a function …
|
|
30
|
+
* (untrack-not-function)`, function-first because a stack already names the source and the sweep reads that shape. The
|
|
31
|
+
* prose comes from a package's table, behind `true `, so a development-only guard costs production nothing.
|
|
32
|
+
*/
|
|
33
|
+
const misuse = (forName, withCode, andProse) => true && andProse
|
|
34
|
+
? `${forName}: ${andProse[0]}${andProse[1] ? ` ${andProse[1]}` : ''} (${withCode})`
|
|
35
|
+
: `${forName}: ${DOCS}${withCode}`;
|
|
36
|
+
const diagnostic = (inArea, bySubject, withCode, andProse) =>
|
|
37
|
+
/** `true ` HERE as well as at the call: production folds this to the one-line form, branch and all. */
|
|
38
|
+
true && andProse
|
|
39
|
+
? `[vera] ${inArea}: ${bySubject} — ${andProse[0]}${andProse[1] ? ` ${andProse[1]}` : ''} (${withCode})`
|
|
40
|
+
: `[vera] ${inArea}: ${bySubject} — ${DOCS}${withCode}`;
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* core's `html`/`svg`/`mathml` and the renderer's `tag` — a tagged template called as a function. The FACT is shared;
|
|
44
|
+
* the EXAMPLE is each emitter's: `html` writes markup, `tag` an element name — so the emitter passes it.
|
|
45
|
+
*/
|
|
46
|
+
/** core's props adoption on an `init()` element, and the renderer's on any other element. */
|
|
47
|
+
const getterOnlyProp = (key) => [
|
|
48
|
+
`received a bound property \`.${key}\` (or \`!${key}\`), but its class declares \`${key}\` as a getter with no setter — the value cannot be delivered and the binding is ignored.`,
|
|
49
|
+
'Add a setter, or stop binding it.',
|
|
50
|
+
];
|
|
51
|
+
/** shared-utils' `adoptProperty` (renderer, spread): an element that never drains the record loses it at upgrade. */
|
|
52
|
+
const upgradeClobber = (name) => [
|
|
53
|
+
`the value bound to \`${name}\` was replaced while the element upgraded. A class field is the usual cause: at ES2022 \`${name}?: …\` emits \`${name};\`, which runs during upgrade and overwrites whatever was set beforehand.`,
|
|
54
|
+
`Write it \`declare ${name}?: …\` instead. A component that calls init() adopts bound properties automatically and never sees this; this element did not. Ignore this if the component replaced the value on purpose.`,
|
|
55
|
+
];
|
|
56
|
+
/** shared-utils' `isSelection` (renderer, spread). */
|
|
57
|
+
const selectMultiple = (name) => [
|
|
58
|
+
`\`${name}\` controls only ONE selection here, and a selection the user adds is kept — it is not controlled.`,
|
|
59
|
+
'Bind `?selected=${…}` on each <option> to control every selection.',
|
|
60
|
+
];
|
|
61
|
+
/** shared-utils' `contentClash` (renderer, spread): a content-replacing property beside content of the element's own. */
|
|
62
|
+
const contentClash$1 = (tag, name, alone) => [
|
|
63
|
+
`<${tag}> binds \`.${name}\`, which replaces the element's content, and also has content of its own — markup or a child binding, which the write would strand.`,
|
|
64
|
+
`Bind one or the other: the property alone (\`${alone}\`), or the content alone.`,
|
|
65
|
+
];
|
|
66
|
+
/** The renderer and spread (two bundles); @verajs/ssr refuses the same URLs silently today. */
|
|
67
|
+
const scriptUrl = (name) => [
|
|
68
|
+
`\`${name}\` was given a javascript: URL — refused, and the attribute removed.`,
|
|
69
|
+
'A bound URL is data, and data must never become code.',
|
|
70
|
+
];
|
|
71
|
+
/**
|
|
72
|
+
* The renderer and spread: `kind` is what the value was (dev-values' `attributeValueKind`); `property` is the
|
|
73
|
+
* emitter's own spelling of a property binding — a template's `.name=${value}`, a spread's `'.name': value`.
|
|
74
|
+
*/
|
|
75
|
+
const attributeValue = (name, kind, property) => [
|
|
76
|
+
`the attribute \`${name}\` was given ${kind}. An attribute value is a string and nothing else.`,
|
|
77
|
+
`If the element is meant to RECEIVE this value, bind a property instead — \`${property}\` — which is how a custom element takes anything that is not text. If it is meant to be read as text, convert it where you know what it means: \`date.toISOString()\`, \`list.join(' ')\`. A Date in particular serializes with the SERVER's timezone on one side and the browser's on the other, so it will not survive hydration.`,
|
|
78
|
+
];
|
|
79
|
+
/** The renderer and spread: `type` is the value's `typeof`. */
|
|
80
|
+
const notAListener = (name, type) => [
|
|
81
|
+
`@${name} was given ${type === 'object' ? 'an object with no handleEvent method' : `a ${type}`}, which cannot listen — the event will do nothing.`,
|
|
82
|
+
'Pass a function, or an object with a handleEvent method. A missing handler is `undefined` or `false`, both of which are fine; this is neither.',
|
|
83
|
+
];
|
|
84
|
+
/** The renderer and spread (two bundles; @verajs/ssr refuses the same): binding `__proto__`. */
|
|
85
|
+
const protoBinding = (written) => [
|
|
86
|
+
`binds \`${written}\`, which would replace the element's own prototype and destroy it — no property write does this, and no use of it is legitimate.`,
|
|
87
|
+
'The binding is ignored.',
|
|
88
|
+
];
|
|
89
|
+
/** The renderer and spread: a bound `srcdoc` ATTRIBUTE. `property` is the emitter's spelling of the property binding. */
|
|
90
|
+
const srcdocAttribute = (property) => [
|
|
91
|
+
'binds the `srcdoc` attribute, which renders its value as an HTML document — refused.',
|
|
92
|
+
`If the markup is trusted and sanitized, bind the property: \`${property}\`.`,
|
|
93
|
+
];
|
|
94
|
+
/** The renderer and spread: a bound inline-handler attribute (`onclick`). `event` is the emitter's event spelling(s). */
|
|
95
|
+
const handlerAttribute = (name, event) => [
|
|
96
|
+
`binds the \`${name}\` attribute, which runs its value as code — refused.`,
|
|
97
|
+
`Bind a function as an event instead: ${event}.`,
|
|
98
|
+
];
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* **Delivering a bound property to a custom element that may not receive it yet** — the one home of the
|
|
102
|
+
* rule `@verajs/renderer` (a `.prop` template binding) and `@verajs/renderer/spread` (a `.prop` bag key)
|
|
103
|
+
* both apply. They ship as separate bundles that cannot import each other, so this package, inlined into
|
|
104
|
+
* each, is where the rule lives once; before, each carried a full copy and a fix had to visit both.
|
|
105
|
+
*
|
|
106
|
+
* Returns where the binding stands after this write:
|
|
107
|
+
* - `0` — still adopting: nothing received the value, so it was recorded in the element-carried
|
|
108
|
+
* `_$props$`, which core's `init()` drains over whatever the class's field initializers wrote at
|
|
109
|
+
* upgrade. Call again on the next write.
|
|
110
|
+
* - `1` — received (a setter anywhere on the chain, an initialized component's `_$adopt$`, or an element
|
|
111
|
+
* that is already upgraded): later writes are plain property writes.
|
|
112
|
+
* - `2` — refused: a getter with no setter, where the plain write would throw. Later writes do nothing.
|
|
113
|
+
*
|
|
114
|
+
* `_$props$` and `_$adopt$` are `$`-named because they cross bundle boundaries (renderer, spread, core)
|
|
115
|
+
* and must survive property mangling.
|
|
116
|
+
*
|
|
117
|
+
* **`_$adopt$` is a BRAND, not just a slot:** present means "core has initialized this component", which is what routes
|
|
118
|
+
* a delivery to the live accessor (`1`) instead of the `_$props$` record. Do not move it to a class's PROTOTYPE
|
|
119
|
+
* (2026-10-10): every instance would carry it BEFORE `init`, and a delivery to an upgraded-but-uninitialized element
|
|
120
|
+
* would be adopted into a store that does not exist yet. It is ONE shared function written onto each element at `init`,
|
|
121
|
+
* called with the element as `this` (`adopt.call(element, …)`) — 2026-10-11: the closure it replaced was free in
|
|
122
|
+
* optimized code (measured) but cost Chrome's interpreted first render one allocation per component.
|
|
123
|
+
*/
|
|
124
|
+
/** Development only: getter-only names already reported, per element — a `!name` re-asserts on every render. */
|
|
125
|
+
let refused;
|
|
126
|
+
const adoptProperty = (element, name, value) => {
|
|
127
|
+
/**
|
|
128
|
+
* **`__proto__` is refused HERE, at the receiver** (2026-11-10): `element.__proto__ = v` replaces the element's
|
|
129
|
+
* prototype, and an own `__proto__` key reaches a bag through `JSON.parse`. This is the choke point every delivery
|
|
130
|
+
* passes; the renderer's template binding and spread's bag key refuse it first, with a development warning naming
|
|
131
|
+
* where it was written (their second addresses: renderer.ts `proto-binding`, spread.ts refusal 3).
|
|
132
|
+
*/
|
|
133
|
+
if (name === '__proto__')
|
|
134
|
+
return 2;
|
|
135
|
+
const adopt = element._$adopt$;
|
|
136
|
+
/** The walk comes first: what it finds decides whether writing is even legal. */
|
|
137
|
+
for (let carrier = element; carrier !== null; carrier = Object.getPrototypeOf(carrier)) {
|
|
138
|
+
const desc = Object.getOwnPropertyDescriptor(carrier, name);
|
|
139
|
+
if (desc === undefined)
|
|
140
|
+
continue;
|
|
141
|
+
if (desc.set !== undefined) {
|
|
142
|
+
element[name] = value;
|
|
143
|
+
return 1;
|
|
144
|
+
}
|
|
145
|
+
if (desc.get !== undefined) {
|
|
146
|
+
if (adopt !== undefined)
|
|
147
|
+
adopt.call(element, name, value);
|
|
148
|
+
else if (true ) {
|
|
149
|
+
const names = (refused ??= new WeakMap()).get(element) ?? new Set();
|
|
150
|
+
refused.set(element, names);
|
|
151
|
+
if (!names.has(name)) {
|
|
152
|
+
names.add(name);
|
|
153
|
+
console.warn(diagnostic('renderer', `<${element.localName}>`, 'getter-only-prop', true && getterOnlyProp(name)));
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
return 2;
|
|
157
|
+
}
|
|
158
|
+
break; // a data property: an own field, or an inherited default — nothing receives it
|
|
159
|
+
}
|
|
160
|
+
element[name] = value;
|
|
161
|
+
if (adopt !== undefined) {
|
|
162
|
+
adopt.call(element, name, value);
|
|
163
|
+
return 1;
|
|
164
|
+
}
|
|
165
|
+
const record = (element._$props$ ??= {});
|
|
166
|
+
const first = true && !Object.hasOwn(record, name);
|
|
167
|
+
record[name] = value;
|
|
168
|
+
/** Upgrade is read off the PROTOTYPE — a bag key named `constructor` can shadow `el.constructor`. The realm is the element's. */
|
|
169
|
+
const view = element.ownerDocument.defaultView;
|
|
170
|
+
const upgraded = view === null || Object.getPrototypeOf(element) !== view.HTMLElement.prototype;
|
|
171
|
+
/** Development only: an element that never drains still loses the value at upgrade — told apart by ownership. */
|
|
172
|
+
if (true && view !== null && !upgraded && first) {
|
|
173
|
+
const tag = element.localName;
|
|
174
|
+
view.customElements.whenDefined(tag).then(() => {
|
|
175
|
+
let owned = false;
|
|
176
|
+
for (let carrier = element; carrier !== null; carrier = Object.getPrototypeOf(carrier)) {
|
|
177
|
+
const desc = Object.getOwnPropertyDescriptor(carrier, name);
|
|
178
|
+
if (desc === undefined)
|
|
179
|
+
continue;
|
|
180
|
+
owned = desc.get !== undefined || desc.set !== undefined;
|
|
181
|
+
break;
|
|
182
|
+
}
|
|
183
|
+
if (!owned && element[name] !== record[name])
|
|
184
|
+
console.warn(diagnostic('renderer', `<${tag}>`, 'upgrade-clobber', true && upgradeClobber(name)));
|
|
185
|
+
});
|
|
186
|
+
}
|
|
187
|
+
return upgraded ? 1 : 0;
|
|
188
|
+
};
|
|
189
|
+
|
|
190
|
+
/**
|
|
191
|
+
* A URL whose scheme a browser reads as `javascript:` — navigating to one runs it, so a BOUND value
|
|
192
|
+
* that parses this way is code arriving as data, never a link.
|
|
193
|
+
*
|
|
194
|
+
* Matched the way the URL Standard's parser reads a scheme, because that is the only reading that
|
|
195
|
+
* matters: leading C0 controls and spaces are stripped, ASCII tab, LF and CR are removed anywhere, and
|
|
196
|
+
* the scheme is case-insensitive. A check that only lowercases is bypassed by `" jAvA\tscript:"`,
|
|
197
|
+
* which every engine navigates to. React's blocking pattern is the same rule.
|
|
198
|
+
*
|
|
199
|
+
* `@verajs/ssr` keeps a twin (it cannot import this package), held to this one by
|
|
200
|
+
* `tests/url-sinks.test.mjs`, so a server never emits a link the client refuses.
|
|
201
|
+
*/
|
|
202
|
+
|
|
203
|
+
const SCRIPT_URL = /^[\u0000- ]*j[\t\n\r]*a[\t\n\r]*v[\t\n\r]*a[\t\n\r]*s[\t\n\r]*c[\t\n\r]*r[\t\n\r]*i[\t\n\r]*p[\t\n\r]*t[\t\n\r]*:/i;
|
|
204
|
+
/**
|
|
205
|
+
* **Every bound name whose value is checked for a `javascript:` URL — and how.** One test answers both.
|
|
206
|
+
*
|
|
207
|
+
* Captured, checked from the start: the attributes (and their reflecting properties) whose value a browser
|
|
208
|
+
* NAVIGATES to or loads as a document — links and areas (`href`, SVG's `xlink:href`), forms (`action`,
|
|
209
|
+
* `formaction`), frames (`src`), and `<object data>`. `src` is matched on every element — refusing one on an `<img>`
|
|
210
|
+
* costs nothing, since an image never runs it. Resource-only attributes (`poster`, `srcset`) are fetched, never run,
|
|
211
|
+
* so they are not listed.
|
|
212
|
+
*
|
|
213
|
+
* Not captured, checked ITEM BY ITEM (`SCRIPT_URL_ITEM`): an SVG animation's values — `to`, `from`, `by`, `values`.
|
|
214
|
+
* `<animate attributeName="href" to="javascript:…">` (or `<set>`, or `values`) writes its value onto the link it
|
|
215
|
+
* animates, and clicking the link then RUNS it: measured 2026-09-30 in Chromium, Firefox and WebKit, through `href`
|
|
216
|
+
* and `xlink:href` alike. Refused on EVERY element and whatever `attributeName` says, because `attributeName` can
|
|
217
|
+
* itself be bound or spread, a server spread has no element to ask, and no legitimate value of any attribute by these
|
|
218
|
+
* names starts with `javascript:` (a component's `to`, a router link's, is a URL too). **Only these names are checked
|
|
219
|
+
* item by item**: an unanchored test scans the whole value for `;`, which on a bound `src` holding a data URI costs
|
|
220
|
+
* ~0.45 ms per MB per update in Chromium and Firefox (measured 2026-09-30), where the anchored `SCRIPT_URL` stops at
|
|
221
|
+
* the first character.
|
|
222
|
+
*
|
|
223
|
+
* Case-insensitive, because property spellings (`formAction`) and attribute spellings meet here. `@verajs/ssr` keeps
|
|
224
|
+
* a twin, held to this one by `tests/url-sinks.test.mjs`.
|
|
225
|
+
*/
|
|
226
|
+
const URL_SINK = /^(?:(href|src|action|formaction|xlink:href|data)|to|from|by|values)$/i;
|
|
227
|
+
/**
|
|
228
|
+
* `SCRIPT_URL` at the start of the value OR of any `;`-separated item of it — an animation's `values` list
|
|
229
|
+
* (`"#a;javascript:…"`) applies every item in turn. Only for an animation's values (`URL_SINK`'s uncaptured names): a `;` inside an `href` is a path
|
|
230
|
+
* character, and `/p;javascript:x` is a working link, never a script. Written out rather than derived from
|
|
231
|
+
* `SCRIPT_URL`: the repeated text costs less gzipped than the code that would build it.
|
|
232
|
+
*/
|
|
233
|
+
|
|
234
|
+
const SCRIPT_URL_ITEM = /(?:^|;)[\u0000- ]*j[\t\n\r]*a[\t\n\r]*v[\t\n\r]*a[\t\n\r]*s[\t\n\r]*c[\t\n\r]*r[\t\n\r]*i[\t\n\r]*p[\t\n\r]*t[\t\n\r]*:/i;
|
|
235
|
+
/**
|
|
236
|
+
* **An inline event-handler attribute** — `on` and a letter, any case (`onclick`, `onLoad`, `onbeforeinput`): its
|
|
237
|
+
* value is run as CODE, so a BOUND one is code arriving as data, refused by the template scanner, `spread` and the
|
|
238
|
+
* server alike (a static `onclick="save()"` is the author's own and untouched). Broad on purpose — it also refuses a
|
|
239
|
+
* bound `once=`/`online=` attribute; the precise rule would need the platform's list of handler names. `@verajs/ssr`
|
|
240
|
+
* keeps a twin, held to this one by `tests/inline-handlers.test.mjs`.
|
|
241
|
+
*/
|
|
242
|
+
const INLINE_HANDLER = /^on./i;
|
|
243
|
+
/**
|
|
244
|
+
* **The properties that replace an element's whole content** — a binding to one owns the element's children, so it
|
|
245
|
+
* cannot share the element with content of its own (markup, or a child binding the write would strand: a later commit
|
|
246
|
+
* into it then throws on a missing parent). Development refuses the pair in the template scanner and in `spread` alike.
|
|
247
|
+
*/
|
|
248
|
+
const CONTENT_PROPERTY = /^(?:textContent|innerHTML|innerText|outerHTML|outerText)$/;
|
|
249
|
+
/**
|
|
250
|
+
* Whether an element has content of its own that a content-replacing write would strand or lose: a child that is not
|
|
251
|
+
* whitespace-only text (formatting whitespace loses nothing), or — `$content`, set in development by the renderer — a
|
|
252
|
+
* child binding that owns the element whole and leaves no node behind until it commits. The element-specific `.text`
|
|
253
|
+
* setters (`<a>`, `<option>`, `<title>`, `<script>`) are deliberately not in the list: a custom element's own `text`
|
|
254
|
+
* prop is common, and would be refused for nothing.
|
|
255
|
+
*/
|
|
256
|
+
const ownsContent = (element) => {
|
|
257
|
+
if (element.$content === true)
|
|
258
|
+
return true;
|
|
259
|
+
for (let node = element.firstChild; node !== null; node = node.nextSibling)
|
|
260
|
+
/**
|
|
261
|
+
* An EMPTY text node is a child binding's anchor, not formatting: formatting whitespace is never empty. And
|
|
262
|
+
* formatting is HTML's whitespace, `[ \t\n\f\r]` — not JS's `trim()`, which would let an ` ` be overwritten.
|
|
263
|
+
*/
|
|
264
|
+
if (node.nodeType !== 3 || node.data === '' || /[^ \t\n\f\r]/.test(node.data))
|
|
265
|
+
return true;
|
|
266
|
+
return false;
|
|
267
|
+
};
|
|
268
|
+
/** `side` is the module the user wired — `renderer` for a template, `spread` for a spread. */
|
|
269
|
+
const contentClash = (side, tag, name) => {
|
|
270
|
+
throw new Error(misuse(side, 'content-clash', true && contentClash$1(tag, name, `<${tag} \${spread({ '.${name}': … })}></${tag}>` )));
|
|
271
|
+
};
|
|
272
|
+
|
|
273
|
+
/** `fn(a, b, c)`, tracked as the caller is — the stand-in for core's `untracked` when no core was wired. */
|
|
274
|
+
const call = (fn, a, b, c) => fn(a, b, c);
|
|
275
|
+
/**
|
|
276
|
+
* **Runs a bound handler, and its callers run it UNTRACKED**: the renderer's template `@event` and spread's event key,
|
|
277
|
+
* each through `untracked(dispatch, holder, event)` (2026-10-09). An effect that fires an event synchronously
|
|
278
|
+
* (`el.click()`, `focus()`, `dispatchEvent`) runs the handler INSIDE itself, and the handler's reads subscribed the
|
|
279
|
+
* effect: a handler doing `state.n++` made the effect re-run on every click, a self-feeding loop held to one round per
|
|
280
|
+
* frame, forever (measured). A handler's reads are event-time decisions, never a hook's inputs. The directives engine's
|
|
281
|
+
* delegated `listen` makes the same choice its own way. A function is called with the element as `this`; an object
|
|
282
|
+
* through its `handleEvent`. One function for both callers (Brian's size-audit ruling, 2026-11-13): it was two
|
|
283
|
+
* identical copies, so a fix had two addresses; each bundle still inlines its own.
|
|
284
|
+
*/
|
|
285
|
+
const dispatch = (holder, event) => {
|
|
286
|
+
const handler = holder._handler;
|
|
287
|
+
if (typeof handler === 'function')
|
|
288
|
+
handler.call(holder._element, event);
|
|
289
|
+
else if (typeof handler?.handleEvent === 'function')
|
|
290
|
+
handler.handleEvent(event);
|
|
291
|
+
};
|
|
292
|
+
/**
|
|
293
|
+
* **Whether a property binding is a `<select>`'s SELECTION** — `value` or `selectedIndex` — which the renderer and
|
|
294
|
+
* `spread` both treat as live: re-asserted every render and compared against the live value (as `!value` is), because
|
|
295
|
+
* a select's options can be replaced under an unchanged value, which drops the selection. One rule, asked once per
|
|
296
|
+
* binding by both, so a template and a spread key cannot disagree about it.
|
|
297
|
+
*
|
|
298
|
+
* In development it names the one shape it cannot serve: on a `<select multiple>` both properties read and set a
|
|
299
|
+
* SINGLE selection, so a selection the user adds is kept rather than controlled. Always writing there was measured
|
|
300
|
+
* 2–3% slower on every table with a select per row, to serve an API that does not fit — hence a warning, not a cost.
|
|
301
|
+
*/
|
|
302
|
+
const isSelection = (element, name) => {
|
|
303
|
+
if ((name !== 'value' && name !== 'selectedIndex') || element.localName !== 'select')
|
|
304
|
+
return false;
|
|
305
|
+
return true;
|
|
306
|
+
};
|
|
307
|
+
/**
|
|
308
|
+
* Development: the one shape a selection binding cannot serve, named by the module the user wired (`side`). Called only
|
|
309
|
+
* behind `true ` at each call site, so production keeps `isSelection` exactly as small as it was (a `side` argument on
|
|
310
|
+
* it measured +1 B, a default +9 B on vera-renderer.min.js — 2026-10-09).
|
|
311
|
+
*/
|
|
312
|
+
const saySelectMultiple = (element, name, side) => {
|
|
313
|
+
if (element.hasAttribute('multiple'))
|
|
314
|
+
console.warn(diagnostic(side, '<select multiple>', 'select-multiple', true && selectMultiple(String(name))));
|
|
315
|
+
};
|
|
316
|
+
/**
|
|
317
|
+
* `target[key]`, as a function — how a component's GETTER is read through `untracked`. Not `Reflect.get`: `untracked`
|
|
318
|
+
* passes three arguments, and `Reflect.get`'s third is the RECEIVER — `undefined` there runs the getter with no `this`.
|
|
319
|
+
*/
|
|
320
|
+
const read = (target, key) => target[key];
|
|
321
|
+
|
|
1
322
|
/**
|
|
2
323
|
* `true ` only: the one home for *"is this value something an attribute can carry?"*
|
|
3
324
|
*
|
|
@@ -33,7 +354,7 @@ let reported;
|
|
|
33
354
|
* Returns the complaint, or `null` when the value is fine. Never throws — the shapes that break a
|
|
34
355
|
* naive guard are exactly the ones worth reporting, so they reach the `object` arm and are named.
|
|
35
356
|
*/
|
|
36
|
-
const
|
|
357
|
+
const attributeValueKind = (tag, name, value) => {
|
|
37
358
|
const type = typeof value;
|
|
38
359
|
if (type === 'string' || type === 'number' || type === 'boolean' || type === 'bigint')
|
|
39
360
|
return null;
|
|
@@ -55,7 +376,7 @@ const attributeValueComplaint = (tag, name, value) => {
|
|
|
55
376
|
* `<my-chart formatter={fn}>` is a coherent intention that this sink simply cannot express. The
|
|
56
377
|
* message names the binding that can, rather than blaming the author.
|
|
57
378
|
*/
|
|
58
|
-
const
|
|
379
|
+
const kind = type === 'function'
|
|
59
380
|
? `a function, which becomes its own SOURCE TEXT`
|
|
60
381
|
: type === 'symbol'
|
|
61
382
|
? `a symbol, which every DOM conversion refuses`
|
|
@@ -64,39 +385,44 @@ const attributeValueComplaint = (tag, name, value) => {
|
|
|
64
385
|
: brand(value) === '[object Date]'
|
|
65
386
|
? `a Date, whose text carries the TIMEZONE of whichever side rendered it`
|
|
66
387
|
: `an ${type}, which cannot survive as text`;
|
|
67
|
-
/**
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
`
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
`
|
|
388
|
+
/** The KIND only: the sentence is the shared `attribute-value` entry, printed by each call site with its area. */
|
|
389
|
+
return kind;
|
|
390
|
+
};
|
|
391
|
+
|
|
392
|
+
const PROSE = {
|
|
393
|
+
'spread-unsafe-name': (key) => [
|
|
394
|
+
`refusing ${key} — an attribute name cannot contain whitespace, a quote, \`<\`, \`>\`, \`/\`, \`=\` or a control character, and one that cannot be written into markup would not survive server rendering.`,
|
|
395
|
+
'Spread names arrive at runtime; check where this key came from.',
|
|
396
|
+
],
|
|
397
|
+
'spread-inner-html': (key) => [
|
|
398
|
+
`refusing ${key} — spread names arrive at runtime, which is exactly the property that makes an HTML sink unreviewable.`,
|
|
399
|
+
'Write it in the template — html`<div .innerHTML=${trusted}>` — sanitized first (renderer README, security note).',
|
|
400
|
+
],
|
|
401
|
+
'spread-not-object': (received) => [
|
|
402
|
+
`ignoring a props bag that is not a plain object — received ${received}. A string is iterated by character index, so \`spread('text')\` would set attributes named 0, 1, 2 and 3; anything else applies nothing at all.`,
|
|
403
|
+
'This is usually an import or a property that resolved to something unexpected.',
|
|
404
|
+
],
|
|
82
405
|
};
|
|
83
406
|
|
|
84
407
|
/**
|
|
85
|
-
* `<div ${spread(props)}>` — bindings whose
|
|
408
|
+
* `<div ${spread(props)}>` — bindings whose NAMES are not known when the template is parsed.
|
|
86
409
|
*
|
|
87
|
-
*
|
|
88
|
-
*
|
|
89
|
-
*
|
|
410
|
+
* Ships separately: the renderer holds one property read (a value at element position carrying
|
|
411
|
+
* `_$apply$` applies itself), so an app that never spreads pays only that. This entry imports nothing
|
|
412
|
+
* from the renderer and reaches it only through that protocol, so it works beside any renderer entry.
|
|
90
413
|
*
|
|
91
|
-
* **
|
|
92
|
-
*
|
|
93
|
-
*
|
|
94
|
-
*
|
|
414
|
+
* **One key, one rule, decided once.** A key's kind and name follow the renderer's template sigils
|
|
415
|
+
* exactly (`.prop`, `?bool`, `@event`, `&ref`, `!live`, `onClick`), and its verdict — including every
|
|
416
|
+
* refusal — is decided when its binding is first created, never again per render. The rules are
|
|
417
|
+
* repeated rather than imported from the renderer (the bundles cannot share state);
|
|
418
|
+
* `tests/spread-written-parity.test.mjs` drives both spellings against each other.
|
|
95
419
|
*
|
|
96
|
-
*
|
|
97
|
-
*
|
|
98
|
-
* the
|
|
99
|
-
*
|
|
420
|
+
* **Security: spread is where the template security model would break**, because its names arrive at
|
|
421
|
+
* runtime, often from data, and are neither greppable nor reviewable. So it refuses, on the client and
|
|
422
|
+
* in the server half (`_$attrs$`) alike: `.innerHTML`/`.outerHTML` (and `!`), `.__proto__`, the `srcdoc`
|
|
423
|
+
* attribute, inline-handler attributes (`onclick` in any casing — `on` + Capital is the event spelling
|
|
424
|
+
* and still works), names that cannot survive markup, and — as the renderer does — a `javascript:` URL
|
|
425
|
+
* where a browser navigates.
|
|
100
426
|
*/
|
|
101
427
|
const ATTR = 0;
|
|
102
428
|
const PROPERTY = 1;
|
|
@@ -105,542 +431,278 @@ const BOOLEAN = 2;
|
|
|
105
431
|
const LIVE = 3;
|
|
106
432
|
const EVENT = 4;
|
|
107
433
|
const REF = 5;
|
|
108
|
-
|
|
109
|
-
const REFUSED = -1;
|
|
434
|
+
const REFUSED = 6;
|
|
110
435
|
/**
|
|
111
|
-
* A
|
|
112
|
-
*
|
|
113
|
-
*
|
|
114
|
-
* `/` and NUL — but a name carrying a quote or a `<` cannot survive **markup**, so `@verajs/ssr`
|
|
115
|
-
* has to refuse it, and a key that works here and vanishes server-side is worse than one that works
|
|
116
|
-
* nowhere. The rule is therefore the HTML attribute-name restriction (control characters,
|
|
117
|
-
* whitespace, `"`, `'`, `>`, `/`, `=`) plus `<` and a backtick, applied identically on both sides.
|
|
118
|
-
*
|
|
119
|
-
* Skipped rather than thrown. `setAttribute` throws `InvalidCharacterError` on some of these, which
|
|
120
|
-
* took down the whole render — for one bad key in a props bag, on a binding whose entire purpose is
|
|
121
|
-
* names that are not known until runtime.
|
|
122
|
-
*
|
|
123
|
-
* The control-character range is the point of the rule, not a mistake in it: a name carrying one
|
|
124
|
-
* is exactly what must never reach markup.
|
|
436
|
+
* A name that cannot be written into a tag: the HTML attribute-name restriction (control characters,
|
|
437
|
+
* whitespace, `"`, `'`, `>`, `/`, `=`) plus `<` and a backtick — refused identically on both sides, so a
|
|
438
|
+
* key cannot work here and vanish server-side. Skipped, never thrown: one bad key must not cost a render.
|
|
125
439
|
*/
|
|
126
440
|
|
|
127
441
|
const UNSAFE_NAME = /^$|[\s"'>/=<`]|[\u0000-\u001f\u007f]/;
|
|
442
|
+
/** Development only: why a key was refused, by refusal code. */
|
|
128
443
|
/**
|
|
129
|
-
*
|
|
130
|
-
*
|
|
131
|
-
* The renderer's posture on `.innerHTML` (README, "security") rests on three properties of the
|
|
132
|
-
* template spelling: greppable, obviously yours, reviewable as the decision it is. A spread key
|
|
133
|
-
* arrives at RUNTIME inside a props object — often built from data — and has none of the three:
|
|
134
|
-
* `spread(fromJson)` carrying `.innerHTML` or an inline `onclick` attribute is markup or code
|
|
135
|
-
* injection through a door no grep can see. So spread refuses the sinks and points at the template
|
|
136
|
-
* spelling, which remains fully available to an author who means it.
|
|
137
|
-
*
|
|
138
|
-
* The list, deliberately minimal and named: `innerHTML`/`outerHTML` as property or live-property
|
|
139
|
-
* keys; `srcdoc` as an attribute (an iframe's inline document); and any attribute whose name the
|
|
140
|
-
* browser would treat as an inline handler (`on…` in any casing) — EXCEPT the documented event
|
|
141
|
-
* spelling `on` + Capital, which the constructor converts to a real listener and which therefore
|
|
142
|
-
* never becomes an attribute. The exemption mirrors the constructor's test byte for byte, because
|
|
143
|
-
* `ONCLICK` must not slip through as "looks like the event spelling": the constructor only
|
|
144
|
-
* converts a lowercase `on`, so only that exact shape is exempt.
|
|
145
|
-
*
|
|
146
|
-
* Returns the hint for the diagnostic, or null for a permitted key.
|
|
444
|
+
* A key's kind and name, and — for a refused key — why (`[REFUSED, code]`). The twin of the renderer's
|
|
445
|
+
* template construction; a refused key's verdict never changes, so it is decided once per binding.
|
|
147
446
|
*/
|
|
148
|
-
const
|
|
447
|
+
const resolve = (key) => {
|
|
149
448
|
const first = key[0];
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
* `element.__proto__ = value` is not a property write — it hits Object.prototype's
|
|
156
|
-
* `__proto__` ACCESSOR and replaces the element's prototype, stripping every DOM method it
|
|
157
|
-
* has. The element is bricked, and the crash lands LATER, in whatever binding next calls
|
|
158
|
-
* `removeAttribute` on it — a data-driven render-kill with a stack that names the renderer
|
|
159
|
-
* and not the data. Found by the run-14 payload probe; there is no legitimate use, so unlike
|
|
160
|
-
* `.innerHTML` there is no template spelling to point at.
|
|
161
|
-
*/
|
|
162
|
-
/** The deliberate twin of the same refusal in `AttrPart`'s constructor (`./renderer.ts`), for
|
|
163
|
-
* the template spellings `.name` / `!name`. Independent bundles, neither imports the other, so
|
|
164
|
-
* the rule is copied — and a fix visits both. `tests/dangerous-binding-matrix.test.mjs` holds
|
|
165
|
-
* the two spellings to the same answer. */
|
|
166
|
-
if (name === '__proto__')
|
|
167
|
-
return "assigning __proto__ replaces the element's own prototype and destroys it — no property write does this, and no use of it is legitimate";
|
|
168
|
-
return null;
|
|
449
|
+
let kind = first === '.' ? PROPERTY : first === '?' ? BOOLEAN : first === '@' ? EVENT : first === '&' ? REF : first === '!' ? LIVE : ATTR;
|
|
450
|
+
let name = kind === ATTR ? key : key.slice(1);
|
|
451
|
+
if (kind === ATTR && /^on[A-Z]/.test(key)) {
|
|
452
|
+
kind = EVENT;
|
|
453
|
+
name = key.slice(2).toLowerCase();
|
|
169
454
|
}
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
455
|
+
const property = kind === PROPERTY || kind === LIVE;
|
|
456
|
+
const refusal = UNSAFE_NAME.test(name)
|
|
457
|
+
? 1
|
|
458
|
+
: property && (name === 'innerHTML' || name === 'outerHTML')
|
|
459
|
+
? 2
|
|
460
|
+
: property && name === '__proto__'
|
|
461
|
+
? 3
|
|
462
|
+
: kind === ATTR && name.toLowerCase() === 'srcdoc'
|
|
463
|
+
? 4
|
|
464
|
+
: kind === ATTR && INLINE_HANDLER.test(name)
|
|
465
|
+
? 5
|
|
466
|
+
: 0;
|
|
467
|
+
return refusal ? [REFUSED, refusal] : [kind, name];
|
|
181
468
|
};
|
|
182
|
-
/** Module-local: one identity comparison, not a global symbol-registry lookup per binding. */
|
|
183
|
-
const UNSET = Symbol();
|
|
184
469
|
/**
|
|
185
|
-
*
|
|
186
|
-
*
|
|
187
|
-
*
|
|
188
|
-
*
|
|
189
|
-
*
|
|
190
|
-
*
|
|
191
|
-
* clobber detector rides along, because a bag key and a written binding are the same mistake with
|
|
192
|
-
* the same author watching.
|
|
193
|
-
*
|
|
194
|
-
* Returns the binding's NEXT kind, exactly as the twin does: `PROPERTY` to latch onto the plain
|
|
195
|
-
* write, `REFUSED` to go inert (a get-only surface), `0` to keep adopting.
|
|
470
|
+
* How a key names a URL a browser navigates to — the renderer's rule, by the same numbers: 0 not one; 1 a custom
|
|
471
|
+
* element's property — often an object (`.data=${rows}`), so only a string is checked and nothing is converted; 2
|
|
472
|
+
* converted ONCE, and that string checked and written (so a `toString` that answers differently each time cannot pass
|
|
473
|
+
* the check as one URL and be written as another); 3 an animation's value (`to`, `values`…), converted once and
|
|
474
|
+
* checked item by item. A refused key needs no case: its name is a refusal code, which no URL
|
|
475
|
+
* attribute name matches.
|
|
196
476
|
*/
|
|
197
|
-
const
|
|
198
|
-
const
|
|
199
|
-
|
|
200
|
-
* component's own error), a getter with no setter refuses instead of throwing a raw TypeError
|
|
201
|
-
* out of the render, and the dev warning defers to `_$adopt$`'s own refusal where it exists. */
|
|
202
|
-
let carrier = el;
|
|
203
|
-
while (carrier !== null) {
|
|
204
|
-
const desc = Object.getOwnPropertyDescriptor(carrier, name);
|
|
205
|
-
if (desc !== undefined) {
|
|
206
|
-
if (desc.set !== undefined) {
|
|
207
|
-
el[name] = value;
|
|
208
|
-
return PROPERTY;
|
|
209
|
-
}
|
|
210
|
-
if (desc.get !== undefined) {
|
|
211
|
-
if (el._$adopt$ !== undefined)
|
|
212
|
-
el._$adopt$(name, value);
|
|
213
|
-
else if (true )
|
|
214
|
-
console.warn(`[vera] renderer: <${element.localName}> declares \`${name}\` as a getter with no ` +
|
|
215
|
-
`setter — the value bound by \`.${name}\` cannot be delivered and the binding is ` +
|
|
216
|
-
`ignored. Add a setter, or stop binding it.`);
|
|
217
|
-
return REFUSED;
|
|
218
|
-
}
|
|
219
|
-
break; // a data property — an own field, or an inherited default: nothing receives it
|
|
220
|
-
}
|
|
221
|
-
carrier = Object.getPrototypeOf(carrier);
|
|
222
|
-
}
|
|
223
|
-
el[name] = value;
|
|
224
|
-
/** An initialized component receives live through `_$adopt$` — a record after the drain would
|
|
225
|
-
* never be read again. The door a spread bag's conditional key arrives through, reactive. */
|
|
226
|
-
if (el._$adopt$ !== undefined) {
|
|
227
|
-
el._$adopt$(name, value);
|
|
228
|
-
return PROPERTY;
|
|
229
|
-
}
|
|
230
|
-
const record = (el._$props$ ??= {});
|
|
231
|
-
const firstRecording = !Object.hasOwn(record, name);
|
|
232
|
-
record[name] = value;
|
|
233
|
-
/** Prototype, never `el.constructor` — a bag key named `constructor` shadows the real one with
|
|
234
|
-
* an own property, and no property write can move a prototype (`__proto__` is refused above). */
|
|
235
|
-
const win = element.ownerDocument.defaultView;
|
|
236
|
-
const upgraded = win === null || Object.getPrototypeOf(el) !== win.HTMLElement.prototype;
|
|
237
|
-
if (true && win !== null && !upgraded && firstRecording) {
|
|
238
|
-
const tag = element.localName;
|
|
239
|
-
win.customElements.whenDefined(tag).then(() => {
|
|
240
|
-
/** Ownership is asked of the whole CHAIN — see the twin: a drain accessor, a handed-to
|
|
241
|
-
* prototype pair, or a refused get-only surface all mean nothing is left to report. */
|
|
242
|
-
let owner = el;
|
|
243
|
-
let owned = false;
|
|
244
|
-
while (owner !== null) {
|
|
245
|
-
const desc = Object.getOwnPropertyDescriptor(owner, name);
|
|
246
|
-
if (desc !== undefined) {
|
|
247
|
-
owned = desc.get !== undefined || desc.set !== undefined;
|
|
248
|
-
break;
|
|
249
|
-
}
|
|
250
|
-
owner = Object.getPrototypeOf(owner);
|
|
251
|
-
}
|
|
252
|
-
if (!owned && el[name] !== record[name])
|
|
253
|
-
console.warn(`[vera] renderer: the value bound by \`.${name}\` on <${tag}> was replaced while the ` +
|
|
254
|
-
`element upgraded. A class field is the usual cause: at ES2022 \`${name}?: …\` emits ` +
|
|
255
|
-
`\`${name};\`, which runs during upgrade and overwrites whatever was set beforehand — ` +
|
|
256
|
-
`write it \`declare ${name}?: …\` instead, which emits nothing. A component that ` +
|
|
257
|
-
`calls init() adopts bound properties automatically and never sees this; this ` +
|
|
258
|
-
`element did not. Ignore this if the component replaced the value on purpose.`);
|
|
259
|
-
});
|
|
260
|
-
}
|
|
261
|
-
return upgraded ? PROPERTY : 0;
|
|
477
|
+
const urlRule = (kind, name, custom) => {
|
|
478
|
+
const sink = URL_SINK.exec(name);
|
|
479
|
+
return kind === BOOLEAN || kind === EVENT || kind === REF || sink === null ? 0 : kind !== ATTR && custom ? 1 : sink[1] ? 2 : 3;
|
|
262
480
|
};
|
|
263
|
-
/**
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
481
|
+
/** What `checked` answers for a `javascript:` URL where the rule looks. */
|
|
482
|
+
const REFUSE = {};
|
|
483
|
+
/** `value` as it is checked AND written under `rule` — converted once, or left as it is — or `REFUSE`. */
|
|
484
|
+
const checked = (rule, value) => {
|
|
485
|
+
if (rule > 1 && value != null && typeof value !== 'string')
|
|
486
|
+
value = `${value}`;
|
|
487
|
+
return rule !== 0 && typeof value === 'string' && (rule === 3 ? SCRIPT_URL_ITEM : SCRIPT_URL).test(value) ? REFUSE : value;
|
|
488
|
+
};
|
|
489
|
+
const UNSET = {};
|
|
490
|
+
/** One key's binding on one element. It is also the `@event` listener — a stable object, so the platform dedupes re-adds. */
|
|
267
491
|
class Binding {
|
|
268
492
|
_kind;
|
|
269
493
|
_name;
|
|
270
494
|
_element;
|
|
271
|
-
/** What the element held before this
|
|
272
|
-
_initial;
|
|
495
|
+
/** What the element held before the bag first wrote this key — restored when the key leaves the bag. */
|
|
496
|
+
_initial = null;
|
|
273
497
|
_committed = UNSET;
|
|
274
498
|
_handler = null;
|
|
275
|
-
/**
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
? LIVE
|
|
291
|
-
: ATTR;
|
|
292
|
-
let name = kind ? key.slice(1) : key;
|
|
293
|
-
/** `on` + a capital: `onClick` ≡ `@click`. All-lowercase `onclick` never reaches here — it is
|
|
294
|
-
* an inline-handler attribute, which `refusedSink` rejects before a binding exists. */
|
|
295
|
-
if (kind === ATTR && first === 'o' && key.charCodeAt(1) === 110 && key.charCodeAt(2) > 64 && key.charCodeAt(2) < 91) {
|
|
296
|
-
kind = EVENT;
|
|
297
|
-
name = key.slice(2).toLowerCase();
|
|
298
|
-
}
|
|
499
|
+
/** For `.prop`: where adoption stands (`adoptProperty`: 0 still adopting, 1 received, 2 refused). */
|
|
500
|
+
_state = 1;
|
|
501
|
+
/** How this key is checked as a URL (`urlRule`) — decided once, with the element in hand. */
|
|
502
|
+
_url;
|
|
503
|
+
/**
|
|
504
|
+
* On a custom element, a property read is the component's GETTER, so it goes through the `untracked` this binding was
|
|
505
|
+
* created with; `null` on a built-in element, whose getters read no state. Decided once.
|
|
506
|
+
*/
|
|
507
|
+
_read;
|
|
508
|
+
constructor(element, key, untracked) {
|
|
509
|
+
const [resolved, name] = resolve(key);
|
|
510
|
+
/** A `<select>`'s selection is live, as in a template — the same rule, asked of the same function. */
|
|
511
|
+
const kind = (resolved === PROPERTY || resolved === LIVE) && isSelection(element, name) ? LIVE : resolved;
|
|
512
|
+
if (true && (resolved === PROPERTY || resolved === LIVE) && isSelection(element, name))
|
|
513
|
+
saySelectMultiple(element, name, 'spread');
|
|
299
514
|
this._kind = kind;
|
|
300
515
|
this._name = name;
|
|
301
516
|
this._element = element;
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
517
|
+
const custom = element.localName.includes('-');
|
|
518
|
+
/** Core's `untracked` for a custom element's getter reads, and for an event key's handler (`dispatch`). */
|
|
519
|
+
this._read = custom || kind === EVENT ? untracked : null;
|
|
520
|
+
this._url = urlRule(kind, name, custom);
|
|
521
|
+
/** A content-replacing property beside content of the element's own: development refuses it, as a template does. */
|
|
522
|
+
if (true && (kind === PROPERTY || kind === LIVE) && CONTENT_PROPERTY.test(name) && ownsContent(element))
|
|
523
|
+
contentClash('spread', element.localName, name);
|
|
524
|
+
if (kind === REFUSED) {
|
|
525
|
+
if (true ) {
|
|
526
|
+
/** Each refusal written out, so the manifest (`diagnostics-tables`) reads every raise from the source. */
|
|
527
|
+
const at = `<${element.localName}>`;
|
|
528
|
+
const written = JSON.stringify(key);
|
|
529
|
+
const why = name;
|
|
530
|
+
if (why === 1)
|
|
531
|
+
console.warn(diagnostic('spread', at, 'spread-unsafe-name', true && PROSE['spread-unsafe-name'](written)));
|
|
532
|
+
else if (why === 2)
|
|
533
|
+
console.warn(diagnostic('spread', at, 'spread-inner-html', true && PROSE['spread-inner-html'](written)));
|
|
534
|
+
else if (why === 3)
|
|
535
|
+
console.warn(diagnostic('spread', at, 'proto-binding', true && protoBinding(written)));
|
|
536
|
+
else if (why === 4)
|
|
537
|
+
console.warn(diagnostic('spread', at, 'srcdoc-attribute', true && srcdocAttribute("'.srcdoc': trusted")));
|
|
538
|
+
else
|
|
539
|
+
console.warn(diagnostic('spread', at, 'handler-attribute', true && handlerAttribute(key, `\`'@${key.slice(2).toLowerCase()}': fn\` (or \`on${key.slice(2, 3).toUpperCase()}${key.slice(3)}\`)`)));
|
|
540
|
+
}
|
|
541
|
+
return;
|
|
542
|
+
}
|
|
543
|
+
if (kind === ATTR)
|
|
544
|
+
this._initial = element.getAttribute(name);
|
|
545
|
+
else if (kind === BOOLEAN)
|
|
546
|
+
this._initial = element.hasAttribute(name);
|
|
547
|
+
/** On a custom element this is the component's getter, run on the parent's behalf: read through `untracked`. */
|
|
548
|
+
else if (kind === PROPERTY || kind === LIVE)
|
|
549
|
+
this._initial = custom ? untracked(read, element, name) : element[name];
|
|
550
|
+
if (kind === PROPERTY && custom)
|
|
551
|
+
this._state = 0;
|
|
311
552
|
}
|
|
312
|
-
/**
|
|
313
|
-
* **Two shapes, because `addEventListener` takes two** — the same rule `AttrPart.handleEvent`
|
|
314
|
-
* applies, and it did not travel here when that one was fixed. A function is called with the
|
|
315
|
-
* element as `this`; an object with a `handleEvent` method is invoked through it — the platform's
|
|
316
|
-
* own `EventListenerObject` protocol, which every engine accepts. This called `.call()`
|
|
317
|
-
* unconditionally, so `spread({ onClick: { handleEvent } })` bound without complaint, never
|
|
318
|
-
* fired, and raised `this._handler.call is not a function` on **every** dispatch — while the
|
|
319
|
-
* identical value through a written `@click` worked.
|
|
320
|
-
*
|
|
321
|
-
* Anything else is inert rather than throwing, exactly as there: development names it at the
|
|
322
|
-
* binding (see the event branch in `write`), where the mistake still is.
|
|
323
|
-
*/
|
|
553
|
+
/** Runs the handler UNTRACKED (shared-utils' `dispatch`): `_read` holds core's `untracked` for an event key too. */
|
|
324
554
|
handleEvent(event) {
|
|
325
|
-
|
|
326
|
-
if (typeof handler === 'function')
|
|
327
|
-
handler.call(this._element, event);
|
|
328
|
-
else if (typeof handler?.handleEvent === 'function')
|
|
329
|
-
handler.handleEvent(event);
|
|
555
|
+
(this._read ?? call)(dispatch, this, event);
|
|
330
556
|
}
|
|
331
557
|
}
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
const owned = new WeakMap();
|
|
341
|
-
const write = (binding, value) => {
|
|
342
|
-
/** One comparison per key per render — the same dirty check a written binding gets. */
|
|
558
|
+
const write = (binding, given, adopting) => {
|
|
559
|
+
const kind = binding._kind;
|
|
560
|
+
const value = checked(binding._url, given);
|
|
561
|
+
const name = binding._name;
|
|
562
|
+
/** One variable, typed for both uses: a cast alias survives minification as a second variable. */
|
|
563
|
+
const element = binding._element;
|
|
564
|
+
if (kind === REFUSED)
|
|
565
|
+
return;
|
|
343
566
|
/**
|
|
344
|
-
*
|
|
345
|
-
*
|
|
346
|
-
*
|
|
567
|
+
* **Adopting server markup** (hydration hands this in): a built-in control's state — `value`, `checked`, `selected`,
|
|
568
|
+
* `open`, by `.name` or `!name` — is RECORDED, not written: the server's default, and anything the user changed before
|
|
569
|
+
* the script arrived, stand, exactly as for a written binding (hydration's `FORM_STATE`, the same list — keep them
|
|
570
|
+
* equal). Any other name is written, and a component's property is always delivered.
|
|
347
571
|
*/
|
|
348
|
-
if (binding.
|
|
572
|
+
if (adopting && binding._read === null && (kind === LIVE || kind === PROPERTY) && /^(?:value|checked|selected|open)$/.test(name)) {
|
|
349
573
|
binding._committed = value;
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
574
|
+
return;
|
|
575
|
+
}
|
|
576
|
+
if (value === REFUSE) {
|
|
577
|
+
if (true && given !== binding._committed)
|
|
578
|
+
console.warn(diagnostic('spread', `<${element.localName}>`, 'script-url', true && scriptUrl(name)));
|
|
579
|
+
binding._committed = given;
|
|
580
|
+
element.removeAttribute(name);
|
|
581
|
+
return;
|
|
582
|
+
}
|
|
583
|
+
if (kind === LIVE) {
|
|
584
|
+
binding._committed = value;
|
|
585
|
+
/**
|
|
586
|
+
* A built-in is compared against its live property. A COMPONENT is compared against its current value — the raw one
|
|
587
|
+
* its store holds (`_$raw$`) for a name it received, else read through `untracked` — and receives a difference
|
|
588
|
+
* through `adoptProperty`. Inline, as the renderer's `commit` reads a template's `!name`: keep the two equal.
|
|
589
|
+
*/
|
|
590
|
+
if (binding._read === null) {
|
|
591
|
+
if (element[name] !== value)
|
|
592
|
+
element[name] = value;
|
|
593
|
+
}
|
|
594
|
+
else {
|
|
595
|
+
const raw = element._$raw$;
|
|
596
|
+
if ((raw !== undefined && name in raw ? raw[name] : binding._read(read, element, name)) !== value)
|
|
597
|
+
adoptProperty(element, name, value);
|
|
598
|
+
}
|
|
353
599
|
return;
|
|
354
600
|
}
|
|
355
601
|
if (value === binding._committed)
|
|
356
602
|
return;
|
|
357
603
|
binding._committed = value;
|
|
358
|
-
const element = binding._element;
|
|
359
|
-
const name = binding._name;
|
|
360
|
-
const kind = binding._kind;
|
|
361
604
|
if (kind === ATTR) {
|
|
362
605
|
if (value == null)
|
|
363
606
|
element.removeAttribute(name);
|
|
364
607
|
else {
|
|
365
608
|
if (true ) {
|
|
366
|
-
const
|
|
367
|
-
if (
|
|
368
|
-
console.warn(
|
|
609
|
+
const kind = attributeValueKind(element.localName, name, value);
|
|
610
|
+
if (kind !== null)
|
|
611
|
+
console.warn(diagnostic('spread', `<${element.localName}>`, 'attribute-value', true && attributeValue(name, kind, `'.${name}': value`)));
|
|
369
612
|
}
|
|
370
|
-
/**
|
|
371
|
-
* `` `${value}` ``, never `String(value)` — the two differ on exactly one thing and it is the
|
|
372
|
-
* one that matters here. `String(sym)` returns `"Symbol(s)"` while every DOM conversion and
|
|
373
|
-
* `@verajs/ssr`'s own escaper throw, so this sink was the ONLY one of three that accepted a
|
|
374
|
-
* symbol, writing to the client an attribute the server refuses to produce. The rule was
|
|
375
|
-
* already recorded in `@verajs/ssr`'s `escapeHtml` — "serving Symbol(s) into markup the client
|
|
376
|
-
* cannot reproduce does not make anything work, it moves the failure across the boundary and
|
|
377
|
-
* strips the context" — and this file used the other form anyway. A house rule written down
|
|
378
|
-
* in one of three homes is a house rule in none of them.
|
|
379
|
-
*/
|
|
380
613
|
element.setAttribute(name, `${value}`);
|
|
381
614
|
}
|
|
382
615
|
}
|
|
383
616
|
else if (kind === PROPERTY) {
|
|
384
|
-
if (binding.
|
|
385
|
-
const next = adopt(element, name, value);
|
|
386
|
-
if (next !== 0) {
|
|
387
|
-
binding._recording = false;
|
|
388
|
-
if (next === REFUSED)
|
|
389
|
-
binding._kind = REFUSED; // inert: `write` matches it against nothing
|
|
390
|
-
}
|
|
391
|
-
}
|
|
392
|
-
else
|
|
617
|
+
if (binding._state === 1)
|
|
393
618
|
element[name] = value;
|
|
619
|
+
else if (binding._state === 0)
|
|
620
|
+
binding._state = adoptProperty(element, name, value);
|
|
394
621
|
}
|
|
395
|
-
else if (kind === BOOLEAN)
|
|
622
|
+
else if (kind === BOOLEAN)
|
|
396
623
|
element.toggleAttribute(name, !!value);
|
|
397
|
-
}
|
|
398
624
|
else if (kind === REF) {
|
|
399
|
-
/**
|
|
400
|
-
* `&name` is the written form's ref sigil (`<input &field=${myRef} />`), and it was the one
|
|
401
|
-
* binding kind a spread could not express: the key fell through to `ATTR` and
|
|
402
|
-
* `setAttribute('&field', …)` threw on the client while the server wrote `&field="[object
|
|
403
|
-
* Object]"` into the markup. A function is called with the element, an object gets it assigned
|
|
404
|
-
* to `.value` — the same two shapes `AttrPart` handles.
|
|
405
|
-
*/
|
|
406
625
|
if (typeof value === 'function')
|
|
407
626
|
value(element);
|
|
408
627
|
else if (value !== null && typeof value === 'object')
|
|
409
628
|
value.value = element;
|
|
410
629
|
}
|
|
411
630
|
else {
|
|
412
|
-
/**
|
|
413
|
-
* A listener is validated when a *user* clicks, which in development may be never — so it is
|
|
414
|
-
* checked where it is written, the same rule `AttrPart` applies to `@event`. `false` stays
|
|
415
|
-
* silent: `{ onClick: enabled && onClick }` is the ordinary conditional form and already
|
|
416
|
-
* behaves correctly, since `handleEvent` finds nothing callable and does nothing.
|
|
417
|
-
*/
|
|
418
631
|
if (true && value != null && value !== false && typeof value !== 'function' &&
|
|
419
632
|
typeof value?.handleEvent !== 'function')
|
|
420
|
-
console.warn(
|
|
421
|
-
`${typeof value === 'object' ? 'an object with no handleEvent method' : `a ${typeof value}`}, ` +
|
|
422
|
-
`which cannot listen — the event will do nothing.\n` +
|
|
423
|
-
`Pass a function, or an object with a handleEvent method. A missing handler is ` +
|
|
424
|
-
`\`undefined\` or \`false\`, both of which are fine; this is neither.`);
|
|
633
|
+
console.warn(diagnostic('spread', `<${element.localName}>`, 'not-a-listener', true && notAListener(name, typeof value)));
|
|
425
634
|
if (binding._handler === null && value != null)
|
|
426
635
|
element.addEventListener(name, binding);
|
|
427
636
|
binding._handler = value ?? null;
|
|
428
637
|
}
|
|
429
638
|
};
|
|
430
639
|
/**
|
|
431
|
-
*
|
|
432
|
-
*
|
|
433
|
-
* This is the question Lit's PR is stuck on, and the trap is asking it as "what value means absent".
|
|
434
|
-
* For a property there is no answer: assigning `undefined` runs through coercing setters, so
|
|
435
|
-
* dropping `.value` yields `""` rather than reverting, and `delete` cannot remove a prototype
|
|
436
|
-
* accessor. Asked instead as *"undo what this binding did"* it is well defined for every kind and
|
|
437
|
-
* never invents a value the author did not write — the initial state was, by definition, acceptable
|
|
438
|
-
* before the binding arrived.
|
|
439
|
-
*
|
|
440
|
-
* And asked that way it needs no code of its own: releasing is writing the initial value back.
|
|
441
|
-
* `null` removes an attribute, `false` untoggles a boolean, `undefined` restores a property to
|
|
442
|
-
* pristine, and an event handler falls to `null` — every case the existing commit already handles.
|
|
443
|
-
* The separate per-kind teardown this replaced was fourteen lines saying the same thing twice.
|
|
444
|
-
*
|
|
445
|
-
* Deliberately unguarded by an ownership check (`is the value still the one we wrote?`). That only
|
|
446
|
-
* matters when a component reassigns a property its parent is binding, which is already confused;
|
|
447
|
-
* per principle #3 the machinery waits for evidence rather than being pre-built.
|
|
640
|
+
* Each binding is owned by the renderer's binding record it arrived through (the `key`), so one element can
|
|
641
|
+
* carry several spreads. A key that leaves the bag is written back to what the element held before.
|
|
448
642
|
*/
|
|
449
|
-
|
|
643
|
+
const owned = new WeakMap();
|
|
644
|
+
/**
|
|
645
|
+
* `untracked` is `_$apply$`'s third argument — core's, through the renderer; `call` when a renderer leaves it out.
|
|
646
|
+
* Each binding keeps the one it was CREATED with, so nothing about it is paid per render, and an apply nested inside
|
|
647
|
+
* another (a component setter rendering a spread) can never change what the outer's bindings use.
|
|
648
|
+
*/
|
|
649
|
+
function apply(element, key, untracked = call, adopting = false) {
|
|
450
650
|
const props = this._props;
|
|
451
|
-
let bindings = owned.get(
|
|
651
|
+
let bindings = owned.get(key);
|
|
452
652
|
if (bindings === undefined)
|
|
453
|
-
owned.set(
|
|
454
|
-
/**
|
|
455
|
-
* Counted here rather than with `Object.keys(props).length`, which allocates an array on every
|
|
456
|
-
* render of every spread — garbage in the render path, for a number already being walked.
|
|
457
|
-
*/
|
|
653
|
+
owned.set(key, (bindings = new Map()));
|
|
458
654
|
let count = 0;
|
|
459
|
-
for (const
|
|
655
|
+
for (const name in props) {
|
|
460
656
|
count++;
|
|
461
|
-
|
|
462
|
-
* Counted before it is skipped, so the size comparison below still describes the key set — a
|
|
463
|
-
* refused key that changed the count would make every render look like a removal.
|
|
464
|
-
*/
|
|
465
|
-
if (UNSAFE_NAME.test(key[0] === '.' || key[0] === '?' || key[0] === '@' || key[0] === '&' ? key.slice(1) : key)) {
|
|
466
|
-
if (true )
|
|
467
|
-
console.warn(`[vera] spread: ignoring the key ${JSON.stringify(key)} — an attribute name ` +
|
|
468
|
-
`cannot contain whitespace, a quote, \`<\`, \`>\`, \`/\`, \`=\` or a control character, ` +
|
|
469
|
-
`and one that cannot be written into markup would not survive server rendering.`);
|
|
470
|
-
continue;
|
|
471
|
-
}
|
|
472
|
-
/** Counted above for the same reason the unsafe skip is. */
|
|
473
|
-
const refused = refusedSink(key);
|
|
474
|
-
if (refused !== null) {
|
|
475
|
-
if (true )
|
|
476
|
-
console.warn(`[vera] spread: refusing ${JSON.stringify(key)} — spread names arrive at runtime, which is ` +
|
|
477
|
-
`exactly the property that makes this sink unreviewable; ${refused}.`);
|
|
478
|
-
continue;
|
|
479
|
-
}
|
|
480
|
-
let binding = bindings.get(key);
|
|
657
|
+
let binding = bindings.get(name);
|
|
481
658
|
if (binding === undefined)
|
|
482
|
-
bindings.set(
|
|
483
|
-
write(binding, props[
|
|
484
|
-
}
|
|
485
|
-
/**
|
|
486
|
-
* A size mismatch is the only way a key can have gone: every key in `props` was just visited, so
|
|
487
|
-
* equal sizes means equal sets. The steady-state render of an unchanged shape — overwhelmingly the
|
|
488
|
-
* common case — costs one integer comparison, not a scan.
|
|
489
|
-
*/
|
|
490
|
-
if (bindings.size !== count) {
|
|
491
|
-
for (const [key, binding] of bindings) {
|
|
492
|
-
if (key in props)
|
|
493
|
-
continue;
|
|
494
|
-
bindings.delete(key);
|
|
495
|
-
write(binding, binding._initial);
|
|
496
|
-
}
|
|
659
|
+
bindings.set(name, (binding = new Binding(element, name, untracked)));
|
|
660
|
+
write(binding, props[name], adopting);
|
|
497
661
|
}
|
|
662
|
+
if (bindings.size !== count)
|
|
663
|
+
for (const [name, binding] of bindings)
|
|
664
|
+
if (!(name in props)) {
|
|
665
|
+
bindings.delete(name);
|
|
666
|
+
write(binding, binding._initial);
|
|
667
|
+
}
|
|
498
668
|
}
|
|
499
669
|
/**
|
|
500
|
-
* The server half of the protocol:
|
|
501
|
-
*
|
|
502
|
-
*
|
|
503
|
-
* Deliberately *not* a serializer. This package knows what a key means — `.value` is a property,
|
|
504
|
-
* `?disabled` a boolean, `onClick` an event — and nothing else. Whether a property belongs in
|
|
505
|
-
* server markup (`value`, `checked`, `selected` do; the rest are client state) and how a value is
|
|
506
|
-
* escaped are `@verajs/ssr`'s decisions, and principle #8 wants escaping in exactly one place. So
|
|
507
|
-
* this returns data, never a string.
|
|
508
|
-
*
|
|
509
|
-
* Kinds are single characters rather than the module's numeric constants, because this crosses a
|
|
510
|
-
* package boundary: `a`ttribute, `b`oolean, `p`roperty, `e`vent, `r`ef. A ref is client state with
|
|
511
|
-
* no markup, exactly like an event, and the serializer drops both.
|
|
670
|
+
* The server half of the protocol: `[kind, name, value]` for each key `@verajs/ssr` should serialize —
|
|
671
|
+
* `a`ttribute, `b`oolean, `p`roperty, `e`vent, `r`ef — with every refusal and every refused URL already
|
|
672
|
+
* applied, by the same `resolve` the client uses, so the two cannot disagree.
|
|
512
673
|
*/
|
|
513
674
|
function attributes() {
|
|
514
675
|
const out = [];
|
|
515
676
|
for (const key in this._props) {
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
677
|
+
const [kind, name] = resolve(key);
|
|
678
|
+
/** No element here: a property key is judged as a custom element's — the server only ever delivers one to a component. */
|
|
679
|
+
const rule = urlRule(kind, name, true);
|
|
680
|
+
const value = checked(rule, this._props[key]);
|
|
681
|
+
if (kind === REFUSED || value === REFUSE)
|
|
519
682
|
continue;
|
|
520
|
-
|
|
521
|
-
/** `!` reports as a property: the server has nothing to re-read, so it serializes as `.` does. */
|
|
522
|
-
const kind = first === '.' || first === '!'
|
|
523
|
-
? 'p'
|
|
524
|
-
: first === '?'
|
|
525
|
-
? 'b'
|
|
526
|
-
: first === '@'
|
|
527
|
-
? 'e'
|
|
528
|
-
: first === '&'
|
|
529
|
-
? 'r'
|
|
530
|
-
: 'a';
|
|
531
|
-
if (kind !== 'a') {
|
|
532
|
-
out.push([kind, key.slice(1), this._props[key]]);
|
|
533
|
-
}
|
|
534
|
-
else if (first === 'o' && key.charCodeAt(1) === 110 && key.charCodeAt(2) > 64 && key.charCodeAt(2) < 91) {
|
|
535
|
-
out.push(['e', key.slice(2).toLowerCase(), this._props[key]]);
|
|
536
|
-
}
|
|
537
|
-
else {
|
|
538
|
-
out.push(['a', key, this._props[key]]);
|
|
539
|
-
}
|
|
683
|
+
out.push([kind === ATTR ? 'a' : kind === BOOLEAN ? 'b' : kind === EVENT ? 'e' : kind === REF ? 'r' : 'p', name, value]);
|
|
540
684
|
}
|
|
541
685
|
return out;
|
|
542
686
|
}
|
|
543
687
|
/**
|
|
544
|
-
* `
|
|
545
|
-
*
|
|
546
|
-
* an INTERFACE does not, so `spread(myProps)` was a TS2345 for every user who declared their props
|
|
547
|
-
* the way the TypeScript handbook teaches — while the sibling `props()` accepted the same value,
|
|
548
|
-
* because it is generic. Two functions in one module disagreeing about a user's own type is the
|
|
549
|
-
* kind of thing nobody reports as a bug; they just stop using the one that refused them.
|
|
688
|
+
* Binds every key of `props` to the element it is placed on. Keys follow the template sigils — `.prop`,
|
|
689
|
+
* `?bool`, `@event` (or `onClick`), `&ref`, `!live` — and a plain key is an attribute.
|
|
550
690
|
*
|
|
551
|
-
*
|
|
552
|
-
*
|
|
553
|
-
*
|
|
554
|
-
* runtime deliberately tolerates.
|
|
691
|
+
* Already-branded input is returned as-is (JSX compiles `{...spread(x)}` to a spread of a spread). A
|
|
692
|
+
* value that is not a plain object is refused in BOTH builds — a string would otherwise be iterated by
|
|
693
|
+
* character index into attributes named `0`, `1`, `2` — and development says so.
|
|
555
694
|
*/
|
|
556
695
|
const spread = (props) => {
|
|
557
|
-
|
|
558
|
-
* **Already branded → returned as-is.** `spread(spread(x))` arises legitimately: JSX compiles
|
|
559
|
-
* `{...props({ date })}` to `spread(props({ date }))`, and `props()` below already returns the
|
|
560
|
-
* branded result. Without this line the brand itself would be iterated as a bag and bind
|
|
561
|
-
* attributes named `_props`, `_$apply$` and `_$attrs$`. Detected by the brand's PRESENCE, never
|
|
562
|
-
* by identity with this bundle's `apply` — on a CDN page the renderer and a second copy of this
|
|
563
|
-
* module are separate bundles with separate `apply` functions, and a result from either must
|
|
564
|
-
* pass through both (the two-registry failure shape `tests/cdn-cross-bundle.test.mjs` guards).
|
|
565
|
-
*/
|
|
566
|
-
if (props !== null && typeof props === 'object' && props._$apply$ !== undefined)
|
|
696
|
+
if (props !== null && typeof props === 'object' && typeof props._$apply$ === 'function')
|
|
567
697
|
return props;
|
|
568
|
-
/**
|
|
569
|
-
* **A props bag that is not an object is iterated anyway, and a browser accepts the result.**
|
|
570
|
-
*
|
|
571
|
-
* Everything below reads `props` with `Object.keys`/`Object.entries`, which answer for any value:
|
|
572
|
-
* a **string** yields its character indices, so `spread('text')` sets four attributes named `0`,
|
|
573
|
-
* `1`, `2`, `3` — measured in Chromium, with no error and no warning. A number, a boolean and
|
|
574
|
-
* `null` yield nothing at all, so `spread(someUndefinedVariable)` applies no props and says
|
|
575
|
-
* nothing, which reads as a renderer that ignored the spread.
|
|
576
|
-
*
|
|
577
|
-
* **jsdom hides this rather than catching it.** It implements the XML Name production and throws
|
|
578
|
-
* `InvalidCharacterError` on `setAttribute('0', …)`, so a probe under jsdom sees a loud failure
|
|
579
|
-
* for the case a real engine performs silently — the inverse of the usual trap, and the reason
|
|
580
|
-
* this was verified in a browser before being called a defect (`tests/browser/spread-names.test.js`
|
|
581
|
-
* records the engines' actual rule).
|
|
582
|
-
*
|
|
583
|
-
* Warned and ignored rather than thrown, which is exactly what an unusable *key* already does a
|
|
584
|
-
* few lines above: one bad props bag should not cost the render.
|
|
585
|
-
*
|
|
586
|
-
* **The message is `true `-only; the refusal is not.** They were both inside the guard, which
|
|
587
|
-
* made the two builds behave differently for the same code — and differently in the direction that
|
|
588
|
-
* hides the bug. Measured: `spread('text')` applies nothing in development, so the app under test
|
|
589
|
-
* looks fine; in production the string is iterated by character index and the element ends up with
|
|
590
|
-
* attributes named `0`, `1`, `2` and `3` (under jsdom, an `InvalidCharacterError` instead — the
|
|
591
|
-
* usual inversion, and why this was measured against both builds rather than reasoned about).
|
|
592
|
-
*
|
|
593
|
-
* A diagnostic belongs in `true `. A guard that changes what the program does cannot, or the
|
|
594
|
-
* development build stops being a faithful model of the production one, which is the property that
|
|
595
|
-
* makes testing in it worth anything. Costs 27 B gzipped (842 → 869, A-B-A) and buys the two builds agreeing.
|
|
596
|
-
*/
|
|
597
698
|
if (props === null || typeof props !== 'object' || Array.isArray(props)) {
|
|
598
699
|
if (true )
|
|
599
|
-
console.warn(
|
|
600
|
-
`${Array.isArray(props) ? 'an array' : typeof props === 'object' ? 'null' : `a ${typeof props}`}. ` +
|
|
601
|
-
`A string is iterated by character index, so \`spread('text')\` would set attributes named ` +
|
|
602
|
-
`0, 1, 2 and 3; anything else applies nothing at all. This is usually an import or a ` +
|
|
603
|
-
`property that resolved to something unexpected.`);
|
|
700
|
+
console.warn(diagnostic('spread', 'spread()', 'spread-not-object', true && PROSE['spread-not-object'](Array.isArray(props) ? 'an array' : typeof props === 'object' ? 'null' : `a ${typeof props}`)));
|
|
604
701
|
props = {};
|
|
605
702
|
}
|
|
606
|
-
return {
|
|
607
|
-
/**
|
|
608
|
-
* The one cast the widened parameter costs. Everything downstream reads this bag with
|
|
609
|
-
* `Object.keys`/`Object.entries`, which answer for any object, and the branch above has already
|
|
610
|
-
* replaced anything that is not a plain object — so the shape is a record by construction, not
|
|
611
|
-
* by assertion.
|
|
612
|
-
*/
|
|
613
|
-
_props: props,
|
|
614
|
-
_$apply$: apply,
|
|
615
|
-
_$attrs$: attributes,
|
|
616
|
-
};
|
|
703
|
+
return { _props: props, _$apply$: apply, _$attrs$: attributes };
|
|
617
704
|
};
|
|
618
|
-
/**
|
|
619
|
-
* A bag of PROPERTY bindings — the object form of `.name=${value}`, one call in both surfaces:
|
|
620
|
-
*
|
|
621
|
-
* ```js
|
|
622
|
-
* html`<calendar-day ${props({ date, events })}></calendar-day>`
|
|
623
|
-
* ```
|
|
624
|
-
* ```jsx
|
|
625
|
-
* <calendar-day {...props({ date, events })}></calendar-day>
|
|
626
|
-
* ```
|
|
627
|
-
*
|
|
628
|
-
* Exists because an attribute is always a string: an array, a `Date` or a store can only reach a
|
|
629
|
-
* custom element as a property — vera's JSX accepts the sigil spelling, TSX's type-checker refuses
|
|
630
|
-
* it (`TS1003`), and this bag is the typed path either way. Every key is a
|
|
631
|
-
* property NAME, never a sigil — `props({ date })` binds `.date`, so `props({ '.date': d })` would
|
|
632
|
-
* bind `..date` and is the caller's mistake to keep.
|
|
633
|
-
*
|
|
634
|
-
* Properties only, by definition: events and boolean attributes keep their own spellings
|
|
635
|
-
* (`@click`/`onClick`, `?disabled`). **Prefer keys spelled conditionally over bags that change
|
|
636
|
-
* shape** — `props({ date: loaded ? date : null })` over `props(loaded ? { date } : {})`. Both
|
|
637
|
-
* work: a key appearing later on a component goes through `_$adopt$` and arrives reactive, and a
|
|
638
|
-
* key that disappears restores what the element held — but a stable shape updates in place, the
|
|
639
|
-
* same reason templates prefer `?hidden` over swapped subtrees.
|
|
640
|
-
*
|
|
641
|
-
* With an explicit type argument the bag is checked against the element —
|
|
642
|
-
* `props<CalendarDay>({ dat })` is a compile error naming the misspelling.
|
|
643
|
-
*/
|
|
705
|
+
/** Every key as a property: `props({ items })` is `spread({ '.items': items })` — how a component receives data. */
|
|
644
706
|
const props = (values) => {
|
|
645
707
|
const sigiled = {};
|
|
646
708
|
for (const key of Object.keys(values))
|