[doc] Document context packages ContextRoot

[AndrewJakubowicz]

While making the basic context example I ran into a footgun with element upgrade order or import order.

I made this example: https://lit.dev/playground/#gist=3ddd4d9368a408508f88a5ae328478a3

However due to the timing of component upgrading, the provider didn't work inside the <slot>, which confused me.

Having two script imports in the example fixed the issue, e.g.:

  <script type="module" src="provider-element.js"></script>
  <script type="module" src="consumer-element.js"></script>

But swapping the imports would again break the slotted consumer.

The fix for this situation is to add a ContextRoot and attach it to document.body.

Solution

ContextRoot is already documented: https://lit.dev/docs/data/context/#contextroot, however I think it could use some documentation above the API section with why you should use it and the tradeoffs.