[doc] Document `context` packages ContextRoot

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.

Start at the ContextRoot documentation page linked in the issue and read the existing API section alongside the linked playground example. Add introductory guidance explaining why to use ContextRoot, the element or import-order problem it addresses, and its tradeoffs; done means the page clearly prepares readers before the API reference.