Repository navigation
feat: allow connectedCallback calls to be filtered in SSR #3159
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
2a34a55
9386406
0e1b171
837846e
5204d8c
fe037f9
79e3f2a
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,24 @@ | ||
| --- | ||
| "@patternfly/pfe-core": minor | ||
| --- | ||
|
|
||
| `ssrCallConnectedCallback`: filter which elements receive `connectedCallback` during SSR. | ||
|
|
||
| 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'; | ||
|
|
||
| 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 }); | ||
| ``` | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,15 @@ | ||
| --- | ||
| "@patternfly/pfe-tools": minor | ||
| --- | ||
|
|
||
| `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'; | ||
|
|
||
| const html = await renderGlobal( | ||
| '<my-el></my-el>', | ||
| ['my-package/my-el.js'], | ||
| { include: el => el.localName.startsWith('my-') }, | ||
| ); | ||
| ``` |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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,113 @@ function getComputedStyle() { | |
| }; | ||
| }; | ||
|
|
||
| // @ts-expect-error: opt in to event support in ssr | ||
| globalThis.litSsrCallConnectedCallback = true; | ||
| 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; | ||
|
|
||
| /** | ||
| * 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. | ||
| * | ||
| * 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. | ||
| * | ||
| * @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`. Omit to opt every | ||
| * element in, as previous versions did. | ||
| */ | ||
| export function ssrCallConnectedCallback( | ||
|
zeroedin marked this conversation as resolved.
Resolved
|
||
| 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 index = LitElementRenderer.renderOptions.indexOf(registered); | ||
| if (index !== -1) { | ||
| LitElementRenderer.renderOptions[index] = option; | ||
| registered = option; | ||
| return; | ||
| } | ||
| } | ||
|
|
||
| registered = option; | ||
| LitElementRenderer.renderOptions.push(option); | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Declare the
Declare the renderer as an optional peer dependency. The shim is used only for SSR, so client-only consumers should not be forced to install it. Suggested fix
|
||
| } | ||
|
|
||
| // Preserve the behavior of importing this module: opt every element in. | ||
| ssrCallConnectedCallback(); | ||
|
|
||
| installWindowOnGlobal({ | ||
| ErrorEvent: Event, | ||
|
|
||
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Uh oh!
There was an error while loading. Please reload this page.