feat: Clarify keyed lists behavior

[maxpatiiuk]

[Regarding the page on lit-html Lists]

Coming from React and Stencil, I have been using this pattern in Lit:

myList.map(item=>
  keyed(item.key, html`...`)
)

(which is similar to myList.map(item=><item key={item.key} ...> you would do in React and Stencil)

After reading Lit's source code, I realized that this is actually wrong and inefficient as it will not move the DOM nodes in response to myList items changing order, and instead re-create the DOM elements from scratch

1. It might be just me, but explicitly calling out the above as wrong in the docs may be a good idea for transplants from other frameworks, and mentioning that repeat() should be used instead
   • for new user this is a bit confusing - i.e why does map() directive exists at all when Array.prototype.map does the job, and with less overhead? though a few other Lit directives like ifDefined() and when() are kind of needless API bloat too
2. Or better, would be nice if lit-html adds support for the above pattern and treats it equivalent to calling repeat() (which, I can understand may be undesirable as it would require you to always bundle repeat() even if not used).
   • As a workaround, for now I augmented my JSX->lit-html transformer to automatically convert code like myList.map(item=><item key={item.key} ...> into repeat(myList,item=>item.key,item=>html`<item ...>`