@verajs/renderer 0.1.3 → 0.1.5
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 +42 -2
- package/dist/development/vera-renderer-hydrate.js +89 -6
- package/dist/development/vera-renderer-hydrate.js.map +1 -1
- package/dist/development/vera-renderer-profiler.js +87 -6
- package/dist/development/vera-renderer-profiler.js.map +1 -1
- package/dist/development/vera-renderer.js +87 -6
- package/dist/development/vera-renderer.js.map +1 -1
- package/dist/vera-renderer-hydrate.min.js +1 -1
- package/dist/vera-renderer-hydrate.min.js.map +1 -1
- package/dist/vera-renderer.min.js +1 -1
- package/dist/vera-renderer.min.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,14 +1,54 @@
|
|
|
1
1
|
# @verajs/renderer
|
|
2
2
|
|
|
3
|
-
A keyed, template-identity renderer (<!--size:renderer.gzip-->3.
|
|
3
|
+
A keyed, template-identity renderer (<!--size:renderer.gzip-->3.55 KB<!--/size:renderer.gzip--> gzip): tagged templates, `.prop`/`?bool`/`@event`
|
|
4
4
|
and React-style `onClick` bindings, element refs, `keyed()` lists, `hold()` DOM preservation.
|
|
5
5
|
`@verajs/renderer/hydrate` is a drop-in superset whose first render ADOPTS server-rendered DOM —
|
|
6
6
|
markerless hydration (no framework comments in server HTML). SSR apps import from `/hydrate`;
|
|
7
7
|
everyone else pays zero hydration bytes.
|
|
8
8
|
|
|
9
|
+
## Escaping, and the deliberate absence of `unsafeHTML`
|
|
10
|
+
|
|
11
|
+
Every interpolated value is escaped at the render boundary. There is no `unsafeHTML` and there will
|
|
12
|
+
not be one: shipping a sanctioned opt-out puts an XSS sink in the public API, where it reads as
|
|
13
|
+
blessed in tutorials and in review.
|
|
14
|
+
|
|
15
|
+
Trusted markup goes through an element ref, so you write the sink yourself:
|
|
16
|
+
|
|
17
|
+
```js
|
|
18
|
+
render(html`<div ${(el) => (el.innerHTML = trustedMarkup)}></div>`, host);
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Greppable, obviously yours, reviewable as the security decision it is. Sanitize first
|
|
22
|
+
(`DOMPurify.sanitize`) unless the markup is genuinely your own, and put it on an element whose
|
|
23
|
+
children nothing else binds — the renderer owns the content of elements it renders into.
|
|
24
|
+
|
|
9
25
|
`@verajs/renderer/profiler` is a development-only entry that reports how many templates were
|
|
10
26
|
committed in place versus torn down and rebuilt, naming the template pairs that churn and where.
|
|
11
27
|
`showProfiler()` puts the same information in a live panel in the corner of the page. It costs
|
|
12
28
|
production nothing — the instrumentation is removed by the build, not merely unused.
|
|
13
29
|
|
|
14
|
-
Wire once
|
|
30
|
+
Wire once, at your app entry, before any component defines itself:
|
|
31
|
+
|
|
32
|
+
<!-- recipe -->
|
|
33
|
+
```js
|
|
34
|
+
import { init, createStore, render, setRenderer, html } from '@verajs/core';
|
|
35
|
+
import { render as domRender } from '@verajs/renderer';
|
|
36
|
+
|
|
37
|
+
setRenderer(domRender);
|
|
38
|
+
|
|
39
|
+
customElements.define(
|
|
40
|
+
'click-counter',
|
|
41
|
+
class extends HTMLElement {
|
|
42
|
+
connectedCallback() {
|
|
43
|
+
init(this, { mode: 'open' });
|
|
44
|
+
const state = createStore({ count: 0 });
|
|
45
|
+
render(() => html`<button @click=${() => state.count++}>Clicked ${state.count} times</button>`);
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
);
|
|
49
|
+
|
|
50
|
+
document.body.append(document.createElement('click-counter'));
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Without `setRenderer`, core has no renderer at all: `render()` warns once in development and puts
|
|
54
|
+
nothing on the page. `@event`, `.prop` and `?bool` bindings are the first things to go missing.
|
|
@@ -429,8 +429,16 @@ class AttrPart {
|
|
|
429
429
|
const first = name[0];
|
|
430
430
|
let kind = first === '.' ? PROPERTY : first === '?' ? BOOLEAN : first === '@' ? EVENT : first === '&' ? REF : ATTR;
|
|
431
431
|
let realName = kind ? name.slice(1) : name;
|
|
432
|
-
/**
|
|
433
|
-
*
|
|
432
|
+
/**
|
|
433
|
+
* React muscle-memory, buildless: `onClick=${fn}` ≡ `@click=${fn}`. Strictly `on` + a capital —
|
|
434
|
+
* all-lowercase `onclick` stays a plain attribute (legal inline-handler HTML).
|
|
435
|
+
*
|
|
436
|
+
* `@verajs/spread` repeats these rules rather than importing them. Sharing them through
|
|
437
|
+
* `@verajs/shared-utils` was tried and reverted: the shared form has to return both the kind and
|
|
438
|
+
* the name, and the tuple it allocates cost this bundle 10 B. Principle #5 allows deliberate
|
|
439
|
+
* duplication where two things can legitimately diverge; here #7 decides it — weight is the
|
|
440
|
+
* product, and core and the renderer are the two packages where that is absolute.
|
|
441
|
+
*/
|
|
434
442
|
if (kind === ATTR && first === 'o' && name.charCodeAt(1) === 110 && name.charCodeAt(2) > 64 && name.charCodeAt(2) < 91) {
|
|
435
443
|
kind = EVENT;
|
|
436
444
|
realName = name.slice(2).toLowerCase();
|
|
@@ -473,7 +481,54 @@ class AttrPart {
|
|
|
473
481
|
this._element.setAttribute(this._name, value);
|
|
474
482
|
}
|
|
475
483
|
else if (kind === PROPERTY) {
|
|
476
|
-
this._element
|
|
484
|
+
const target = this._element;
|
|
485
|
+
const name = this._name;
|
|
486
|
+
target[name] = value;
|
|
487
|
+
/**
|
|
488
|
+
* Detection only, and deliberately not repair.
|
|
489
|
+
*
|
|
490
|
+
* A property set on a custom element that has not upgraded yet lands as an own property on
|
|
491
|
+
* the instance. When the definition arrives — lazily imported, code-split, or a module that
|
|
492
|
+
* simply had not run — `customElements.define` upgrades synchronously and the class's field
|
|
493
|
+
* initializers execute. At target ES2022 a field declaration is a `[[Define]]`, so
|
|
494
|
+
* `item?: T` emits `item;` and overwrites the bound value with `undefined`. Nothing throws;
|
|
495
|
+
* it reads as broken reactivity.
|
|
496
|
+
*
|
|
497
|
+
* Repairing it was tried and removed. Re-applying when the slot came back `undefined`
|
|
498
|
+
* covered `item?: T` but not `item = someDefault`, which overwrites with the default and
|
|
499
|
+
* never looks clobbered — so the repair was silently partial, and made the bug intermittent
|
|
500
|
+
* across two spellings of the same mistake. It also cost 74 B in every app while leaving
|
|
501
|
+
* `declare` mandatory anyway, because a property assigned imperatively is unrecoverable:
|
|
502
|
+
* the renderer never saw it, and by the time `init()` runs the value is already gone.
|
|
503
|
+
*
|
|
504
|
+
* So this is `true`-only and production pays nothing — no check, no message, no
|
|
505
|
+
* `whenDefined` subscription. Lit reached the same place from the other direction and
|
|
506
|
+
* throws (`lit.dev/msg/class-field-shadowing`); a warning suffices here because Vera has no
|
|
507
|
+
* prototype accessors to shadow permanently — the damage is one lost value, not a property
|
|
508
|
+
* that never updates again.
|
|
509
|
+
*/
|
|
510
|
+
if (true) {
|
|
511
|
+
const tag = this._element.localName;
|
|
512
|
+
if (tag.indexOf('-') > 0 && !customElements.get(tag)) {
|
|
513
|
+
customElements.whenDefined(tag).then(() => {
|
|
514
|
+
/**
|
|
515
|
+
* States what was observed rather than diagnosing it. A class field is the usual
|
|
516
|
+
* cause by a wide margin, but a component that assigns the property itself during
|
|
517
|
+
* upgrade produces the same observation, and that is a legitimate — if confusing —
|
|
518
|
+
* thing to do, since the renderer's dirty check will not re-apply the bound value on
|
|
519
|
+
* the next render either.
|
|
520
|
+
*/
|
|
521
|
+
if (target[name] !== value)
|
|
522
|
+
console.warn(`@verajs/renderer: the value bound by \`.${name}=\${…}\` on <${tag}> was replaced ` +
|
|
523
|
+
`while the element upgraded. A class field is the usual cause: at ES2022 ` +
|
|
524
|
+
`\`${name}?: …\` emits \`${name};\`, which runs during upgrade and overwrites ` +
|
|
525
|
+
`whatever was set beforehand — write it \`declare ${name}?: …\` instead, which ` +
|
|
526
|
+
`emits nothing. A plain field also wipes properties assigned imperatively, ` +
|
|
527
|
+
`which cannot be detected at all. Ignore this if the component replaced the ` +
|
|
528
|
+
`value on purpose.`);
|
|
529
|
+
});
|
|
530
|
+
}
|
|
531
|
+
}
|
|
477
532
|
}
|
|
478
533
|
else if (kind === BOOLEAN) {
|
|
479
534
|
if (!isFirst || value)
|
|
@@ -492,8 +547,23 @@ class AttrPart {
|
|
|
492
547
|
*/
|
|
493
548
|
if (typeof value === 'function')
|
|
494
549
|
value(this._element);
|
|
495
|
-
else if (typeof value === 'object')
|
|
496
|
-
|
|
550
|
+
else if (typeof value === 'object') {
|
|
551
|
+
/**
|
|
552
|
+
* A self-applying value: anything that knows what to do with an element applies itself.
|
|
553
|
+
* `@verajs/renderer/spread` is the first, and the whole protocol is this one property
|
|
554
|
+
* read — the implementation lives in that entry, so an app that never spreads pays for
|
|
555
|
+
* the check and nothing else. `_$…$` is exempt from property mangling, like `_$litType$`.
|
|
556
|
+
*
|
|
557
|
+
* Deliberately confined to the element position, which is rare. A protocol in the text,
|
|
558
|
+
* attribute or property commits would sit in the hot path every benchmark measures.
|
|
559
|
+
*/
|
|
560
|
+
const self = value;
|
|
561
|
+
/** The part is passed as the ownership key: one element can carry several spreads. */
|
|
562
|
+
if (self._$apply$)
|
|
563
|
+
self._$apply$(this._element, this);
|
|
564
|
+
else
|
|
565
|
+
self.value = this._element;
|
|
566
|
+
}
|
|
497
567
|
// any other value type at element position is consumed and ignored
|
|
498
568
|
}
|
|
499
569
|
}
|
|
@@ -617,14 +687,25 @@ class ChildPart {
|
|
|
617
687
|
}
|
|
618
688
|
_clear() {
|
|
619
689
|
const parent = this._start.parentNode;
|
|
690
|
+
const end = this._end;
|
|
620
691
|
/**
|
|
621
692
|
* When this part owns its parent's entire contents, one `textContent = ''` replaces removing
|
|
622
693
|
* every node individually. For a 1 000-row table body that is the difference between ~22 ms
|
|
623
694
|
* (lit-html's per-node teardown) and ~5 ms.
|
|
695
|
+
*
|
|
696
|
+
* A part owns the whole parent when nothing precedes its start AND nothing follows its end —
|
|
697
|
+
* `_end === null` (a root part, which runs to the end by definition) or `_end` is the last
|
|
698
|
+
* child. The second case is the common one and used to miss this path entirely: every list
|
|
699
|
+
* written as `<tbody>${rows}</tbody>` sits inside a template, and since 0.1.2 a nested part
|
|
700
|
+
* always owns an end marker, so `_end === null` alone never held for it.
|
|
701
|
+
*
|
|
702
|
+
* Re-appending both anchors in order restores the part's boundary exactly as it was.
|
|
624
703
|
*/
|
|
625
|
-
if (this._start.previousSibling === null &&
|
|
704
|
+
if (this._start.previousSibling === null && (end === null || end.nextSibling === null)) {
|
|
626
705
|
parent.textContent = '';
|
|
627
706
|
parent.appendChild(this._start);
|
|
707
|
+
if (end !== null)
|
|
708
|
+
parent.appendChild(end);
|
|
628
709
|
}
|
|
629
710
|
else {
|
|
630
711
|
let node = this._start.nextSibling;
|
|
@@ -1288,6 +1369,8 @@ const tryAdopt = (result, container) => {
|
|
|
1288
1369
|
const clearPreservingStyles = (container) => {
|
|
1289
1370
|
let node = container.firstChild;
|
|
1290
1371
|
while (node !== null) {
|
|
1372
|
+
/** `nextSibling` already yields `ChildNode | null`; annotating it `Node` widened it and broke
|
|
1373
|
+
* the assignment back into `node`, which `firstChild` typed as `ChildNode | null`. */
|
|
1291
1374
|
const next = node.nextSibling;
|
|
1292
1375
|
if (!(node.nodeType === 1 && node.hasAttribute('vera-styles')))
|
|
1293
1376
|
container.removeChild(node);
|