[Refactor/Tests] verify components in SSR

[maxpatiiuk]

Priority impact

p - medium

Test type

SSR

Which Component(s)

all

Unstable Tests

[not actionable before the migration]

When Stencil component is rendered in the Hydrate build, Stencil was providing mocks for a lot of dom APIs. (source code)

When Lit elements are rendered in SSR, Lit also provides a mock dom API, but it's much more lightweight (source code 1, source code 2)

That means that if before Stencil would mock the element.closest() calls in SSR, these are no longer mocked in Lit. This may cause some Calcite components to start failing in SSR after migration (with errors like element.closest is not a function)

Options:

• After the migration, manually test each Calcite component in SSR
• After the migration, setup automated SSR test for each component
• Look for an alternative DOM API shim (or maybe continue using Stencil's shim if that is possible) so that most DOM APIs are still covered. Cons: complexity and slower SSR
• If you really need some DOM APIs in Node.js, the Lit team would likely be open to contributions

When you identify a place where a DOM API that is not available in SSR is accessed, you have a few options:

• Use optional chaining for property/methods:

  - const parent = element.closest("calcite-tree");
  + const parent = element.closest?.("calcite-tree");

• Use globalThis with optional chaining for global APIs:

  - const userAgent = navigator.userAgent;
  + const userAgent = globalThis.navigator?.userAgent;

• Conditionally execute code in browser environment only:

  import {isServer} from 'lit';
  
  if (isServer) {
    // only runs in server environments like Node
  } else {
    // runs in the browser
  }

  • I know that Calcite had issues in the past with the isBrowser check that Stencil provided. The Stencil check was based on presence/absence of DOM globals like window.navigator and etc. Lit's check instead is determined at build-time. That works thanks to a feature called export conditions (this let's Lit set that variable to true in the node.js build, and false in the browser build)

• Tell consumers of Calcite components in SSR that they need to have happy-dom or jsdom environment setup to correctly render Calcite components.

Lit docs:

• Authoring components with SSR in mind
• DOM emulation in SSR

Test error, if applicable

No response

PR skipped, if applicable

No response

Additional Info

No response

[jcfranco]

Blocked by #10310.