@verajs/renderer 0.2.0 → 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 +112 -7
- 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 +229 -50
- 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 +229 -50
- package/dist/development/vera-renderer-profiler.js.map +1 -1
- package/dist/development/vera-renderer-spread.d.ts +44 -41
- package/dist/development/vera-renderer-spread.d.ts.map +1 -1
- package/dist/development/vera-renderer-spread.js +157 -4
- package/dist/development/vera-renderer-spread.js.map +1 -1
- package/dist/development/vera-renderer-tag.js +124 -3
- 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 +229 -50
- 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-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.min.js +1 -1
- package/dist/vera-renderer.min.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @verajs/renderer
|
|
2
2
|
|
|
3
|
-
The DOM renderer for VeraJS — <!--size:renderer.gzip-->4.
|
|
3
|
+
The DOM renderer for VeraJS — <!--size:renderer.gzip-->4.58 KB<!--/size:renderer.gzip--> gzipped,
|
|
4
4
|
no dependencies, no build step required.
|
|
5
5
|
|
|
6
6
|
Tagged templates parse once and clone; every render after the first walks only the value slots, so
|
|
@@ -138,7 +138,8 @@ What a child position does with each kind of value. These match lit-html exactly
|
|
|
138
138
|
|
|
139
139
|
| Value | Renders |
|
|
140
140
|
| --- | --- |
|
|
141
|
-
| string, number, `
|
|
141
|
+
| string, number, `0` | as text |
|
|
142
|
+
| `true`, `false` | as text — **and development says so**; see below |
|
|
142
143
|
| `null`, `undefined` | nothing |
|
|
143
144
|
| a template result | the template, updated in place while its shape holds |
|
|
144
145
|
| an array or iterable | each entry in order; key them with `keyed()` |
|
|
@@ -148,6 +149,22 @@ What a child position does with each kind of value. These match lit-html exactly
|
|
|
148
149
|
Strings render as **text**, always. There is no path by which an interpolated value becomes markup
|
|
149
150
|
— see [Trusted HTML](#trusted-html-and-why-there-is-no-unsafehtml).
|
|
150
151
|
|
|
152
|
+
### A boolean child renders the word, and JSX is the exception
|
|
153
|
+
|
|
154
|
+
`${items.length > 0 && html\`…\`}` is the ordinary conditional idiom, and when the test fails the
|
|
155
|
+
whole expression is `false` — which renders the text **"false"** on the page. The value is
|
|
156
|
+
legitimate and nothing throws, so **development names it** at the binding rather than leaving it to
|
|
157
|
+
be found by looking at the page. Write the form that renders nothing:
|
|
158
|
+
|
|
159
|
+
```js
|
|
160
|
+
html`<p>${cond ? html`<em>yes</em>` : null}</p>` // or: ${(cond && html`…`) || null}
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
**In JSX the same code needs no change** — `@verajs/jsx` compiles a boolean child away, which is
|
|
164
|
+
React's rule and where React expectations live. That is the **one** value semantic on which JSX and
|
|
165
|
+
a hand-written template differ, and this warning is what meets JSX-shaped code pasted into a
|
|
166
|
+
template. `0` still renders in both, exactly as in React: the rule is about booleans, not falsiness.
|
|
167
|
+
|
|
151
168
|
A DOM node renders as itself, which is how a template holds something another library owns:
|
|
152
169
|
|
|
153
170
|
```js
|
|
@@ -283,6 +300,13 @@ Native `<slot>` needs a shadow root. This entry teaches the renderer to distribu
|
|
|
283
300
|
component's own children into the `<slot name="…">` positions of its template, so **one component
|
|
284
301
|
works in both modes** — users write `<div slot="title">` exactly as they would against shadow DOM.
|
|
285
302
|
|
|
303
|
+
**Wire it at your app entry, before anything renders.** A template resolves this once, at
|
|
304
|
+
construction, and is interned per call site for the life of the page — so wiring `slots` after a
|
|
305
|
+
component has already rendered does not reach that component, and it keeps showing its fallback
|
|
306
|
+
content while the children the host was given sit beside it as stray markup. Development names it
|
|
307
|
+
when it happens, but the rule is cheaper than the diagnostic: wire it in the same call as the
|
|
308
|
+
renderer, `wire([renderer, slots])`.
|
|
309
|
+
|
|
286
310
|
Given this markup:
|
|
287
311
|
|
|
288
312
|
```html
|
|
@@ -649,6 +673,70 @@ Keys are strings carrying sigils, so TypeScript cannot check them against the el
|
|
|
649
673
|
That is a genuine step down from written bindings, and the trade for names that are not known until
|
|
650
674
|
runtime.
|
|
651
675
|
|
|
676
|
+
### `props()` — a typed bag of property bindings
|
|
677
|
+
|
|
678
|
+
For the common case where every key is a **property**, `props()` removes both the sigils and the
|
|
679
|
+
typing gap:
|
|
680
|
+
|
|
681
|
+
```js
|
|
682
|
+
import { props } from '@verajs/renderer/spread';
|
|
683
|
+
|
|
684
|
+
html`<calendar-day ${props({ date, events })}></calendar-day>`
|
|
685
|
+
```
|
|
686
|
+
|
|
687
|
+
```jsx
|
|
688
|
+
<calendar-day {...props({ date, events })}></calendar-day>
|
|
689
|
+
<calendar-day date={date} events={events} /> // JSX only: bare props ARE props on a component tag
|
|
690
|
+
```
|
|
691
|
+
|
|
692
|
+
One function, both surfaces — JSX compiles `{...x}` to `spread(x)`, and `spread()` recognises an
|
|
693
|
+
already-branded result, so the two spellings are literally the same call. In JSX the bag is
|
|
694
|
+
optional altogether: on a dash-named tag a bare prop compiles to the `.name` binding directly
|
|
695
|
+
(`@verajs/jsx`'s README has the two attribute carve-outs), so `props()` is the template's
|
|
696
|
+
spelling and the bag for names not known until runtime. It exists because an
|
|
697
|
+
attribute is always a string: an array, a `Date` or a store can only reach a custom element as a
|
|
698
|
+
property — and while vera's JSX accepts the sigil spelling `.date={d}`, TSX's type-checker refuses
|
|
699
|
+
it (TS1003), so the bag is the typed path.
|
|
700
|
+
|
|
701
|
+
Three rules, each earned:
|
|
702
|
+
|
|
703
|
+
- **Keys are property names, never sigils** — `props({ date })` binds `.date`. Events and boolean
|
|
704
|
+
attributes keep their own spellings (`@click`/`onClick`, `?disabled`); this bag is properties
|
|
705
|
+
only, by definition.
|
|
706
|
+
- **Prefer keys spelled conditionally over bags that change shape**:
|
|
707
|
+
`props({ date: loaded ? date : null })` — key present from the first render — over
|
|
708
|
+
`props(loaded ? { date } : {})`. Both work (a key that appears later on a component is adopted
|
|
709
|
+
live, and one that disappears restores what the element held), but a stable shape means values
|
|
710
|
+
update in place, the same reason templates prefer `?hidden` over swapped subtrees.
|
|
711
|
+
- **A type argument makes the bag checked**: `props<CalendarDay>({ dat })` is a compile error
|
|
712
|
+
naming the misspelling — the checking that sigil-keyed spread genuinely cannot have.
|
|
713
|
+
|
|
714
|
+
### How a component receives them
|
|
715
|
+
|
|
716
|
+
Nothing to declare on the other side — no `static properties`, no props argument. A component that
|
|
717
|
+
calls `init()` finds every bound property on `this`, **reactively**: reading `this.date` in a
|
|
718
|
+
render tracks it, the parent's next commit re-renders, and a store or `ref()` passed through stays
|
|
719
|
+
live because it arrives by identity. The full reception contract — including what happens when the
|
|
720
|
+
component's module loads *after* the parent rendered — is documented with `init()` in
|
|
721
|
+
`@verajs/core`'s README; this package's half is the delivery:
|
|
722
|
+
|
|
723
|
+
- **A property is not an attribute.** `date="…"` is an attribute — always a string, visible in
|
|
724
|
+
markup. `.date=${…}`/`props({ date })` is a property — any value, by identity, invisible to
|
|
725
|
+
`getAttribute`. Components receive **properties**; attributes are for CSS hooks and static
|
|
726
|
+
markup.
|
|
727
|
+
- **Delivery survives lazy definition.** A property bound before the element's module runs would
|
|
728
|
+
otherwise be destroyed by the class's field initializers at upgrade (at ES2022,
|
|
729
|
+
`item?: T` emits a real `item;` that runs during upgrade). The renderer records what nothing
|
|
730
|
+
received yet, and `init()` re-applies it — so a bound value outranks a class default, in both
|
|
731
|
+
field spellings. Elements that never call `init()` keep the development warning and the
|
|
732
|
+
`declare` advice instead.
|
|
733
|
+
- **Platform and foreign elements are untouched.** A property with an accessor anywhere —
|
|
734
|
+
`.title`, a Lit-style element, anything that already receives it — is delivered plainly and
|
|
735
|
+
never recorded.
|
|
736
|
+
- **SSR delivers, never serializes.** Under `@verajs/ssr`, a property bound on a rendered
|
|
737
|
+
component tag reaches that child's server render by identity — the markup never carries it, and
|
|
738
|
+
an unregistered tag passes through for the client to handle.
|
|
739
|
+
|
|
652
740
|
### Removing a key
|
|
653
741
|
|
|
654
742
|
A key that disappears between renders **restores what the element held before the binding existed**.
|
|
@@ -688,7 +776,7 @@ a pair of totals — the totals move with every change to this package and the d
|
|
|
688
776
|
which is the mistake this line already made once. `llms.txt` and this file disagreed about the figure
|
|
689
777
|
for a while, at 16 B and 8 B respectively, and both were wrong. Nothing regenerates it, so it is
|
|
690
778
|
dated; re-measure the same way if it matters.
|
|
691
|
-
The entry itself is **<!--size:spread.gzip-->1.
|
|
779
|
+
The entry itself is **<!--size:spread.gzip-->1.60 KB<!--/size:spread.gzip-->** gzipped, and only apps
|
|
692
780
|
that import it pay for that.
|
|
693
781
|
|
|
694
782
|
Runtime is at parity with writing the bindings out: both do one comparison per binding per render,
|
|
@@ -730,7 +818,17 @@ each other in the same corner, and the second one's teardown would stop profilin
|
|
|
730
818
|
which kept repainting a frozen report.
|
|
731
819
|
|
|
732
820
|
Full API: `startProfiling()`, `stopProfiling()`, `getReport()`, `isProfiling()`, `profile(fn)`,
|
|
733
|
-
`formatReport(report)`, `showProfiler(options?)`.
|
|
821
|
+
`formatReport(report)`, `showProfiler(options?)`. The first four are `profile()` unrolled, for a
|
|
822
|
+
session that does not fit one callback — a long-running tab, a REPL:
|
|
823
|
+
|
|
824
|
+
```js
|
|
825
|
+
import { startProfiling, stopProfiling, getReport, isProfiling, formatReport } from '@verajs/renderer/profiler';
|
|
826
|
+
|
|
827
|
+
startProfiling();
|
|
828
|
+
// … interact with the app for as long as you like …
|
|
829
|
+
if (isProfiling()) console.log(formatReport(getReport())); // read mid-flight without stopping
|
|
830
|
+
stopProfiling(); // freezes the report
|
|
831
|
+
```
|
|
734
832
|
|
|
735
833
|
This costs production nothing, and there is nothing to strip: the instrumentation sits behind a
|
|
736
834
|
`__DEV__` constant the build folds to `false`, so `vera-renderer.min.js` is byte-identical whether
|
|
@@ -830,7 +928,7 @@ life of three defects.
|
|
|
830
928
|
writing tests for it.
|
|
831
929
|
- HTML only. There is no `svg`/`mathml` equivalent yet.
|
|
832
930
|
|
|
833
|
-
<!--size:tag.gzip-->
|
|
931
|
+
<!--size:tag.gzip-->2.20 KB<!--/size:tag.gzip--> gzipped, which includes `/spread` — the factory
|
|
834
932
|
needs it to apply props whose names it cannot know. Additive, like `/spread` and unlike the other
|
|
835
933
|
entries: it inlines no renderer internals, so it is safe alongside any of them.
|
|
836
934
|
|
|
@@ -839,7 +937,14 @@ They are the table this entry uses to map React's names, and `@verajs/jsx` carri
|
|
|
839
937
|
deliberately — the two are build-time and runtime, and a shared package would be a dependency where
|
|
840
938
|
a test does the job. `tests/jsx-name-mapping.test.mjs` asserts the two agree on every key, and it can
|
|
841
939
|
only do that against the built artifact, which is why they are exported at all. Read them if you are
|
|
842
|
-
writing something that has to agree with both; do not build on them
|
|
940
|
+
writing something that has to agree with both; do not build on them:
|
|
941
|
+
|
|
942
|
+
```js
|
|
943
|
+
import { jsxName, BOOLEAN_ATTRIBUTES } from '@verajs/renderer/tag';
|
|
944
|
+
|
|
945
|
+
jsxName('className'); // 'class' — the runtime half of the React-name mapping
|
|
946
|
+
BOOLEAN_ATTRIBUTES.has('disabled'); // true — the names the tag entry toggles rather than assigns
|
|
947
|
+
```
|
|
843
948
|
|
|
844
949
|
## Extending it — `_$apply$` and `_$child$`
|
|
845
950
|
|
|
@@ -980,7 +1085,7 @@ Directives other renderers ship, and what replaces them here.
|
|
|
980
1085
|
| `ifDefined()` | built in — `null`/`undefined` remove an attribute |
|
|
981
1086
|
| `classMap()` / `styleMap()` | build the string: `class="base ${extra}"` |
|
|
982
1087
|
| `guard()` | reactivity already skips unchanged work |
|
|
983
|
-
| `until()`, `asyncReplace()` | render a loading state and re-render from an effect — or nine lines against [`_$child$`](#extending-it--
|
|
1088
|
+
| `until()`, `asyncReplace()` | render a loading state and re-render from an effect — or nine lines against [`_$child$`](#extending-it--_apply-and-_child) |
|
|
984
1089
|
| `unsafeHTML()` | `.innerHTML=${trusted}`, above |
|
|
985
1090
|
| `literal()` / `static-html` | [`/tag`](#verajsrenderertag) — and a tag doubles as a JSX component |
|
|
986
1091
|
| `live()` | [`!name`](#name--a-live-property) — a sigil, for the case that needs it |
|
|
@@ -1,3 +1,39 @@
|
|
|
1
|
+
/**
|
|
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.
|
|
22
|
+
*
|
|
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
|
+
|
|
1
37
|
/**
|
|
2
38
|
* @verajs/renderer — a ground-up, keyed, template-identity renderer.
|
|
3
39
|
*
|
|
@@ -57,14 +93,7 @@
|
|
|
57
93
|
* deliberately do not match the pattern: the first is an interop wire format, the second is called
|
|
58
94
|
* by the DOM itself.
|
|
59
95
|
*/
|
|
60
|
-
|
|
61
|
-
/** 1 = html, 2 = svg, 3 = mathml — the markers core's built-in tags produce. */
|
|
62
|
-
_$litType$?: number;
|
|
63
|
-
strings: TemplateStringsArray;
|
|
64
|
-
values: unknown[];
|
|
65
|
-
/** Set by `keyed()`; drives keyed list reconciliation. */
|
|
66
|
-
key?: unknown;
|
|
67
|
-
};
|
|
96
|
+
|
|
68
97
|
/**
|
|
69
98
|
* Preserves the DOM of templates a child position toggles away from, instead of destroying it —
|
|
70
99
|
* form values, scroll positions and media playback survive the round trip (lit-html calls this
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"vera-renderer-hydrate.d.ts","sources":["../../src/renderer.ts","../../src/hydrate.ts"],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DG;
|
|
1
|
+
{"version":3,"file":"vera-renderer-hydrate.d.ts","sources":["../../src/types.ts","../../src/renderer.ts","../../src/hydrate.ts"],"mappings":"AAAA;;;;;;;;;;;;;;;;;AAiBG;;;;;;;;;;;;;;;;;;;ACjBH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DG;;;;;;;;;;;;;;;;AAwBA;AACH;AAEI,kBAAgC;sBACvB;AAEb;;;;;;;;;;;;;;;;;;ACtEG;AACH;AAyBA,cAAa;AAGb;AACA;AAEA;;;;AAIG;AACH;;;;","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 = {};
|
|
@@ -800,6 +801,143 @@ const LIVE = 3;
|
|
|
800
801
|
const EVENT = 4; // @name
|
|
801
802
|
/** A binding that must never write — see the `__proto__` refusal in the constructor. */
|
|
802
803
|
const REFUSED = -1;
|
|
804
|
+
/** `.name` on a custom element nothing receives yet — records into `_$props$`, then becomes
|
|
805
|
+
* `PROPERTY`. A distinct kind keeps the steady-state property path free of any adoption check. */
|
|
806
|
+
const PROP_ADOPT = 6;
|
|
807
|
+
/**
|
|
808
|
+
* The `PROP_ADOPT` commit, kept OUT of `_commit` so that function's size — and the JIT layout of
|
|
809
|
+
* its hot `PROPERTY`/`ATTR` branches — is unchanged from before this feature. `_commit` carries one
|
|
810
|
+
* dispatch line; all of this lives here, off every part's steady state.
|
|
811
|
+
*
|
|
812
|
+
* One question decides everything: **after the write, does anything receive this property?** An
|
|
813
|
+
* accessor anywhere on the chain — the platform's own (`title`, `hidden`), a component's declared
|
|
814
|
+
* one, or the pair core's `init()` defines — means the write just landed in real hands: no record,
|
|
815
|
+
* and the part rejoins `PROPERTY` for good. The walk is one step when the write created an own data
|
|
816
|
+
* property (nobody consumed it) and stops at the first descriptor either way, and it is what keeps
|
|
817
|
+
* a platform property on a lazy tag out of the record — recording `.title` would end with the drain
|
|
818
|
+
* shadowing `HTMLElement.prototype.title` and breaking it.
|
|
819
|
+
*
|
|
820
|
+
* An unreceived write is recorded under the sigiled expando **`_$props$`**, because two arrival
|
|
821
|
+
* orders both need it: on a LAZY tag the value sits as a plain own property that the class's field
|
|
822
|
+
* initializers will overwrite at upgrade (the clobber the `PROPERTY` branch only *detects*), and on
|
|
823
|
+
* an EAGER one the value survives but is indistinguishable from the component's own fields by the
|
|
824
|
+
* time `init()` runs. The record answers both — core's `init()` drains it, re-applying values
|
|
825
|
+
* unconditionally, which repairs BOTH spellings of the clobber (`item;` and `item = default`): it
|
|
826
|
+
* never asks whether a clobber happened, it asserts a bound value outranks a class default, which
|
|
827
|
+
* is what props mean. Element-carried because `./spread.ts` writes the same properties from a
|
|
828
|
+
* separate bundle with no shared registry — the `_$`-sigiled member is the cross-bundle channel,
|
|
829
|
+
* and the recorder there is this one's deliberate twin.
|
|
830
|
+
*
|
|
831
|
+
* Returns the part's NEXT kind: `PROPERTY` once something receives the property or the element is
|
|
832
|
+
* upgraded (its record is final — `init()` drains it in the same tick) or has no realm; `REFUSED`
|
|
833
|
+
* for a getter with no setter, so the binding goes inert instead of the flipped plain write
|
|
834
|
+
* throwing on the next commit; `0` to stay adopting — a dash-named element that never upgrades and
|
|
835
|
+
* never receives keeps recording, so its record stays current rather than staling. The one
|
|
836
|
+
* retention this leaves: a defined non-vera element with a plain data property keeps its FIRST
|
|
837
|
+
* committed values in `_$props$` for its lifetime — bounded, one generation, and the part itself
|
|
838
|
+
* already retains the current generation in `_committed`.
|
|
839
|
+
*/
|
|
840
|
+
const commitAdopt = (element, name, value) => {
|
|
841
|
+
const el = element;
|
|
842
|
+
/**
|
|
843
|
+
* The walk comes BEFORE the write, because what the walk finds decides whether writing is even
|
|
844
|
+
* legal: a SETTER receives the value (and a setter that throws is the component's own error), a
|
|
845
|
+
* GETTER with no setter cannot — the old order assigned first, which in strict mode threw a raw
|
|
846
|
+
* TypeError out of the render for the eager spelling of exactly the case the drain refuses by
|
|
847
|
+
* name for the lazy one. Same contested state, one rule, both arrival orders — and the server's
|
|
848
|
+
* `deliverProperty` applies it too. The dev warning defers to `_$adopt$` where it exists: an
|
|
849
|
+
* initialized component's drain already speaks, and two voices for one binding is noise.
|
|
850
|
+
*/
|
|
851
|
+
let carrier = el;
|
|
852
|
+
while (carrier !== null) {
|
|
853
|
+
const desc = Object.getOwnPropertyDescriptor(carrier, name);
|
|
854
|
+
if (desc !== undefined) {
|
|
855
|
+
if (desc.set !== undefined) {
|
|
856
|
+
el[name] = value;
|
|
857
|
+
return PROPERTY;
|
|
858
|
+
}
|
|
859
|
+
if (desc.get !== undefined) {
|
|
860
|
+
/** An initialized component's receiver owns the refusal (and its channel); for anything
|
|
861
|
+
* else this is the only door, so it says so itself. Either way the binding goes INERT —
|
|
862
|
+
* flipping to `PROPERTY` would make the next commit's plain write throw. */
|
|
863
|
+
if (el._$adopt$ !== undefined)
|
|
864
|
+
el._$adopt$(name, value);
|
|
865
|
+
else if (true )
|
|
866
|
+
console.warn(`[vera] renderer: <${element.localName}> declares \`${name}\` as a getter with no ` +
|
|
867
|
+
`setter — the value bound by \`.${name}=\${…}\` cannot be delivered and the binding ` +
|
|
868
|
+
`is ignored. Add a setter, or stop binding it.`);
|
|
869
|
+
return REFUSED;
|
|
870
|
+
}
|
|
871
|
+
break; // a data property — an own field, or an inherited default: nothing receives it
|
|
872
|
+
}
|
|
873
|
+
carrier = Object.getPrototypeOf(carrier);
|
|
874
|
+
}
|
|
875
|
+
el[name] = value;
|
|
876
|
+
/**
|
|
877
|
+
* An initialized component receives LIVE: `init()` left `_$adopt$` on the element, and a key it
|
|
878
|
+
* has not adopted yet goes through that door — a record here would never be read again, because
|
|
879
|
+
* the drain already ran. This is how a hydrated child gets the props its parent commits after
|
|
880
|
+
* the child settled, and how a spread bag's conditional key arrives reactive on a live element.
|
|
881
|
+
*/
|
|
882
|
+
if (el._$adopt$ !== undefined) {
|
|
883
|
+
el._$adopt$(name, value);
|
|
884
|
+
return PROPERTY;
|
|
885
|
+
}
|
|
886
|
+
const record = (el._$props$ ??= {});
|
|
887
|
+
const firstRecording = !Object.hasOwn(record, name);
|
|
888
|
+
record[name] = value;
|
|
889
|
+
/**
|
|
890
|
+
* Upgrade is read off the PROTOTYPE, never off `el.constructor`: a spread bag's keys are runtime
|
|
891
|
+
* data, so a bag carrying a key named `constructor` writes an own property that shadows the real
|
|
892
|
+
* one, and a check that reads it would then misjudge every later commit. No property write can
|
|
893
|
+
* move an element's prototype — the one assignment that could, `__proto__`, both twins refuse.
|
|
894
|
+
* The realm comes from the element, as always.
|
|
895
|
+
*/
|
|
896
|
+
const win = element.ownerDocument.defaultView;
|
|
897
|
+
const upgraded = win === null || Object.getPrototypeOf(el) !== win.HTMLElement.prototype;
|
|
898
|
+
/**
|
|
899
|
+
* **The clobber detector, for the element the drain will never reach.** A component that calls
|
|
900
|
+
* `init()` has the record re-applied, so for it the pre-upgrade window is repaired; an element
|
|
901
|
+
* that never drains — a plain custom element with a class field — still loses the bound value to
|
|
902
|
+
* the field initializer at upgrade, exactly as before this feature, and still deserves the
|
|
903
|
+
* warning. Told apart by OWNERSHIP, not by value: after the definition arrives (and, for a
|
|
904
|
+
* connected element, `connectedCallback` and the drain have run synchronously inside `define()`),
|
|
905
|
+
* an own accessor means the drain took the property and there is nothing to report. Identity
|
|
906
|
+
* against the COMMITTED value would lie twice — a drained value reads back through the store's
|
|
907
|
+
* proxy, and a value superseded by a later pre-upgrade commit differs without anything being
|
|
908
|
+
* wrong — so the comparison is against the RECORD, which later recordings keep current, and the
|
|
909
|
+
* subscription is installed once per (element, property), on the first recording. The registry
|
|
910
|
+
* is the element's own realm's. Development only; production carries no check, no message, no
|
|
911
|
+
* `whenDefined` subscription.
|
|
912
|
+
*/
|
|
913
|
+
if (true && win !== null && !upgraded && firstRecording) {
|
|
914
|
+
const tag = element.localName;
|
|
915
|
+
win.customElements.whenDefined(tag).then(() => {
|
|
916
|
+
/** Ownership is asked of the whole CHAIN: the drain's own accessor, a class's prototype
|
|
917
|
+
* pair the value was handed to, or a get-only surface the drain refused by name — every
|
|
918
|
+
* one means the property has an owner and this closure has nothing left to report. */
|
|
919
|
+
let carrier = el;
|
|
920
|
+
let owned = false;
|
|
921
|
+
while (carrier !== null) {
|
|
922
|
+
const desc = Object.getOwnPropertyDescriptor(carrier, name);
|
|
923
|
+
if (desc !== undefined) {
|
|
924
|
+
owned = desc.get !== undefined || desc.set !== undefined;
|
|
925
|
+
break;
|
|
926
|
+
}
|
|
927
|
+
carrier = Object.getPrototypeOf(carrier);
|
|
928
|
+
}
|
|
929
|
+
if (!owned && el[name] !== record[name])
|
|
930
|
+
console.warn(`[vera] renderer: the value bound by \`.${name}=\${…}\` on <${tag}> was replaced ` +
|
|
931
|
+
`while the element upgraded. A class field is the usual cause: at ES2022 ` +
|
|
932
|
+
`\`${name}?: …\` emits \`${name};\`, which runs during upgrade and overwrites ` +
|
|
933
|
+
`whatever was set beforehand — write it \`declare ${name}?: …\` instead, which ` +
|
|
934
|
+
`emits nothing. A component that calls init() adopts bound properties automatically ` +
|
|
935
|
+
`and never sees this; this element did not. Ignore this if the component replaced ` +
|
|
936
|
+
`the value on purpose.`);
|
|
937
|
+
});
|
|
938
|
+
}
|
|
939
|
+
return upgraded ? PROPERTY : 0;
|
|
940
|
+
};
|
|
803
941
|
/**
|
|
804
942
|
* Calls an element ref, and survives one that throws.
|
|
805
943
|
*
|
|
@@ -890,6 +1028,19 @@ class AttrPart {
|
|
|
890
1028
|
kind = EVENT;
|
|
891
1029
|
realName = name.slice(2).toLowerCase();
|
|
892
1030
|
}
|
|
1031
|
+
/**
|
|
1032
|
+
* **A property write to a custom element starts as `PROP_ADOPT`**, a distinct kind so the
|
|
1033
|
+
* steady-state `PROPERTY` commit path stays byte-for-byte unchanged — zero added instruction
|
|
1034
|
+
* for every `.value=` on a built-in. Every dash-named element starts here, defined or not,
|
|
1035
|
+
* because the record has to exist for BOTH arrival orders: an eager component's first commit
|
|
1036
|
+
* lands after upgrade but before `init()` (one commit records, then the part flips), and a
|
|
1037
|
+
* lazy one's land before upgrade (the part records until the definition arrives). `commitAdopt`
|
|
1038
|
+
* decides which per commit and flips the part back to `PROPERTY` the moment something real
|
|
1039
|
+
* receives the property, so the window is one commit for a defined element and the pre-upgrade
|
|
1040
|
+
* stretch for a lazy one.
|
|
1041
|
+
*/
|
|
1042
|
+
if (kind === PROPERTY && element.localName.includes('-'))
|
|
1043
|
+
kind = PROP_ADOPT;
|
|
893
1044
|
this._kind = kind;
|
|
894
1045
|
this._name = realName;
|
|
895
1046
|
this._element = element;
|
|
@@ -1002,13 +1153,29 @@ class AttrPart {
|
|
|
1002
1153
|
if (kind === LIVE) {
|
|
1003
1154
|
this._committed = value;
|
|
1004
1155
|
/**
|
|
1005
|
-
* **Except while adopting.** Hydration reaches a DOM a person may
|
|
1006
|
-
* click that checked a radio happened before any handler existed
|
|
1007
|
-
* so re-asserting the server's choice here would throw the
|
|
1008
|
-
* ever put it back. Recorded, not written, exactly as
|
|
1009
|
-
* first state-driven render after that applies live
|
|
1156
|
+
* **Except while adopting — on a form control.** Hydration reaches a DOM a person may
|
|
1157
|
+
* already have used, and the click that checked a radio happened before any handler existed
|
|
1158
|
+
* to tell the store about it — so re-asserting the server's choice here would throw the
|
|
1159
|
+
* interaction away and nothing would ever put it back. Recorded, not written, exactly as
|
|
1160
|
+
* the other form properties are; the first state-driven render after that applies live
|
|
1161
|
+
* semantics normally.
|
|
1162
|
+
*
|
|
1163
|
+
* **A COMPONENT tag is the exception to the exception**: there is no user-editable carrier
|
|
1164
|
+
* behind `!prop` on a component — it is a property delivery spelled with `!` — and the
|
|
1165
|
+
* server DELIVERED it to the child's render, so yielding here dropped the one copy the
|
|
1166
|
+
* client would ever get and hydration regressed the child's content to its prop-less state.
|
|
1167
|
+
* Found by the hydration fixture on its first run. The write is unconditional and routes
|
|
1168
|
+
* through the element like any component prop: an accessor receives it, an initialized
|
|
1169
|
+
* component adopts it live.
|
|
1010
1170
|
*/
|
|
1011
|
-
if (
|
|
1171
|
+
if (true && adopting) {
|
|
1172
|
+
/** Routed through `commitAdopt`, not written raw: the child hydrated BEFORE this commit,
|
|
1173
|
+
* so only the adoption door re-runs its render. The part stays `LIVE` — the return is
|
|
1174
|
+
* deliberately dropped — so live semantics resume on the next state-driven render. */
|
|
1175
|
+
if (this._element.localName.includes('-'))
|
|
1176
|
+
commitAdopt(this._element, this._name, value);
|
|
1177
|
+
}
|
|
1178
|
+
else {
|
|
1012
1179
|
const liveTarget = this._element;
|
|
1013
1180
|
if (liveTarget[this._name] !== value)
|
|
1014
1181
|
liveTarget[this._name] = value;
|
|
@@ -1088,52 +1255,16 @@ class AttrPart {
|
|
|
1088
1255
|
this._committed = value;
|
|
1089
1256
|
return index + this._slots;
|
|
1090
1257
|
}
|
|
1091
|
-
target[name] = value;
|
|
1092
1258
|
/**
|
|
1093
|
-
*
|
|
1094
|
-
*
|
|
1095
|
-
*
|
|
1096
|
-
*
|
|
1097
|
-
*
|
|
1098
|
-
*
|
|
1099
|
-
*
|
|
1100
|
-
* it reads as broken reactivity.
|
|
1101
|
-
*
|
|
1102
|
-
* Repairing it was tried and removed. Re-applying when the slot came back `undefined`
|
|
1103
|
-
* covered `item?: T` but not `item = someDefault`, which overwrites with the default and
|
|
1104
|
-
* never looks clobbered — so the repair was silently partial, and made the bug intermittent
|
|
1105
|
-
* across two spellings of the same mistake. It also cost 74 B in every app while leaving
|
|
1106
|
-
* `declare` mandatory anyway, because a property assigned imperatively is unrecoverable:
|
|
1107
|
-
* the renderer never saw it, and by the time `init()` runs the value is already gone.
|
|
1108
|
-
*
|
|
1109
|
-
* So this is `true `-only and production pays nothing — no check, no message, no
|
|
1110
|
-
* `whenDefined` subscription. Lit reached the same place from the other direction and
|
|
1111
|
-
* throws (`lit.dev/msg/class-field-shadowing`); a warning suffices here because Vera has no
|
|
1112
|
-
* prototype accessors to shadow permanently — the damage is one lost value, not a property
|
|
1113
|
-
* that never updates again.
|
|
1259
|
+
* No un-upgraded custom element can be behind this write: a dash-named property part is
|
|
1260
|
+
* born `PROP_ADOPT` and only flips here once something receives the property, so the
|
|
1261
|
+
* pre-upgrade window — the clobber, its repair for components, and the `whenDefined`
|
|
1262
|
+
* detector for elements that never drain — lives entirely in `commitAdopt` above. History
|
|
1263
|
+
* worth keeping: an earlier repair was tried HERE and removed as silently partial (it
|
|
1264
|
+
* re-applied on `undefined`, so `item = someDefault` never looked clobbered); the record
|
|
1265
|
+
* the drain re-applies unconditionally is what answered that objection.
|
|
1114
1266
|
*/
|
|
1115
|
-
|
|
1116
|
-
const tag = this._element.localName;
|
|
1117
|
-
if (tag.indexOf('-') > 0 && !customElements.get(tag)) {
|
|
1118
|
-
customElements.whenDefined(tag).then(() => {
|
|
1119
|
-
/**
|
|
1120
|
-
* States what was observed rather than diagnosing it. A class field is the usual
|
|
1121
|
-
* cause by a wide margin, but a component that assigns the property itself during
|
|
1122
|
-
* upgrade produces the same observation, and that is a legitimate — if confusing —
|
|
1123
|
-
* thing to do, since the renderer's dirty check will not re-apply the bound value on
|
|
1124
|
-
* the next render either.
|
|
1125
|
-
*/
|
|
1126
|
-
if (target[name] !== value)
|
|
1127
|
-
console.warn(`[vera] renderer: the value bound by \`.${name}=\${…}\` on <${tag}> was replaced ` +
|
|
1128
|
-
`while the element upgraded. A class field is the usual cause: at ES2022 ` +
|
|
1129
|
-
`\`${name}?: …\` emits \`${name};\`, which runs during upgrade and overwrites ` +
|
|
1130
|
-
`whatever was set beforehand — write it \`declare ${name}?: …\` instead, which ` +
|
|
1131
|
-
`emits nothing. A plain field also wipes properties assigned imperatively, ` +
|
|
1132
|
-
`which cannot be detected at all. Ignore this if the component replaced the ` +
|
|
1133
|
-
`value on purpose.`);
|
|
1134
|
-
});
|
|
1135
|
-
}
|
|
1136
|
-
}
|
|
1267
|
+
target[name] = value;
|
|
1137
1268
|
}
|
|
1138
1269
|
else if (kind === BOOLEAN) {
|
|
1139
1270
|
/** Unconditional for the same reason: `<b hidden ?hidden=${false}>` must end up not hidden. */
|
|
@@ -1160,6 +1291,11 @@ class AttrPart {
|
|
|
1160
1291
|
this._element.addEventListener(this._name, this);
|
|
1161
1292
|
this._handler = value ?? null;
|
|
1162
1293
|
}
|
|
1294
|
+
else if (kind === PROP_ADOPT) {
|
|
1295
|
+
const next = commitAdopt(this._element, this._name, value);
|
|
1296
|
+
if (next !== 0)
|
|
1297
|
+
this._kind = next;
|
|
1298
|
+
}
|
|
1163
1299
|
else if (value != null) {
|
|
1164
1300
|
/**
|
|
1165
1301
|
* Element ref: `<input ${myRef} />`. A function is called with the element; an object gets
|
|
@@ -1422,6 +1558,38 @@ const isTemplateResult = (value) => value.strings !== undefined;
|
|
|
1422
1558
|
* with a text node — so the steady state is compare-and-assign on `.data`. This part carries only
|
|
1423
1559
|
* that, upgrading itself to a full ChildPart the first time it sees null, a template, or an array.
|
|
1424
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
|
+
};
|
|
1425
1593
|
class TextPart {
|
|
1426
1594
|
_text;
|
|
1427
1595
|
_value = '';
|
|
@@ -1477,6 +1645,8 @@ class TextPart {
|
|
|
1477
1645
|
return index + 1;
|
|
1478
1646
|
}
|
|
1479
1647
|
if (value !== this._value) {
|
|
1648
|
+
if (true )
|
|
1649
|
+
warnBooleanChild(value);
|
|
1480
1650
|
this._value = value;
|
|
1481
1651
|
this._text.data = value;
|
|
1482
1652
|
}
|
|
@@ -1761,6 +1931,15 @@ class ChildPart {
|
|
|
1761
1931
|
return;
|
|
1762
1932
|
}
|
|
1763
1933
|
if (typeof value !== 'object') {
|
|
1934
|
+
/**
|
|
1935
|
+
* Gated on the value CHANGING, which is the same condition the commit below uses. Called
|
|
1936
|
+
* before that check it fired on every render of an unchanged `false` — a channel that
|
|
1937
|
+
* repeats is as useless as one that stays silent, and the comment on `warnBooleanChild`
|
|
1938
|
+
* claimed this was already true. `_value` holds whatever was last committed here, so a part
|
|
1939
|
+
* arriving from a template state differs and reports once.
|
|
1940
|
+
*/
|
|
1941
|
+
if (true && this._value !== value)
|
|
1942
|
+
warnBooleanChild(value);
|
|
1764
1943
|
if (this._mode === TEXT) {
|
|
1765
1944
|
if (this._value !== value) {
|
|
1766
1945
|
this._value = value;
|