feat: allow connectedCallback calls to be filtered in SSR

.changeset/lost-days-sick.md

@@ -0,0 +1,15 @@
+---
+"@patternfly/pfe-core": minor
+---
+
+`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';
+
+ssrCallConnectedCallback(el =>
+  el.localName.startsWith('pf-') || el.localName.startsWith('rh-')
+);
+```

.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-el></my-el>',
+  ['my-package/my-el.js'],
+  el => el.localName.startsWith('my-'),
+);
+```

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,41 @@ function getComputedStyle() {
   };
 };
 
-// @ts-expect-error: opt in to event support in ssr
-globalThis.litSsrCallConnectedCallback = true;
+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,
+): void {
+  const filter = predicate ?? (() => true);
+  const option: RenderOption = element =>
+    filter(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,

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",

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<string> {
   // 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);