@verajs/renderer 0.2.1 → 0.2.2
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 +18 -1
- package/dist/development/vera-renderer-hydrate.d.ts +37 -8
- package/dist/development/vera-renderer-hydrate.d.ts.map +1 -1
- package/dist/development/vera-renderer-hydrate.js +44 -0
- package/dist/development/vera-renderer-hydrate.js.map +1 -1
- package/dist/development/vera-renderer-profiler.d.ts +70 -47
- package/dist/development/vera-renderer-profiler.d.ts.map +1 -1
- package/dist/development/vera-renderer-profiler.js +44 -0
- package/dist/development/vera-renderer-profiler.js.map +1 -1
- package/dist/development/vera-renderer-spread.d.ts +14 -1
- package/dist/development/vera-renderer-spread.d.ts.map +1 -1
- package/dist/development/vera-renderer-spread.js +19 -0
- package/dist/development/vera-renderer-spread.js.map +1 -1
- package/dist/development/vera-renderer-tag.js +19 -0
- package/dist/development/vera-renderer-tag.js.map +1 -1
- package/dist/development/vera-renderer.d.ts +37 -8
- package/dist/development/vera-renderer.d.ts.map +1 -1
- package/dist/development/vera-renderer.js +44 -0
- package/dist/development/vera-renderer.js.map +1 -1
- package/dist/vera-renderer-hydrate.min.js.map +1 -1
- package/dist/vera-renderer-spread.min.js.map +1 -1
- package/dist/vera-renderer-tag.min.js.map +1 -1
- package/dist/vera-renderer.min.js.map +1 -1
- package/package.json +1 -1
|
@@ -1,25 +1,82 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* The
|
|
3
|
-
*
|
|
2
|
+
* The renderer's cross-file and public types — one `types.ts` at the import-graph root, per
|
|
3
|
+
* CODE-PRINCIPLES §1.
|
|
4
|
+
*
|
|
5
|
+
* **What is here and what deliberately is not.** Everything in this file is a pure data shape: it
|
|
6
|
+
* names no runtime value, so it can sit upstream of every module in the package and nothing here
|
|
7
|
+
* can pull a class into the import graph. The renderer's remaining cross-file types — `Item`,
|
|
8
|
+
* `ListStrategy`, `KeyedResult` — name the `Instance` and `ChildPart` CLASSES in their definitions,
|
|
9
|
+
* which puts them structurally downstream of `renderer.ts`; they stay beside those classes, and
|
|
10
|
+
* §1's "one file at the import-graph root" records that limit rather than pretending otherwise.
|
|
11
|
+
* Restating a class's shape here to satisfy the letter of the rule would create exactly the twin
|
|
12
|
+
* §1 forbids.
|
|
13
|
+
*
|
|
14
|
+
* Moving `ProfileReport` and `OverlayOptions` here dissolved a real cycle: `profiler.ts` imported
|
|
15
|
+
* `OverlayOptions` from `overlay.ts` while `overlay.ts` imported `ProfileReport` back from
|
|
16
|
+
* `profiler.ts`. Type-only, so it was erased and never a runtime cycle — but it is the shape this
|
|
17
|
+
* file's position in the graph exists to make impossible.
|
|
18
|
+
*/
|
|
19
|
+
/**
|
|
20
|
+
* What a template tag (`html`, `svg`, `mathml`) produces — the compiled shape every renderer entry
|
|
21
|
+
* point accepts, and the one type a consumer normally names.
|
|
4
22
|
*
|
|
5
|
-
*
|
|
23
|
+
* `strings` is the template literal's own `strings` array and is the TEMPLATE'S IDENTITY: the
|
|
24
|
+
* engine interns it per call site, so two literals with identical text are two templates and
|
|
25
|
+
* rendering one after the other is a teardown, not an update. Anything building these by hand must
|
|
26
|
+
* hand back the same array to get an update.
|
|
27
|
+
*/
|
|
28
|
+
type TemplateResult = {
|
|
29
|
+
/** 1 = html, 2 = svg, 3 = mathml — the markers core's built-in tags produce. */
|
|
30
|
+
_$litType$?: number;
|
|
31
|
+
strings: TemplateStringsArray;
|
|
32
|
+
values: unknown[];
|
|
33
|
+
/** Set by `keyed()`; drives keyed list reconciliation. */
|
|
34
|
+
key?: unknown;
|
|
35
|
+
};
|
|
36
|
+
/** One template identity replacing another at the same position, and how often. */
|
|
37
|
+
type Churn = {
|
|
38
|
+
/** The template that was torn down, rendered readably. */
|
|
39
|
+
from: string;
|
|
40
|
+
/** The template that replaced it. */
|
|
41
|
+
to: string;
|
|
42
|
+
/** How many times this exact swap happened while profiling. */
|
|
43
|
+
count: number;
|
|
44
|
+
/** Where in the DOM it happened, e.g. `main#app > ul.list`. First occurrence only. */
|
|
45
|
+
where: string;
|
|
46
|
+
};
|
|
47
|
+
/**
|
|
48
|
+
* What `getReport()`, `stopProfiling()` and `profile()` hand back.
|
|
6
49
|
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
* 3. **It must work with no toolchain**, like everything else here — no CSS file, no framework,
|
|
12
|
-
* one import.
|
|
50
|
+
* The number to read first is `rebuilds`, with `churn` naming the culprits: an update commits
|
|
51
|
+
* values into DOM that already exists, while a rebuild tears a subtree down and builds another,
|
|
52
|
+
* and a template that rebuilds every render is the single most expensive mistake available in this
|
|
53
|
+
* renderer. `creates` is not a problem — it is what rendering into an empty slot costs once.
|
|
13
54
|
*/
|
|
14
|
-
|
|
15
|
-
|
|
55
|
+
type ProfileReport = {
|
|
56
|
+
/** Completed top-level `render()` calls. Nested renders are folded into their outermost frame. */
|
|
57
|
+
frames: number;
|
|
58
|
+
/** Total milliseconds spent inside `render()`. */
|
|
59
|
+
ms: number;
|
|
60
|
+
/** The slowest single frame, in milliseconds. */
|
|
61
|
+
slowestFrameMs: number;
|
|
62
|
+
/** Templates committed in place — the good path. */
|
|
63
|
+
updates: number;
|
|
64
|
+
/** Templates rendered into a slot that held nothing. Unavoidable and not a problem. */
|
|
65
|
+
creates: number;
|
|
66
|
+
/** Templates that replaced a *different* template — a teardown, not an update. */
|
|
67
|
+
rebuilds: number;
|
|
68
|
+
/** Rebuilds grouped by template pair, worst first. */
|
|
69
|
+
churn: Churn[];
|
|
70
|
+
};
|
|
71
|
+
/** How `showProfiler()` places and paces its in-page panel. Every field has a default. */
|
|
72
|
+
type OverlayOptions = {
|
|
16
73
|
/** Corner to pin to. Default `bottom-right`. */
|
|
17
74
|
corner?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
|
|
18
75
|
/** How often to repaint, in milliseconds. Default 400. */
|
|
19
76
|
interval?: number;
|
|
20
77
|
/** Churn rows to show before collapsing the rest into a count. Default 4. */
|
|
21
78
|
rows?: number;
|
|
22
|
-
}
|
|
79
|
+
};
|
|
23
80
|
|
|
24
81
|
/**
|
|
25
82
|
* @verajs/renderer — a ground-up, keyed, template-identity renderer.
|
|
@@ -80,14 +137,7 @@ interface OverlayOptions {
|
|
|
80
137
|
* deliberately do not match the pattern: the first is an interop wire format, the second is called
|
|
81
138
|
* by the DOM itself.
|
|
82
139
|
*/
|
|
83
|
-
|
|
84
|
-
/** 1 = html, 2 = svg, 3 = mathml — the markers core's built-in tags produce. */
|
|
85
|
-
_$litType$?: number;
|
|
86
|
-
strings: TemplateStringsArray;
|
|
87
|
-
values: unknown[];
|
|
88
|
-
/** Set by `keyed()`; drives keyed list reconciliation. */
|
|
89
|
-
key?: unknown;
|
|
90
|
-
};
|
|
140
|
+
|
|
91
141
|
/**
|
|
92
142
|
* Preserves the DOM of templates a child position toggles away from, instead of destroying it —
|
|
93
143
|
* form values, scroll positions and media playback survive the round trip (lit-html calls this
|
|
@@ -145,33 +195,6 @@ declare const renderer: {
|
|
|
145
195
|
}) => void;
|
|
146
196
|
};
|
|
147
197
|
|
|
148
|
-
/** One template identity replacing another at the same position, and how often. */
|
|
149
|
-
interface Churn {
|
|
150
|
-
/** The template that was torn down, rendered readably. */
|
|
151
|
-
from: string;
|
|
152
|
-
/** The template that replaced it. */
|
|
153
|
-
to: string;
|
|
154
|
-
/** How many times this exact swap happened while profiling. */
|
|
155
|
-
count: number;
|
|
156
|
-
/** Where in the DOM it happened, e.g. `main#app > ul.list`. First occurrence only. */
|
|
157
|
-
where: string;
|
|
158
|
-
}
|
|
159
|
-
interface ProfileReport {
|
|
160
|
-
/** Completed top-level `render()` calls. Nested renders are folded into their outermost frame. */
|
|
161
|
-
frames: number;
|
|
162
|
-
/** Total milliseconds spent inside `render()`. */
|
|
163
|
-
ms: number;
|
|
164
|
-
/** The slowest single frame, in milliseconds. */
|
|
165
|
-
slowestFrameMs: number;
|
|
166
|
-
/** Templates committed in place — the good path. */
|
|
167
|
-
updates: number;
|
|
168
|
-
/** Templates rendered into a slot that held nothing. Unavoidable and not a problem. */
|
|
169
|
-
creates: number;
|
|
170
|
-
/** Templates that replaced a *different* template — a teardown, not an update. */
|
|
171
|
-
rebuilds: number;
|
|
172
|
-
/** Rebuilds grouped by template pair, worst first. */
|
|
173
|
-
churn: Churn[];
|
|
174
|
-
}
|
|
175
198
|
/** Begin collecting. Calling this while already profiling restarts the collection. */
|
|
176
199
|
declare const startProfiling: () => void;
|
|
177
200
|
/** What has been measured so far, without ending the session. Drives the live overlay. */
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"vera-renderer-profiler.d.ts","sources":["../../src/
|
|
1
|
+
{"version":3,"file":"vera-renderer-profiler.d.ts","sources":["../../src/types.ts","../../src/renderer.ts","../../src/profiler.ts"],"mappings":"AAAA;;;;;;;;;;;;;;;;;AAiBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACjBH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DG;;;;;;;;;;;;;;;;AAwBA;AACH;AAEI,kBAAgC;sBACvB;AAEb;;AA+cM;AAEN;AAEA;AAEA;AACE;;AAsBA;AACE;AACA;;;AAGA;AACA;AACA;AACE;;;AAEA;;AAGF;;;;;AAKG;AACH;;AAEA;AACA;;AAEE;AACE;AACA;;AAEJ;AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC/jBD;AACH;AASA,cAAS,YAAc,2BAAqB;AAK5C;AAIA,cAAa,YAAM,WAAA,aAAA;;;;","names":[]}
|
|
@@ -763,6 +763,7 @@ const getTemplate = (result) => {
|
|
|
763
763
|
templateCache.set(result.strings, (template = new Template(result)));
|
|
764
764
|
return template;
|
|
765
765
|
};
|
|
766
|
+
/** Anything bound to a live position: commits values[index..], returns the next value index. */
|
|
766
767
|
const IGNORED_PART = { _commit: (_values, index) => index + 1 };
|
|
767
768
|
/** Never equal to any user value, so the first commit always runs. */
|
|
768
769
|
const UNSET = {};
|
|
@@ -1557,6 +1558,38 @@ const isTemplateResult = (value) => value.strings !== undefined;
|
|
|
1557
1558
|
* with a text node — so the steady state is compare-and-assign on `.data`. This part carries only
|
|
1558
1559
|
* that, upgrading itself to a full ChildPart the first time it sees null, a template, or an array.
|
|
1559
1560
|
*/
|
|
1561
|
+
/**
|
|
1562
|
+
* **A boolean in a child position renders the WORD, and almost nobody means that.**
|
|
1563
|
+
*
|
|
1564
|
+
* `${items.length > 0 && html`…`}` is the ordinary conditional idiom, and when the test is false
|
|
1565
|
+
* the whole expression is `false` — which becomes the text `false` on the page. Nothing throws;
|
|
1566
|
+
* the value is legitimate; only the intent is wrong. lit-html does the same and this renderer
|
|
1567
|
+
* matches it deliberately (anything not nullish renders), so the BEHAVIOUR stays and the mistake
|
|
1568
|
+
* is named where it happens instead of being found by looking at the page.
|
|
1569
|
+
*
|
|
1570
|
+
* `@verajs/jsx` compiles this case away — in JSX a boolean child becomes nothing, React's rule,
|
|
1571
|
+
* because that is where React expectations live. **That is the one value semantic on which JSX and
|
|
1572
|
+
* a hand-written template differ**, which makes this the warning that meets JSX-shaped code pasted
|
|
1573
|
+
* into a template.
|
|
1574
|
+
*
|
|
1575
|
+
* Called from BOTH child sinks, because a text position is a `TextPart` until something upgrades
|
|
1576
|
+
* it and a boolean never triggers that upgrade — putting the check in `ChildPart` alone left it
|
|
1577
|
+
* silent for exactly the common case. One function, two call sites, per the standing rule that a
|
|
1578
|
+
* deliberate duplication is a fix's second address.
|
|
1579
|
+
*
|
|
1580
|
+
* Both sinks gate this on the value CHANGING — not merely on reaching a commit — so an unchanged
|
|
1581
|
+
* `false` is reported once and not once per render. `ChildPart` needed that stated explicitly: its
|
|
1582
|
+
* dirty check sits below, and calling this above it spammed every pass.
|
|
1583
|
+
*/
|
|
1584
|
+
const warnBooleanChild = (value) => {
|
|
1585
|
+
if (typeof value !== 'boolean')
|
|
1586
|
+
return;
|
|
1587
|
+
console.warn(`[vera] renderer: a child position was given \`${value}\`, which renders as the word ` +
|
|
1588
|
+
`"${value}" — the usual cause is \`\${cond && …}\` with a false \`cond\`.\n` +
|
|
1589
|
+
`Write \`\${cond ? … : null}\`, or \`\${(cond && …) || null}\`; \`null\` and \`undefined\` are ` +
|
|
1590
|
+
`the values that render nothing. If you meant to display the boolean, say so with ` +
|
|
1591
|
+
`\`\${String(value)}\` and this goes quiet.`);
|
|
1592
|
+
};
|
|
1560
1593
|
class TextPart {
|
|
1561
1594
|
_text;
|
|
1562
1595
|
_value = '';
|
|
@@ -1612,6 +1645,8 @@ class TextPart {
|
|
|
1612
1645
|
return index + 1;
|
|
1613
1646
|
}
|
|
1614
1647
|
if (value !== this._value) {
|
|
1648
|
+
if (true )
|
|
1649
|
+
warnBooleanChild(value);
|
|
1615
1650
|
this._value = value;
|
|
1616
1651
|
this._text.data = value;
|
|
1617
1652
|
}
|
|
@@ -1901,6 +1936,15 @@ class ChildPart {
|
|
|
1901
1936
|
return;
|
|
1902
1937
|
}
|
|
1903
1938
|
if (typeof value !== 'object') {
|
|
1939
|
+
/**
|
|
1940
|
+
* Gated on the value CHANGING, which is the same condition the commit below uses. Called
|
|
1941
|
+
* before that check it fired on every render of an unchanged `false` — a channel that
|
|
1942
|
+
* repeats is as useless as one that stays silent, and the comment on `warnBooleanChild`
|
|
1943
|
+
* claimed this was already true. `_value` holds whatever was last committed here, so a part
|
|
1944
|
+
* arriving from a template state differs and reports once.
|
|
1945
|
+
*/
|
|
1946
|
+
if (true && this._value !== value)
|
|
1947
|
+
warnBooleanChild(value);
|
|
1904
1948
|
if (this._mode === TEXT) {
|
|
1905
1949
|
if (this._value !== value) {
|
|
1906
1950
|
this._value = value;
|