Merge pull request #440 from podium-lib/next

Merge down next into main

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)
 
 

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 |