[docs] Add documentation for SSR event handling

[kyubisation]

This PR adds the relevant documentation for the functionality in lit/lit#4755

[bennypowers]

the overloaded constructor signature for ContextProvider is

  constructor(host: HostElement, options: Options<T>);
  /** @deprecated Use new ContextProvider(host, options) */
  constructor(host: HostElement, context: T, initialValue?: ContextType<T>);
  constructor(
    host: HostElement,
    contextOrOptions: T | Options<T>,
    initialValue?: ContextType<T>
  ) { /*...* }

ContextRoot does not have any constructor params.

Do you mean something like this?

  const root = new ContextRoot();
  if (!isServer) {
    root.attach(document.body);
  } else {
    root.attach(globalThis.litServerRoot);
  }

[kyubisation]

No, I am referring to the use case of registering a ContextProvider globally. (See https://www.npmjs.com/package/@lit/context and search for document.body)
ContextRoot should not be necessary in an SSR environment, as classes are loaded in order (from my understanding).

But thank you for pointing out, that my example is incomplete and easily misunderstood. I will extend it. 😄 👍

[e111077]

I think this section needs to focus a bit more on the information of "I am googling around and I just want to get this thing done where can I copy paste a solution" and then follow up with the explanation. So like questions a user might have:

• Does Context work in SSR?
• If so how do I do it?
• I am running into X error when I try to use Context in SSR, how do I fix it?
• Why is this the solution? (probably lower priority question they have)

So maybe rephrasing a bit backwards might help e.g.

// answer the questions
Lit SSR provides basic support for global and component-scoped context. Context in SSR requires that globalThis.litSsrCallConnectedCallback = true to be enabled. (insert link to docs on that)

// give a copy-pastable example

// server.ts
globalThis.litSsrCallConnectedCallback = true; // or however / wherever you're supposed to set this
...

// client.ts
import {isServer} from 'lit';
import {ContextProvider} from '@lit/context';
const globalRoot = isServer ? globalThis.litServerRoot : document.body;
new ContextProvider(globalRoot, {...});

// then include wonky explanation why
As DOM nodes like document.body are not typically available in the server environment, Lit SSR will provide globalThis.litServerRoot for event-emitting purposes. Additionally, Lit Context provides setup in the native web component connectedCallback lifecycle callback, so globalThis.litSsrCallConnectedCallback needs to be set to true to enable Lit SSR to include that callback in the server lifecycle.

To use Lit Context in a component, you can do the following:

// copy-pastable example

// I actually don't know, please provide

// wonky explanation why the code above is like that

[e111077]

Can you please give an example of this in this document?