From f0dbafd7b87911f567fbaebf6aab40d343f01fe4 Mon Sep 17 00:00:00 2001
From: Lukas Spirig <lukas.spirig@gmail.com>
Date: Fri, 10 Jan 2025 23:38:22 +0100
Subject: [PATCH] [docs] Add documentation for SSR event handling

---
 .../lit-dev-content/site/docs/v3/data/context.md  | 15 +++++++++++++++
 .../lit-dev-content/site/docs/v3/ssr/authoring.md |  4 ++--
 .../site/docs/v3/ssr/dom-emulation.md             |  5 +++--
 3 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/packages/lit-dev-content/site/docs/v3/data/context.md b/packages/lit-dev-content/site/docs/v3/data/context.md
index 150dfe1d6..ee2beb915 100644
--- a/packages/lit-dev-content/site/docs/v3/data/context.md
+++ b/packages/lit-dev-content/site/docs/v3/data/context.md
@@ -281,6 +281,21 @@ and the ContextConsumer controller:
   );
 ```
 
+### SSR
+
+Basic support for server side rendering can be enabled by assigning
+`globalThis.litSsrCallConnectedCallback = true`. This will configure `@lit-labs/ssr` to call
+`connectedCallback()` and `ReactiveController.hostConnected()`, which allows `@lit/context`
+to register the necessary event handlers for SSR.
+
+As an alternative to `document.documentElement` or `document.body` (which are expected to be undefined
+in the server environment) for global event listeners (e.g. for `@lit/context ContextProvider`), you can
+use the global variable `globalThis.litServerRoot` which is (only) available during SSR.
+
+```ts
+  new ContextProvider(isServer ? globalThis.litServerRoot : document.body, {...});
+```
+
 ## Example Use Cases
 
 ### Current user, locale, etc.
diff --git a/packages/lit-dev-content/site/docs/v3/ssr/authoring.md b/packages/lit-dev-content/site/docs/v3/ssr/authoring.md
index b62f7e475..badae7506 100644
--- a/packages/lit-dev-content/site/docs/v3/ssr/authoring.md
+++ b/packages/lit-dev-content/site/docs/v3/ssr/authoring.md
@@ -103,7 +103,7 @@ Whether a method is called on the server is subject to change while Lit SSR is p
 | Method | Called on server | Notes |
 |-|-|-|
 | `constructor()` | Yes ⚠️ | |
-| `connectedCallback()` | No | |
+| `connectedCallback()` | No | Can be enabled with `globalThis.litSsrCallConnectedCallback = true` |
 | `disconnectedCallback()` | No | |
 | `attributeChangedCallback()` | No | |
 | `adoptedCallback()` | No | |
@@ -119,7 +119,7 @@ Whether a method is called on the server is subject to change while Lit SSR is p
 | Method | Called on server | Notes |
 |-|-|-|
 | `constructor()` | Yes ⚠️ | |
-| `hostConnected()` | No | |
+| `hostConnected()` | No | Can be enabled with `globalThis.litSsrCallConnectedCallback = true` |
 | `hostDisconnected()` | No | |
 | `hostUpdate()` | No | |
 | `hostUpdated()` | No | |
diff --git a/packages/lit-dev-content/site/docs/v3/ssr/dom-emulation.md b/packages/lit-dev-content/site/docs/v3/ssr/dom-emulation.md
index fff9485f3..e7275cb88 100644
--- a/packages/lit-dev-content/site/docs/v3/ssr/dom-emulation.md
+++ b/packages/lit-dev-content/site/docs/v3/ssr/dom-emulation.md
@@ -17,7 +17,8 @@ When running in Node, Lit automatically imports and uses a set of DOM shims, and
 <!-- TODO(augustinekim) Consider replacing emojis below with icons https://github.com/lit/lit.dev/pull/880#discussion_r944821511 -->
 | Property | Notes |
 |-|-|
-| `Element` | ⚠️ Partial <table><tbody><tr><td>`attributes`</td><td>✅</td><tr><td>`shadowRoot`</td><td>⚠️ Returns `{host: this}` if `attachShadow()` was called with `{mode: 'open'}`</td><tr><td>`setAttribute()`</td><td>✅</td><tr><td>`removeAttribute()`</td><td>✅</td><tr><td>`hasAttribute()`</td><td>✅</td><tr><td>`attachShadow()`</td><td>⚠️ Returns `{host: this}`</td><tr><td>`getAttribute()`</td><td>✅</td></tr></tbody></table> |
-| `HTMLElement` | ⚠️ Empty class |
+| `EventTarget` | ⚠️ Partial <table><tbody><tr><td>`addEventListener()`</td><td>✅</td><tr><td>`removeEventListener()`</td><td>✅</td><tr><td>`dispatchEvent()`</td><td>✅</td></tr></tbody></table> |
+| `Element` | Inherits `EventTarget`<br> ⚠️ Partial <table><tbody><tr><td>`attributes`</td><td>✅</td><tr><td>`shadowRoot`</td><td>⚠️ Returns `{host: this}` if `attachShadow()` was called with `{mode: 'open'}`</td><tr><td>`setAttribute()`</td><td>✅</td><tr><td>`removeAttribute()`</td><td>✅</td><tr><td>`hasAttribute()`</td><td>✅</td><tr><td>`attachShadow()`</td><td>⚠️ Returns `{host: this}`</td><tr><td>`getAttribute()`</td><td>✅</td></tr></tbody></table> |
+| `HTMLElement` | Inherits `Element`<br> ⚠️ Empty class |
 | `CustomElementRegistry` | <table><tbody><tr><td>`define()`</td><td>✅</td></tr><tr><td>`get()`</td><td>✅</td></tr></tbody></table> |
 | `customElements` | Instance of `CustomElementRegistry` |