[lit-html] Add when, map, join, and range directives. #2335

justinfagnani · 2021-12-04T01:38:12Z

These helpers are simple functions, not directives, that help make a template read a bit more declaratively when containing conditionals and loops. They're not strictly necessary, but we've found a number of users ask for them or write their own.

Adds:

when(): sugar for ternaries. Especially nice when there's no else clause
map(): Evaluate a function of items in an iterable. Stylistically more "declarative" and works with iterables.
join(): Interleaves the items of an iterable with a joiner value or result of calling a joiner function.
range(): Returns an iterable that contains number in a range. Useful when combined with map().

changeset-bot · 2021-12-04T01:38:15Z

🦋 Changeset detected

Latest commit: f6003ea

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 · 2021-12-04T01:38:36Z

📊 Tachometer Benchmark Results

Summary

nop-update

lit-html-kitchen-sink: unsure 🔍 -2% - +5% (-0.47ms - +1.15ms)
^{this-change vs tip-of-tree}

render

lit-element-list: unsure 🔍 -2% - +1% (-1.39ms - +0.83ms)
^{this-change vs tip-of-tree}
lit-html-kitchen-sink: unsure 🔍 -1% - +0% (-0.24ms - +0.07ms)
^{this-change vs tip-of-tree}
lit-html-repeat: unsure 🔍 -3% - +0% (-0.29ms - +0.05ms)
^{this-change vs tip-of-tree}
lit-html-template-heavy: unsure 🔍 -1% - +1% (-0.37ms - +0.71ms)
^{this-change vs tip-of-tree}
reactive-element-list: unsure 🔍 -2% - +1% (-0.86ms - +0.54ms)
^{this-change vs tip-of-tree}

update

lit-element-list: unsure 🔍 -0% - +1% (-2.88ms - +4.52ms)
^{this-change vs tip-of-tree}
lit-html-kitchen-sink: unsure 🔍 -3% - +1% (-2.21ms - +1.13ms)
^{this-change vs tip-of-tree}
lit-html-repeat: unsure 🔍 -1% - +1% (-1.69ms - +4.07ms)
^{this-change vs tip-of-tree}
lit-html-template-heavy: unsure 🔍 -1% - +1% (-0.62ms - +0.97ms)
^{this-change vs tip-of-tree}
reactive-element-list: unsure 🔍 -1% - +0% (-4.11ms - +1.13ms)
^{this-change vs tip-of-tree}

update-reflect

lit-element-list: unsure 🔍 -0% - +1% (-3.20ms - +6.24ms)
^{this-change vs tip-of-tree}
reactive-element-list: unsure 🔍 -1% - +0% (-6.19ms - +3.28ms)
^{this-change vs tip-of-tree}

Results

lit-element-list

Browser: chrome-headless 96.0.4664.45
Sample size: 50
Built by: Benchmarks #2109
Commit: f431741

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	70.94ms - 72.19ms	-	unsure 🔍 -2% - +1% -1.39ms - +0.83ms	faster ✔ 20% - 23% 18.48ms - 20.94ms
tip-of-tree tip-of-tree	70.92ms - 72.76ms	unsure 🔍 -1% - +2% -0.83ms - +1.39ms	-	faster ✔ 20% - 23% 18.03ms - 20.84ms
previous-release previous-release	90.22ms - 92.33ms	slower ❌ 26% - 29% 18.48ms - 20.94ms	slower ❌ 25% - 29% 18.03ms - 20.84ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	618.82ms - 624.69ms	-	unsure 🔍 -0% - +1% -2.88ms - +4.52ms	faster ✔ 7% - 8% 47.40ms - 56.35ms
tip-of-tree tip-of-tree	618.69ms - 623.19ms	unsure 🔍 -1% - +0% -4.52ms - +2.88ms	-	faster ✔ 7% - 8% 48.63ms - 56.75ms
previous-release previous-release	670.25ms - 677.01ms	slower ❌ 8% - 9% 47.40ms - 56.35ms	slower ❌ 8% - 9% 48.63ms - 56.75ms	-

update-reflect

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	680.53ms - 688.63ms	-	unsure 🔍 -0% - +1% -3.20ms - +6.24ms	faster ✔ 2% - 4% 15.61ms - 26.07ms
tip-of-tree tip-of-tree	680.64ms - 685.49ms	unsure 🔍 -1% - +0% -6.24ms - +3.20ms	-	faster ✔ 3% - 4% 18.25ms - 26.46ms
previous-release previous-release	702.11ms - 708.73ms	slower ❌ 2% - 4% 15.61ms - 26.07ms	slower ❌ 3% - 4% 18.25ms - 26.46ms	-

lit-html-kitchen-sink

Browser: chrome-headless 96.0.4664.45
Sample size: 30
Built by: Benchmarks #2109
Commit: f431741

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	28.43ms - 28.61ms	-	unsure 🔍 -1% - +0% -0.24ms - +0.07ms	faster ✔ 15% - 18% 5.09ms - 6.45ms
tip-of-tree tip-of-tree	28.48ms - 28.73ms	unsure 🔍 -0% - +1% -0.07ms - +0.24ms	-	faster ✔ 15% - 18% 5.00ms - 6.37ms
previous-release previous-release	33.61ms - 34.96ms	slower ❌ 18% - 23% 5.09ms - 6.45ms	slower ❌ 17% - 22% 5.00ms - 6.37ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	76.59ms - 79.21ms	-	unsure 🔍 -3% - +1% -2.21ms - +1.13ms	faster ✔ 2% - 8% 1.19ms - 6.63ms
tip-of-tree tip-of-tree	77.40ms - 79.46ms	unsure 🔍 -1% - +3% -1.13ms - +2.21ms	-	faster ✔ 1% - 7% 0.78ms - 5.97ms
previous-release previous-release	79.43ms - 84.19ms	slower ❌ 1% - 9% 1.19ms - 6.63ms	slower ❌ 1% - 8% 0.78ms - 5.97ms	-

nop-update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	24.97ms - 26.53ms	-	unsure 🔍 -2% - +5% -0.47ms - +1.15ms	faster ✔ 9% - 15% 2.61ms - 4.36ms
tip-of-tree tip-of-tree	25.19ms - 25.64ms	unsure 🔍 -4% - +2% -1.15ms - +0.47ms	-	faster ✔ 12% - 14% 3.37ms - 4.28ms
previous-release previous-release	28.84ms - 29.63ms	slower ❌ 10% - 17% 2.61ms - 4.36ms	slower ❌ 13% - 17% 3.37ms - 4.28ms	-

lit-html-repeat

Browser: chrome-headless 96.0.4664.45
Sample size: 30
Built by: Benchmarks #2109
Commit: f431741

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	11.42ms - 11.66ms	-	unsure 🔍 -3% - +0% -0.29ms - +0.05ms	faster ✔ 7% - 9% 0.89ms - 1.14ms
tip-of-tree tip-of-tree	11.53ms - 11.78ms	unsure 🔍 -0% - +3% -0.05ms - +0.29ms	-	faster ✔ 6% - 8% 0.76ms - 1.03ms
previous-release previous-release	12.51ms - 12.60ms	slower ❌ 8% - 10% 0.89ms - 1.14ms	slower ❌ 6% - 9% 0.76ms - 1.03ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	276.06ms - 280.79ms	-	unsure 🔍 -1% - +1% -1.69ms - +4.07ms	faster ✔ 28% - 30% 110.47ms - 117.01ms
tip-of-tree tip-of-tree	275.59ms - 278.88ms	unsure 🔍 -1% - +1% -4.07ms - +1.69ms	-	faster ✔ 29% - 30% 112.13ms - 117.73ms
previous-release previous-release	389.91ms - 394.43ms	slower ❌ 39% - 42% 110.47ms - 117.01ms	slower ❌ 40% - 43% 112.13ms - 117.73ms	-

lit-html-template-heavy

Browser: chrome-headless 96.0.4664.45
Sample size: 50
Built by: Benchmarks #2109
Commit: f431741

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	51.69ms - 52.34ms	-	unsure 🔍 -1% - +1% -0.37ms - +0.71ms	faster ✔ 15% - 18% 9.31ms - 11.03ms
tip-of-tree tip-of-tree	51.41ms - 52.28ms	unsure 🔍 -1% - +1% -0.71ms - +0.37ms	-	faster ✔ 15% - 18% 9.44ms - 11.25ms
previous-release previous-release	61.39ms - 62.98ms	slower ❌ 18% - 21% 9.31ms - 11.03ms	slower ❌ 18% - 22% 9.44ms - 11.25ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	109.77ms - 110.86ms	-	unsure 🔍 -1% - +1% -0.62ms - +0.97ms	faster ✔ 12% - 13% 14.42ms - 16.61ms
tip-of-tree tip-of-tree	109.56ms - 110.71ms	unsure 🔍 -1% - +1% -0.97ms - +0.62ms	-	faster ✔ 12% - 13% 14.58ms - 16.80ms
previous-release previous-release	124.88ms - 126.77ms	slower ❌ 13% - 15% 14.42ms - 16.61ms	slower ❌ 13% - 15% 14.58ms - 16.80ms	-

reactive-element-list

Browser: chrome-headless 96.0.4664.45
Sample size: 50
Built by: Benchmarks #2109
Commit: f431741

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	51.69ms - 52.57ms	-	unsure 🔍 -2% - +1% -0.86ms - +0.54ms	unsure 🔍 -2% - +1% -0.87ms - +0.58ms
tip-of-tree tip-of-tree	51.75ms - 52.83ms	unsure 🔍 -1% - +2% -0.54ms - +0.86ms	-	unsure 🔍 -1% - +2% -0.77ms - +0.80ms
previous-release previous-release	51.71ms - 52.84ms	unsure 🔍 -1% - +2% -0.58ms - +0.87ms	unsure 🔍 -2% - +1% -0.80ms - +0.77ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	625.07ms - 628.28ms	-	unsure 🔍 -1% - +0% -4.11ms - +1.13ms	unsure 🔍 -0% - +0% -2.83ms - +2.18ms
tip-of-tree tip-of-tree	626.09ms - 630.23ms	unsure 🔍 -0% - +1% -1.13ms - +4.11ms	-	unsure 🔍 -0% - +1% -1.66ms - +3.99ms
previous-release previous-release	625.08ms - 628.92ms	unsure 🔍 -0% - +0% -2.18ms - +2.83ms	unsure 🔍 -1% - +0% -3.99ms - +1.66ms	-

update-reflect

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	707.71ms - 714.77ms	-	unsure 🔍 -1% - +0% -6.19ms - +3.28ms	unsure 🔍 -1% - +1% -5.31ms - +4.03ms
tip-of-tree tip-of-tree	709.53ms - 715.86ms	unsure 🔍 -0% - +1% -3.28ms - +6.19ms	-	unsure 🔍 -1% - +1% -3.59ms - +5.22ms
previous-release previous-release	708.82ms - 714.94ms	unsure 🔍 -1% - +1% -4.03ms - +5.31ms	unsure 🔍 -1% - +1% -5.22ms - +3.59ms	-

_{tachometer-reporter-action v2 for Benchmarks}

packages/lit-html/src/helpers.ts

.changeset/new-guests-refuse.md

packages/lit-html/src/helpers.ts

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

aomarks · 2021-12-07T15:59:42Z

We had this discussion offline, writing up here:

From a usage perspective, these new helpers seem to be in the same category as directives. The difference is really just an implementation detail -- that these ones don't need to use the Directive class.

E.g. it could be difficult for users to remember that repeat is imported from directives/repeat.js, but join is imported from helpers.js. To users who aren't familiar with the implementations, there would probably be no obvious reason why we've organized them this way.

Some options:

Keep the distinction. Helpers implemented with Directive are imported from directives/<directive>.js, otherwise from helpers.js (except for ifDefined which doesn't use Directive but is already under directives/).
Grant these new helpers the "directive" title, even though they technically aren't. Synecdoches are ok sometimes?
Move existing directives and these new helpers into a new helpers/ or similar folder, and add re-exports to make non-breaking. "Helpers" becomes our broad term for template-utility-functions, and "directives" are for the specific type of helper that needs deeper control into how Lit renders.

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

packages/lit-html/src/helpers.ts

graynorton · 2021-12-07T16:07:03Z

I like this option:

Move existing directives and these new helpers into a new helpers/ or similar folder, and add re-exports to make non-breaking. "Helpers" becomes our broad term for template-utility-functions, and "directives" are for the specific type of helper that needs deeper control into how Lit renders.

justinfagnani · 2021-12-07T18:00:29Z

Moved the helpers into directives/

aomarks

LGTM!

justinfagnani · 2021-12-07T21:24:39Z

@kevinpschaaf are you good with this now?

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

Add when, map, join, and range tempalte helpers.

aa428e2

justinfagnani requested review from kevinpschaaf and sorvell December 4, 2021 01:38

google-cla bot added the cla: yes label Dec 4, 2021

aomarks requested changes Dec 4, 2021

View reviewed changes

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

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

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

.changeset/new-guests-refuse.md Outdated Show resolved Hide resolved

Add tests

39a56ae

justinfagnani requested a review from aomarks December 6, 2021 22:40

justinfagnani marked this pull request as ready for review December 6, 2021 22:40

justinfagnani added this to the Lit 2.1 milestone Dec 6, 2021

justinfagnani added 3 commits December 6, 2021 14:48

Add exampels

4501300

oops

4f85fd2

oops 2

c6fe5b3

aomarks reviewed Dec 6, 2021

View reviewed changes

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

aomarks reviewed Dec 6, 2021

View reviewed changes

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

aomarks requested changes Dec 6, 2021

View reviewed changes

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

kevinpschaaf reviewed Dec 7, 2021

View reviewed changes

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

Address review feedback

7b4042d

justinfagnani requested review from aomarks and kevinpschaaf December 7, 2021 01:59

justinfagnani changed the title ~~Add when, map, join, and range template helpers.~~ [lit-html] Add when, map, join, and range template helpers. Dec 7, 2021

justinfagnani added 2 commits December 6, 2021 18:17

Address feedback

b23a665

once more

74e73b1

aomarks requested changes Dec 7, 2021

View reviewed changes

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

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

Move helpers into directives

16c0bd8

justinfagnani requested a review from aomarks December 7, 2021 18:02

justinfagnani changed the title ~~[lit-html] Add when, map, join, and range template helpers.~~ [lit-html] Add when, map, join, and range directives. Dec 7, 2021

aomarks approved these changes Dec 7, 2021

View reviewed changes

Update changeset description

2749d97

justinfagnani mentioned this pull request Dec 7, 2021

Add map, join, range, when directive docs lit/lit.dev#608

Closed

kevinpschaaf reviewed Dec 7, 2021

View reviewed changes

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

Chaneg when condition type to unknown

bee041e

kevinpschaaf approved these changes Dec 7, 2021

View reviewed changes

Update rollup entrypoints

f6003ea

justinfagnani merged commit d319cf5 into main Dec 7, 2021

justinfagnani deleted the template-helpers branch December 7, 2021 23:00

This was referenced Jan 5, 2022

Version Packages #2375

Closed

Version Packages #2377

Merged

snyk-bot mentioned this pull request Jan 16, 2022

[Snyk] Security upgrade marked from 0.3.12 to 4.0.10 tjenkinson/lit-html#17

Open

tjenkinson mentioned this pull request Sep 30, 2022

[Snyk] Fix for 11 vulnerabilities tjenkinson/lit-html#18

Open

[lit-html] Add when, map, join, and range directives. #2335

[lit-html] Add when, map, join, and range directives. #2335

Uh oh!

Conversation

justinfagnani commented Dec 4, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Dec 4, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions bot commented Dec 4, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📊 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

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aomarks commented Dec 7, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

graynorton commented Dec 7, 2021

Uh oh!

justinfagnani commented Dec 7, 2021

Uh oh!

aomarks left a comment

Choose a reason for hiding this comment

Uh oh!

justinfagnani commented Dec 7, 2021

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

justinfagnani commented Dec 4, 2021 •

edited

Loading

changeset-bot bot commented Dec 4, 2021 •

edited

Loading

github-actions bot commented Dec 4, 2021 •

edited

Loading

aomarks commented Dec 7, 2021 •

edited

Loading