@podium/podlet 5.1.19 → 5.2.0-next.10

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [5.2.0-next.10](https://github.com/podium-lib/podlet/compare/v5.2.0-next.9...v5.2.0-next.10) (2024-11-06)
+
+
+### Bug Fixes
+
+* **deps:** update dependency @podium/proxy to v5.0.29 ([0bbc78b](https://github.com/podium-lib/podlet/commit/0bbc78b07a7f3059cb8f659a23c75896c1081b2f))
+
 ## [5.1.19](https://github.com/podium-lib/podlet/compare/v5.1.18...v5.1.19) (2024-11-04)
 
 

package/README.md

@@ -79,20 +79,23 @@ const podlet = new Podlet(options);
 
 ### options
 
-| option      | type      | default          | required |
-| ----------- | --------- | ---------------- | -------- |
-| name        | `string`  |                  | ✓  |
-| version     | `string`  |                  | ✓  |
-| pathname    | `string`  |                  | ✓  |
-| manifest    | `string`  | `/manifest.json` |          |
-| content     | `string`  | `/`              |          |
-| fallback    | `string`  |                  |          |
-| logger      | `object`  |                  |          |
-| development | `boolean` | `false`          |          |
+| option       | type      | default          | required |
+| ------------ | --------- | ---------------- | -------- |
+| name         | `string`  |                  | ✓  |
+| version      | `string`  |                  | ✓  |
+| pathname     | `string`  |                  | ✓  |
+| manifest     | `string`  | `/manifest.json` |          |
+| content      | `string`  | `/`              |          |
+| fallback     | `string`  |                  |          |
+| logger       | `object`  |                  |          |
+| development  | `boolean` | `false`          |          |
+| useShadowDOM | `boolean` | `false`          |          |
 
 #### name
 
-The name the podlet identifies itself by. This value must be in camelCase.
+The name the podlet identifies itself by. This value can contain upper and lower case letters, numbers, the - character and the \_ character. No spaces.
+When shadow DOM is used, either via the `useShadowDOM` constructor option or via the `wrapWithShadowDOM` method, the name must comply with custom element naming rules.
+See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define#valid_custom_element_names) for more information.
 
 _Example:_
 
@@ -257,6 +260,53 @@ further details.
 
 Turns development mode on or off. See the section about development mode.
 
+#### useShadowDOM
+
+Turns declarative shadow DOM encapsulation on for the podlet. When enabled, the podlet content will be wrapped inside a declarative shadow DOM wrapper to isolate it from the rest of whichever
+page it is being included on.
+
+```js
+const podlet = new Podlet({ ..., useShadowDOM: true });
+```
+
+Please note the following caveats when using this feature:
+
+1. You must name your podlet following custom element naming conventions as explained here: https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define#valid_custom_element_names
+2. In order to style your content, you will need to include your CSS inside the shadow DOM wrapper. You can do this using one of the following 2 options:
+
+You can include a `<style>` tag before your content
+
+```js
+res.podiumSend(`
+	<style>
+		...styles here...
+	</style>
+	<div>...content here...</div>
+`);
+```
+
+You can have your podlet CSS included for you by using the "shadow-dom" scope
+
+```js
+podlet.css({ value: '/path/to/css', scope: 'shadow-dom' });
+res.podiumSend(`
+	<div>...content here...</div>
+`);
+```
+
+For more fine grained control, you can use the `podlet.wrapWithShadowDOM` method directly
+
+```js
+const podlet = new Podlet({ ..., useShadowDOM: false });
+```
+
+```js
+const wrapped = podlet.wrapWithShadowDOM(`<div>...content here...</div>`);
+res.podiumSend(`
+	${wrapped}
+`);
+```
+
 ## Podlet Instance
 
 The podlet instance has the following API:
@@ -551,6 +601,8 @@ Sets the pathname for a podlet's javascript assets.
 When a value is set it will be internally kept and used when the podlet
 instance is serialized into a manifest JSON string.
 
+In addition, JS information will be serialized into a Link header and sent as an HTTP 103 early hint with content and fallback responses so that the layout client can get access to assets before the main podlet body. The layout can use this information to generate 103 early hints for the browser so that the browser can begin downloading asset files while still waiting for the podlet and layout bodys.
+
 ### options
 
 | option | type      | default   | required |
@@ -647,6 +699,8 @@ Sets the options for a podlet's CSS assets.
 When a value is set it will be internally kept and used when the podlet
 instance is serialized into a manifest JSON string.
 
+In addition, CSS information will be serialized into a Link header and sent as an HTTP 103 early hint with content and fallback responses so that the layout client can get access to assets before the main podlet body. The layout can use this information to generate 103 early hints for the browser so that the browser can begin downloading asset files while still waiting for the podlet and layout bodys.
+
 ### options
 
 | option | type      | default | required |

package/lib/podlet.js

@@ -7,12 +7,18 @@ import {
 import * as schema from '@podium/schemas';
 import Metrics from '@metrics/client';
 import abslog from 'abslog';
+// @ts-ignore
 import objobj from 'objobj';
 import * as utils from '@podium/utils';
 import Proxy from '@podium/proxy';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
+// @ts-ignore
 import fs from 'node:fs';
+import assert from 'node:assert';
+
+const customElementRegex =
+    /^(?!(annotation-xml|color-profile|font-face|font-face-src|font-face-uri|font-face-format|font-face-name|missing-glyph)$)[a-z][a-z0-9.-]*-[a-z0-9.-]*$/;
 
 const currentDirectory = dirname(fileURLToPath(import.meta.url));
 const pkgJson = fs.readFileSync(
@@ -25,19 +31,20 @@ const { template } = utils;
 
 /**
  * @typedef {Object} PodletOptions
- * @property {string} name - Podlet name
- * @property {string} version - Podlet version
- * @property {string} pathname - Podlet pathname
- * @property {string} [manifest="/manifest.json"] - Path where the podlet manifest file is served from.
- * @property {string} [content="/"] - Path where the podlet content HTML markup is served from.
- * @property {string} [fallback=""] - Path where the podlet fallback HTML markup is served from. By default there is no fallback. Set this to for instance `"/fallback"` to serve a cacheable version of the contents in case the podlet goes down.
- * @property {boolean} [development=false] - a boolean flag that, when true, enables additional development setup
- * @property {import('abslog').AbstractLoggerOptions} [logger] - a logger to use when provided. Can be the console object if console logging is desired but can also be any Log4j compatible logging object as well. Nothing is logged if no logger is provided.
+ * @property {string} name - (required) podlet name
+ * @property {string} version - (required) podlet version
+ * @property {string} pathname - (required) podlet pathname
+ * @property {string} [manifest="/manifest.json"] - path where the podlet manifest file is served from (default '/manifest.json')
+ * @property {string} [content="/"] - path where the podlet content HTML markup is served from (default '/')
+ * @property {string} [fallback=""] - path where the podlet fallback HTML markup is served from (default '/fallback')
+ * @property {boolean} [development=false] - a boolean flag that, when true, enables additional development setup (default false)
+ * @property {boolean} [useShadowDOM=false] - a boolean flag that, when true, enables the use of ShadowDOM (default false)
+ * @property {import("abslog").AbstractLoggerOptions} [logger] - a logger to use when provided. Can be the console object if console logging is desired but can also be any Log4j compatible logging object as well. Nothing is logged if no logger is provided. (default null)
  * @property {import("@podium/proxy").PodiumProxyOptions} [proxy] - options that can be provided to configure the @podium/proxy instance used by the podlet. See that module for details.
  *
  * @typedef {{ debug: 'true' | 'false', locale: string, deviceType: string, requestedBy: string, mountOrigin: string, mountPathname: string, publicPathname: string }} PodletContext
- * @typedef {{ as?: string | false | null, crossorigin?: string | null | boolean, disabled?: boolean | '' | null, hreflang?: string | false | null, title?: string | false | null, media?: string | false | null, rel?: string | false | null, type?: string | false | null, value: string | false | null, data?: Array<{ key: string; value: string }>, strategy?: "beforeInteractive" | "afterInteractive" | "lazy", scope?: "content" | "fallback" | "all", [key: string]: any }} AssetCssLike
- * @typedef {{ value: string | null, crossorigin?: string | null | boolean, type?: string | null | false, integrity?: string | null | false, referrerpolicy?: string | null | false, nomodule?: boolean | null | '', async?: boolean | null | '', defer?: boolean | null | '', data?: Array<{ key: string; value: string }>, strategy?: "beforeInteractive" | "afterInteractive" | "lazy", scope?: "content" | "fallback" | "all", [key: string]: any }} AssetJsLike
+ * @typedef {{ as?: string | false | null, crossorigin?: string | null | boolean, disabled?: boolean | '' | null, hreflang?: string | false | null, title?: string | false | null, media?: string | false | null, rel?: string | false | null, type?: string | false | null, value: string | false | null, strategy?: "beforeInteractive" | "afterInteractive" | "lazy" | "shadow-dom", scope?: "content" | "fallback" | "all", [key: string]: any }} AssetCssLike
+ * @typedef {{ value: string | null, crossorigin?: string | null | boolean, type?: string | null | false, integrity?: string | null | false, referrerpolicy?: string | null | false, nomodule?: boolean | null | '', async?: boolean | null | '', defer?: boolean | null | '', data?: {[key: string]: string} | Array<{ key: string; value: string }>, strategy?: "beforeInteractive" | "afterInteractive" | "lazy" | "shadow-dom", scope?: "content" | "fallback" | "all" | "shadow-dom", [key: string]: any }} AssetJsLike
  */
 
 export default class PodiumPodlet {
@@ -281,10 +288,26 @@ export default class PodiumPodlet {
      */
     metrics = new Metrics();
 
+    /**
+     * Boolean flag that, when true, enables the use of declarative ShadowDOM in the podlet.
+     */
+    #useShadowDOM = false;
+
     /**
      * Creates a new instance of a Podium podlet which can be used in conjunction with your framework of choice to build podlet server apps.
      * `name`, `version` and `pathname` constructor arguments are required. All other options are optional.
      *
+     * * `name` - podlet name (**required**)
+     * * `version` - podlet version (**required**)
+     * * `pathname` - podlet pathname (**required**)
+     * * `manifest` - path where the podlet manifest file is served from (**default** `'/manifest.json'`)
+     * * `content` - path where the podlet content HTML markup is served from (**default** `'/'`)
+     * * `fallback` - path where the podlet fallback HTML markup is served from (**default** `'/fallback'`)
+     * * `development` - a boolean flag that, when true, enables additional development setup (**default** `false`)
+     * * `useShadowDOM` - a boolean flag that, when true, enables the use of declarative ShadowDOM in the podlet (**default** `false`)
+     * * `logger` - a logger to use when provided. Can be the console object if console logging is desired but can also be any Log4j compatible logging object as well. Nothing is logged if no logger is provided. (**default** `null`)
+     * * `proxy` - options that can be provided to configure the @podium/proxy instance used by the podlet. See that module for details. (**default**: `{}`)
+     *
      * @see https://podium-lib.io/docs/api/podlet/#constructor
      * @see https://podium-lib.io/docs/podlet/getting_started
      *
@@ -305,6 +328,7 @@ export default class PodiumPodlet {
         logger = undefined,
         development = false,
         proxy = {},
+        useShadowDOM = false,
     }) {
         if (schema.name(name).error)
             throw new Error(
@@ -362,6 +386,7 @@ export default class PodiumPodlet {
                 this.name,
             ),
         };
+        this.#useShadowDOM = useShadowDOM;
 
         // Skip a tick to ensure the metric stream has been consumed
         setImmediate(() => {
@@ -517,9 +542,9 @@ export default class PodiumPodlet {
      * Takes an AssetCss instance or an object with equivalent properties, converts it to an AssetCss instance if necessary and adds it to the
      * cssRoute array.
      * @param { AssetCss | AssetCssLike } options
-     * @returns {void}
+     * @returns {AssetCss}
      */
-    #addCssAsset(options) {
+    #cssAsset(options) {
         const clonedOptions = JSON.parse(JSON.stringify(options));
         clonedOptions.value = this.#sanitize(
             clonedOptions.value,
@@ -530,7 +555,7 @@ export default class PodiumPodlet {
             ...clonedOptions,
             pathname: this.#pathname,
         };
-        this.cssRoute.push(new AssetCss(args));
+        return new AssetCss(args);
     }
 
     /**
@@ -555,20 +580,19 @@ export default class PodiumPodlet {
     css(options) {
         if (Array.isArray(options)) {
             for (const opts of options) {
-                this.#addCssAsset(opts);
+                this.cssRoute.push(this.#cssAsset(opts));
             }
             return;
         }
-        this.#addCssAsset(options);
+        this.cssRoute.push(this.#cssAsset(options));
     }
 
     /**
-     * Takes an AssetJs instance or an object with equivalent properties, converts it to an AssetJs instance if necessary and adds it to the
-     * jsRoute array.
+     * Takes an AssetJs instance or an object with equivalent properties, converts it to an AssetJs instance if necessary and returns it.
      * @param { AssetJs | AssetJsLike } options
-     * @returns {void}
+     * @returns {AssetJs}
      */
-    #addJsAsset(options) {
+    #jsAsset(options) {
         const clonedOptions = JSON.parse(JSON.stringify(options));
         clonedOptions.value = this.#sanitize(
             clonedOptions.value,
@@ -581,19 +605,31 @@ export default class PodiumPodlet {
             pathname: this.#pathname,
         };
 
-        // Convert data attribute object structure to array of key value objects
-        if (typeof args.data === 'object' && args.data !== null) {
-            const data = [];
-            Object.keys(args.data).forEach((key) => {
-                data.push({
-                    value: args.data[key],
-                    key,
+        if (args.data) {
+            // validate that key value objects provided are compliant
+            if (Array.isArray(args.data)) {
+                for (const data of args.data) {
+                    if (!data.key || !data.value) {
+                        throw new TypeError(
+                            `JS Asset data object "${JSON.stringify(data)}" must contain both a 'key' and a 'value' attribute.`,
+                        );
+                    }
+                }
+            }
+            // Convert data attribute object structure to array of key value objects
+            else if (typeof args.data === 'object') {
+                const data = [];
+                Object.keys(args.data).forEach((key) => {
+                    data.push({
+                        value: args.data[key],
+                        key,
+                    });
                 });
-            });
-            args.data = data;
+                args.data = data;
+            }
         }
 
-        this.jsRoute.push(new AssetJs(args));
+        return new AssetJs(args);
     }
 
     /**
@@ -618,11 +654,11 @@ export default class PodiumPodlet {
     js(options) {
         if (Array.isArray(options)) {
             for (const opts of options) {
-                this.#addJsAsset(opts);
+                this.jsRoute.push(this.#jsAsset(opts));
             }
             return;
         }
-        this.#addJsAsset(options);
+        this.jsRoute.push(this.#jsAsset(options));
     }
 
     /**
@@ -800,10 +836,50 @@ export default class PodiumPodlet {
      * @returns {string}
      */
     render(incoming, data, ...args) {
+        const markup = this.#useShadowDOM ? this.wrapWithShadowDOM(data) : data;
         if (!incoming.development) {
-            return data;
+            return markup;
         }
-        return this.#view(incoming, data, ...args);
+        return this.#view(incoming, markup, ...args);
+    }
+
+    /**
+     * Function that takes in the podlet content,wraps it in declarative shadow DOM and returns it.
+     * @param {string} data - the podlet content to wrap in declarative shadow DOM as an HTML markup string
+     *
+     * @example
+     * ```js
+     * const content = podlet.wrapWithShadowDOM('<div>content to render</div>');
+     * ```
+     */
+    wrapWithShadowDOM(data) {
+        assert.ok(
+            customElementRegex.test(this.name),
+            `When using the constructor argument "useShadowDOM" or the method podlet.wrapWithShadowDOM, podlet.name must conform to custom element naming conventions. The name "${this.name}" does not comply. See https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define#valid_custom_element_names for more information.`,
+        );
+
+        const styles = this.cssRoute
+            .filter((css) => css.strategy === 'shadow-dom')
+            .map((css) => css.toHTML());
+
+        const scripts = this.jsRoute
+            .filter((js) => js.strategy === 'shadow-dom')
+            .map((js) => js.toHTML());
+
+        // Wrap the markup in DSD.
+        return `
+          <${this.name}>
+            <template shadowrootmode="open">
+              ${styles.join('\n')}
+              ${data}
+              ${scripts.join('\n')}
+            </template>
+          </${this.name}>
+          <script>(()=>{function e(d){HTMLTemplateElement.prototype.hasOwnProperty("shadowRootMode")||d.querySelectorAll("template[shadowrootmode]").forEach(o=>{let
+          n=o.getAttribute("shadowrootmode"),s=o.hasAttribute("shadowrootdelegatesfocus"),t=o.parentNode.attachShadow({mode:n,delegatesFocus:s});t.appendChild(o.content),o.remove(),e(t)})}var
+          r;(r=document.currentScript)!=null&&r.previousElementSibling&&e(document.currentScript.previousElementSibling);})();
+          </script>
+        `;
     }
 
     /**
@@ -865,8 +941,9 @@ export default class PodiumPodlet {
             );
         }
 
-        // Determin if the request should be proxied and do if so
+        // Determine if the request should be proxied and do if so
         if (incoming.development && proxy) {
+            // @ts-ignore
             await this.httpProxy.process(incoming);
         }
 
@@ -903,6 +980,18 @@ export default class PodiumPodlet {
                 // if this is a proxy request then no further work should be done.
                 if (incoming.proxy) return;
 
+                const js = incoming.js.map(
+                    // @ts-ignore
+                    (asset) => asset.toHeader() + '; asset-type=script',
+                );
+
+                const css = incoming.css.map(
+                    // @ts-ignore
+                    (asset) => asset.toHeader() + '; asset-type=style',
+                );
+
+                res.header('Link', [...js, ...css].join(', '));
+
                 // set "incoming" on res.locals.podium
                 objobj.set('locals.podium', incoming, res);
 
@@ -910,8 +999,15 @@ export default class PodiumPodlet {
                     res.header('podlet-version', this.version);
                 }
 
-                res.podiumSend = (data, ...args) =>
-                    res.send(this.render(incoming, data, ...args));
+                res.sendHeaders = () => {
+                    res.write('');
+                    return res;
+                };
+
+                res.podiumSend = (data, ...args) => {
+                    res.write(this.render(incoming, data, ...args));
+                    res.end();
+                };
 
                 next();
             } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podium/podlet",
-  "version": "5.1.19",
+  "version": "5.2.0-next.10",
   "type": "module",
   "description": "Module for building page fragment servers in a micro frontend architecture.",
   "license": "MIT",
@@ -34,8 +34,8 @@
   },
   "dependencies": {
     "@metrics/client": "2.5.3",
+    "@podium/schemas": "5.1.0",
     "@podium/proxy": "5.0.29",
-    "@podium/schemas": "5.0.6",
     "@podium/utils": "5.3.1",
     "abslog": "2.4.4",
     "ajv": "8.17.1",
@@ -55,6 +55,7 @@
     "prettier": "3.3.3",
     "semantic-release": "24.1.2",
     "tap": "18.8.0",
-    "typescript": "5.5.4"
+    "typescript": "5.5.4",
+    "undici": "^6.19.7"
   }
 }

package/types/podlet.d.ts

@@ -73,25 +73,37 @@ declare global {
 
 /**
  * @typedef {Object} PodletOptions
- * @property {string} name - Podlet name
- * @property {string} version - Podlet version
- * @property {string} pathname - Podlet pathname
- * @property {string} [manifest="/manifest.json"] - Path where the podlet manifest file is served from.
- * @property {string} [content="/"] - Path where the podlet content HTML markup is served from.
- * @property {string} [fallback=""] - Path where the podlet fallback HTML markup is served from. By default there is no fallback. Set this to for instance `"/fallback"` to serve a cacheable version of the contents in case the podlet goes down.
- * @property {boolean} [development=false] - a boolean flag that, when true, enables additional development setup
- * @property {import('abslog').AbstractLoggerOptions} [logger] - a logger to use when provided. Can be the console object if console logging is desired but can also be any Log4j compatible logging object as well. Nothing is logged if no logger is provided.
+ * @property {string} name - (required) podlet name
+ * @property {string} version - (required) podlet version
+ * @property {string} pathname - (required) podlet pathname
+ * @property {string} [manifest="/manifest.json"] - path where the podlet manifest file is served from (default '/manifest.json')
+ * @property {string} [content="/"] - path where the podlet content HTML markup is served from (default '/')
+ * @property {string} [fallback=""] - path where the podlet fallback HTML markup is served from (default '/fallback')
+ * @property {boolean} [development=false] - a boolean flag that, when true, enables additional development setup (default false)
+ * @property {boolean} [useShadowDOM=false] - a boolean flag that, when true, enables the use of ShadowDOM (default false)
+ * @property {import("abslog").AbstractLoggerOptions} [logger] - a logger to use when provided. Can be the console object if console logging is desired but can also be any Log4j compatible logging object as well. Nothing is logged if no logger is provided. (default null)
  * @property {import("@podium/proxy").PodiumProxyOptions} [proxy] - options that can be provided to configure the @podium/proxy instance used by the podlet. See that module for details.
  *
  * @typedef {{ debug: 'true' | 'false', locale: string, deviceType: string, requestedBy: string, mountOrigin: string, mountPathname: string, publicPathname: string }} PodletContext
- * @typedef {{ as?: string | false | null, crossorigin?: string | null | boolean, disabled?: boolean | '' | null, hreflang?: string | false | null, title?: string | false | null, media?: string | false | null, rel?: string | false | null, type?: string | false | null, value: string | false | null, data?: Array<{ key: string; value: string }>, strategy?: "beforeInteractive" | "afterInteractive" | "lazy", scope?: "content" | "fallback" | "all", [key: string]: any }} AssetCssLike
- * @typedef {{ value: string | null, crossorigin?: string | null | boolean, type?: string | null | false, integrity?: string | null | false, referrerpolicy?: string | null | false, nomodule?: boolean | null | '', async?: boolean | null | '', defer?: boolean | null | '', data?: Array<{ key: string; value: string }>, strategy?: "beforeInteractive" | "afterInteractive" | "lazy", scope?: "content" | "fallback" | "all", [key: string]: any }} AssetJsLike
+ * @typedef {{ as?: string | false | null, crossorigin?: string | null | boolean, disabled?: boolean | '' | null, hreflang?: string | false | null, title?: string | false | null, media?: string | false | null, rel?: string | false | null, type?: string | false | null, value: string | false | null, strategy?: "beforeInteractive" | "afterInteractive" | "lazy" | "shadow-dom", scope?: "content" | "fallback" | "all", [key: string]: any }} AssetCssLike
+ * @typedef {{ value: string | null, crossorigin?: string | null | boolean, type?: string | null | false, integrity?: string | null | false, referrerpolicy?: string | null | false, nomodule?: boolean | null | '', async?: boolean | null | '', defer?: boolean | null | '', data?: {[key: string]: string} | Array<{ key: string; value: string }>, strategy?: "beforeInteractive" | "afterInteractive" | "lazy" | "shadow-dom", scope?: "content" | "fallback" | "all" | "shadow-dom", [key: string]: any }} AssetJsLike
  */
 export default class PodiumPodlet {
     /**
      * Creates a new instance of a Podium podlet which can be used in conjunction with your framework of choice to build podlet server apps.
      * `name`, `version` and `pathname` constructor arguments are required. All other options are optional.
      *
+     * * `name` - podlet name (**required**)
+     * * `version` - podlet version (**required**)
+     * * `pathname` - podlet pathname (**required**)
+     * * `manifest` - path where the podlet manifest file is served from (**default** `'/manifest.json'`)
+     * * `content` - path where the podlet content HTML markup is served from (**default** `'/'`)
+     * * `fallback` - path where the podlet fallback HTML markup is served from (**default** `'/fallback'`)
+     * * `development` - a boolean flag that, when true, enables additional development setup (**default** `false`)
+     * * `useShadowDOM` - a boolean flag that, when true, enables the use of declarative ShadowDOM in the podlet (**default** `false`)
+     * * `logger` - a logger to use when provided. Can be the console object if console logging is desired but can also be any Log4j compatible logging object as well. Nothing is logged if no logger is provided. (**default** `null`)
+     * * `proxy` - options that can be provided to configure the @podium/proxy instance used by the podlet. See that module for details. (**default**: `{}`)
+     *
      * @see https://podium-lib.io/docs/api/podlet/#constructor
      * @see https://podium-lib.io/docs/podlet/getting_started
      *
@@ -102,7 +114,7 @@ export default class PodiumPodlet {
      * const podlet = new Podlet({ name: 'foo', version: '1.0.0', pathname: '/' });
      * ```
      */
-    constructor({ name, version, pathname, manifest, fallback, content, logger, development, proxy, }: PodletOptions);
+    constructor({ name, version, pathname, manifest, fallback, content, logger, development, proxy, useShadowDOM, }: PodletOptions);
     /**
      * The name that the podlet identifies itself by. (set in the constructor) This is used internally for things like metrics but can also be used by a layout server.
      * This value must be in camelCase.
@@ -581,6 +593,16 @@ export default class PodiumPodlet {
     render<T extends {
         [key: string]: unknown;
     }>(incoming: HttpIncoming<T>, data: string, ...args: any[]): string;
+    /**
+     * Function that takes in the podlet content,wraps it in declarative shadow DOM and returns it.
+     * @param {string} data - the podlet content to wrap in declarative shadow DOM as an HTML markup string
+     *
+     * @example
+     * ```js
+     * const content = podlet.wrapWithShadowDOM('<div>content to render</div>');
+     * ```
+     */
+    wrapWithShadowDOM(data: string): string;
     /**
      * Method for processing an incoming HTTP request. This method is intended to be used to implement support for multiple HTTP frameworks and in most cases will not need to be used directly by podlet developers when creating podlet servers.
      *
@@ -620,35 +642,39 @@ export default class PodiumPodlet {
 }
 export type PodletOptions = {
     /**
-     * - Podlet name
+     * - (required) podlet name
      */
     name: string;
     /**
-     * - Podlet version
+     * - (required) podlet version
      */
     version: string;
     /**
-     * - Podlet pathname
+     * - (required) podlet pathname
      */
     pathname: string;
     /**
-     * - Path where the podlet manifest file is served from.
+     * - path where the podlet manifest file is served from (default '/manifest.json')
      */
     manifest?: string;
     /**
-     * - Path where the podlet content HTML markup is served from.
+     * - path where the podlet content HTML markup is served from (default '/')
      */
     content?: string;
     /**
-     * - Path where the podlet fallback HTML markup is served from. By default there is no fallback. Set this to for instance `"/fallback"` to serve a cacheable version of the contents in case the podlet goes down.
+     * - path where the podlet fallback HTML markup is served from (default '/fallback')
      */
     fallback?: string;
     /**
-     * - a boolean flag that, when true, enables additional development setup
+     * - a boolean flag that, when true, enables additional development setup (default false)
      */
     development?: boolean;
     /**
-     * - a logger to use when provided. Can be the console object if console logging is desired but can also be any Log4j compatible logging object as well. Nothing is logged if no logger is provided.
+     * - a boolean flag that, when true, enables the use of ShadowDOM (default false)
+     */
+    useShadowDOM?: boolean;
+    /**
+     * - a logger to use when provided. Can be the console object if console logging is desired but can also be any Log4j compatible logging object as well. Nothing is logged if no logger is provided. (default null)
      */
     logger?: import("abslog").AbstractLoggerOptions;
     /**
@@ -675,11 +701,7 @@ export type AssetCssLike = {
     rel?: string | false | null;
     type?: string | false | null;
     value: string | false | null;
-    data?: Array<{
-        key: string;
-        value: string;
-    }>;
-    strategy?: "beforeInteractive" | "afterInteractive" | "lazy";
+    strategy?: "beforeInteractive" | "afterInteractive" | "lazy" | "shadow-dom";
     scope?: "content" | "fallback" | "all";
     [key: string]: any;
 };
@@ -692,12 +714,14 @@ export type AssetJsLike = {
     nomodule?: boolean | null | "";
     async?: boolean | null | "";
     defer?: boolean | null | "";
-    data?: Array<{
+    data?: {
+        [key: string]: string;
+    } | Array<{
         key: string;
         value: string;
     }>;
-    strategy?: "beforeInteractive" | "afterInteractive" | "lazy";
-    scope?: "content" | "fallback" | "all";
+    strategy?: "beforeInteractive" | "afterInteractive" | "lazy" | "shadow-dom";
+    scope?: "content" | "fallback" | "all" | "shadow-dom";
     [key: string]: any;
 };
 import Proxy from '@podium/proxy';