[lit-html] Add keyed directive

[justinfagnani]

Adds a keyed(key, value) directive that clears a part if the key changes. This is useful for ensuring stateful DOM is cleared and with animations that require adding or removing elements for fly-in / fly-out animations.

Fixes #2165

[changeset-bot]

🦋 Changeset detected

Latest commit: 950c2cb

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]

📊 Tachometer Benchmark Results

Summary

nop-update

• lit-html-kitchen-sink: unsure 🔍 -1% - +1% (-0.36ms - +0.26ms)
  ^{this-change vs tip-of-tree}

render

• lit-element-list: unsure 🔍 -7% - +5% (-5.25ms - +4.23ms)
  ^{this-change vs tip-of-tree}
• lit-html-kitchen-sink: unsure 🔍 -7% - +2% (-2.28ms - +0.53ms)
  ^{this-change vs tip-of-tree}
• lit-html-repeat: unsure 🔍 -3% - +3% (-0.35ms - +0.33ms)
  ^{this-change vs tip-of-tree}
• lit-html-template-heavy: unsure 🔍 -2% - +1% (-1.07ms - +0.50ms)
  ^{this-change vs tip-of-tree}
• reactive-element-list: unsure 🔍 -1% - +2% (-0.67ms - +1.21ms)
  ^{this-change vs tip-of-tree}

update

• lit-element-list: unsure 🔍 -5% - +3% (-43.21ms - +25.12ms)
  ^{this-change vs tip-of-tree}
• lit-html-kitchen-sink: unsure 🔍 -4% - +2% (-3.04ms - +1.60ms)
  ^{this-change vs tip-of-tree}
• lit-html-repeat: unsure 🔍 -1% - +2% (-3.41ms - +6.00ms)
  ^{this-change vs tip-of-tree}
• lit-html-template-heavy: unsure 🔍 -3% - +1% (-3.42ms - +1.22ms)
  ^{this-change vs tip-of-tree}
• reactive-element-list: unsure 🔍 -1% - +2% (-9.94ms - +13.18ms)
  ^{this-change vs tip-of-tree}

update-reflect

• lit-element-list: unsure 🔍 -1% - +1% (-7.50ms - +9.77ms)
  ^{this-change vs tip-of-tree}
• reactive-element-list: unsure 🔍 -1% - +1% (-9.64ms - +13.69ms)
  ^{this-change vs tip-of-tree}

Results

lit-element-list

• Browser: chrome-headless 96.0.4664.45
• Sample size: 50
• Built by: Benchmarks #2110

• Commit: fe2f1c6

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	74.54ms - 80.74ms	-	unsure 🔍 -7% - +5% -5.25ms - +4.23ms	faster ✔ 16% - 23% 15.39ms - 21.82ms
tip-of-tree tip-of-tree	74.57ms - 81.74ms	unsure 🔍 -5% - +7% -4.23ms - +5.25ms	-	faster ✔ 15% - 23% 14.41ms - 21.78ms
previous-release previous-release	95.38ms - 97.12ms	slower ❌ 19% - 29% 15.39ms - 21.82ms	slower ❌ 17% - 29% 14.41ms - 21.78ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	813.46ms - 837.55ms	-	unsure 🔍 -5% - +3% -43.21ms - +25.12ms	faster ✔ 6% - 9% 50.11ms - 76.71ms
tip-of-tree tip-of-tree	802.58ms - 866.52ms	unsure 🔍 -3% - +5% -25.12ms - +43.21ms	-	faster ✔ 2% - 10% 21.90ms - 86.83ms
previous-release previous-release	883.26ms - 894.57ms	slower ❌ 6% - 9% 50.11ms - 76.71ms	slower ❌ 2% - 11% 21.90ms - 86.83ms	-

update-reflect

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	910.86ms - 923.63ms	-	unsure 🔍 -1% - +1% -7.50ms - +9.77ms	faster ✔ 4% - 6% 37.24ms - 56.80ms
tip-of-tree tip-of-tree	910.30ms - 921.91ms	unsure 🔍 -1% - +1% -9.77ms - +7.50ms	-	faster ✔ 4% - 6% 38.75ms - 57.56ms
previous-release previous-release	956.86ms - 971.66ms	slower ❌ 4% - 6% 37.24ms - 56.80ms	slower ❌ 4% - 6% 38.75ms - 57.56ms	-

lit-html-kitchen-sink

• Browser: chrome-headless 96.0.4664.45
• Sample size: 30
• Built by: Benchmarks #2110

• Commit: fe2f1c6

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	30.31ms - 30.61ms	-	unsure 🔍 -7% - +2% -2.28ms - +0.53ms	faster ✔ 15% - 17% 5.51ms - 6.26ms
tip-of-tree tip-of-tree	29.95ms - 32.73ms	unsure 🔍 -2% - +7% -0.53ms - +2.28ms	-	faster ✔ 10% - 18% 3.57ms - 6.45ms
previous-release previous-release	36.00ms - 36.70ms	slower ❌ 18% - 21% 5.51ms - 6.26ms	slower ❌ 11% - 21% 3.57ms - 6.45ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	84.28ms - 86.81ms	-	unsure 🔍 -4% - +2% -3.04ms - +1.60ms	faster ✔ 2% - 8% 1.47ms - 6.96ms
tip-of-tree tip-of-tree	84.32ms - 88.21ms	unsure 🔍 -2% - +4% -1.60ms - +3.04ms	-	faster ✔ 1% - 7% 0.38ms - 6.61ms
previous-release previous-release	87.33ms - 92.20ms	slower ❌ 2% - 8% 1.47ms - 6.96ms	slower ❌ 0% - 8% 0.38ms - 6.61ms	-

nop-update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	25.20ms - 25.60ms	-	unsure 🔍 -1% - +1% -0.36ms - +0.26ms	faster ✔ 14% - 16% 4.04ms - 4.82ms
tip-of-tree tip-of-tree	25.22ms - 25.69ms	unsure 🔍 -1% - +1% -0.26ms - +0.36ms	-	faster ✔ 13% - 16% 3.97ms - 4.79ms
previous-release previous-release	29.49ms - 30.17ms	slower ❌ 16% - 19% 4.04ms - 4.82ms	slower ❌ 15% - 19% 3.97ms - 4.79ms	-

lit-html-repeat

• Browser: chrome-headless 96.0.4664.45
• Sample size: 30
• Built by: Benchmarks #2110

• Commit: fe2f1c6

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	11.44ms - 11.83ms	-	unsure 🔍 -3% - +3% -0.35ms - +0.33ms	faster ✔ 5% - 9% 0.64ms - 1.07ms
tip-of-tree tip-of-tree	11.37ms - 11.92ms	unsure 🔍 -3% - +3% -0.33ms - +0.35ms	-	faster ✔ 4% - 9% 0.56ms - 1.13ms
previous-release previous-release	12.41ms - 12.57ms	slower ❌ 5% - 9% 0.64ms - 1.07ms	slower ❌ 5% - 10% 0.56ms - 1.13ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	314.54ms - 321.57ms	-	unsure 🔍 -1% - +2% -3.41ms - +6.00ms	faster ✔ 30% - 32% 135.78ms - 146.25ms
tip-of-tree tip-of-tree	313.63ms - 319.89ms	unsure 🔍 -2% - +1% -6.00ms - +3.41ms	-	faster ✔ 30% - 32% 137.32ms - 147.29ms
previous-release previous-release	455.19ms - 462.95ms	slower ❌ 42% - 46% 135.78ms - 146.25ms	slower ❌ 43% - 47% 137.32ms - 147.29ms	-

lit-html-template-heavy

• Browser: chrome-headless 96.0.4664.45
• Sample size: 50
• Built by: Benchmarks #2110

• Commit: fe2f1c6

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	55.14ms - 56.09ms	-	unsure 🔍 -2% - +1% -1.07ms - +0.50ms	faster ✔ 16% - 19% 10.71ms - 12.87ms
tip-of-tree tip-of-tree	55.28ms - 56.52ms	unsure 🔍 -1% - +2% -0.50ms - +1.07ms	-	faster ✔ 16% - 19% 10.35ms - 12.66ms
previous-release previous-release	66.43ms - 68.37ms	slower ❌ 19% - 23% 10.71ms - 12.87ms	slower ❌ 18% - 23% 10.35ms - 12.66ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	128.42ms - 131.40ms	-	unsure 🔍 -3% - +1% -3.42ms - +1.22ms	faster ✔ 13% - 16% 18.97ms - 23.82ms
tip-of-tree tip-of-tree	129.23ms - 132.79ms	unsure 🔍 -1% - +3% -1.22ms - +3.42ms	-	faster ✔ 12% - 15% 17.68ms - 22.91ms
previous-release previous-release	149.39ms - 153.22ms	slower ❌ 14% - 18% 18.97ms - 23.82ms	slower ❌ 13% - 18% 17.68ms - 22.91ms	-

reactive-element-list

• Browser: chrome-headless 96.0.4664.45
• Sample size: 50
• Built by: Benchmarks #2110

• Commit: fe2f1c6

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	55.49ms - 56.81ms	-	unsure 🔍 -1% - +2% -0.67ms - +1.21ms	unsure 🔍 -3% - +0% -1.69ms - +0.25ms
tip-of-tree tip-of-tree	55.21ms - 56.55ms	unsure 🔍 -2% - +1% -1.21ms - +0.67ms	-	faster ✔ 0% - 3% 0.02ms - 1.97ms
previous-release previous-release	56.16ms - 57.58ms	unsure 🔍 -0% - +3% -0.25ms - +1.69ms	slower ❌ 0% - 4% 0.02ms - 1.97ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	841.34ms - 858.65ms	-	unsure 🔍 -1% - +2% -9.94ms - +13.18ms	unsure 🔍 -1% - +1% -11.84ms - +11.59ms
tip-of-tree tip-of-tree	840.71ms - 856.04ms	unsure 🔍 -2% - +1% -13.18ms - +9.94ms	-	unsure 🔍 -1% - +1% -12.75ms - +9.26ms
previous-release previous-release	842.22ms - 858.02ms	unsure 🔍 -1% - +1% -11.59ms - +11.84ms	unsure 🔍 -1% - +2% -9.26ms - +12.75ms	-

update-reflect

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	964.61ms - 981.68ms	-	unsure 🔍 -1% - +1% -9.64ms - +13.69ms	unsure 🔍 -1% - +2% -8.00ms - +15.69ms
tip-of-tree tip-of-tree	963.17ms - 979.06ms	unsure 🔍 -1% - +1% -13.69ms - +9.64ms	-	unsure 🔍 -1% - +1% -9.61ms - +13.24ms
previous-release previous-release	961.09ms - 977.51ms	unsure 🔍 -2% - +1% -15.69ms - +8.00ms	unsure 🔍 -1% - +1% -13.24ms - +9.61ms	-

_{tachometer-reporter-action v2 for Benchmarks}

[kevinpschaaf]

Small nits.