@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 CHANGED
@@ -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, `true`, `false`, `0` | as text — `${cond && 'x'}` puts the word `false` on the page |
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
@@ -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
- type TemplateResult = {
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;AAEH,KAAA,cAAS;AAYT;;;;;;;;;;;;;;;AAeG;AACH;AAEI;;AAGJ;;;AAGG;AACH,cAAA,IAAA;AACA,QAAM,cAAgB;AACtB;;;;;;;;;;;;;;;;;;ACjFG;AACH;AAwBA,cAAa;AAGb;AACA;AAEA;;;;AAIG;AACH;;;;","names":[]}
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 = {};
@@ -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
  }
@@ -1896,6 +1931,15 @@ class ChildPart {
1896
1931
  return;
1897
1932
  }
1898
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);
1899
1943
  if (this._mode === TEXT) {
1900
1944
  if (this._value !== value) {
1901
1945
  this._value = value;