@verajs/ssr 0.1.3 → 0.2.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 +369 -8
- package/package.json +37 -4
- package/src/vera/escaping.js +135 -0
- package/src/vera/events.js +164 -0
- package/src/vera/frames.js +102 -0
- package/src/vera/index.js +1116 -46
- package/src/vera/nodes.js +2270 -0
- package/src/vera/parse.js +381 -0
- package/src/vera/reflections.js +811 -0
- package/src/vera/registry.js +9 -0
- package/src/vera/select.js +234 -0
- package/src/vera/serializer.js +835 -32
- package/src/vera/shim.js +734 -108
- package/src/vera/stylesheets.js +155 -0
- package/src/vera/views.js +240 -0
- package/types/escaping.d.ts +27 -0
- package/types/events.d.ts +4 -0
- package/types/frames.d.ts +12 -0
- package/types/index.d.ts +13 -0
- package/types/nodes.d.ts +738 -0
- package/types/parse.d.ts +19 -0
- package/types/reflections.d.ts +657 -0
- package/types/registry.d.ts +8 -0
- package/types/select.d.ts +5 -0
- package/types/serializer.d.ts +26 -0
- package/types/shim.d.ts +23 -0
- package/types/stylesheets.d.ts +53 -0
- package/types/views.d.ts +26 -0
package/types/nodes.d.ts
ADDED
|
@@ -0,0 +1,738 @@
|
|
|
1
|
+
export function serializeElement(element: any): any;
|
|
2
|
+
export class TextShim extends CharacterDataShim {
|
|
3
|
+
get nodeType(): number;
|
|
4
|
+
get nodeName(): string;
|
|
5
|
+
get wholeText(): string;
|
|
6
|
+
markup(): string;
|
|
7
|
+
cloneNode(): TextShim;
|
|
8
|
+
/** Splits at `offset`, leaving this node with the first half and inserting the second after it. */
|
|
9
|
+
splitText(offset: any): TextShim;
|
|
10
|
+
}
|
|
11
|
+
export class CommentShim extends CharacterDataShim {
|
|
12
|
+
get nodeType(): number;
|
|
13
|
+
get nodeName(): string;
|
|
14
|
+
markup(): string;
|
|
15
|
+
cloneNode(): CommentShim;
|
|
16
|
+
}
|
|
17
|
+
export class ContainerShim extends EventTarget {
|
|
18
|
+
/**
|
|
19
|
+
* **Children are entries, not one string.** Each entry is either a retained node or a chunk of
|
|
20
|
+
* raw markup. Serialisation happens when `innerHTML` is *read*, not when a child is appended —
|
|
21
|
+
* appending used to serialise immediately and drop the node, so `appendChild(kid)` followed by
|
|
22
|
+
* `kid.textContent = 'x'` rendered `<b></b>` and lost the text with no diagnostic.
|
|
23
|
+
*/
|
|
24
|
+
_entries: any[];
|
|
25
|
+
_parent: any;
|
|
26
|
+
/** A server-rendered node is in the document being built, so it is connected. */
|
|
27
|
+
isConnected: boolean;
|
|
28
|
+
/**
|
|
29
|
+
* Registered here rather than on the platform's `EventTarget`; see `events.js`.
|
|
30
|
+
* @override
|
|
31
|
+
*/
|
|
32
|
+
override addEventListener(type: any, callback: any, options: any): void;
|
|
33
|
+
/** @override */
|
|
34
|
+
override removeEventListener(type: any, callback: any, options: any): void;
|
|
35
|
+
/** @override */
|
|
36
|
+
override dispatchEvent(event: any): boolean;
|
|
37
|
+
set innerHTML(markup: string);
|
|
38
|
+
get innerHTML(): string;
|
|
39
|
+
/** New markup has not been looked at yet, whatever was true of the markup it replaced. */
|
|
40
|
+
_parsed: boolean | undefined;
|
|
41
|
+
appendChild(node: any): any;
|
|
42
|
+
/**
|
|
43
|
+
* **Position a node among the children**, which needed a tree and now has one. `reference` of
|
|
44
|
+
* `null` appends, as the platform says, and a reference that is not a child is a `NotFoundError`
|
|
45
|
+
* rather than a silent append — the difference between "put it at the end" and "you asked about
|
|
46
|
+
* a node I do not have" is exactly the kind of thing a server should not paper over.
|
|
47
|
+
*/
|
|
48
|
+
insertBefore(node: any, reference: any): any;
|
|
49
|
+
/**
|
|
50
|
+
* **`moveBefore` is `insertBefore` with a precondition**: the node must already have a parent.
|
|
51
|
+
* Measured on Chromium and Firefox, which agree on all of it (WebKit does not implement it yet):
|
|
52
|
+
* an unparented node is a `HierarchyRequestError`, and a *parented* node with a reference that is
|
|
53
|
+
* not a child here is a `NotFoundError` — a different error from the same call depending on which
|
|
54
|
+
* argument is wrong, and checked in that order.
|
|
55
|
+
*
|
|
56
|
+
* The point of the API in a browser is moving a node without tearing down its state. There is no
|
|
57
|
+
* state to preserve on a server, so this is a move; having it means code written for the browser
|
|
58
|
+
* runs here rather than hitting a missing method.
|
|
59
|
+
*/
|
|
60
|
+
moveBefore(node: any, reference: any): any;
|
|
61
|
+
replaceChild(node: any, old: any): any;
|
|
62
|
+
/**
|
|
63
|
+
* **Where each node sits relative to another**, as the spec's bit field. Two nodes with no common
|
|
64
|
+
* root are `DISCONNECTED | IMPLEMENTATION_SPECIFIC` plus a direction the spec leaves to the
|
|
65
|
+
* implementation, so only the disconnected bit is worth comparing across implementations.
|
|
66
|
+
*/
|
|
67
|
+
compareDocumentPosition(other: any): number;
|
|
68
|
+
/** Remove a node from this container's entries without touching its own parent pointer. */
|
|
69
|
+
_detach(node: any): void;
|
|
70
|
+
/**
|
|
71
|
+
* **Absent until nodes were retained**, so `host.removeChild(kid)` was a `TypeError` — there was
|
|
72
|
+
* nothing to remove, the child having been flattened into a string at append time.
|
|
73
|
+
*/
|
|
74
|
+
removeChild(node: any): any;
|
|
75
|
+
/**
|
|
76
|
+
* What a node with no tree above or below it answers — shared, because an element and a shadow
|
|
77
|
+
* root answer these identically and two copies is how they came to disagree in the first place.
|
|
78
|
+
*
|
|
79
|
+
* Every one is the truthful answer rather than a placeholder: a detached node has no parent, no
|
|
80
|
+
* siblings and no box, and a browser returns exactly these. They are here because their
|
|
81
|
+
* *absence* was a `TypeError` that took the whole render down — `this.parentElement && …` is
|
|
82
|
+
* ordinary defensive code and it crashed.
|
|
83
|
+
*/
|
|
84
|
+
get parentNode(): any;
|
|
85
|
+
/** `null` when the parent is not an element — a shadow root is a parent and not an element. */
|
|
86
|
+
get parentElement(): any;
|
|
87
|
+
get firstChild(): any;
|
|
88
|
+
get lastChild(): any;
|
|
89
|
+
get lastElementChild(): any;
|
|
90
|
+
/**
|
|
91
|
+
* **The siblings are real now.** These answered `null` unconditionally, which was truthful while a
|
|
92
|
+
* child was flattened into its parent's markup and became a lie the moment nodes were retained —
|
|
93
|
+
* `element.nextSibling` on the middle of three children reported nothing at all. There are no text
|
|
94
|
+
* nodes in this DOM, so the element-wise and node-wise spellings answer the same list.
|
|
95
|
+
*/
|
|
96
|
+
get nextSibling(): any;
|
|
97
|
+
get previousSibling(): any;
|
|
98
|
+
get nextElementSibling(): any;
|
|
99
|
+
get previousElementSibling(): any;
|
|
100
|
+
/** @param {number} step @param {(container: any) => Array<any>} view */
|
|
101
|
+
_siblingAt(step: number, view?: (container: any) => Array<any>): any;
|
|
102
|
+
/**
|
|
103
|
+
* **The slot this node is projected into**, which needs the host's shadow root and the node's own
|
|
104
|
+
* `slot` name — both of which are here. It answered `null` for every node, so a component asking
|
|
105
|
+
* where its light DOM had landed was told "nowhere".
|
|
106
|
+
*/
|
|
107
|
+
get assignedSlot(): any;
|
|
108
|
+
get offsetParent(): null;
|
|
109
|
+
get childElementCount(): number;
|
|
110
|
+
hasChildNodes(): boolean;
|
|
111
|
+
get nodeValue(): null;
|
|
112
|
+
get baseURI(): string;
|
|
113
|
+
get namespaceURI(): string;
|
|
114
|
+
get prefix(): null;
|
|
115
|
+
get ownerDocument(): Document;
|
|
116
|
+
/**
|
|
117
|
+
* **Walks the parent chain**, as the platform does. It compared identity only, so
|
|
118
|
+
* `host.contains(child)` was `false` for a child the host plainly held — ordinary defensive code
|
|
119
|
+
* reading as "this is not mine".
|
|
120
|
+
*/
|
|
121
|
+
contains(node: any): boolean;
|
|
122
|
+
/** The `ChildNode` trio, shared with text and comments through `insertAround`. */
|
|
123
|
+
before(...nodes: any[]): void;
|
|
124
|
+
after(...nodes: any[]): void;
|
|
125
|
+
replaceWith(...nodes: any[]): void;
|
|
126
|
+
isSameNode(node: any): boolean;
|
|
127
|
+
/**
|
|
128
|
+
* **Structural equality, not identity** — that is what `isSameNode` is for, and this answered the
|
|
129
|
+
* same thing, so two elements built identically reported themselves different. The spec compares
|
|
130
|
+
* type, name, attributes as a set, and children pairwise.
|
|
131
|
+
*/
|
|
132
|
+
isEqualNode(node: any): any;
|
|
133
|
+
/**
|
|
134
|
+
* **Merges adjacent text and drops the empty**, which is what it is for. It was a no-op because
|
|
135
|
+
* there were no text nodes to merge — appending two of them left two entries a browser would have
|
|
136
|
+
* joined into one, so `childNodes.length` disagreed after the most ordinary DOM building there is.
|
|
137
|
+
*/
|
|
138
|
+
normalize(): void;
|
|
139
|
+
/**
|
|
140
|
+
* The furthest ancestor, which is the shadow root for anything a component rendered into one —
|
|
141
|
+
* unless `composed` is asked for, which keeps going out through the root's host as a browser does.
|
|
142
|
+
*/
|
|
143
|
+
getRootNode(options: any): any;
|
|
144
|
+
/** Needs layout, which a string does not have; a browser with no box returns nothing either. */
|
|
145
|
+
elementFromPoint(): null;
|
|
146
|
+
elementsFromPoint(): never[];
|
|
147
|
+
getSelection(): null;
|
|
148
|
+
/** `append` takes several nodes, and strings as text — the modern spelling of `appendChild`. */
|
|
149
|
+
/**
|
|
150
|
+
* A string is markup to escape and keep as a chunk. It used to go through `innerHTML +=`, which
|
|
151
|
+
* now reads every retained node back into text and writes it as one chunk — flattening the tree
|
|
152
|
+
* this class exists to keep. Pushing the chunk is the same bytes and keeps the nodes.
|
|
153
|
+
*/
|
|
154
|
+
append(...nodes: any[]): void;
|
|
155
|
+
replaceChildren(...nodes: any[]): void;
|
|
156
|
+
/** Splices the entries rather than concatenating markup, for the reason `append` gives. */
|
|
157
|
+
/**
|
|
158
|
+
* **The restore has to survive a throw.** `append` can reject a node — an ancestor of `this` is a
|
|
159
|
+
* `HierarchyRequestError` — and the children were already moved aside by then, so the final
|
|
160
|
+
* `push` never ran and **every existing child was destroyed by a call that failed**.
|
|
161
|
+
*
|
|
162
|
+
* Measured against jsdom: `child.prepend(root)` throws on both, and afterwards jsdom still holds
|
|
163
|
+
* the child's text while this held nothing. A failed operation that mutates is worse than one that
|
|
164
|
+
* does the wrong thing, because the caller has already handled the error and moved on.
|
|
165
|
+
*
|
|
166
|
+
* `finally`, not a validity pre-pass: matching the spec exactly would mean checking every argument
|
|
167
|
+
* before inserting any, so that a second bad node undoes a first good one. That difference is
|
|
168
|
+
* narrower than this one and is left alone deliberately — what is fixed here is the destruction of
|
|
169
|
+
* children that were never arguments.
|
|
170
|
+
*
|
|
171
|
+
* Found by fuzzing sequences of tree mutations against jsdom; the failing sequence ended
|
|
172
|
+
* `prepend(n1, root)` and the loss showed up as a missing text node four operations later.
|
|
173
|
+
*/
|
|
174
|
+
prepend(...nodes: any[]): void;
|
|
175
|
+
/**
|
|
176
|
+
* **Answers from the node view**, which markup assigned as a string now has. Every query used to
|
|
177
|
+
* return nothing whatever was asked, so a component branched the wrong way with nothing said.
|
|
178
|
+
* A selector this DOM cannot answer honestly throws rather than answering `null` — see
|
|
179
|
+
* `select.js`.
|
|
180
|
+
*/
|
|
181
|
+
querySelector(selector: any): any;
|
|
182
|
+
querySelectorAll(selector: any): any[];
|
|
183
|
+
getElementById(id: any): any;
|
|
184
|
+
/**
|
|
185
|
+
* **Only retained nodes.** Every entry this DOM holds as an element *is* an element, so `children`
|
|
186
|
+
* and `childNodes` answer the same list — there are no text nodes to separate them, and markup
|
|
187
|
+
* kept as a string is not nodes at all (`nodesOf` says so).
|
|
188
|
+
*/
|
|
189
|
+
get children(): any[];
|
|
190
|
+
get childNodes(): any[];
|
|
191
|
+
get firstElementChild(): any;
|
|
192
|
+
}
|
|
193
|
+
/**
|
|
194
|
+
* A fragment is a container and nothing more.
|
|
195
|
+
*
|
|
196
|
+
* Its own class rather than a reused `ElementShim`, so `instanceof DocumentFragment` answers `false`
|
|
197
|
+
* for an element — a check the renderer makes, and one that a shared class would have made true for
|
|
198
|
+
* everything.
|
|
199
|
+
*/
|
|
200
|
+
export class FragmentShim extends ContainerShim {
|
|
201
|
+
get nodeType(): number;
|
|
202
|
+
get nodeName(): string;
|
|
203
|
+
}
|
|
204
|
+
export class ShadowRootShim extends ContainerShim {
|
|
205
|
+
constructor(init: any);
|
|
206
|
+
mode: any;
|
|
207
|
+
_init: any;
|
|
208
|
+
/** Set by `attachShadow`; a shadow root's `host` is part of the contract the router reads. */
|
|
209
|
+
_host: any;
|
|
210
|
+
_styles: any[];
|
|
211
|
+
/** `shadowrootmode` plus whatever else the root was opened with, as the parser expects them. */
|
|
212
|
+
templateAttributes(): string;
|
|
213
|
+
/** A shadow root's `host` is part of the contract `@verajs/router` reads. */
|
|
214
|
+
get host(): any;
|
|
215
|
+
/**
|
|
216
|
+
* The options it was opened with, readable the way a browser exposes them.
|
|
217
|
+
*
|
|
218
|
+
* These are already serialized into the declarative template — they have to be, because
|
|
219
|
+
* `attachShadow` reuses a declarative root and ignores the options it is handed. A component
|
|
220
|
+
* that *reads* them back, to decide whether to manage focus itself, saw `undefined`.
|
|
221
|
+
*/
|
|
222
|
+
get delegatesFocus(): boolean;
|
|
223
|
+
get clonable(): boolean;
|
|
224
|
+
get serializable(): boolean;
|
|
225
|
+
get slotAssignment(): any;
|
|
226
|
+
get nodeType(): number;
|
|
227
|
+
get nodeName(): string;
|
|
228
|
+
/** Nothing is focused on a server, and nothing is in a top layer. */
|
|
229
|
+
get activeElement(): null;
|
|
230
|
+
get fullscreenElement(): null;
|
|
231
|
+
get pointerLockElement(): null;
|
|
232
|
+
get pictureInPictureElement(): null;
|
|
233
|
+
/** `<style>` elements appended here; the constructed ones are `adoptedStyleSheets`. */
|
|
234
|
+
get styleSheets(): (StyleSheetShim & {
|
|
235
|
+
cssText: any;
|
|
236
|
+
})[];
|
|
237
|
+
set textContent(value: string);
|
|
238
|
+
/** A shadow root's text is its content's text, and setting it replaces the content. */
|
|
239
|
+
get textContent(): string;
|
|
240
|
+
/**
|
|
241
|
+
* Constructed sheets land here; serialized alongside string styles.
|
|
242
|
+
*
|
|
243
|
+
* **Checked, because the platform checks.** A browser raises `TypeError` for a value that is not
|
|
244
|
+
* a sequence and for an entry that is not a `CSSStyleSheet`, and taking anything meant that
|
|
245
|
+
* `root.adoptedStyleSheets = sheet` — the single missing `[…]`, and the most likely way to get
|
|
246
|
+
* this wrong — was accepted here and threw in the browser, after the server had already rendered.
|
|
247
|
+
*/
|
|
248
|
+
set adoptedStyleSheets(sheets: any);
|
|
249
|
+
get adoptedStyleSheets(): any;
|
|
250
|
+
_adopted: any;
|
|
251
|
+
/**
|
|
252
|
+
* The `<style>` tags, kept separate from the content.
|
|
253
|
+
*
|
|
254
|
+
* They used to be concatenated here and the whole string handed to the nested-component scan,
|
|
255
|
+
* which then read the stylesheet as markup: CSS containing a registered tag name — a
|
|
256
|
+
* `content: "<some-comp>"` is enough — had that component **rendered inside the stylesheet**.
|
|
257
|
+
* A scan for elements has no business reading a raw-text element.
|
|
258
|
+
*/
|
|
259
|
+
styleTags(): string;
|
|
260
|
+
}
|
|
261
|
+
export namespace NODE_CONSTANTS {
|
|
262
|
+
let ELEMENT_NODE: number;
|
|
263
|
+
let ATTRIBUTE_NODE: number;
|
|
264
|
+
let TEXT_NODE: number;
|
|
265
|
+
let CDATA_SECTION_NODE: number;
|
|
266
|
+
let ENTITY_REFERENCE_NODE: number;
|
|
267
|
+
let ENTITY_NODE: number;
|
|
268
|
+
let PROCESSING_INSTRUCTION_NODE: number;
|
|
269
|
+
let COMMENT_NODE: number;
|
|
270
|
+
let DOCUMENT_NODE: number;
|
|
271
|
+
let DOCUMENT_TYPE_NODE: number;
|
|
272
|
+
let DOCUMENT_FRAGMENT_NODE: number;
|
|
273
|
+
let NOTATION_NODE: number;
|
|
274
|
+
let DOCUMENT_POSITION_DISCONNECTED: number;
|
|
275
|
+
let DOCUMENT_POSITION_PRECEDING: number;
|
|
276
|
+
let DOCUMENT_POSITION_FOLLOWING: number;
|
|
277
|
+
let DOCUMENT_POSITION_CONTAINS: number;
|
|
278
|
+
let DOCUMENT_POSITION_CONTAINED_BY: number;
|
|
279
|
+
let DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC: number;
|
|
280
|
+
}
|
|
281
|
+
export class ElementShim extends ContainerShim {
|
|
282
|
+
constructor(localName?: string, namespaceURI?: string);
|
|
283
|
+
_ns: string;
|
|
284
|
+
localName: string;
|
|
285
|
+
_attributes: Map<any, any>;
|
|
286
|
+
_shadowRoot: ShadowRootShim | null;
|
|
287
|
+
/**
|
|
288
|
+
* The bytes this element's own tags were parsed from, when it came from markup rather than
|
|
289
|
+
* `createElement`. Declared here so every element has the same shape — and so a type-checker
|
|
290
|
+
* knows about a field the parser is what assigns.
|
|
291
|
+
*/
|
|
292
|
+
_sourceOpenTag: string | null;
|
|
293
|
+
_sourceCloseTag: string | null;
|
|
294
|
+
/**
|
|
295
|
+
* An attribute name as this element stores it.
|
|
296
|
+
*
|
|
297
|
+
* A browser lower-cases the name inside `setAttribute` on an HTML element, so `setAttribute('Data-Flag', '1')`
|
|
298
|
+
* and `getAttribute('data-flag')` are the *same* attribute. Storing the name as written made them two,
|
|
299
|
+
* and a component that set one spelling and read another got `null` on the server and `'1'` in the
|
|
300
|
+
* browser — a lifecycle divergence with no symptom until the two renders disagreed. Worse, an
|
|
301
|
+
* attribute handed in as `{ 'User-ID': … }` never matched an `observedAttributes` entry, so
|
|
302
|
+
* `attributeChangedCallback` simply did not fire.
|
|
303
|
+
*/
|
|
304
|
+
_name(name: any): string;
|
|
305
|
+
/**
|
|
306
|
+
* **`mode: 'closed'` means `element.shadowRoot` is `null`** — that is the entire difference between
|
|
307
|
+
* the two modes, and it was not honoured: a closed root was handed straight back, so a component
|
|
308
|
+
* guarding on `this.shadowRoot` took the branch the browser will not, and anything holding the
|
|
309
|
+
* element could reach inside a root the platform hides. The root is kept on `_shadowRoot`, because
|
|
310
|
+
* it still has to be serialized — declarative shadow DOM expresses `closed` perfectly well
|
|
311
|
+
* (`<template shadowrootmode="closed">`) and the client's parser re-creates it just as hidden.
|
|
312
|
+
*/
|
|
313
|
+
get shadowRoot(): ShadowRootShim | null;
|
|
314
|
+
/**
|
|
315
|
+
* Both refusals are the platform's. `mode` is a required member, and an element that already has
|
|
316
|
+
* a root raises `NotSupportedError` rather than getting a second one — which matters here because
|
|
317
|
+
* silently replacing the first root discards everything rendered into it, on the server only.
|
|
318
|
+
* `@verajs/core` already guards against calling this twice *because* the browser throws; the shim
|
|
319
|
+
* accepting it meant the server was the one place that guard was not being checked.
|
|
320
|
+
*/
|
|
321
|
+
attachShadow(init?: {}): ShadowRootShim;
|
|
322
|
+
getAttribute(name: any): any;
|
|
323
|
+
setAttribute(name: any, value: any): void;
|
|
324
|
+
hasAttribute(name: any): boolean;
|
|
325
|
+
/**
|
|
326
|
+
* `force` decides, and when the attribute is already in the wanted state **nothing happens** —
|
|
327
|
+
* no write, no callback. This used to reset the value to `''` on `toggleAttribute(name, true)`
|
|
328
|
+
* for an attribute that was already there, which silently erased it.
|
|
329
|
+
*/
|
|
330
|
+
toggleAttribute(name: any, force: any): any;
|
|
331
|
+
/**
|
|
332
|
+
* Upgrade, the way the parser does it: `attributeChangedCallback` fires once per **present**
|
|
333
|
+
* observed attribute, before `connectedCallback`, with a `null` old value.
|
|
334
|
+
*
|
|
335
|
+
* It never fired at all on the server. `attributeChangedCallback` is the only reactive-attribute
|
|
336
|
+
* mechanism a plain custom element has, so a component that derives its state there rendered
|
|
337
|
+
* its *initial* state into the page and then corrected itself on the client — a hydration
|
|
338
|
+
* mismatch on every such component, and a flash of the wrong content for anyone without JS.
|
|
339
|
+
*/
|
|
340
|
+
upgrade(): void;
|
|
341
|
+
_observed: string[] | undefined;
|
|
342
|
+
_upgraded: boolean | undefined;
|
|
343
|
+
/**
|
|
344
|
+
* And it keeps firing afterwards, because a browser does: a component that changes its own
|
|
345
|
+
* attribute during a render sees the callback on the client and must see it here.
|
|
346
|
+
*
|
|
347
|
+
* Guarded on `_upgraded` first, which is the common case for the renderer's attribute writes —
|
|
348
|
+
* an element mid-upgrade has no observers yet, and one that observes nothing never reaches the
|
|
349
|
+
* `includes`.
|
|
350
|
+
*/
|
|
351
|
+
_attributeChanged(name: any, previous: any): void;
|
|
352
|
+
/** Enough of a `NamedNodeMap` to iterate, which is what component code does with it. */
|
|
353
|
+
/**
|
|
354
|
+
* An array rather than a live `NamedNodeMap` — already a recorded difference, since there is
|
|
355
|
+
* nothing to be live over in a single render pass. **The map's own methods are on it**, though:
|
|
356
|
+
* `attributes.getNamedItem('x')` is how a good deal of existing code reads an attribute, and it
|
|
357
|
+
* was simply missing, so that code got a `TypeError` on the server and worked in a browser.
|
|
358
|
+
*/
|
|
359
|
+
get attributes(): any;
|
|
360
|
+
getAttributeNames(): any[];
|
|
361
|
+
/**
|
|
362
|
+
* `this.dataset.x = 'y'` and `this.style.color = 'red'` both change the markup, so both write
|
|
363
|
+
* through to the attribute they are a view of. A plain object would accept the assignment and
|
|
364
|
+
* lose it.
|
|
365
|
+
*/
|
|
366
|
+
get dataset(): {};
|
|
367
|
+
get style(): {};
|
|
368
|
+
removeAttribute(name: any): void;
|
|
369
|
+
/**
|
|
370
|
+
* The rest of the surface an ordinary custom element reaches for.
|
|
371
|
+
*
|
|
372
|
+
* The shim was built as "the smallest DOM core's server path touches", which is the wrong bar:
|
|
373
|
+
* the code that runs here is *user* code, and a component that emits an event, reads its
|
|
374
|
+
* `tagName`, or adds a class in `connectedCallback` is doing nothing unusual. Each of these threw
|
|
375
|
+
* a `TypeError` that took the whole render down — measured: `dispatchEvent`, `ownerDocument`,
|
|
376
|
+
* `tagName`, `children`, `classList`, `closest` and `getRootNode`, all of them.
|
|
377
|
+
*
|
|
378
|
+
* They answer the way a detached, childless element would, because that is what this is.
|
|
379
|
+
*/
|
|
380
|
+
get tagName(): string;
|
|
381
|
+
get nodeType(): number;
|
|
382
|
+
get nodeName(): string;
|
|
383
|
+
/** Walks the real parent chain, which exists now that children are nodes. */
|
|
384
|
+
closest(selector: any): any;
|
|
385
|
+
matches(selector: any): any;
|
|
386
|
+
/**
|
|
387
|
+
* **A no-op until nodes were retained** — an appended child had been flattened into its parent's
|
|
388
|
+
* markup, so there was no parent to ask and nothing to take out. It silently left the element on
|
|
389
|
+
* the page.
|
|
390
|
+
*/
|
|
391
|
+
remove(): void;
|
|
392
|
+
/** `[PutForwards=value]`, for the same reason as `part`. */
|
|
393
|
+
set classList(value: {
|
|
394
|
+
add: (...names: any[]) => void;
|
|
395
|
+
remove: (...names: any[]) => void;
|
|
396
|
+
toggle: (name: any, force: any) => any;
|
|
397
|
+
replace: (oldToken: any, newToken: any) => boolean;
|
|
398
|
+
contains: (name: any) => any;
|
|
399
|
+
supports: () => never;
|
|
400
|
+
item: (index: any) => any;
|
|
401
|
+
forEach: (callback: any, thisArg: any) => any;
|
|
402
|
+
keys: () => any;
|
|
403
|
+
values: () => any;
|
|
404
|
+
entries: () => any;
|
|
405
|
+
toString: () => any;
|
|
406
|
+
value: any;
|
|
407
|
+
readonly length: any;
|
|
408
|
+
[Symbol.iterator]: () => any;
|
|
409
|
+
});
|
|
410
|
+
/**
|
|
411
|
+
* Backed by the `class` attribute, so a class added during `connectedCallback` reaches the
|
|
412
|
+
* markup — which it now can, because the opening tag is written from these attributes rather
|
|
413
|
+
* than copied from the source text.
|
|
414
|
+
*/
|
|
415
|
+
get classList(): {
|
|
416
|
+
add: (...names: any[]) => void;
|
|
417
|
+
remove: (...names: any[]) => void;
|
|
418
|
+
toggle: (name: any, force: any) => any;
|
|
419
|
+
replace: (oldToken: any, newToken: any) => boolean;
|
|
420
|
+
contains: (name: any) => any;
|
|
421
|
+
supports: () => never;
|
|
422
|
+
item: (index: any) => any;
|
|
423
|
+
forEach: (callback: any, thisArg: any) => any;
|
|
424
|
+
keys: () => any;
|
|
425
|
+
values: () => any;
|
|
426
|
+
entries: () => any;
|
|
427
|
+
toString: () => any;
|
|
428
|
+
value: any;
|
|
429
|
+
readonly length: any;
|
|
430
|
+
[Symbol.iterator]: () => any;
|
|
431
|
+
};
|
|
432
|
+
/**
|
|
433
|
+
* What a **detached, childless** element answers.
|
|
434
|
+
*
|
|
435
|
+
* Every one of these is the truthful answer for this element, not a placeholder: an element with
|
|
436
|
+
* no parent has no siblings and no parent, an element outside a document has no box, and a
|
|
437
|
+
* childless one contains nothing. A browser returns exactly these values for a detached element.
|
|
438
|
+
* They are here because their *absence* was a `TypeError` that took the whole render down —
|
|
439
|
+
* `this.parentElement && …` is ordinary defensive code and it crashed.
|
|
440
|
+
*/
|
|
441
|
+
/** No layout on a server, and none for a detached element in a browser either. */
|
|
442
|
+
getBoundingClientRect(): {
|
|
443
|
+
x: number;
|
|
444
|
+
y: number;
|
|
445
|
+
top: number;
|
|
446
|
+
left: number;
|
|
447
|
+
right: number;
|
|
448
|
+
bottom: number;
|
|
449
|
+
width: number;
|
|
450
|
+
height: number;
|
|
451
|
+
toJSON: () => {};
|
|
452
|
+
};
|
|
453
|
+
getClientRects(): never[];
|
|
454
|
+
checkVisibility(): boolean;
|
|
455
|
+
/**
|
|
456
|
+
* **The collection queries answer from the tree.** Each returned an empty array whatever the tree
|
|
457
|
+
* held — the same placeholder shape `querySelector` had, and just as silent. They are live
|
|
458
|
+
* `HTMLCollection`s in a browser and plain arrays here, a deliberate difference recorded in the
|
|
459
|
+
* README: there is nothing to be live *over* while a render is a single pass. (That comment said
|
|
460
|
+
* "already recorded" while the README said nothing about it — the difference is written down now,
|
|
461
|
+
* along with the `item()`/`namedItem()` half of it that was a side effect rather than a decision.)
|
|
462
|
+
*/
|
|
463
|
+
getElementsByTagName(name: any): any[];
|
|
464
|
+
getElementsByTagNameNS(namespace: any, name: any): any[];
|
|
465
|
+
getElementsByClassName(names: any): any[];
|
|
466
|
+
/**
|
|
467
|
+
* Namespaces collapse to the plain attribute methods. This DOM serializes HTML, where an
|
|
468
|
+
* `xml:lang` or `xlink:href` is one attribute with a colon in its name — which is how the
|
|
469
|
+
* serializer already treats it, and how the markup reads it back.
|
|
470
|
+
*/
|
|
471
|
+
getAttributeNS(_namespace: any, name: any): any;
|
|
472
|
+
setAttributeNS(_namespace: any, name: any, value: any): void;
|
|
473
|
+
hasAttributeNS(_namespace: any, name: any): boolean;
|
|
474
|
+
removeAttributeNS(_namespace: any, name: any): void;
|
|
475
|
+
hasAttributes(): boolean;
|
|
476
|
+
getAttributeNode(name: any): {
|
|
477
|
+
name: any;
|
|
478
|
+
value: any;
|
|
479
|
+
} | null;
|
|
480
|
+
getAttributeNodeNS(_namespace: any, name: any): {
|
|
481
|
+
name: any;
|
|
482
|
+
value: any;
|
|
483
|
+
} | null;
|
|
484
|
+
setAttributeNode(node: any): null;
|
|
485
|
+
setAttributeNodeNS(node: any): null;
|
|
486
|
+
removeAttributeNode(node: any): any;
|
|
487
|
+
/** Aliases the engines still carry. */
|
|
488
|
+
webkitMatchesSelector(): boolean;
|
|
489
|
+
mozMatchesSelector(): boolean;
|
|
490
|
+
/**
|
|
491
|
+
* Interaction, which a server has none of — but the calls are ordinary and must not throw.
|
|
492
|
+
*
|
|
493
|
+
* `click()` is the exception: it *dispatches an event*, and now that listeners are real, a
|
|
494
|
+
* component that clicks itself to seed its own state gets the same result on both sides.
|
|
495
|
+
*/
|
|
496
|
+
focus(): void;
|
|
497
|
+
blur(): void;
|
|
498
|
+
click(): void;
|
|
499
|
+
scrollIntoView(): void;
|
|
500
|
+
scroll(): void;
|
|
501
|
+
scrollTo(): void;
|
|
502
|
+
scrollBy(): void;
|
|
503
|
+
/**
|
|
504
|
+
* All four positions. `beforebegin`/`afterend` used to be refused outright on the claim that
|
|
505
|
+
* this element has no parent — true for a component root, and FALSE for everything inside one:
|
|
506
|
+
* `_parent` is live for any nested element (the `outerHTML` setter below runs on it), so a
|
|
507
|
+
* component doing `this.querySelector(…).insertAdjacentHTML('afterend', …)` worked in the
|
|
508
|
+
* browser and took the whole server render down. The two positions now splice into the parent's
|
|
509
|
+
* entries exactly as `outerHTML=` does, and only a genuine orphan refuses — with the platform's
|
|
510
|
+
* own answer, `NoModificationAllowedError`, measured on jsdom and Chromium (the spec raises it
|
|
511
|
+
* for a null or Document parent; a bare `Error` here was a second divergence inside the first).
|
|
512
|
+
*
|
|
513
|
+
* **A markup sink, deliberately** (CODE-PRINCIPLES #8). It writes what it is given, exactly as
|
|
514
|
+
* the DOM's own `insertAdjacentHTML` does, because a component calling it has already decided
|
|
515
|
+
* that: the same call on the client is the same sink, and a server that escaped where the browser
|
|
516
|
+
* does not would render one page and hydrate into another. `insertAdjacentText` escapes, which is
|
|
517
|
+
* the difference between the two methods and the one to reach for with anything from a request.
|
|
518
|
+
*/
|
|
519
|
+
insertAdjacentHTML(position: any, markup: any): void;
|
|
520
|
+
insertAdjacentText(position: any, text: any): void;
|
|
521
|
+
insertAdjacentElement(position: any, element: any): any;
|
|
522
|
+
/**
|
|
523
|
+
* **Replaces this element in its parent with the given markup.** Assigning it used to be a
|
|
524
|
+
* `TypeError` — there was no setter — so `element.outerHTML = '<p>x</p>'`, an ordinary way to swap
|
|
525
|
+
* a node out, did nothing on the server and worked in the browser.
|
|
526
|
+
*
|
|
527
|
+
* **With no parent it returns silently**, which is what the spec says and what all three engines
|
|
528
|
+
* do — measured, because the obvious guess was a `NoModificationAllowedError` and that is wrong:
|
|
529
|
+
* the spec raises it only when the parent is a *Document*, not when there is no parent at all.
|
|
530
|
+
*/
|
|
531
|
+
set outerHTML(markup: any);
|
|
532
|
+
/** The element's own markup, which the serializer builds anyway. */
|
|
533
|
+
get outerHTML(): any;
|
|
534
|
+
/**
|
|
535
|
+
* **A line break becomes a `<br>`, which is the whole difference from `textContent`.** Every
|
|
536
|
+
* engine splits the assigned string on `\r\n`, `\r` and `\n` and joins the escaped pieces with
|
|
537
|
+
* `<br>`; assigning through `textContent` instead left a literal newline, which collapses to a
|
|
538
|
+
* single space when the page is laid out. So a component that set `innerText` rendered its lines
|
|
539
|
+
* run together on the server and correctly broken on the client — a visible difference in the
|
|
540
|
+
* markup itself, not merely in what a property reads back.
|
|
541
|
+
*
|
|
542
|
+
* Measured on Chromium, Firefox and WebKit, attached and detached, in
|
|
543
|
+
* `tests/browser/inner-text.test.js`.
|
|
544
|
+
*/
|
|
545
|
+
set innerText(value: string);
|
|
546
|
+
get innerText(): string;
|
|
547
|
+
/**
|
|
548
|
+
* **Assignable, because the IDL says `[PutForwards=value]`.** Both `part` and `classList` are
|
|
549
|
+
* declared that way, so `element.part = 'a b'` is a legal operation in every engine and writes
|
|
550
|
+
* the attribute. A getter with no setter made it a `TypeError` here instead — a server that
|
|
551
|
+
* refuses what the browser performs, which is the same failure as being too permissive with the
|
|
552
|
+
* direction reversed.
|
|
553
|
+
*/
|
|
554
|
+
set part(value: {
|
|
555
|
+
add: (...names: any[]) => void;
|
|
556
|
+
remove: (...names: any[]) => void;
|
|
557
|
+
toggle: (name: any, force: any) => any;
|
|
558
|
+
replace: (oldToken: any, newToken: any) => boolean;
|
|
559
|
+
contains: (name: any) => any;
|
|
560
|
+
supports: () => never;
|
|
561
|
+
item: (index: any) => any;
|
|
562
|
+
forEach: (callback: any, thisArg: any) => any;
|
|
563
|
+
keys: () => any;
|
|
564
|
+
values: () => any;
|
|
565
|
+
entries: () => any;
|
|
566
|
+
toString: () => any;
|
|
567
|
+
value: any;
|
|
568
|
+
readonly length: any;
|
|
569
|
+
[Symbol.iterator]: () => any;
|
|
570
|
+
});
|
|
571
|
+
/** `part` is a token list over the `part` attribute, exactly as `classList` is over `class`. */
|
|
572
|
+
get part(): {
|
|
573
|
+
add: (...names: any[]) => void;
|
|
574
|
+
remove: (...names: any[]) => void;
|
|
575
|
+
toggle: (name: any, force: any) => any;
|
|
576
|
+
replace: (oldToken: any, newToken: any) => boolean;
|
|
577
|
+
contains: (name: any) => any;
|
|
578
|
+
supports: () => never;
|
|
579
|
+
item: (index: any) => any;
|
|
580
|
+
forEach: (callback: any, thisArg: any) => any;
|
|
581
|
+
keys: () => any;
|
|
582
|
+
values: () => any;
|
|
583
|
+
entries: () => any;
|
|
584
|
+
toString: () => any;
|
|
585
|
+
value: any;
|
|
586
|
+
readonly length: any;
|
|
587
|
+
[Symbol.iterator]: () => any;
|
|
588
|
+
};
|
|
589
|
+
/**
|
|
590
|
+
* Form-associated custom elements.
|
|
591
|
+
*
|
|
592
|
+
* `attachInternals()` not existing meant `static formAssociated = true` — the standard way to
|
|
593
|
+
* write a custom form control — threw during `connectedCallback` and took the page with it. None
|
|
594
|
+
* of what internals carry reaches markup (form value, validity and implicit ARIA are all
|
|
595
|
+
* internal state), so this is inert by design rather than by omission: the component runs, and
|
|
596
|
+
* the client's real internals take over on hydration.
|
|
597
|
+
*/
|
|
598
|
+
attachInternals(): any;
|
|
599
|
+
/**
|
|
600
|
+
* The element's own opening tag, written from the attributes it holds **now**.
|
|
601
|
+
*
|
|
602
|
+
* Copying the source text instead meant everything a component did to itself during
|
|
603
|
+
* `connectedCallback` was thrown away: `setAttribute('role', 'button')`, a class, an `aria-*` —
|
|
604
|
+
* present on the client after hydration, absent in the server markup, so the two disagreed on
|
|
605
|
+
* every one.
|
|
606
|
+
*/
|
|
607
|
+
/**
|
|
608
|
+
* **A copy that shares nothing.** The reason this was out of scope was that a copy sharing the
|
|
609
|
+
* markup string would alias it; entries are an array now, so a deep clone copies them. The source
|
|
610
|
+
* text rides along, so a cloned subtree still reproduces the markup it was parsed from.
|
|
611
|
+
*/
|
|
612
|
+
cloneNode(deep?: boolean): any;
|
|
613
|
+
/** This element's own markup, end tag included — the call every node kind answers. */
|
|
614
|
+
/**
|
|
615
|
+
* A `<slot>` shows the host's children that name it; see `assignedTo`.
|
|
616
|
+
*
|
|
617
|
+
* **Getters returning `undefined` off a slot**, because these live on `HTMLSlotElement` and this
|
|
618
|
+
* DOM has one element class. Defining them as plain methods put them on every element, where
|
|
619
|
+
* `typeof element.assignedNodes === 'function'` — the ordinary way to ask "is this a slot" —
|
|
620
|
+
* answered yes for a `<div>`. Being present where the platform has nothing is the same kind of
|
|
621
|
+
* divergence as answering wrongly, and it is the one a feature check walks straight into.
|
|
622
|
+
*/
|
|
623
|
+
get assignedNodes(): ((options: any) => any) | undefined;
|
|
624
|
+
get assignedElements(): ((options: any) => any) | undefined;
|
|
625
|
+
markup(): any;
|
|
626
|
+
openTag(): string;
|
|
627
|
+
/**
|
|
628
|
+
* Escaped for an ordinary element, stored as-is for a raw-text one.
|
|
629
|
+
*
|
|
630
|
+
* `@verajs/styles` sets a `<style>` element's `textContent` to the stylesheet, and escaping it
|
|
631
|
+
* turned every `>` into `>` and every `"` into `"`. A browser does not decode those inside
|
|
632
|
+
* `<style>`, so a component with `static styles = '.a > .b { … }'` shipped a broken stylesheet —
|
|
633
|
+
* every child selector, every attribute selector, every `content: "…"`. The client never had it:
|
|
634
|
+
* there, `textContent` sets real text and the serializer of a raw-text element emits it verbatim.
|
|
635
|
+
*/
|
|
636
|
+
/**
|
|
637
|
+
* **`null` and `undefined` are the empty string, not their own names.** `textContent` is a
|
|
638
|
+
* nullable `DOMString` with `[LegacyNullToEmptyString]`, and WebIDL converts `undefined` to `null`
|
|
639
|
+
* for a nullable type — so both erase the content in every engine. This wrote the text `null`,
|
|
640
|
+
* which meant `this.textContent = maybeMissing` put the word on the page server-side and nothing
|
|
641
|
+
* client-side: a hydration mismatch produced by ordinary defensive code.
|
|
642
|
+
*/
|
|
643
|
+
set textContent(value: string);
|
|
644
|
+
/**
|
|
645
|
+
* Tags stripped and the escaping undone, so what goes in comes back out.
|
|
646
|
+
*
|
|
647
|
+
* Reading back what `textContent` had just written returned `<b>` for `<b>` — the setter
|
|
648
|
+
* escapes and the getter did not decode, so the round trip a component may reasonably rely on was
|
|
649
|
+
* broken. Only the numeric references the setter emits need undoing; anything else in there came
|
|
650
|
+
* from author markup and is text as written.
|
|
651
|
+
*/
|
|
652
|
+
get textContent(): string;
|
|
653
|
+
}
|
|
654
|
+
export function createElement(localName: any, namespaceURI?: string): any;
|
|
655
|
+
/**
|
|
656
|
+
* Instances handed to `appendChild` before they have rendered, so the scan renders **them** rather
|
|
657
|
+
* than a fresh copy built from their markup.
|
|
658
|
+
*
|
|
659
|
+
* The nested-component scan reads emitted markup and instantiates what it finds, which is right for
|
|
660
|
+
* a tag written in a template and wrong for an element the component built itself: everything
|
|
661
|
+
* assigned to it — `kid.rows = data`, the ordinary way to hand structured data to a child — was
|
|
662
|
+
* lost, because an attribute cannot carry it and a fresh instance never saw it. The marker attribute
|
|
663
|
+
* is the handle, and `renderComponent` removes it as it renders.
|
|
664
|
+
*/
|
|
665
|
+
export const pendingInstances: Map<any, any>;
|
|
666
|
+
/**
|
|
667
|
+
* The marker's **name** carries a per-process random token, because the markup it is written into is
|
|
668
|
+
* not all ours.
|
|
669
|
+
*
|
|
670
|
+
* `children` and the string form of `attributes` are raw markup by design, so a caller passing
|
|
671
|
+
* request data through either hands an attacker a way to write attributes into this document. With a
|
|
672
|
+
* fixed name, injected markup could claim a component's prepared instance — and win, because it is
|
|
673
|
+
* already in the markup when the real one is appended, and the scan reads in order. Demonstrated: an
|
|
674
|
+
* injected `<x-y vera-ssr-instance="1">` rendered with the parent's data while the parent's own
|
|
675
|
+
* child fell back to defaults. A name nothing outside this module can guess closes it, and
|
|
676
|
+
* `renderComponent` also refuses a marker whose instance is not the tag being rendered.
|
|
677
|
+
*
|
|
678
|
+
* Import-time rather than per-render: an attacker cannot read either, and the output never contains
|
|
679
|
+
* the marker, so nothing observable depends on it.
|
|
680
|
+
*/
|
|
681
|
+
export const INSTANCE_ATTRIBUTE: string;
|
|
682
|
+
/**
|
|
683
|
+
* **Text and comments are nodes.**
|
|
684
|
+
*
|
|
685
|
+
* They were not: `createTextNode` returned an object literal with an `innerHTML` string, so it had
|
|
686
|
+
* no identity, no parent and no `nodeType`, and appending one inlined its markup and lost the node.
|
|
687
|
+
* `childNodes` therefore reported `1` for `text <b>bold</b> tail`, where every browser says `3`.
|
|
688
|
+
*
|
|
689
|
+
* Like an element, a parsed one keeps **the exact bytes it came from** so re-serialising reproduces
|
|
690
|
+
* the input — `&` stays `&` rather than becoming this package's `&` — and falls back to
|
|
691
|
+
* escaping its data the moment somebody writes to it.
|
|
692
|
+
*/
|
|
693
|
+
declare class CharacterDataShim extends EventTarget {
|
|
694
|
+
constructor(data: any);
|
|
695
|
+
_data: string;
|
|
696
|
+
_source: string | null;
|
|
697
|
+
_parent: any;
|
|
698
|
+
isConnected: boolean;
|
|
699
|
+
/**
|
|
700
|
+
* Registered here rather than on the platform's `EventTarget`; see `events.js`.
|
|
701
|
+
* @override
|
|
702
|
+
*/
|
|
703
|
+
override addEventListener(type: any, callback: any, options: any): void;
|
|
704
|
+
/** @override */
|
|
705
|
+
override removeEventListener(type: any, callback: any, options: any): void;
|
|
706
|
+
/** @override */
|
|
707
|
+
override dispatchEvent(event: any): boolean;
|
|
708
|
+
set data(value: string);
|
|
709
|
+
get data(): string;
|
|
710
|
+
set nodeValue(value: string);
|
|
711
|
+
get nodeValue(): string;
|
|
712
|
+
set textContent(value: string);
|
|
713
|
+
get textContent(): string;
|
|
714
|
+
get length(): number;
|
|
715
|
+
get parentNode(): any;
|
|
716
|
+
get parentElement(): any;
|
|
717
|
+
get childNodes(): never[];
|
|
718
|
+
get firstChild(): null;
|
|
719
|
+
get lastChild(): null;
|
|
720
|
+
hasChildNodes(): boolean;
|
|
721
|
+
get ownerDocument(): Document;
|
|
722
|
+
get nextSibling(): any;
|
|
723
|
+
get previousSibling(): any;
|
|
724
|
+
/** @param {number} step @param {(container: any) => Array<any>} view */
|
|
725
|
+
_siblingAt(step: number, view?: (container: any) => Array<any>): any;
|
|
726
|
+
remove(): void;
|
|
727
|
+
before(...nodes: any[]): void;
|
|
728
|
+
after(...nodes: any[]): void;
|
|
729
|
+
replaceWith(...nodes: any[]): void;
|
|
730
|
+
isSameNode(node: any): boolean;
|
|
731
|
+
isEqualNode(node: any): boolean;
|
|
732
|
+
contains(node: any): boolean;
|
|
733
|
+
getRootNode(): any;
|
|
734
|
+
appendData(value: any): void;
|
|
735
|
+
substringData(offset: any, count: any): string;
|
|
736
|
+
}
|
|
737
|
+
import { StyleSheetShim } from './stylesheets.js';
|
|
738
|
+
export {};
|