@verajs/renderer 0.2.1 → 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 +729 -226
- 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 +113 -138
- package/dist/development/vera-renderer-profiler.d.ts.map +1 -1
- package/dist/development/vera-renderer-profiler.js +2428 -2101
- 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 +8 -29
- package/dist/development/vera-renderer-spread.d.ts.map +1 -1
- package/dist/development/vera-renderer-spread.js +542 -461
- 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 -494
- 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 +77 -96
- package/dist/development/vera-renderer.d.ts.map +1 -1
- package/dist/development/vera-renderer.js +2401 -2061
- 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 -118
- package/dist/development/vera-renderer-hydrate.d.ts.map +0 -1
- package/dist/development/vera-renderer-hydrate.js +0 -3092
- 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,61 +1,29 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
2
|
+
* The renderer's cross-file and public types — one `types.ts` at the import-graph root, per
|
|
3
|
+
* CODE-PRINCIPLES §1.
|
|
3
4
|
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
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.
|
|
7
13
|
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
* 3. Arrays reconcile KEYED (see `keyed()`), with head/tail fast paths and map-based moves, so a
|
|
17
|
-
* reorder moves nodes instead of rebuilding them.
|
|
18
|
-
*
|
|
19
|
-
* Built in, where lit-html requires directive imports: keyed list reconciliation (`keyed`),
|
|
20
|
-
* element refs (element-position expressions), toggled-DOM preservation (`hold`), and a
|
|
21
|
-
* whole-range fast clear — one `textContent = ''` where lit removes thousands of nodes one at a
|
|
22
|
-
* time. Like-for-like (lit-html + repeat + ref + cache: 5 021 B gzip), this file is ~28% smaller.
|
|
23
|
-
*
|
|
24
|
-
* What it deliberately does NOT have, which is why it is smaller than lit-html: no directive
|
|
25
|
-
* protocol, no `noChange`/`nothing` sentinels (in a single-expression attribute, `null`/`undefined`
|
|
26
|
-
* REMOVE the attribute; in a child, they clear it), no sanitizer indirection, no async parts, no
|
|
27
|
-
* dev-mode branches.
|
|
28
|
-
*
|
|
29
|
-
* Known limits, deliberate and shared with lit-html's envelope: no bindings inside comments (the
|
|
30
|
-
* value is consumed and ignored), no dynamic tag names, and nested `<template>` elements' contents
|
|
31
|
-
* are not traversed.
|
|
32
|
-
*
|
|
33
|
-
* CONTRACTS THE SPEED PAYS FOR — these are the trade, documented rather than discovered:
|
|
34
|
-
*
|
|
35
|
-
* - **The renderer owns its container below the mount point.** The whole-range fast clear wipes
|
|
36
|
-
* everything in a parent the part fully owns, including nodes user code appended there by hand
|
|
37
|
-
* (lit-html would preserve them). Same contract as mounting Vue or React into a container.
|
|
38
|
-
* - **Do not call `Node.normalize()` on rendered content.** Child anchors are text nodes, and
|
|
39
|
-
* normalize merges adjacent text — lit-html's comment anchors are immune to this; ours are not.
|
|
40
|
-
* - **A plain string renders as text, never as HTML.** The Reef renderer parsed strings as markup;
|
|
41
|
-
* this one has no innerHTML sink at all (an XSS class removed). The deliberate escape hatch for
|
|
42
|
-
* trusted markup is a property binding: `.innerHTML=${trusted}`.
|
|
43
|
-
* - **Hydration is automatic and markerless.** The first render into a container that already has
|
|
44
|
-
* children adopts them as server output of the same template (statics matched byte-for-byte,
|
|
45
|
-
* anchors installed by splitting live text at known value positions), falling back to a clean
|
|
46
|
-
* render on any mismatch. Requires the initial client render to match server state — same
|
|
47
|
-
* contract as React/Vue hydration.
|
|
48
|
-
* - **No directive protocol.** The template language itself is closed to extension — Vera extends
|
|
49
|
-
* at the framework layer (inserts) and through element refs, not inside the renderer's value
|
|
50
|
-
* handling.
|
|
51
|
-
* - Event handlers are invoked with `this` bound to the ELEMENT (lit binds its host).
|
|
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.
|
|
52
22
|
*
|
|
53
|
-
*
|
|
54
|
-
*
|
|
55
|
-
*
|
|
56
|
-
*
|
|
57
|
-
* deliberately do not match the pattern: the first is an interop wire format, the second is called
|
|
58
|
-
* by the DOM itself.
|
|
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.
|
|
59
27
|
*/
|
|
60
28
|
type TemplateResult = {
|
|
61
29
|
/** 1 = html, 2 = svg, 3 = mathml — the markers core's built-in tags produce. */
|
|
@@ -65,62 +33,75 @@ type TemplateResult = {
|
|
|
65
33
|
/** Set by `keyed()`; drives keyed list reconciliation. */
|
|
66
34
|
key?: unknown;
|
|
67
35
|
};
|
|
36
|
+
|
|
68
37
|
/**
|
|
69
|
-
*
|
|
70
|
-
*
|
|
71
|
-
* `
|
|
38
|
+
* @verajs/renderer — a template-identity renderer.
|
|
39
|
+
*
|
|
40
|
+
* A tagged template's `strings` array is interned per call site, so it keys a parsed `<template>`.
|
|
41
|
+
* An instance clones it and binds the expression positions; every later render of the same shape
|
|
42
|
+
* commits only the values that changed. Lists reconcile by index here, by key through
|
|
43
|
+
* `@verajs/renderer/keyed`.
|
|
44
|
+
*
|
|
45
|
+
* Contracts the speed pays for:
|
|
46
|
+
* - The renderer owns its container below the mount point: a part that owns a whole parent clears it
|
|
47
|
+
* with one `textContent = ''`.
|
|
48
|
+
* - Do not `normalize()` rendered content — child anchors are text nodes.
|
|
49
|
+
* - A string renders as text, never as markup. There is no `innerHTML` sink.
|
|
50
|
+
*
|
|
51
|
+
* Internal members are `_`-prefixed because the production build mangles `/^_[a-z]/`. `$`-named
|
|
52
|
+
* members cross bundle boundaries (keyed, spread, slots) and survive mangling by not matching it.
|
|
53
|
+
*/
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* Preserves the DOM of a template a position toggles away from, instead of destroying it — form values
|
|
57
|
+
* and media state survive the round trip. Anything that is not a template passes straight through, so
|
|
58
|
+
* `hold(editing && editor())` is fine.
|
|
72
59
|
*
|
|
73
60
|
* ```js
|
|
74
61
|
* html`<div>${hold(editing ? editor() : viewer())}</div>`
|
|
75
62
|
* ```
|
|
76
|
-
*
|
|
77
|
-
* **Anything that is not a template passes straight through.** There is nothing to park for a
|
|
78
|
-
* string, a list, `null` or `false`, and the branch that produces one is the ordinary shape of the
|
|
79
|
-
* expression this wraps — `hold(editing && editor())`, `hold(row ?? null)`. Wrapping those handed
|
|
80
|
-
* the renderer a `{ $h }` carrying a non-template, which reached the held-commit path and threw on
|
|
81
|
-
* `result.strings`: a whole render lost, from a value the same expression renders happily one
|
|
82
|
-
* character to the left. Decided here rather than in the renderer so the hot path pays nothing.
|
|
83
63
|
*/
|
|
84
64
|
declare const hold: <T>(result: T) => T | {
|
|
85
65
|
$h: TemplateResult;
|
|
86
66
|
};
|
|
67
|
+
declare const renderInto: (result: unknown, container: Node, owns?: boolean) => void;
|
|
68
|
+
type Registry = {
|
|
69
|
+
get(name: never): unknown;
|
|
70
|
+
$S?: unknown;
|
|
71
|
+
$F?: unknown;
|
|
72
|
+
};
|
|
87
73
|
/**
|
|
88
|
-
*
|
|
89
|
-
*
|
|
90
|
-
* `
|
|
91
|
-
*
|
|
92
|
-
*
|
|
93
|
-
* **It owns its own range and nothing else.** The first call appends a marker and anchors a root
|
|
94
|
-
* part there; later calls with the same container reuse that part and walk only the value slots, so
|
|
95
|
-
* nodes are updated in place rather than rebuilt. Content that was already in the container stays.
|
|
96
|
-
*
|
|
97
|
-
* **Named for the relationship, not the act.** It was `render` until 0.2.0, which collided with
|
|
98
|
-
* core's `render` — a different function, with a different arity, that declares a *reactive*
|
|
99
|
-
* template and commits a component's setup. Both were public and both were documented, so a reader
|
|
100
|
-
* who knew one misread the other. `renderElement` and `renderDom` were considered and rejected: this
|
|
101
|
-
* renders *into* a container, and the container is a `Node` — a shadow root and a fragment are both
|
|
102
|
-
* valid, so "element" would be a lie in the type. Argument order is lit-html's on purpose.
|
|
103
|
-
*
|
|
104
|
-
* HYDRATION lives in `@verajs/renderer/hydrate` — a drop-in superset entry whose `renderInto` adopts
|
|
105
|
-
* existing server-rendered children on first render. SSR apps import from there instead of here;
|
|
106
|
-
* this entry carries zero hydration code.
|
|
74
|
+
* What a consumer's TypeScript sees — the shape `wire` accepts (`Wireable`, structurally: this package imports no
|
|
75
|
+
* types from `@verajs/inserts`): a DESCRIPTOR, `on: 'render'`, callable with options to give `[renderer, a connector]`.
|
|
76
|
+
* On a server `on` is in fact `undefined` (decided at load, below) — a runtime decision the type does not carry, as
|
|
77
|
+
* the previous `on: 'render' | undefined` did: that matched neither a descriptor nor a connector, so `wire([renderer])`
|
|
78
|
+
* stopped compiling in a consumer's project (tests/consumer, 2026-10-10).
|
|
107
79
|
*/
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
80
|
+
type RendererModule = ((options?: {
|
|
81
|
+
shadow?: 'open' | 'closed' | false | ShadowRootInit;
|
|
82
|
+
foreignNodes?: 'preserve' | 'drop';
|
|
83
|
+
}) => readonly [RendererModule, (registry: Registry) => void]) & {
|
|
84
|
+
readonly on: 'render';
|
|
112
85
|
fn: never;
|
|
113
86
|
priority: number;
|
|
114
|
-
|
|
115
|
-
* Typed against the registry `wire` actually hands over, not a narrower shape that happens to
|
|
116
|
-
* describe the one lookup this makes. A structural `{ get(name: 'value'): … }` is **not**
|
|
117
|
-
* assignable from `Inserts`, so `wire([renderer])` failed to compile in a consumer's project while
|
|
118
|
-
* this repo's own typecheck — which reads sources, not the shipped `.d.ts` — saw nothing.
|
|
119
|
-
*/
|
|
120
|
-
connect: (given: {
|
|
121
|
-
get(name: never): unknown;
|
|
122
|
-
}) => void;
|
|
87
|
+
connect: (given: Registry) => void;
|
|
123
88
|
};
|
|
89
|
+
/**
|
|
90
|
+
* **`renderer` is a DUAL** — `wire([renderer])` as it always was, or `wire([renderer({ shadow: 'open' })])` to set the
|
|
91
|
+
* app's default root: every component whose own `shadow` option says nothing gets it (core's `init` reads it after the
|
|
92
|
+
* component's own and before light DOM). `renderer({ foreignNodes: 'preserve' })` is the same for `foreignNodes`, and sets
|
|
93
|
+
* COMPONENT roots only — a container handed to `renderInto` (`document.body`, `#app`) always keeps foreign nodes. Called, it returns `[renderer, a connector setting the default]` — `wire`
|
|
94
|
+
* takes nested arrays — so the module is one function with its descriptor fields on it, and nothing is made per call
|
|
95
|
+
* but that connector.
|
|
96
|
+
*
|
|
97
|
+
* **On a server it declines its render insert** (Brian's (b′), 2026-10-10): `@verajs/ssr` renders with its own renderer,
|
|
98
|
+
* and a client one wired in shared app code used to DISPLACE it, breaking every server render. There `on` is undefined,
|
|
99
|
+
* which makes `wire` hand this function the registry as a CONNECTOR: it still CONNECTS — the registry, `untracked`, the
|
|
100
|
+
* hydration hand-off: a process that loaded ssr may install a client DOM and call renderInto directly (tests/spread-ssr
|
|
101
|
+
* does) — and only the render INSERT is declined, so one shared `wire([renderer({ shadow })])` carries the same default
|
|
102
|
+
* to both sides. Development says so once per process.
|
|
103
|
+
*/
|
|
104
|
+
declare const renderer: RendererModule;
|
|
124
105
|
|
|
125
106
|
export { hold, renderInto, renderer };
|
|
126
107
|
export type { TemplateResult };
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"vera-renderer.d.ts","sources":["../../src/renderer.ts"],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"vera-renderer.d.ts","sources":["../../src/types.ts","../../src/renderer.ts"],"mappings":"AAAA;;;;;;;;;;;;;;;;;AAiBG;;;;;;;;;;;;;;;;;;;ACjBH;;;;;;;;;;;;;;;;AAgBG;;AAqPC;;;;AAIG;AACH;AACA;AACA;;cAEE,IAAI;sBACM;AACV;AAYA,cAAA,UAAU,+BAAW,IAAA;AACrB,KAAA,QAAA;;;AAEA;;;;AAIA;AACA;AACE;;;AAEA,KAAA,cAAE;AACF,yCAAyB,cAAA;AACvB;8BAA6B,aAAc,QAAC;AACvC;;;AAEH,qBAAA,QAAI;AAAwD;AAC5D;;;;;AAGG;;AAEL;AACE;;;AAEK;;;AAEL;wBACA,cAAY;;;;","names":[]}
|