From 2a34a55b5ed8cc761a70a32caef895e984a1c0fa Mon Sep 17 00:00:00 2001 From: Steven Spriggs Date: Thu, 6 Aug 2026 16:18:14 -0400 Subject: [PATCH 1/7] feat: allow connectedCallback calls to be filtered in SSR --- .changeset/lost-days-sick.md | 13 +++++++++++++ .changeset/poor-sky-blue.md | 15 +++++++++++++++ core/pfe-core/ssr-shims.ts | 10 ++++++++-- package-lock.json | 16 ++++++++-------- tools/pfe-tools/package.json | 2 +- tools/pfe-tools/ssr/global.ts | 6 +++++- 6 files changed, 50 insertions(+), 12 deletions(-) create mode 100644 .changeset/lost-days-sick.md create mode 100644 .changeset/poor-sky-blue.md diff --git a/.changeset/lost-days-sick.md b/.changeset/lost-days-sick.md new file mode 100644 index 0000000000..18415e294f --- /dev/null +++ b/.changeset/lost-days-sick.md @@ -0,0 +1,13 @@ +--- +"@patternfly/pfe-core": minor +--- + +`ssrCallConnectedCallback`: exported from `ssr-shims.js`, replacing the deprecated `globalThis.litSsrCallConnectedCallback` global. Pass a predicate to limit which elements receive `connectedCallback` during SSR, or omit it to opt in all elements. + +```typescript +import { ssrCallConnectedCallback } from '@patternfly/pfe-core/ssr-shims.js'; + +ssrCallConnectedCallback(el => + el.localName.startsWith('pf-') || el.localName.startsWith('rh-') +); +``` diff --git a/.changeset/poor-sky-blue.md b/.changeset/poor-sky-blue.md new file mode 100644 index 0000000000..407dbc2479 --- /dev/null +++ b/.changeset/poor-sky-blue.md @@ -0,0 +1,15 @@ +--- +"@patternfly/pfe-tools": minor +--- + +`renderGlobal`: third `connectedCallbackFilter` parameter limits which elements receive `connectedCallback` during SSR. Without it, all elements opt in. + +```typescript +import { renderGlobal } from '@patternfly/pfe-tools/ssr/global.js'; + +const html = await renderGlobal( + '', + ['my-package/my-el.js'], + el => el.localName.startsWith('my-'), +); +``` diff --git a/core/pfe-core/ssr-shims.ts b/core/pfe-core/ssr-shims.ts index 32d0168960..7eef70229a 100644 --- a/core/pfe-core/ssr-shims.ts +++ b/core/pfe-core/ssr-shims.ts @@ -1,4 +1,5 @@ import { installWindowOnGlobal } from '@lit-labs/ssr/lib/dom-shim.js'; +import { LitElementRenderer } from '@lit-labs/ssr/lib/lit-element-renderer.js'; class ObserverShim { observe(): void { @@ -30,8 +31,13 @@ function getComputedStyle() { }; }; -// @ts-expect-error: opt in to event support in ssr -globalThis.litSsrCallConnectedCallback = true; +export function ssrCallConnectedCallback( + predicate: (element: { localName: string }) => boolean = () => true, +): void { + LitElementRenderer.renderOptions.push( + element => predicate(element) ? { connectedCallback: true } : undefined, + ); +} installWindowOnGlobal({ ErrorEvent: Event, diff --git a/package-lock.json b/package-lock.json index e6e5f2b58b..962b137401 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1906,14 +1906,14 @@ } }, "node_modules/@lit-labs/ssr": { - "version": "4.0.0", - "resolved": "https://registry.npmjs.org/@lit-labs/ssr/-/ssr-4.0.0.tgz", - "integrity": "sha512-pODr+t7cZVIrCRLuSLuWAACDnztEk5IrRFwFsbxyAyWcP2XP8aKuUZdVM/biXqxvIyHyCKtNZ92Gdcr+pjA5BQ==", + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/@lit-labs/ssr/-/ssr-4.1.0.tgz", + "integrity": "sha512-m0zymVVlHB1ddJQ1lastsV8ROW3whFOiHJhVPQWd04MnGTkTlUUVLQctux1QlyD9BtLXNN6iASxv388vhgKMFg==", "license": "BSD-3-Clause", "peer": true, "dependencies": { "@lit-labs/ssr-client": "^1.1.7", - "@lit-labs/ssr-dom-shim": "^1.5.0", + "@lit-labs/ssr-dom-shim": "^1.6.0", "@lit/reactive-element": "^2.0.4", "@parse5/tools": "^0.3.0", "enhanced-resolve": "^5.10.0", @@ -1948,9 +1948,9 @@ } }, "node_modules/@lit-labs/ssr-dom-shim": { - "version": "1.5.1", - "resolved": "https://registry.npmjs.org/@lit-labs/ssr-dom-shim/-/ssr-dom-shim-1.5.1.tgz", - "integrity": "sha512-Aou5UdlSpr5whQe8AA/bZG0jMj96CoJIWbGfZ91qieWu5AWUMKw8VR/pAkQkJYvBNhmCcWnZlyyk5oze8JIqYA==", + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/@lit-labs/ssr-dom-shim/-/ssr-dom-shim-1.6.0.tgz", + "integrity": "sha512-VHb0ALPMTlgKjM6yIxxoQNnpKyUKLD04VzeQdsiXkMqkvYlAHxq9glGLmgbb889/1GsohSOAjvQYoiBppXFqrQ==", "license": "BSD-3-Clause" }, "node_modules/@lit/context": { @@ -16022,7 +16022,7 @@ "@11ty/eleventy-plugin-syntaxhighlight": "^5.0.2", "@changesets/cli": "^2.29.8", "@koa/router": "^15.1.1", - "@lit-labs/ssr": "^4.0.0", + "@lit-labs/ssr": "^4.1.0", "@open-wc/testing": "^4.0.0", "@playwright/test": "~1.57.0", "@pwrs/mappa": "^0.0.4", diff --git a/tools/pfe-tools/package.json b/tools/pfe-tools/package.json index 9951194275..c604a1514b 100644 --- a/tools/pfe-tools/package.json +++ b/tools/pfe-tools/package.json @@ -68,7 +68,7 @@ "@11ty/eleventy-plugin-syntaxhighlight": "^5.0.2", "@changesets/cli": "^2.29.8", "@koa/router": "^15.1.1", - "@lit-labs/ssr": "^4.0.0", + "@lit-labs/ssr": "^4.1.0", "@open-wc/testing": "^4.0.0", "@playwright/test": "~1.57.0", "@pwrs/mappa": "^0.0.4", diff --git a/tools/pfe-tools/ssr/global.ts b/tools/pfe-tools/ssr/global.ts index eecb84a620..e23b5a7a48 100644 --- a/tools/pfe-tools/ssr/global.ts +++ b/tools/pfe-tools/ssr/global.ts @@ -3,14 +3,18 @@ * first importing the provided component defintions into nodejs' global scope. * @param html string to render * @param importSpecifiers list of web component definition module import specifiers + * @param connectedCallbackFilter optional predicate to limit which elements + * receive `connectedCallback` during SSR. Defaults to all elements. */ export async function renderGlobal( html: string, importSpecifiers: string[], + connectedCallbackFilter?: (element: { localName: string }) => boolean, ): Promise { // hack to avoid circular typescript project reference const spec = '@patternfly/pfe-core/ssr-shims.js'; - await import(spec); + const { ssrCallConnectedCallback } = await import(spec); + ssrCallConnectedCallback(connectedCallbackFilter); const { ssr } = await import('./ssr.js'); await Promise.all(importSpecifiers.map(x => import(x))); return ssr(html); From 9386406cfabe4367b2cc1ca7f231628c2581f931 Mon Sep 17 00:00:00 2001 From: Steven Spriggs Date: Thu, 20 Aug 2026 10:11:02 -0400 Subject: [PATCH 2/7] fix(core): preserve default connectedcallback opt-in on ssr-shims import --- core/pfe-core/ssr-shims.ts | 33 ++++++++++++++++++++++++++++++--- 1 file changed, 30 insertions(+), 3 deletions(-) diff --git a/core/pfe-core/ssr-shims.ts b/core/pfe-core/ssr-shims.ts index 7eef70229a..682a98e2ca 100644 --- a/core/pfe-core/ssr-shims.ts +++ b/core/pfe-core/ssr-shims.ts @@ -31,14 +31,41 @@ function getComputedStyle() { }; }; +type RenderOption = (typeof LitElementRenderer.renderOptions)[number]; + +/** Callback this module last registered on `LitElementRenderer.renderOptions`. */ +let registered: RenderOption | undefined; + +/** + * Opt elements into `connectedCallback` during SSR. + * Importing this module registers a default that matches all elements, so a + * bare `import '@patternfly/pfe-core/ssr-shims.js'` keeps the previous behavior. + * A later call with a predicate replaces that default. + * Lit evaluates `renderOptions` first-match, so a second push would never + * restrict the set. + * @param predicate return true for elements that should receive `connectedCallback` + */ export function ssrCallConnectedCallback( predicate: (element: { localName: string }) => boolean = () => true, ): void { - LitElementRenderer.renderOptions.push( - element => predicate(element) ? { connectedCallback: true } : undefined, - ); + const option: RenderOption = element => + predicate(element) ? { connectedCallback: true } : undefined; + + if (registered) { + const i = LitElementRenderer.renderOptions.indexOf(registered); + if (i !== -1) { + LitElementRenderer.renderOptions[i] = option; + registered = option; + return; + } + } + + registered = option; + LitElementRenderer.renderOptions.push(option); } +ssrCallConnectedCallback(); + installWindowOnGlobal({ ErrorEvent: Event, IntersectionObserver: ObserverShim, From 0e1b1719ea9e180777f107bff41f77f7ebd37ef8 Mon Sep 17 00:00:00 2001 From: Steven Spriggs Date: Thu, 20 Aug 2026 10:11:16 -0400 Subject: [PATCH 3/7] chore: update changeset --- .changeset/lost-days-sick.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.changeset/lost-days-sick.md b/.changeset/lost-days-sick.md index 18415e294f..36db6a0778 100644 --- a/.changeset/lost-days-sick.md +++ b/.changeset/lost-days-sick.md @@ -2,7 +2,7 @@ "@patternfly/pfe-core": minor --- -`ssrCallConnectedCallback`: exported from `ssr-shims.js`, replacing the deprecated `globalThis.litSsrCallConnectedCallback` global. Pass a predicate to limit which elements receive `connectedCallback` during SSR, or omit it to opt in all elements. +`ssrCallConnectedCallback`: filter which elements receive `connectedCallback` during SSR. Importing `ssr-shims.js` opts in all elements, matching the previous `globalThis.litSsrCallConnectedCallback` behavior. Pass a predicate to replace that default. ```typescript import { ssrCallConnectedCallback } from '@patternfly/pfe-core/ssr-shims.js'; From 837846e0cb3711c86f36ca0fe8d47b36e6fff45f Mon Sep 17 00:00:00 2001 From: Steven Spriggs Date: Thu, 20 Aug 2026 10:52:12 -0400 Subject: [PATCH 4/7] fix(core): guard against undefined predicate --- core/pfe-core/ssr-shims.ts | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/core/pfe-core/ssr-shims.ts b/core/pfe-core/ssr-shims.ts index 682a98e2ca..3a72c34184 100644 --- a/core/pfe-core/ssr-shims.ts +++ b/core/pfe-core/ssr-shims.ts @@ -46,10 +46,11 @@ let registered: RenderOption | undefined; * @param predicate return true for elements that should receive `connectedCallback` */ export function ssrCallConnectedCallback( - predicate: (element: { localName: string }) => boolean = () => true, + predicate?: (element: { localName: string }) => boolean, ): void { + const filter = predicate ?? (() => true); const option: RenderOption = element => - predicate(element) ? { connectedCallback: true } : undefined; + filter(element) ? { connectedCallback: true } : undefined; if (registered) { const i = LitElementRenderer.renderOptions.indexOf(registered); From 5204d8c300c1f0abaa585800d2ad41cb009c7302 Mon Sep 17 00:00:00 2001 From: Steven Spriggs Date: Thu, 20 Aug 2026 10:55:29 -0400 Subject: [PATCH 5/7] chore(core): improve changeset --- .changeset/lost-days-sick.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.changeset/lost-days-sick.md b/.changeset/lost-days-sick.md index 36db6a0778..053c2f33e0 100644 --- a/.changeset/lost-days-sick.md +++ b/.changeset/lost-days-sick.md @@ -2,7 +2,9 @@ "@patternfly/pfe-core": minor --- -`ssrCallConnectedCallback`: filter which elements receive `connectedCallback` during SSR. Importing `ssr-shims.js` opts in all elements, matching the previous `globalThis.litSsrCallConnectedCallback` behavior. Pass a predicate to replace that default. +`ssrCallConnectedCallback`: filter which elements receive `connectedCallback` during SSR. + +Importing `ssr-shims.js` still opts in all elements (matching the previous `globalThis.litSsrCallConnectedCallback` behavior). Call `ssrCallConnectedCallback` with a predicate to restrict the set: ```typescript import { ssrCallConnectedCallback } from '@patternfly/pfe-core/ssr-shims.js'; From fe037f9fcaa2785cf3a36f38dfef3b47c8380f26 Mon Sep 17 00:00:00 2001 From: Steven Spriggs Date: Thu, 12 Nov 2026 13:36:23 -0500 Subject: [PATCH 6/7] fix: address review feedback --- .changeset/lost-days-sick.md | 15 ++++++++---- .changeset/poor-sky-blue.md | 4 ++-- core/pfe-core/ssr-shims.ts | 44 +++++++++++++++++++++++++++++++---- tools/pfe-tools/ssr/global.ts | 23 ++++++++++++++---- 4 files changed, 71 insertions(+), 15 deletions(-) diff --git a/.changeset/lost-days-sick.md b/.changeset/lost-days-sick.md index 053c2f33e0..2ff0480e12 100644 --- a/.changeset/lost-days-sick.md +++ b/.changeset/lost-days-sick.md @@ -4,12 +4,19 @@ `ssrCallConnectedCallback`: filter which elements receive `connectedCallback` during SSR. -Importing `ssr-shims.js` still opts in all elements (matching the previous `globalThis.litSsrCallConnectedCallback` behavior). Call `ssrCallConnectedCallback` with a predicate to restrict the set: +Importing `ssr-shims.js` still opts in all elements (matching the previous `globalThis.litSsrCallConnectedCallback` behavior). Call `ssrCallConnectedCallback` with `include` and/or `exclude` predicates to restrict the set. `exclude` takes precedence when an element matches both: ```typescript import { ssrCallConnectedCallback } from '@patternfly/pfe-core/ssr-shims.js'; -ssrCallConnectedCallback(el => - el.localName.startsWith('pf-') || el.localName.startsWith('rh-') -); +ssrCallConnectedCallback({ + include: el => el.localName.startsWith('pf-') || el.localName.startsWith('rh-'), + exclude: el => el.localName === 'pf-icon', +}); +``` + +To opt out entirely, exclude every element: + +```typescript +ssrCallConnectedCallback({ exclude: () => true }); ``` diff --git a/.changeset/poor-sky-blue.md b/.changeset/poor-sky-blue.md index 407dbc2479..7c57b3af92 100644 --- a/.changeset/poor-sky-blue.md +++ b/.changeset/poor-sky-blue.md @@ -2,7 +2,7 @@ "@patternfly/pfe-tools": minor --- -`renderGlobal`: third `connectedCallbackFilter` parameter limits which elements receive `connectedCallback` during SSR. Without it, all elements opt in. +`renderGlobal`: third `connectedCallbackOptions` parameter limits which elements receive `connectedCallback` during SSR. Without it, all elements opt in. ```typescript import { renderGlobal } from '@patternfly/pfe-tools/ssr/global.js'; @@ -10,6 +10,6 @@ import { renderGlobal } from '@patternfly/pfe-tools/ssr/global.js'; const html = await renderGlobal( '', ['my-package/my-el.js'], - el => el.localName.startsWith('my-'), + { include: el => el.localName.startsWith('my-') }, ); ``` diff --git a/core/pfe-core/ssr-shims.ts b/core/pfe-core/ssr-shims.ts index 3a72c34184..6bd654f627 100644 --- a/core/pfe-core/ssr-shims.ts +++ b/core/pfe-core/ssr-shims.ts @@ -33,6 +33,24 @@ function getComputedStyle() { type RenderOption = (typeof LitElementRenderer.renderOptions)[number]; +type ElementPredicate = (element: { localName: string }) => boolean; + +/** Options for {@link ssrCallConnectedCallback}. */ +export interface SsrCallConnectedCallbackOptions { + /** + * Return true for elements that should receive `connectedCallback` during SSR. + * @default () => true + */ + include?: ElementPredicate; + + /** + * Return true for elements that should not receive `connectedCallback` during SSR. + * Takes precedence over {@link include}. + * @default () => false + */ + exclude?: ElementPredicate; +} + /** Callback this module last registered on `LitElementRenderer.renderOptions`. */ let registered: RenderOption | undefined; @@ -40,17 +58,33 @@ let registered: RenderOption | undefined; * Opt elements into `connectedCallback` during SSR. * Importing this module registers a default that matches all elements, so a * bare `import '@patternfly/pfe-core/ssr-shims.js'` keeps the previous behavior. - * A later call with a predicate replaces that default. + * A later call replaces that default. * Lit evaluates `renderOptions` first-match, so a second push would never * restrict the set. - * @param predicate return true for elements that should receive `connectedCallback` + * + * Elements matched by `exclude` never receive `connectedCallback` from this + * module, even when `include` also matches them. + * + * @example Restrict the opt-in to PatternFly and Red Hat elements + * ```ts + * ssrCallConnectedCallback({ + * include: el => el.localName.startsWith('pf-') || el.localName.startsWith('rh-'), + * exclude: el => el.localName === 'pf-icon', + * }); + * ``` + * @example Opt out entirely + * ```ts + * ssrCallConnectedCallback({ exclude: () => true }); + * ``` + * @param options which elements receive `connectedCallback` */ export function ssrCallConnectedCallback( - predicate?: (element: { localName: string }) => boolean, + options: SsrCallConnectedCallbackOptions = {}, ): void { - const filter = predicate ?? (() => true); + const include = options.include ?? (() => true); + const exclude = options.exclude ?? (() => false); const option: RenderOption = element => - filter(element) ? { connectedCallback: true } : undefined; + include(element) && !exclude(element) ? { connectedCallback: true } : undefined; if (registered) { const i = LitElementRenderer.renderOptions.indexOf(registered); diff --git a/tools/pfe-tools/ssr/global.ts b/tools/pfe-tools/ssr/global.ts index e23b5a7a48..a2df16837d 100644 --- a/tools/pfe-tools/ssr/global.ts +++ b/tools/pfe-tools/ssr/global.ts @@ -3,18 +3,33 @@ * first importing the provided component defintions into nodejs' global scope. * @param html string to render * @param importSpecifiers list of web component definition module import specifiers - * @param connectedCallbackFilter optional predicate to limit which elements - * receive `connectedCallback` during SSR. Defaults to all elements. + * @param connectedCallbackOptions which elements receive `connectedCallback` + * during SSR. Defaults to all elements. + * @param connectedCallbackOptions.include return true for elements that should receive `connectedCallback` + * @param connectedCallbackOptions.exclude return true for elements that should not receive `connectedCallback` + * @example Call `connectedCallback` only for elements whose tag starts with `my-` + * ```ts + * await renderGlobal(html, ['my-package/my-el.js'], { + * include: el => el.localName.startsWith('my-'), + * }); + * ``` + * @example Opt out entirely + * ```ts + * await renderGlobal(html, ['my-package/my-el.js'], { exclude: () => true }); + * ``` */ export async function renderGlobal( html: string, importSpecifiers: string[], - connectedCallbackFilter?: (element: { localName: string }) => boolean, + connectedCallbackOptions?: { + include?: (element: { localName: string }) => boolean; + exclude?: (element: { localName: string }) => boolean; + }, ): Promise { // hack to avoid circular typescript project reference const spec = '@patternfly/pfe-core/ssr-shims.js'; const { ssrCallConnectedCallback } = await import(spec); - ssrCallConnectedCallback(connectedCallbackFilter); + ssrCallConnectedCallback(connectedCallbackOptions); const { ssr } = await import('./ssr.js'); await Promise.all(importSpecifiers.map(x => import(x))); return ssr(html); From 79e3f2a2f8e0e6699c8cc66a3e5a6cb73af50e32 Mon Sep 17 00:00:00 2001 From: Steven Spriggs Date: Mon, 16 Nov 2026 11:40:00 -0500 Subject: [PATCH 7/7] fix(core): preserve existing SSR connectedCallback behavior by default --- .changeset/lost-days-sick.md | 4 ++- .changeset/poor-sky-blue.md | 2 +- core/pfe-core/ssr-shims.ts | 58 +++++++++++++++++++++++++++++------ tools/pfe-tools/ssr/global.ts | 3 +- 4 files changed, 54 insertions(+), 13 deletions(-) diff --git a/.changeset/lost-days-sick.md b/.changeset/lost-days-sick.md index 2ff0480e12..6e4bb7b5fe 100644 --- a/.changeset/lost-days-sick.md +++ b/.changeset/lost-days-sick.md @@ -4,7 +4,9 @@ `ssrCallConnectedCallback`: filter which elements receive `connectedCallback` during SSR. -Importing `ssr-shims.js` still opts in all elements (matching the previous `globalThis.litSsrCallConnectedCallback` behavior). Call `ssrCallConnectedCallback` with `include` and/or `exclude` predicates to restrict the set. `exclude` takes precedence when an element matches both: +Importing `ssr-shims.js`, or calling `ssrCallConnectedCallback()` with no options, keeps the previous behavior: every element opts in through the same `globalThis.litSsrCallConnectedCallback` flag earlier versions set, and this module adds nothing to `LitElementRenderer.renderOptions`. Existing `renderOptions` configuration (such as `disableSsr`) therefore keeps its order and precedence. + +Call `ssrCallConnectedCallback` with `include` and/or `exclude` predicates to restrict the set. Filtering clears the legacy flag (Lit ORs it with `renderOptions`, so it would otherwise override the filter) and registers a single `renderOptions` entry. `exclude` takes precedence when an element matches both: ```typescript import { ssrCallConnectedCallback } from '@patternfly/pfe-core/ssr-shims.js'; diff --git a/.changeset/poor-sky-blue.md b/.changeset/poor-sky-blue.md index 7c57b3af92..12d97958c7 100644 --- a/.changeset/poor-sky-blue.md +++ b/.changeset/poor-sky-blue.md @@ -2,7 +2,7 @@ "@patternfly/pfe-tools": minor --- -`renderGlobal`: third `connectedCallbackOptions` parameter limits which elements receive `connectedCallback` during SSR. Without it, all elements opt in. +`renderGlobal`: third `connectedCallbackOptions` parameter limits which elements receive `connectedCallback` during SSR. Without it, all elements opt in exactly as before, and existing `LitElementRenderer.renderOptions` configuration keeps its order and precedence. ```typescript import { renderGlobal } from '@patternfly/pfe-tools/ssr/global.js'; diff --git a/core/pfe-core/ssr-shims.ts b/core/pfe-core/ssr-shims.ts index 6bd654f627..369b77a414 100644 --- a/core/pfe-core/ssr-shims.ts +++ b/core/pfe-core/ssr-shims.ts @@ -54,13 +54,31 @@ export interface SsrCallConnectedCallbackOptions { /** Callback this module last registered on `LitElementRenderer.renderOptions`. */ let registered: RenderOption | undefined; +/** + * Set the legacy global flag Lit reads to opt every element in. + * Assigning through this helper keeps the property typed without augmenting + * the global type for consumers. + * @param value whether every element opts in + */ +function setLegacyConnectedCallbackFlag(value: boolean): void { + (globalThis as typeof globalThis & { litSsrCallConnectedCallback?: boolean }) + .litSsrCallConnectedCallback = value; +} + /** * Opt elements into `connectedCallback` during SSR. - * Importing this module registers a default that matches all elements, so a - * bare `import '@patternfly/pfe-core/ssr-shims.js'` keeps the previous behavior. - * A later call replaces that default. - * Lit evaluates `renderOptions` first-match, so a second push would never - * restrict the set. + * + * Called with no options, this keeps the previous behavior: every element + * receives `connectedCallback`. It does so through the same + * `globalThis.litSsrCallConnectedCallback` flag earlier versions set, and adds + * nothing to `LitElementRenderer.renderOptions`, so existing `renderOptions` + * configuration (such as `disableSsr`) keeps its order and precedence. + * + * Called with options, it filters which elements receive `connectedCallback`. + * The legacy global is cleared because Lit ORs it with `renderOptions`, so it + * would otherwise override the filter. A later call replaces this module's + * option in place, since Lit evaluates `renderOptions` first-match and a second + * push would never restrict the set. * * Elements matched by `exclude` never receive `connectedCallback` from this * module, even when `include` also matches them. @@ -76,20 +94,39 @@ let registered: RenderOption | undefined; * ```ts * ssrCallConnectedCallback({ exclude: () => true }); * ``` - * @param options which elements receive `connectedCallback` + * @param options which elements receive `connectedCallback`. Omit to opt every + * element in, as previous versions did. */ export function ssrCallConnectedCallback( - options: SsrCallConnectedCallbackOptions = {}, + options?: SsrCallConnectedCallbackOptions, ): void { + if (options === undefined) { + // Preserve the pre-filter behavior exactly: the legacy global opts every + // element in and renderOptions is left untouched. + setLegacyConnectedCallbackFlag(true); + if (registered) { + const index = LitElementRenderer.renderOptions.indexOf(registered); + if (index !== -1) { + LitElementRenderer.renderOptions.splice(index, 1); + } + registered = undefined; + } + return; + } + const include = options.include ?? (() => true); const exclude = options.exclude ?? (() => false); const option: RenderOption = element => include(element) && !exclude(element) ? { connectedCallback: true } : undefined; + // Lit checks the legacy global before renderOptions; clear it so the filter + // can actually narrow the set. + setLegacyConnectedCallbackFlag(false); + if (registered) { - const i = LitElementRenderer.renderOptions.indexOf(registered); - if (i !== -1) { - LitElementRenderer.renderOptions[i] = option; + const index = LitElementRenderer.renderOptions.indexOf(registered); + if (index !== -1) { + LitElementRenderer.renderOptions[index] = option; registered = option; return; } @@ -99,6 +136,7 @@ export function ssrCallConnectedCallback( LitElementRenderer.renderOptions.push(option); } +// Preserve the behavior of importing this module: opt every element in. ssrCallConnectedCallback(); installWindowOnGlobal({ diff --git a/tools/pfe-tools/ssr/global.ts b/tools/pfe-tools/ssr/global.ts index a2df16837d..34685bce28 100644 --- a/tools/pfe-tools/ssr/global.ts +++ b/tools/pfe-tools/ssr/global.ts @@ -4,7 +4,8 @@ * @param html string to render * @param importSpecifiers list of web component definition module import specifiers * @param connectedCallbackOptions which elements receive `connectedCallback` - * during SSR. Defaults to all elements. + * during SSR. Defaults to all elements, matching previous behavior and + * leaving existing `LitElementRenderer.renderOptions` configuration intact. * @param connectedCallbackOptions.include return true for elements that should receive `connectedCallback` * @param connectedCallbackOptions.exclude return true for elements that should not receive `connectedCallback` * @example Call `connectedCallback` only for elements whose tag starts with `my-`