[lit-html] Add svg tagged template literal documentation #2479

AndrewJakubowicz · 2022-02-02T02:43:26Z

Addresses issue: lit/lit.dev#652
Also addresses generated docs for svg: #1883 (comment)

This is a documentation only change to guide correct usage of the svg tagged template literal. Currently it's easy to reach for this whenever anything svg related comes up.

Instead of going into the implementation details for how the svg TTL copies the fragment into an <svg> element and then copies that fragment over, I've instead focussed on correct usage and provided an example that shows both an svg fragment and complete svg element.

Test of the code example: Lit Playground

Risks

No codebase risk, docs only change. Main risk is adding incorrect documentation.

changeset-bot · 2022-02-02T02:43:28Z

🦋 Changeset detected

Latest commit: 99105f5

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions · 2022-02-02T02:43:49Z

📊 Tachometer Benchmark Results

Summary

nop-update

lit-html-kitchen-sink: unsure 🔍 -4% - +3% (-1.31ms - +0.91ms)
^{this-change vs tip-of-tree}

render

lit-element-list: unsure 🔍 -4% - +1% (-4.20ms - +1.67ms)
^{this-change vs tip-of-tree}
lit-html-kitchen-sink: unsure 🔍 -3% - +2% (-1.27ms - +1.07ms)
^{this-change vs tip-of-tree}
lit-html-repeat: unsure 🔍 -3% - +4% (-0.49ms - +0.54ms)
^{this-change vs tip-of-tree}
lit-html-template-heavy: unsure 🔍 -4% - +2% (-2.74ms - +1.57ms)
^{this-change vs tip-of-tree}
reactive-element-list: unsure 🔍 -2% - +3% (-1.27ms - +2.05ms)
^{this-change vs tip-of-tree}

update

lit-element-list: unsure 🔍 -2% - +4% (-16.90ms - +42.72ms)
^{this-change vs tip-of-tree}
lit-html-kitchen-sink: unsure 🔍 -5% - +3% (-6.06ms - +3.08ms)
^{this-change vs tip-of-tree}
lit-html-repeat: unsure 🔍 -5% - +7% (-18.76ms - +26.85ms)
^{this-change vs tip-of-tree}
lit-html-template-heavy: unsure 🔍 -5% - +2% (-7.80ms - +2.83ms)
^{this-change vs tip-of-tree}
reactive-element-list: unsure 🔍 -2% - +1% (-23.94ms - +12.95ms)
^{this-change vs tip-of-tree}

update-reflect

lit-element-list: unsure 🔍 -2% - +4% (-24.42ms - +41.24ms)
^{this-change vs tip-of-tree}
reactive-element-list: unsure 🔍 -2% - +1% (-27.46ms - +6.85ms)
^{this-change vs tip-of-tree}

Results

lit-element-list

Browser: chrome-headless 97.0.4692.99
Sample size: 50
Built by: Benchmarks #2330
Commit: 73e426a

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	107.46ms - 111.40ms	-	unsure 🔍 -4% - +1% -4.20ms - +1.67ms	faster ✔ 21% - 24% 28.74ms - 34.50ms
tip-of-tree tip-of-tree	108.51ms - 112.87ms	unsure 🔍 -2% - +4% -1.67ms - +4.20ms	-	faster ✔ 20% - 23% 27.32ms - 33.38ms
previous-release previous-release	138.94ms - 143.14ms	slower ❌ 26% - 32% 28.74ms - 34.50ms	slower ❌ 24% - 31% 27.32ms - 33.38ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	1025.76ms - 1067.48ms	-	unsure 🔍 -2% - +4% -16.90ms - +42.72ms	faster ✔ 4% - 9% 42.96ms - 106.11ms
tip-of-tree tip-of-tree	1012.42ms - 1055.00ms	unsure 🔍 -4% - +2% -42.72ms - +16.90ms	-	faster ✔ 5% - 11% 55.59ms - 119.31ms
previous-release previous-release	1097.46ms - 1144.86ms	slower ❌ 4% - 10% 42.96ms - 106.11ms	slower ❌ 5% - 12% 55.59ms - 119.31ms	-

update-reflect

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	1125.97ms - 1174.75ms	-	unsure 🔍 -2% - +4% -24.42ms - +41.24ms	faster ✔ 1% - 7% 16.06ms - 83.71ms
tip-of-tree tip-of-tree	1119.98ms - 1163.92ms	unsure 🔍 -4% - +2% -41.24ms - +24.42ms	-	faster ✔ 2% - 7% 26.17ms - 90.42ms
previous-release previous-release	1176.81ms - 1223.68ms	slower ❌ 1% - 7% 16.06ms - 83.71ms	slower ❌ 2% - 8% 26.17ms - 90.42ms	-

lit-html-kitchen-sink

Browser: chrome-headless 97.0.4692.99
Sample size: 30
Built by: Benchmarks #2330
Commit: 73e426a

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	42.54ms - 44.16ms	-	unsure 🔍 -3% - +2% -1.27ms - +1.07ms	faster ✔ 11% - 17% 5.18ms - 8.44ms
tip-of-tree tip-of-tree	42.61ms - 44.29ms	unsure 🔍 -2% - +3% -1.07ms - +1.27ms	-	faster ✔ 10% - 16% 5.07ms - 8.36ms
previous-release previous-release	48.75ms - 51.58ms	slower ❌ 12% - 20% 5.18ms - 8.44ms	slower ❌ 11% - 19% 5.07ms - 8.36ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	107.83ms - 114.35ms	-	unsure 🔍 -5% - +3% -6.06ms - +3.08ms	unsure 🔍 -7% - +0% -8.47ms - +0.43ms
tip-of-tree tip-of-tree	109.38ms - 115.79ms	unsure 🔍 -3% - +5% -3.08ms - +6.06ms	-	unsure 🔍 -6% - +2% -6.94ms - +1.88ms
previous-release previous-release	112.08ms - 118.14ms	unsure 🔍 -0% - +8% -0.43ms - +8.47ms	unsure 🔍 -2% - +6% -1.88ms - +6.94ms	-

nop-update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	31.64ms - 33.18ms	-	unsure 🔍 -4% - +3% -1.31ms - +0.91ms	faster ✔ 7% - 14% 2.57ms - 5.05ms
tip-of-tree tip-of-tree	31.81ms - 33.41ms	unsure 🔍 -3% - +4% -0.91ms - +1.31ms	-	faster ✔ 7% - 13% 2.35ms - 4.87ms
previous-release previous-release	35.25ms - 37.19ms	slower ❌ 8% - 16% 2.57ms - 5.05ms	slower ❌ 7% - 15% 2.35ms - 4.87ms	-

lit-html-repeat

Browser: chrome-headless 97.0.4692.99
Sample size: 30
Built by: Benchmarks #2330
Commit: 73e426a

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	13.92ms - 14.74ms	-	unsure 🔍 -3% - +4% -0.49ms - +0.54ms	faster ✔ 8% - 16% 1.30ms - 2.57ms
tip-of-tree tip-of-tree	14.00ms - 14.61ms	unsure 🔍 -4% - +3% -0.54ms - +0.49ms	-	faster ✔ 9% - 15% 1.39ms - 2.53ms
previous-release previous-release	15.79ms - 16.75ms	slower ❌ 9% - 18% 1.30ms - 2.57ms	slower ❌ 10% - 18% 1.39ms - 2.53ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	367.35ms - 401.48ms	-	unsure 🔍 -5% - +7% -18.76ms - +26.85ms	faster ✔ 26% - 34% 142.52ms - 191.98ms
tip-of-tree tip-of-tree	365.25ms - 395.50ms	unsure 🔍 -7% - +5% -26.85ms - +18.76ms	-	faster ✔ 28% - 35% 147.86ms - 194.73ms
previous-release previous-release	533.77ms - 569.57ms	slower ❌ 36% - 51% 142.52ms - 191.98ms	slower ❌ 38% - 52% 147.86ms - 194.73ms	-

lit-html-template-heavy

Browser: chrome-headless 97.0.4692.99
Sample size: 50
Built by: Benchmarks #2330
Commit: 73e426a

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	66.64ms - 69.69ms	-	unsure 🔍 -4% - +2% -2.74ms - +1.57ms	faster ✔ 13% - 18% 10.31ms - 14.66ms
tip-of-tree tip-of-tree	67.23ms - 70.27ms	unsure 🔍 -2% - +4% -1.57ms - +2.74ms	-	faster ✔ 12% - 17% 9.73ms - 14.07ms
previous-release previous-release	79.10ms - 82.20ms	slower ❌ 15% - 22% 10.31ms - 14.66ms	slower ❌ 14% - 21% 9.73ms - 14.07ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	145.21ms - 152.44ms	-	unsure 🔍 -5% - +2% -7.80ms - +2.83ms	faster ✔ 11% - 17% 17.87ms - 28.94ms
tip-of-tree tip-of-tree	147.42ms - 155.21ms	unsure 🔍 -2% - +5% -2.83ms - +7.80ms	-	faster ✔ 9% - 15% 15.19ms - 26.64ms
previous-release previous-release	168.04ms - 176.42ms	slower ❌ 12% - 20% 17.87ms - 28.94ms	slower ❌ 10% - 18% 15.19ms - 26.64ms	-

reactive-element-list

Browser: chrome-headless 97.0.4692.99
Sample size: 50
Built by: Benchmarks #2330
Commit: 73e426a

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	76.38ms - 78.89ms	-	unsure 🔍 -2% - +3% -1.27ms - +2.05ms	unsure 🔍 -1% - +3% -1.09ms - +2.09ms
tip-of-tree tip-of-tree	76.16ms - 78.32ms	unsure 🔍 -3% - +2% -2.05ms - +1.27ms	-	unsure 🔍 -2% - +2% -1.34ms - +1.57ms
previous-release previous-release	76.16ms - 78.10ms	unsure 🔍 -3% - +1% -2.09ms - +1.09ms	unsure 🔍 -2% - +2% -1.57ms - +1.34ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	1075.87ms - 1103.90ms	-	unsure 🔍 -2% - +1% -23.94ms - +12.95ms	unsure 🔍 -1% - +2% -15.19ms - +22.45ms
tip-of-tree tip-of-tree	1083.39ms - 1107.38ms	unsure 🔍 -1% - +2% -12.95ms - +23.94ms	-	unsure 🔍 -1% - +2% -8.24ms - +26.50ms
previous-release previous-release	1073.70ms - 1098.82ms	unsure 🔍 -2% - +1% -22.45ms - +15.19ms	unsure 🔍 -2% - +1% -26.50ms - +8.24ms	-

update-reflect

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	1190.50ms - 1214.26ms	-	unsure 🔍 -2% - +1% -27.46ms - +6.85ms	unsure 🔍 -2% - +1% -20.47ms - +13.99ms
tip-of-tree tip-of-tree	1200.32ms - 1225.06ms	unsure 🔍 -1% - +2% -6.85ms - +27.46ms	-	unsure 🔍 -1% - +2% -10.50ms - +24.64ms
previous-release previous-release	1193.14ms - 1218.10ms	unsure 🔍 -1% - +2% -13.99ms - +20.47ms	unsure 🔍 -2% - +1% -24.64ms - +10.50ms	-

_{tachometer-reporter-action v2 for Benchmarks}

arthurevans

LGTM. Made some optional suggestions to better match the language in the guides.

packages/lit-html/src/lit-html.ts

Co-authored-by: Arthur Evans <arthure@google.com>

justinfagnani

Sorry it took me a bit to get to this. I know it's merged, but one small thought

justinfagnani · 2022-02-04T21:44:05Z

packages/lit-html/src/lit-html.ts

+ * function. The `<svg>` element is an HTML element and should be used within a
+ * template tagged with the {@linkcode html} tag function.
+ *
+ * In LitElement usage, it's rare to return an SVG fragment from the `render()`


s/rare/invalid

Include Justin's feedback on #2479. Replace rare with invalid and reflow markdown.

Include Justin's feedback on #2479. Replace 'rare' with 'invalid' and reflow markdown. Co-authored-by: Andrew Jakubowicz <ajakubowicz@google.com>

AndrewJakubowicz added 2 commits February 1, 2022 18:31

[lit-html] Expand JSDoc for svg tagged template literal.

6709ee2

Add changeset

b64095d

AndrewJakubowicz requested a review from justinfagnani as a code owner February 2, 2022 02:43

AndrewJakubowicz requested a review from arthurevans February 2, 2022 02:43

arthurevans approved these changes Feb 3, 2022

View reviewed changes

packages/lit-html/src/lit-html.ts Outdated Show resolved Hide resolved

packages/lit-html/src/lit-html.ts Outdated Show resolved Hide resolved

packages/lit-html/src/lit-html.ts Outdated Show resolved Hide resolved

packages/lit-html/src/lit-html.ts Outdated Show resolved Hide resolved

AndrewJakubowicz and others added 5 commits February 3, 2022 13:48

Update packages/lit-html/src/lit-html.ts

970f46c

Co-authored-by: Arthur Evans <arthure@google.com>

Update packages/lit-html/src/lit-html.ts

527234c

Co-authored-by: Arthur Evans <arthure@google.com>

Update packages/lit-html/src/lit-html.ts

8c894de

Co-authored-by: Arthur Evans <arthure@google.com>

Update packages/lit-html/src/lit-html.ts

11de8fe

Co-authored-by: Arthur Evans <arthure@google.com>

Formatting and removed another usage of TTL with tag function.

7de8d99

aomarks approved these changes Feb 3, 2022

View reviewed changes

Update changeset message

99105f5

kevinpschaaf approved these changes Feb 4, 2022

View reviewed changes

AndrewJakubowicz merged commit 8956052 into main Feb 4, 2022

AndrewJakubowicz deleted the document-svg-ttl branch February 4, 2022 21:13

justinfagnani reviewed Feb 4, 2022

View reviewed changes

justinfagnani mentioned this pull request Feb 4, 2022

Document usage of svg tagged template literal lit/lit.dev#652

Closed

AndrewJakubowicz added a commit that referenced this pull request Feb 7, 2022

[lit-html] svg tag function JSDoc tiny update.

9a4944e

Include Justin's feedback on #2479. Replace rare with invalid and reflow markdown.

AndrewJakubowicz mentioned this pull request Feb 7, 2022

[lit-html] svg tag function JSDoc replace 'rare' with 'invalid' #2498

Merged

lit-robot mentioned this pull request Feb 7, 2022

Version Packages #2500

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[lit-html] Add svg tagged template literal documentation #2479

[lit-html] Add svg tagged template literal documentation #2479

AndrewJakubowicz commented Feb 2, 2022 •

edited

changeset-bot bot commented Feb 2, 2022 •

edited

github-actions bot commented Feb 2, 2022 •

edited

📊 Tachometer Benchmark Results

Summary

nop-update

render

update

update-reflect

Results

render

update

update-reflect

render

update

nop-update

render

update

render

update

render

update

update-reflect

arthurevans left a comment

justinfagnani left a comment

justinfagnani Feb 4, 2022

[lit-html] Add svg tagged template literal documentation #2479

[lit-html] Add svg tagged template literal documentation #2479

Conversation

AndrewJakubowicz commented Feb 2, 2022 • edited

Risks

changeset-bot bot commented Feb 2, 2022 • edited

🦋 Changeset detected

github-actions bot commented Feb 2, 2022 • edited

📊 Tachometer Benchmark Results

Summary

nop-update

render

update

update-reflect

Results

render

update

update-reflect

render

update

nop-update

render

update

render

update

render

update

update-reflect

arthurevans left a comment

Choose a reason for hiding this comment

justinfagnani left a comment

Choose a reason for hiding this comment

justinfagnani Feb 4, 2022

Choose a reason for hiding this comment

AndrewJakubowicz commented Feb 2, 2022 •

edited

changeset-bot bot commented Feb 2, 2022 •

edited

github-actions bot commented Feb 2, 2022 •

edited