@lwrjs/client-modules 0.20.0 → 0.20.2

package/build/bundle/prod/lwr/init/init.js

@@ -1,2 +1,2 @@
-import{BOOTSTRAP_END as e,INIT as o,INIT_MODULE as r}from"lwr/metrics";import{logOperationStart as t,logOperationEnd as n}from"lwr/profiler";import{hydrateComponent as i,createElement as c}from"lwc";const l=(()=>{const e=globalThis,{SSREnabled:o}=e.LWR&&e.LWR.env||{};if(!globalThis.performance||!o)return()=>!1;let r=globalThis.performance.now();return()=>{const e=globalThis.performance.now();return e-r>50&&(r=e,!0)}})();function s(e,o){return c(e,{is:o})}function a(e){return e.replace(/\/v\/[a-zA-Z0-9-_.]+$/,"").replace("/","-").replace(/([A-Z])/g,(e=>`-${e.toLowerCase()}`))}const d=/-([a-z])/g;function p(e){return e.replace(d,(e=>e[1].toUpperCase()))}function f(c,d={}){void 0!==globalThis.customElements&&void 0!==globalThis.document?(t({id:o}),(async()=>{let e=0;const o=globalThis.document;for(const[b,g]of c){l()&&await u();const c=++e,w=a(b);if(!o.body.querySelector(w)){t({id:r,specifier:b,specifierIndex:c});const e=s(w,g),i=o.querySelector("[lwr-root]");i?i.appendChild(e):o.body.appendChild(e),n({id:r,specifier:b,specifierIndex:c,metadata:{renderMode:"spa"}});continue}const y=o.querySelectorAll(w);for(const e of y){t({id:r,specifier:b,specifierIndex:c});const o=e.dataset.lwrPropsId;if(o){f=e,m=g,h=d[o]||{},i(f,m,h),n({id:r,specifier:b,specifierIndex:c,metadata:{renderMode:"ssr"}});continue}const l=s(w,g);for(const{name:o,value:r}of e.attributes){l.setAttribute(o,r);const e=p(o);e in l&&(l[e]=r)}for(;e.childNodes.length>0;)l.appendChild(e.childNodes[0]);const a=e.parentElement;a&&a.replaceChild(l,e),n({id:r,specifier:b,specifierIndex:c,metadata:{renderMode:"csr"}})}}var f,m,h})(),n({id:o}),t({id:e})):t({id:e})}async function u(){const e=globalThis.scheduler;return function(e){let o,r=e[0],t=1;for(;t<e.length;){const n=e[t],i=e[t+1];if(t+=2,("optionalAccess"===n||"optionalCall"===n)&&null==r)return;"access"===n||"optionalAccess"===n?(o=r,r=i(r)):"call"!==n&&"optionalCall"!==n||(r=i(((...e)=>r.call(o,...e))),o=void 0)}return r}([e,"optionalAccess",e=>e.yield])?e.yield():new Promise((e=>setTimeout(e,0)))}export{p as getPropFromAttrName,f as init,a as toKebabCase};
+import{BOOTSTRAP_END as e,INIT as o,INIT_MODULE as t}from"lwr/metrics";import{logOperationStart as r,logOperationEnd as n}from"lwr/profiler";import{hydrateComponent as i,createElement as s}from"lwc";const c="lwr:hydrate",l="visible";function a(e,o,t){i(e,o,t)}function d(e,o,t){const r=f||(f=new IntersectionObserver(((e,o)=>{e.forEach((e=>{if(e.isIntersecting){const t=e.target;o.unobserve(t);const r=p.get(t);if(r){p.delete(t);const{ctor:e,props:o}=r;a(t,e,o)}}}))}),{root:null,rootMargin:"100px"}),f);p.set(e,{ctor:o,props:t}),r.observe(e)}const p=new Map;let f;function u(e){return"IntersectionObserver"in globalThis&&e.getAttribute(c)===l}const m=(()=>{const e=globalThis,{SSREnabled:o}=e.LWR&&e.LWR.env||{};if(!globalThis.performance||!o)return()=>!1;let t=globalThis.performance.now();return()=>{const e=globalThis.performance.now();return e-t>50&&(t=e,!0)}})();function b(e,o){return s(e,{is:o})}function h(e){return e.replace(/\/v\/[a-zA-Z0-9-_.]+$/,"").replace("/","-").replace(/([A-Z])/g,(e=>`-${e.toLowerCase()}`))}const g=/-([a-z])/g;function w(e){return e.replace(g,(e=>e[1].toUpperCase()))}function v(i,s={}){void 0!==globalThis.customElements&&void 0!==globalThis.document?(r({id:o}),(async()=>{let e=0;const o=globalThis.document;for(const[c,l]of i){m()&&await y();const i=++e,p=h(c);if(!o.body.querySelector(p)){r({id:t,specifier:c,specifierIndex:i});const e=b(p,l),s=o.querySelector("[lwr-root]");s?s.appendChild(e):o.body.appendChild(e),n({id:t,specifier:c,specifierIndex:i,metadata:{renderMode:"spa"}});continue}const f=o.querySelectorAll(p);for(const e of f){r({id:t,specifier:c,specifierIndex:i});const o=e.dataset.lwrPropsId;if(o){u(e)?d(e,l,s[o]||{}):a(e,l,s[o]||{}),n({id:t,specifier:c,specifierIndex:i,metadata:{renderMode:"ssr"}});continue}const f=b(p,l);for(const{name:o,value:t}of e.attributes){f.setAttribute(o,t);const e=w(o);e in f&&(f[e]=t)}for(;e.childNodes.length>0;)f.appendChild(e.childNodes[0]);const m=e.parentElement;m&&m.replaceChild(f,e),n({id:t,specifier:c,specifierIndex:i,metadata:{renderMode:"csr"}})}}})(),n({id:o}),r({id:e})):r({id:e})}async function y(){const e=globalThis.scheduler;return function(e){let o,t=e[0],r=1;for(;r<e.length;){const n=e[r],i=e[r+1];if(r+=2,("optionalAccess"===n||"optionalCall"===n)&&null==t)return;"access"===n||"optionalAccess"===n?(o=t,t=i(t)):"call"!==n&&"optionalCall"!==n||(t=i(((...e)=>t.call(o,...e))),o=void 0)}return t}([e,"optionalAccess",e=>e.yield])?e.yield():new Promise((e=>setTimeout(e,0)))}export{c as HYDRATE_DIRECTIVE,l as HYDRATE_VISIBLE_VALUE,w as getPropFromAttrName,v as init,h as toKebabCase};
 //# sourceMappingURL=init.js.map

package/build/es/modules/lwr/init/init.d.ts

@@ -1,5 +1,7 @@
 import type { LightningElement } from 'lwc';
 import type { ServerData } from '@lwrjs/types';
+export declare const HYDRATE_DIRECTIVE = "lwr:hydrate";
+export declare const HYDRATE_VISIBLE_VALUE = "visible";
 /**
  * Convert a module specifier into a valid CustomElement registry name:
  *      - remove any version linking

package/build/es/modules/lwr/init/init.js

@@ -7,10 +7,76 @@ import { createElement } from 'lwc';
 // Note: a build step uses these comments to strip the code for core.
 // eslint-disable-next-line lwr/only-allowed-imports
 import { hydrateComponent } from 'lwc';
+// hydration directive + value constants
+// must align with the constants in @lwrjs/shared-utils/src/html-meta.ts
+export const HYDRATE_DIRECTIVE = 'lwr:hydrate';
+export const HYDRATE_VISIBLE_VALUE = 'visible';
 function hydrateComponentProxy(customElement, Ctor, props) {
     hydrateComponent(customElement, Ctor, props);
 }
 // </hydrateComponentProxy>
+/**
+ * Hydrate the custom element only when it is visible.
+ * @param customElement - The custom element to hydrate
+ * @param ctor - The constructor of the custom element
+ * @param props - The properties of the custom element
+ */
+function hydrateComponentOnVisible(customElement, ctor, props) {
+    // Use IntersectionObserver for visibility-based hydration
+    const observer = createVisibilityObserver();
+    // add the element to the pending hydrations and observe it
+    pendingHydrations.set(customElement, { ctor, props });
+    observer.observe(customElement);
+}
+// store component metadata for pending hydrations
+const pendingHydrations = new Map();
+// store the visibility observer so that we don't create a new one each time
+let visibilityObserver;
+/**
+ * Determines if a component should be hydrated when it becomes visible in the viewport.
+ * This requires IntersectionObserver to be available and the hydrate directive to be set to 'visible'.
+ * @param element - The element to check for visibility-based hydration
+ * @returns True if the component should be hydrated when visible, false otherwise
+ */
+function shouldHydrateComponentWhenVisible(element) {
+    return ('IntersectionObserver' in globalThis &&
+        element.getAttribute(HYDRATE_DIRECTIVE) === HYDRATE_VISIBLE_VALUE);
+}
+/**
+ * Create an intersection observer for hydrating islands when visible, if one doesn't already exist.
+ * @returns An intersection observer that will hydrate the island when visible
+ */
+function createVisibilityObserver() {
+    // return the existing observer if it already exists
+    if (visibilityObserver)
+        return visibilityObserver;
+    // create a new observer if it doesn't already exist
+    visibilityObserver = new IntersectionObserver((entries, observer) => {
+        // for each observed element, check if it is intersecting with the viewport
+        entries.forEach((entry) => {
+            // if intersecting, hydrate the island
+            if (entry.isIntersecting) {
+                const element = entry.target;
+                // stop observing the element
+                observer.unobserve(element);
+                // get the hydration data for the element
+                const hydrationData = pendingHydrations.get(element);
+                if (hydrationData) {
+                    // delete the hydration data for the element
+                    pendingHydrations.delete(element);
+                    const { ctor, props } = hydrationData;
+                    // hydrate the island
+                    hydrateComponentProxy(element, ctor, props);
+                }
+            }
+        });
+    }, {
+        root: null,
+        // adds a buffer to the intersection observer to hydrate the island slightly before it enters the viewport
+        rootMargin: '100px',
+    });
+    return visibilityObserver;
+}
 const shouldYield = (() => {
     const globalThisLWR = globalThis;
     const { SSREnabled } = (globalThisLWR.LWR && globalThisLWR.LWR.env) || {};
@@ -112,7 +178,15 @@ export function init(rootModules, serverData = {}) {
                 const propsId = element.dataset.lwrPropsId;
                 // hydrate SSR'd components
                 if (propsId) {
-                    hydrateComponentProxy(element, ctor, serverData[propsId] || {});
+                    // check if the element is a hydration visible island
+                    if (shouldHydrateComponentWhenVisible(element)) {
+                        // hydrate the island when visible
+                        hydrateComponentOnVisible(element, ctor, serverData[propsId] || {});
+                    }
+                    else {
+                        // hydrate the island immediately
+                        hydrateComponentProxy(element, ctor, serverData[propsId] || {});
+                    }
                     logOperationEnd({
                         id: INIT_MODULE,
                         specifier,

package/build/modules/lwr/init/init.js

@@ -13,11 +13,90 @@ import { createElement } from 'lwc';
 // Note: a build step uses these comments to strip the code for core.
 // eslint-disable-next-line lwr/only-allowed-imports
 import { hydrateComponent } from 'lwc';
+
+// hydration directive + value constants
+// must align with the constants in @lwrjs/shared-utils/src/html-meta.ts
+export const HYDRATE_DIRECTIVE = 'lwr:hydrate';
+export const HYDRATE_VISIBLE_VALUE = 'visible';
 function hydrateComponentProxy(customElement, Ctor, props) {
   hydrateComponent(customElement, Ctor, props);
 }
 // </hydrateComponentProxy>
 
+/**
+ * Hydrate the custom element only when it is visible.
+ * @param customElement - The custom element to hydrate
+ * @param ctor - The constructor of the custom element
+ * @param props - The properties of the custom element
+ */
+function hydrateComponentOnVisible(customElement, ctor, props) {
+  // Use IntersectionObserver for visibility-based hydration
+  const observer = createVisibilityObserver();
+
+  // add the element to the pending hydrations and observe it
+  pendingHydrations.set(customElement, {
+    ctor,
+    props
+  });
+  observer.observe(customElement);
+}
+
+// store component metadata for pending hydrations
+const pendingHydrations = new Map();
+
+// store the visibility observer so that we don't create a new one each time
+let visibilityObserver;
+
+/**
+ * Determines if a component should be hydrated when it becomes visible in the viewport.
+ * This requires IntersectionObserver to be available and the hydrate directive to be set to 'visible'.
+ * @param element - The element to check for visibility-based hydration
+ * @returns True if the component should be hydrated when visible, false otherwise
+ */
+function shouldHydrateComponentWhenVisible(element) {
+  return 'IntersectionObserver' in globalThis && element.getAttribute(HYDRATE_DIRECTIVE) === HYDRATE_VISIBLE_VALUE;
+}
+
+/**
+ * Create an intersection observer for hydrating islands when visible, if one doesn't already exist.
+ * @returns An intersection observer that will hydrate the island when visible
+ */
+function createVisibilityObserver() {
+  // return the existing observer if it already exists
+  if (visibilityObserver) return visibilityObserver;
+
+  // create a new observer if it doesn't already exist
+  visibilityObserver = new IntersectionObserver((entries, observer) => {
+    // for each observed element, check if it is intersecting with the viewport
+    entries.forEach(entry => {
+      // if intersecting, hydrate the island
+      if (entry.isIntersecting) {
+        const element = entry.target;
+
+        // stop observing the element
+        observer.unobserve(element);
+
+        // get the hydration data for the element
+        const hydrationData = pendingHydrations.get(element);
+        if (hydrationData) {
+          // delete the hydration data for the element
+          pendingHydrations.delete(element);
+          const {
+            ctor,
+            props
+          } = hydrationData;
+          // hydrate the island
+          hydrateComponentProxy(element, ctor, props);
+        }
+      }
+    });
+  }, {
+    root: null,
+    // adds a buffer to the intersection observer to hydrate the island slightly before it enters the viewport
+    rootMargin: '100px'
+  });
+  return visibilityObserver;
+}
 const shouldYield = (() => {
   const globalThisLWR = globalThis;
   const {
@@ -143,7 +222,14 @@ export function init(rootModules, serverData = {}) {
 
         // hydrate SSR'd components
         if (propsId) {
-          hydrateComponentProxy(element, ctor, serverData[propsId] || {});
+          // check if the element is a hydration visible island
+          if (shouldHydrateComponentWhenVisible(element)) {
+            // hydrate the island when visible
+            hydrateComponentOnVisible(element, ctor, serverData[propsId] || {});
+          } else {
+            // hydrate the island immediately
+            hydrateComponentProxy(element, ctor, serverData[propsId] || {});
+          }
           logOperationEnd({
             id: INIT_MODULE,
             specifier,

package/package.json

@@ -4,7 +4,7 @@
     "publishConfig": {
         "access": "public"
     },
-    "version": "0.20.0",
+    "version": "0.20.2",
     "homepage": "https://developer.salesforce.com/docs/platform/lwr/overview",
     "repository": {
         "type": "git",
@@ -34,10 +34,10 @@
     },
     "dependencies": {
         "@locker/sandbox": "0.25.3",
-        "@lwrjs/shared-utils": "0.20.0"
+        "@lwrjs/shared-utils": "0.20.2"
     },
     "devDependencies": {
-        "@lwrjs/types": "0.20.0",
+        "@lwrjs/types": "0.20.2",
         "@rollup/plugin-node-resolve": "^15.2.3",
         "@rollup/plugin-sucrase": "^5.0.2",
         "@rollup/plugin-terser": "^0.4.4",
@@ -70,5 +70,5 @@
     "volta": {
         "extends": "../../../package.json"
     },
-    "gitHead": "d2632661c89b535cc33b131edf04b7a75ca9469c"
+    "gitHead": "be82aca54f9a3b6cd18a4aac86f2f96c0184a930"
 }