feat(hydrate): extended hydrateDocument to include serializeShadowRoot opt

Armand-Lluka · Armand-Lluka · commit 09327e097830 · 2025-05-22T19:12:10.000+02:00
diff --git a/src/declarations/stencil-public-compiler.ts b/src/declarations/stencil-public-compiler.ts
@@ -902,6 +902,34 @@ export interface HydrateDocumentOptions {
    * Sets `navigator.userAgent`
    */
   userAgent?: string;
+  /**
+   * Configure how Stencil serializes the components shadow root.
+   * - If set to `declarative-shadow-dom` the component will be rendered within a Declarative Shadow DOM.
+   * - If set to `scoped` Stencil will render the contents of the shadow root as a `scoped: true` component
+   *   and the shadow DOM will be created during client-side hydration.
+   * - Alternatively you can mix and match the two by providing an object with `declarative-shadow-dom` and `scoped` keys,
+   * the value arrays containing the tag names of the components that should be rendered in that mode.
+   *
+   * Examples:
+   * - `{ 'declarative-shadow-dom': ['my-component-1', 'another-component'], default: 'scoped' }`
+   * Render all components as `scoped` apart from `my-component-1` and `another-component`
+   * -  `{ 'scoped': ['an-option-component'], default: 'declarative-shadow-dom' }`
+   * Render all components within `declarative-shadow-dom` apart from `an-option-component`
+   * - `'scoped'` Render all components as `scoped`
+   * - `false` disables shadow root serialization
+   *
+   * *NOTE* `true` has been deprecated in favor of `declarative-shadow-dom` and `scoped`
+   * @default 'declarative-shadow-dom'
+   */
+  serializeShadowRoot?:
+    | 'declarative-shadow-dom'
+    | 'scoped'
+    | {
+        'declarative-shadow-dom'?: string[];
+        scoped?: string[];
+        default: 'declarative-shadow-dom' | 'scoped';
+      }
+    | boolean;
 }
 
 export interface SerializeDocumentOptions extends HydrateDocumentOptions {
diff --git a/src/hydrate/runner/render.ts b/src/hydrate/runner/render.ts
@@ -70,6 +70,11 @@ export function hydrateDocument(
   asStream?: boolean,
 ): Promise<HydrateResults> | Readable {
   const opts = normalizeHydrateOptions(options);
+  /**
+   * Defines whether we render the shadow root as a declarative shadow root or as scoped shadow root.
+   */
+  opts.serializeShadowRoot =
+    typeof opts.serializeShadowRoot === 'undefined' ? 'declarative-shadow-dom' : opts.serializeShadowRoot;
 
   let win: MockWindow | null = null;
   const results = generateHydrateResults(opts);
diff --git a/test/end-to-end/src/declarative-shadow-dom/test.e2e.ts b/test/end-to-end/src/declarative-shadow-dom/test.e2e.ts
@@ -30,6 +30,7 @@ type HydrateModule = typeof import('../../hydrate');
 let renderToString: HydrateModule['renderToString'];
 let streamToString: HydrateModule['streamToString'];
 let hydrateDocument: HydrateModule['hydrateDocument'];
+let createWindowFromHtml: HydrateModule['createWindowFromHtml'];
 
 describe('renderToString', () => {
   beforeAll(async () => {
@@ -38,6 +39,7 @@ describe('renderToString', () => {
     renderToString = mod.renderToString;
     streamToString = mod.streamToString;
     hydrateDocument = mod.hydrateDocument;
+    createWindowFromHtml = mod.createWindowFromHtml;
   });
 
   it('resolves to a Promise<HydrateResults> by default', async () => {
@@ -379,4 +381,32 @@ describe('renderToString', () => {
   </nested-cmp-child>
 </nested-cmp-parent>`);
   });
+
+  describe('hydrateDocument', () => {
+    it('can hydrate components with open shadow dom by default', async () => {
+      const template = `<another-car-detail></another-car-detail>`;
+      const fullHTML = `<html><head></head><body>${template}</body></html>`;
+      const win = createWindowFromHtml(fullHTML, Math.random().toString());
+      const document = win.document;
+      await hydrateDocument(document);
+      const html = document.documentElement.outerHTML;
+
+      expect(html).toContain('shadowrootmode="open"');
+      expect(html).not.toContain('sc-');
+    });
+
+    it('can hydrate components with scoped shadow dom', async () => {
+      const template = `<another-car-detail></another-car-detail>`;
+      const fullHTML = `<html><head></head><body>${template}</body></html>`;
+      const win = createWindowFromHtml(fullHTML, Math.random().toString());
+      const document = win.document;
+      await hydrateDocument(document, {
+        serializeShadowRoot: 'scoped',
+      });
+      const html = document.documentElement.outerHTML;
+
+      expect(html).not.toContain('shadowrootmode="open"');
+      expect(html).toContain('sc-');
+    });
+  });
 });
