Adds optional error callback to customElement decorator; provides define helper

[sorvell]

Fixes #4455.

• Adds optional error callback to customElements decorator.
• Provides a define helper with an optional error callback for javascript use.
• Provides a warn error callback which issues a console.warn
• Provides a warnPackageVersion error callback which issues a console.warn when an incompatible package and/or version is defined.
• A provided error callback is called with the error, tagName, and constructor when customElements.deine fails; providing any error callback catches the define exception.

[changeset-bot]

🦋 Changeset detected

Latest commit: b82e78e

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

This PR includes changesets to release 3 packages

Name	Type
@lit/reactive-element	Patch
lit	Patch
lit-element	Patch

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

• this-change, tip-of-tree, previous-release: faster ✔ 2% - 9% (0.17ms - 1.08ms)
  ^{this-change vs tip-of-tree}

render

• this-change: 47.50ms - 49.86ms
• this-change, tip-of-tree, previous-release: unsure 🔍 -5% - +3% (-1.03ms - +0.56ms)
  ^{this-change vs tip-of-tree}
• this-change, tip-of-tree, previous-release: unsure 🔍 -2% - +2% (-0.77ms - +0.73ms)
  ^{this-change vs tip-of-tree}
• this-change, tip-of-tree, previous-release: unsure 🔍 -1% - +2% (-0.32ms - +0.81ms)
  ^{this-change vs tip-of-tree}

update

• this-change: 498.68ms - 512.90ms
• this-change, tip-of-tree, previous-release: faster ✔ 0% - 11% (0.03ms - 4.66ms)
  ^{this-change vs tip-of-tree}
• this-change, tip-of-tree, previous-release: unsure 🔍 -1% - +1% (-0.86ms - +0.70ms)
  ^{this-change vs tip-of-tree}
• this-change, tip-of-tree, previous-release: unsure 🔍 -1% - +0% (-5.97ms - +1.25ms)
  ^{this-change vs tip-of-tree}

update-reflect

• this-change: 497.88ms - 504.75ms
• this-change, tip-of-tree, previous-release: unsure 🔍 -1% - +0% (-3.90ms - +2.25ms)
  ^{this-change vs tip-of-tree}

Results

this-change

• Browser: chrome-headless 120.0.6099.109
• Sample size: 50
• Built by: Benchmarks #5960

• Commit: 4bf2e57

render

Version	Avg time	vs
	47.50ms - 49.86ms	-

update

Version	Avg time	vs
	498.68ms - 512.90ms	-

update-reflect

Version	Avg time	vs
	497.88ms - 504.75ms	-

this-change, tip-of-tree, previous-release

• Browser: chrome-headless 120.0.6099.109
• Sample size: 30
• Built by: Benchmarks #5960

• Commit: 4bf2e57

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	17.79ms - 19.09ms	-	unsure 🔍 -5% - +3% -1.03ms - +0.56ms	unsure 🔍 -8% - +2% -1.60ms - +0.34ms
tip-of-tree tip-of-tree	18.21ms - 19.13ms	unsure 🔍 -3% - +6% -0.56ms - +1.03ms	-	unsure 🔍 -7% - +2% -1.26ms - +0.46ms
previous-release previous-release	18.34ms - 19.79ms	unsure 🔍 -2% - +9% -0.34ms - +1.60ms	unsure 🔍 -3% - +7% -0.46ms - +1.26ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	36.52ms - 39.66ms	-	faster ✔ 0% - 11% 0.03ms - 4.66ms	faster ✔ 0% - 12% 0.08ms - 5.09ms
tip-of-tree tip-of-tree	38.73ms - 42.14ms	unsure 🔍 -0% - +12% +0.03ms - +4.66ms	-	unsure 🔍 -7% - +6% -2.83ms - +2.35ms
previous-release previous-release	38.72ms - 42.63ms	slower ❌ 0% - 14% 0.08ms - 5.09ms	unsure 🔍 -6% - +7% -2.35ms - +2.83ms	-

nop-update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	10.39ms - 11.05ms	-	faster ✔ 2% - 9% 0.17ms - 1.08ms	faster ✔ 3% - 10% 0.27ms - 1.18ms
tip-of-tree tip-of-tree	11.04ms - 11.66ms	slower ❌ 1% - 10% 0.17ms - 1.08ms	-	unsure 🔍 -5% - +3% -0.54ms - +0.34ms
previous-release previous-release	11.13ms - 11.76ms	slower ❌ 2% - 11% 0.27ms - 1.18ms	unsure 🔍 -3% - +5% -0.34ms - +0.54ms	-

this-change, tip-of-tree, previous-release

• Browser: chrome-headless 120.0.6099.109
• Sample size: 50
• Built by: Benchmarks #5960

• Commit: 4bf2e57

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	32.86ms - 33.81ms	-	unsure 🔍 -2% - +2% -0.77ms - +0.73ms	unsure 🔍 -2% - +2% -0.78ms - +0.57ms
tip-of-tree tip-of-tree	32.77ms - 33.94ms	unsure 🔍 -2% - +2% -0.73ms - +0.77ms	-	unsure 🔍 -3% - +2% -0.84ms - +0.67ms
previous-release previous-release	32.96ms - 33.92ms	unsure 🔍 -2% - +2% -0.57ms - +0.78ms	unsure 🔍 -2% - +3% -0.67ms - +0.84ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	66.79ms - 67.81ms	-	unsure 🔍 -1% - +1% -0.86ms - +0.70ms	unsure 🔍 -2% - +1% -1.31ms - +0.39ms
tip-of-tree tip-of-tree	66.79ms - 67.96ms	unsure 🔍 -1% - +1% -0.70ms - +0.86ms	-	unsure 🔍 -2% - +1% -1.27ms - +0.52ms
previous-release previous-release	67.08ms - 68.43ms	unsure 🔍 -1% - +2% -0.39ms - +1.31ms	unsure 🔍 -1% - +2% -0.52ms - +1.27ms	-

this-change, tip-of-tree, previous-release

• Browser: chrome-headless 120.0.6099.109
• Sample size: 50
• Built by: Benchmarks #5960

• Commit: 4bf2e57

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	32.26ms - 33.15ms	-	unsure 🔍 -1% - +2% -0.32ms - +0.81ms	unsure 🔍 -1% - +2% -0.42ms - +0.78ms
tip-of-tree tip-of-tree	32.12ms - 32.80ms	unsure 🔍 -2% - +1% -0.81ms - +0.32ms	-	unsure 🔍 -2% - +1% -0.59ms - +0.46ms
previous-release previous-release	32.12ms - 32.92ms	unsure 🔍 -2% - +1% -0.78ms - +0.42ms	unsure 🔍 -1% - +2% -0.46ms - +0.59ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	493.77ms - 497.74ms	-	unsure 🔍 -1% - +0% -5.97ms - +1.25ms	unsure 🔍 -1% - +0% -4.49ms - +2.46ms
tip-of-tree tip-of-tree	495.10ms - 501.12ms	unsure 🔍 -0% - +1% -1.25ms - +5.97ms	-	unsure 🔍 -1% - +1% -2.80ms - +5.49ms
previous-release previous-release	493.91ms - 499.62ms	unsure 🔍 -0% - +1% -2.46ms - +4.49ms	unsure 🔍 -1% - +1% -5.49ms - +2.80ms	-

update-reflect

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	501.76ms - 505.55ms	-	unsure 🔍 -1% - +0% -3.90ms - +2.25ms	unsure 🔍 -1% - +0% -6.12ms - +2.18ms
tip-of-tree tip-of-tree	502.05ms - 506.90ms	unsure 🔍 -0% - +1% -2.25ms - +3.90ms	-	unsure 🔍 -1% - +1% -5.57ms - +3.27ms
previous-release previous-release	501.93ms - 509.32ms	unsure 🔍 -0% - +1% -2.18ms - +6.12ms	unsure 🔍 -1% - +1% -3.27ms - +5.57ms	-

_{tachometer-reporter-action v2 for Benchmarks}

[github-actions]

The size of lit-html.js and lit-core.min.js are as expected.

[augustjk]

This is a new feature so maybe it warrants a minor bump rather than patch?

Suggested change

	---
	'@lit/reactive-element': patch
	'lit': patch
	'lit-element': patch
	---
	---
	'@lit/reactive-element': minor
	'lit': minor
	'lit-element': minor
	---

[augustjk]

This could be used by users that aren't using the decorator but they'd have to import it from lit/decorators/custom-element.js or lit/decorators.js.

Would it maybe make sense to move define, warn, and warnPackabeVErsion to a separate submodule like @lit/reactive-element/define.js, which will be mirrored in lit-element and lit?