@tylertech/forge-core 3.0.1 → 3.1.0

package/dist/custom-elements/component-utils.d.ts

@@ -44,19 +44,19 @@ export declare function attachLightTemplate<T extends HTMLElement>(componentInst
  * Attaches a shadow root to the given web component instance.
  * @param {T} componentInstance A component instance.
  * @param {string} elementName The name of the element the shadow root is to be attached to.
- * @param {string} template The shadow root template HTML string.
+ * @param {string | HTMLTemplateElement} template The shadow root template HTML string or element.
  * @param {string | string[]} styles The shadow root styles string to be encapsulated by this shadow root.
  * @param {boolean} [delegatesFocus=false] Should the component delegate focus.
  */
-export declare function attachShadowTemplate<T extends HTMLElement>(componentInstance: T, template: string, styles?: string | string[], delegatesFocus?: boolean): void;
+export declare function attachShadowTemplate<T extends HTMLElement>(componentInstance: T, template: string | HTMLTemplateElement, styles?: string | string[], delegatesFocus?: boolean): void;
 /**
  * Replaces the template of an existing shadow root with the provided template.
  * @param {T} componentInstance A component instance.
  * @param {string} elementName The name of the element the shadow root is to be attached to.
- * @param {string} template The shadow root template HTML string.
+ * @param {string | HTMLTemplateElement} template The shadow root template HTML string or element.
  * @param {string | string[]} styles The shadow root styles string to be encapsulated by this shadow root.
  */
-export declare function replaceShadowTemplate<T extends HTMLElement>(componentInstance: T, template: string, styles?: string | string[]): void;
+export declare function replaceShadowTemplate<T extends HTMLElement>(componentInstance: T, template: string | HTMLTemplateElement, styles?: string | string[]): void;
 /**
  * Creates and prepares an HTML template element for rendering within a shadow root.
  * @param {string} elementName The name of the element the shadow root is to be attached to.
@@ -67,9 +67,11 @@ export declare function prepareShadowTemplate(template: string, styles?: string
 /**
  * Appends a template to the provided components shadow root.
  * @param {T} componentInstance A component instance.
- * @param {HTMLTemplateElement} templateElement A template element to be cloned.
+ * @param {string | HTMLTemplateElement} template A template string or template element to be cloned.
  */
-export declare function setShadowTemplate<T extends HTMLElement>(componentInstance: T, templateElement: HTMLTemplateElement): void;
+export declare function setShadowTemplate<T extends HTMLElement>(componentInstance: T, template: string | HTMLTemplateElement, { force }?: {
+    force: boolean;
+}): void;
 /**
  * Applies styles to the shadow root of the provided element instance.
  * @param {T} componentInstance A component instance.
@@ -80,9 +82,9 @@ export declare function setShadowStyles<T extends HTMLElement>(componentInstance
     force: boolean;
 }): void;
 /**
- * Reapplies styles to the shadow root of the provided element instance. This function was
+ * Re-applies styles to the shadow root of the provided element instance. This function is
  * intended to be called after an element has been adopted by a new document to reconstruct the
- * adopted stylesheet instances within the context of the new document.
+ * adopted stylesheet instances within the context (view) of the new document.
  *
  * @param componentInstance The component instance to reapply styles to.
  */

package/dist/custom-elements/component-utils.js

@@ -1,5 +1,5 @@
 import { replaceElement, isArray, removeAllChildren, walkUpUntil } from '../utils';
-import { CUSTOM_ELEMENT_CSS_PROPERTY, CUSTOM_ELEMENT_DEPENDENCIES_PROPERTY, CUSTOM_ELEMENT_NAME_PROPERTY, CUSTOM_ELEMENT_STYLESHEETS_PROPERTY, supportsConstructableStyleSheets } from './constants';
+import { CUSTOM_ELEMENT_CSS_PROPERTY, CUSTOM_ELEMENT_DEPENDENCIES_PROPERTY, CUSTOM_ELEMENT_NAME_PROPERTY, CUSTOM_ELEMENT_STYLESHEETS_PROPERTY, CUSTOM_ELEMENT_TEMPLATE_PROPERTY, supportsConstructableStyleSheets } from './constants';
 /**
  * Recursively defines a component as a custom elements and all of its dependencies.
  * @param component The component to import.
@@ -81,37 +81,35 @@ export function attachLightTemplate(componentInstance, template) {
  * Attaches a shadow root to the given web component instance.
  * @param {T} componentInstance A component instance.
  * @param {string} elementName The name of the element the shadow root is to be attached to.
- * @param {string} template The shadow root template HTML string.
+ * @param {string | HTMLTemplateElement} template The shadow root template HTML string or element.
  * @param {string | string[]} styles The shadow root styles string to be encapsulated by this shadow root.
  * @param {boolean} [delegatesFocus=false] Should the component delegate focus.
  */
 export function attachShadowTemplate(componentInstance, template, styles, delegatesFocus = false) {
-    const templateElement = prepareShadowTemplate(template);
     componentInstance.attachShadow({ mode: 'open', delegatesFocus });
     if (styles) {
         setShadowStyles(componentInstance, styles);
     }
-    setShadowTemplate(componentInstance, templateElement);
+    setShadowTemplate(componentInstance, template);
 }
 /**
  * Replaces the template of an existing shadow root with the provided template.
  * @param {T} componentInstance A component instance.
  * @param {string} elementName The name of the element the shadow root is to be attached to.
- * @param {string} template The shadow root template HTML string.
+ * @param {string | HTMLTemplateElement} template The shadow root template HTML string or element.
  * @param {string | string[]} styles The shadow root styles string to be encapsulated by this shadow root.
  */
 export function replaceShadowTemplate(componentInstance, template, styles) {
     if (!componentInstance.shadowRoot) {
         throw new Error('This element does not contain a shadow root. Did you mean to call `attachShadowTemplate`?');
     }
-    const templateElement = prepareShadowTemplate(template);
     if (componentInstance.shadowRoot.children.length) {
         removeAllChildren(componentInstance.shadowRoot);
     }
     if (styles) {
         setShadowStyles(componentInstance, styles, { force: true });
     }
-    setShadowTemplate(componentInstance, templateElement);
+    setShadowTemplate(componentInstance, template, { force: true });
 }
 /**
  * Creates and prepares an HTML template element for rendering within a shadow root.
@@ -139,10 +137,16 @@ export function prepareShadowTemplate(template, styles) {
 /**
  * Appends a template to the provided components shadow root.
  * @param {T} componentInstance A component instance.
- * @param {HTMLTemplateElement} templateElement A template element to be cloned.
+ * @param {string | HTMLTemplateElement} template A template string or template element to be cloned.
  */
-export function setShadowTemplate(componentInstance, templateElement) {
-    componentInstance.shadowRoot.appendChild(templateElement.content.cloneNode(true));
+export function setShadowTemplate(componentInstance, template, { force } = { force: false }) {
+    const ctor = componentInstance.constructor;
+    if (force || !ctor[CUSTOM_ELEMENT_TEMPLATE_PROPERTY]) {
+        const templateElement = template instanceof HTMLTemplateElement ? template : parseTemplateString(template);
+        ctor[CUSTOM_ELEMENT_TEMPLATE_PROPERTY] = templateElement;
+    }
+    const resolvedTemplate = ctor[CUSTOM_ELEMENT_TEMPLATE_PROPERTY];
+    componentInstance.shadowRoot.appendChild(resolvedTemplate.content.cloneNode(true));
 }
 /**
  * Applies styles to the shadow root of the provided element instance.
@@ -187,22 +191,21 @@ export function setShadowStyles(componentInstance, styles, { force } = { force:
     }
 }
 /**
- * Reapplies styles to the shadow root of the provided element instance. This function was
+ * Re-applies styles to the shadow root of the provided element instance. This function is
  * intended to be called after an element has been adopted by a new document to reconstruct the
- * adopted stylesheet instances within the context of the new document.
+ * adopted stylesheet instances within the context (view) of the new document.
  *
  * @param componentInstance The component instance to reapply styles to.
  */
 export function readoptStyles(componentInstance) {
     if (!supportsConstructableStyleSheets ||
         !componentInstance.shadowRoot ||
-        !componentInstance.constructor[CUSTOM_ELEMENT_CSS_PROPERTY]) {
+        !componentInstance.constructor[CUSTOM_ELEMENT_CSS_PROPERTY] ||
+        !componentInstance.ownerDocument.defaultView) {
         return;
     }
-    const cssText = componentInstance.constructor[CUSTOM_ELEMENT_CSS_PROPERTY];
-    const context = componentInstance.ownerDocument.defaultView ?? window;
-    const sheet = new context.CSSStyleSheet();
-    sheet.replaceSync(cssText);
+    const sheet = new componentInstance.ownerDocument.defaultView.CSSStyleSheet();
+    sheet.replaceSync(componentInstance.constructor[CUSTOM_ELEMENT_CSS_PROPERTY]);
     componentInstance.shadowRoot.adoptedStyleSheets = [sheet];
 }
 /**

package/dist/custom-elements/constants.d.ts

@@ -1,5 +1,6 @@
 export declare const CUSTOM_ELEMENT_NAME_PROPERTY: unique symbol;
 export declare const CUSTOM_ELEMENT_DEPENDENCIES_PROPERTY: unique symbol;
+export declare const CUSTOM_ELEMENT_TEMPLATE_PROPERTY: unique symbol;
 export declare const CUSTOM_ELEMENT_CSS_PROPERTY: unique symbol;
 export declare const CUSTOM_ELEMENT_STYLESHEETS_PROPERTY: unique symbol;
 /** Whether the browser supports constructable stylesheets */

package/dist/custom-elements/constants.js

@@ -1,5 +1,6 @@
 export const CUSTOM_ELEMENT_NAME_PROPERTY = Symbol('Forge custom element tag name');
 export const CUSTOM_ELEMENT_DEPENDENCIES_PROPERTY = Symbol('Forge custom element dependencies');
+export const CUSTOM_ELEMENT_TEMPLATE_PROPERTY = Symbol('Forge custom element parsed template');
 export const CUSTOM_ELEMENT_CSS_PROPERTY = Symbol('Forge custom element CSS text');
 export const CUSTOM_ELEMENT_STYLESHEETS_PROPERTY = Symbol('Forge custom element CSSStyleSheet instances');
 /** Whether the browser supports constructable stylesheets */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tylertech/forge-core",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "A library of core web utilities that support Tyler Forge™ based libraries.",
   "author": "Tyler Technologies, Inc.",
   "license": "Apache-2.0",