@podium/podlet 5.2.0-next.2 → 5.2.0-next.3

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [5.2.0-next.3](https://github.com/podium-lib/podlet/compare/v5.2.0-next.2...v5.2.0-next.3) (2024-09-10)
+
+
+### Features
+
+* add DSD shadow DOM encapsulation support ([02c9a64](https://github.com/podium-lib/podlet/commit/02c9a64a6bb2f460c035416e43405ae380cb6d1c))
+
 # [5.2.0-next.2](https://github.com/podium-lib/podlet/compare/v5.2.0-next.1...v5.2.0-next.2) (2024-09-06)
 
 

package/README.md

@@ -79,16 +79,17 @@ 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
 
@@ -257,6 +258,52 @@ 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:

package/lib/podlet.js

@@ -15,6 +15,10 @@ 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(
@@ -30,16 +34,17 @@ const { template } = utils;
  * @property {string} name - (required) podlet name
  * @property {string} version - (required) podlet version
  * @property {string} pathname - (required) podlet pathname
- * @property {string} [manifest] - 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] - a boolean flag that, when true, enables additional development setup (default false)
+ * @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, 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?: {[key: string]: string} | 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", scope?: "content" | "fallback" | "all" | "shadow-dom", [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", scope?: "content" | "fallback" | "all" | "shadow-dom", [key: string]: any }} AssetJsLike
  */
 
 export default class PodiumPodlet {
@@ -283,6 +288,11 @@ 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.
@@ -294,6 +304,7 @@ export default class PodiumPodlet {
      * * `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**: `{}`)
      *
@@ -317,6 +328,7 @@ export default class PodiumPodlet {
         logger = undefined,
         development = false,
         proxy = {},
+        useShadowDOM = false,
     }) {
         if (schema.name(name).error)
             throw new Error(
@@ -374,6 +386,7 @@ export default class PodiumPodlet {
                 this.name,
             ),
         };
+        this.#useShadowDOM = useShadowDOM;
 
         // Skip a tick to ensure the metric stream has been consumed
         setImmediate(() => {
@@ -811,10 +824,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", podlet.name must conform to custom element naming conventions: https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define#valid_custom_element_names',
+        );
+
+        const styles = this.cssRoute
+            .filter((css) => css.scope === 'shadow-dom')
+            .map((css) => css.toHTML());
+
+        const scripts = this.jsRoute
+            .filter((js) => js.scope === '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>
+        `;
     }
 
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podium/podlet",
-  "version": "5.2.0-next.2",
+  "version": "5.2.0-next.3",
   "type": "module",
   "description": "Module for building page fragment servers in a micro frontend architecture.",
   "license": "MIT",

package/types/podlet.d.ts

@@ -30,16 +30,17 @@ declare global {
  * @property {string} name - (required) podlet name
  * @property {string} version - (required) podlet version
  * @property {string} pathname - (required) podlet pathname
- * @property {string} [manifest] - 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] - a boolean flag that, when true, enables additional development setup (default false)
+ * @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, 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?: {[key: string]: string} | 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", scope?: "content" | "fallback" | "all" | "shadow-dom", [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", scope?: "content" | "fallback" | "all" | "shadow-dom", [key: string]: any }} AssetJsLike
  */
 export default class PodiumPodlet {
     /**
@@ -53,6 +54,7 @@ export default class PodiumPodlet {
      * * `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**: `{}`)
      *
@@ -66,7 +68,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.
@@ -545,6 +547,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.
      *
@@ -611,6 +623,10 @@ export type PodletOptions = {
      * - a boolean flag that, when true, enables additional development setup (default false)
      */
     development?: boolean;
+    /**
+     * - 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)
      */
@@ -640,7 +656,7 @@ export type AssetCssLike = {
     type?: string | false | null;
     value: string | false | null;
     strategy?: "beforeInteractive" | "afterInteractive" | "lazy";
-    scope?: "content" | "fallback" | "all";
+    scope?: "content" | "fallback" | "all" | "shadow-dom";
     [key: string]: any;
 };
 export type AssetJsLike = {
@@ -659,7 +675,7 @@ export type AssetJsLike = {
         value: string;
     }>;
     strategy?: "beforeInteractive" | "afterInteractive" | "lazy";
-    scope?: "content" | "fallback" | "all";
+    scope?: "content" | "fallback" | "all" | "shadow-dom";
     [key: string]: any;
 };
 import Proxy from '@podium/proxy';