@financial-times/custom-code-component 2.0.14 → 2.0.16

package/src/custom-code-component.ts

@@ -6,7 +6,7 @@
 import type { ContentTree } from "@financial-times/content-tree";
 import { BaseRenderer } from "../../ccc-sdk/src/renderers/BaseRenderer";
 import Tracking from "./tracking";
-import { convertStringLogLevel, Logger } from "./logger";
+import { Logger } from "./logger";
 import {
   CCCError,
   CCCImportError,
@@ -20,8 +20,20 @@ import { assignTestURL, useComponentTestEnv } from "./environment";
 import styles from "./custom-code-component.css?inline";
 
 export class FTCustomCodeComponent extends HTMLElement {
+  /**
+   * The component renderer, resolved from dynamic import
+   */
   app?: typeof BaseRenderer.prototype.render;
+
+  /**
+   * Set whether component is "open" or "closed". Defaults to "open".
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/attachShadow#mode
+   */
   mode: "closed" | "open" = "open";
+
+  /**
+   * Reserved attributes we don't pass to the child component
+   */
   RESERVED_ATTRS = new Set([
     "iframe",
     "path",
@@ -33,14 +45,36 @@ export class FTCustomCodeComponent extends HTMLElement {
     "load-timeout",
   ]);
 
+  /**
+   * URI of component module for CCC webcomponent to load
+   */
   source?: string;
+
+  /**
+   * OTracking config
+   */
   tracking?: Tracking;
+
+  /**
+   * Alternative base URL, used for testing
+   */
   testUrl?: URL;
+
+  /**
+   * ComponentPath instance with `org`, `repo`, `name` and `versionRange` attributes
+   */
   component = new ComponentPath();
 
+  /**
+   * Logger instance. Set log level using `this.log.setLogLevel(string|number|null)`.
+   */
   log: Logger;
 
+  /**
+   * IntersectionObserver that dispatches CCCViewportEvents
+   */
   observer = new IntersectionObserver((entries) => {
+    this.log.debug("Intersection Observer callback", { entries });
     entries.forEach((entry) => {
       this.dispatchEvent(
         new CCCViewportEvent({
@@ -53,11 +87,15 @@ export class FTCustomCodeComponent extends HTMLElement {
     });
   });
 
+  /**
+   * Custom Element constructor.
+   *
+   * n.b., attributes and ShadowDOM aren't available in custom element constructors.
+   * Use connectedCallback() and other lifecycle methods if you want to eg. this.getAttribute()
+   */
   constructor() {
     super();
-    this.log = new Logger({
-      level: convertStringLogLevel(this.getAttribute("log")),
-    });
+    this.log = new Logger();
 
     const supportsDeclarative =
       HTMLElement.prototype.hasOwnProperty("attachInternals");
@@ -69,8 +107,16 @@ export class FTCustomCodeComponent extends HTMLElement {
     }
   }
 
+  /**
+   * connectedCallback() CE lifecycle callback
+   *
+   * Called whenever a <custom-code-component> element is mounted to the DOM.
+   */
   async connectedCallback() {
     try {
+      this.log.setLogLevel(this.getAttribute("log"));
+      this.log.debug("connectedCallback");
+
       const path = this.getAttribute("path");
       const versionRange = this.getAttribute("version");
       this.component = ComponentPath.fromString(path, versionRange);
@@ -89,8 +135,13 @@ export class FTCustomCodeComponent extends HTMLElement {
     }
   }
 
+  /**
+   * Error handler. Decorates errors for easier ingestion.
+   *
+   * @param error
+   */
   emitError(error: Error) {
-    console.debug("ccc#emitError", error);
+    this.log.debug("emitError", { error });
     if (error instanceof CCCError) {
       this.dispatchEvent(
         new ErrorEvent("ccc:error", {
@@ -120,17 +171,42 @@ export class FTCustomCodeComponent extends HTMLElement {
     }
   }
 
+  /**
+   * disconnectedCallback() CE lifecycle event.
+   *
+   * Called when a <custom-code-component> element is removed from DOM.
+   */
   disconnectedCallback() {
+    this.log.debug("disconnectedCallback");
     const path = this.getAttribute("path");
     this.log.info(`<custom-code-component:${path}> disconnected`);
     this.observer.disconnect();
   }
 
+  /**
+   * MessageChannel interface.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/MessageChannel
+   */
   channel = new MessageChannel();
 
-  onmessage() {}
+  /**
+   * MessageChannel postMessage callback
+   *
+   * @param e
+   */
+  onmessage(e?: any) {
+    this.log.debug("onmessage", { event: e });
+  }
 
+  /**
+   * This error handler is called by the child component on e.g. unrecoverable error.
+   * It then calls unmount(), which restores the fallback.
+   *
+   * @param e
+   */
   onunmount(e: Error) {
+    this.log.debug("onunmount", { error: e });
     if (e instanceof Error) {
       const renderError = new CCCRenderError(e.message, {
         error: e,
@@ -143,9 +219,16 @@ export class FTCustomCodeComponent extends HTMLElement {
     }
   }
 
+  /**
+   * onready event callback.
+   * Called by mount() after kicking off initial component render.
+   *
+   * @param app
+   */
   async onready(app: Promise<void>) {
     try {
       await app;
+      this.log.debug("onready", { app });
       this.dispatchEvent(
         new CCCReadyEvent({
           component: this.component,
@@ -158,6 +241,7 @@ export class FTCustomCodeComponent extends HTMLElement {
 
       this.observer.observe(this);
     } catch (e) {
+      this.log.debug("onready caught error", { error: e });
       if (e instanceof Error) {
         const renderError = new CCCRenderError(e.message, {
           error: e,
@@ -171,11 +255,27 @@ export class FTCustomCodeComponent extends HTMLElement {
     }
   }
 
+  /**
+   * MessageChannel postMessage handler.
+   * This can be used for inter-CCC communication.
+   * @param event
+   */
   postMessage(event: any) {
+    this.log.debug("postmessage", { event });
     this.channel.port1.postMessage(event);
   }
 
+  /**
+   * Initial mounting behaviour.
+   *
+   * Attaches ShadowDOM if needed, dispatches ccc:connected event, adds component base styles,
+   * generates fallback template element if one doesn't exist already, initialises tracking,
+   * then kicks off component rendering. Passes component render promise to onready().
+   *
+   * @param prerendered
+   */
   async mount(prerendered?: ShadowRoot | null) {
+    this.log.debug("mount", prerendered);
     try {
       this.mode =
         this.getAttribute("shadow-open") == "false" ? "closed" : "open";
@@ -200,6 +300,7 @@ export class FTCustomCodeComponent extends HTMLElement {
           !shadow.adoptedStyleSheets.length
         ) {
           if (!window.CCC_LAYOUT_STYLESHEET) {
+            this.log.debug("mount generating CCC_LAYOUT_STYLESHEET");
             window.CCC_LAYOUT_STYLESHEET = new CSSStyleSheet();
             window.CCC_LAYOUT_STYLESHEET.replaceSync(styles);
           }
@@ -207,6 +308,7 @@ export class FTCustomCodeComponent extends HTMLElement {
         }
 
         if (!ssr) {
+          this.log.debug("mount generating fallback template");
           const template = document.createElement("template");
           template.innerHTML = "<div data-component-root><slot></slot></div>";
           this.appendChild(template);
@@ -252,6 +354,7 @@ export class FTCustomCodeComponent extends HTMLElement {
             shadow,
             {
               ...(data ?? extraProps),
+              log: this.log,
               data: data ?? extraProps,
               port: this.channel.port2,
               tracking: this.tracking,
@@ -276,16 +379,23 @@ export class FTCustomCodeComponent extends HTMLElement {
     }
   }
 
-  // Called in top-level error handler
-  // Replace shadow root with either <slot> or template[data-component-fallback]
-  // slot on failure
+  /**
+   * Called in top-level error handler or by child component on unhandled error.
+   * Replace shadow root with either <slot> or template[data-component-fallback]
+   * slot on failure
+   *
+   * @param e
+   */
   unmount(e: Error) {
+    this.log.debug("unmount", { error: e });
+
     const template =
       this.querySelector<HTMLTemplateElement>(
         "template[data-component-fallback]"
       ) ?? this.querySelector<HTMLTemplateElement>("template");
 
     if (template) {
+      this.log.debug("unmount replacing shadowRoot with fallback");
       this.shadowRoot?.replaceChildren(template.content.cloneNode(true));
     }
 
@@ -297,10 +407,18 @@ export class FTCustomCodeComponent extends HTMLElement {
     this.observer.disconnect();
   }
 
+  /**
+   * Asynchronously loads the CCC child component.
+   *
+   * @returns Promise resolving to component renderer function
+   */
   async load() {
+    this.log.debug("load");
+
     if (!this.component.isValid) {
       throw new Error("No path found");
     }
+
     const path = this.getAttribute("path");
     const componentVersionRange = this.getAttribute("version");
     const timeout = Number(this.getAttribute("load-timeout") || 10000);
@@ -315,6 +433,7 @@ export class FTCustomCodeComponent extends HTMLElement {
     const id = this.getAttribute("id");
 
     if (isTestEnv && this.testUrl) {
+      this.log.debug("load adding Vite scripts");
       this.injectViteScripts();
     }
 
@@ -384,7 +503,11 @@ export class FTCustomCodeComponent extends HTMLElement {
     }
   }
 
+  /**
+   * Initialises OTracking
+   */
   initTracking = async () => {
+    this.log.debug("initTracking", { cccId: this.id });
     try {
       this.tracking?.init(this.id);
     } catch (e) {
@@ -397,6 +520,9 @@ export class FTCustomCodeComponent extends HTMLElement {
     }
   };
 
+  /**
+   * Injects Vite HMR scripts during dev environment usage
+   */
   injectViteScripts = () => {
     if (document.querySelector('script[name="ccc-sdk-react-preamble"]')) return;
 
@@ -418,6 +544,28 @@ export class FTCustomCodeComponent extends HTMLElement {
     viteClientScript.src = `${this.testUrl?.origin}/@vite/client`;
     document.head.appendChild(viteClientScript);
   };
+
+  /**
+   * Called whenever the <custom-code-component>'s attributes are changed.
+   * Currently only used to dynamically set log level.
+   *
+   * @param name
+   * @param oldValue
+   * @param newValue
+   */
+  attributeChangedCallback(name: string, oldValue: string, newValue: string) {
+    this.log.debug("attributeChangedCallback lifecycle method", {
+      name,
+      oldValue,
+      newValue,
+    });
+
+    switch (name) {
+      case "log": {
+        this.log.setLogLevel(newValue);
+      }
+    }
+  }
 }
 
 export interface CustomCodeComponent extends ContentTree.Node {

package/src/logger.ts

@@ -7,6 +7,8 @@ export const LogLevel = Object.freeze({
   DEFAULT: 2,
 });
 
+const LOG_PREFIX = "CCC:";
+
 export function convertStringLogLevel(value: string | null) {
   const level = value?.toLowerCase();
 
@@ -34,18 +36,20 @@ export function convertStringLogLevel(value: string | null) {
 }
 
 export class Logger {
-  level: number;
+  public level: number;
   constructor(
     { level = LogLevel.DEFAULT }: { level: number } = {
       level: LogLevel.DEFAULT,
     }
   ) {
-    this.level = level;
+    this.level = localStorage.getItem("CCC_LOG_LEVEL")
+      ? convertStringLogLevel(localStorage.getItem("CCC_LOG_LEVEL"))
+      : level;
   }
 
   debug(...args: any[]) {
     if (this.level <= LogLevel.DEBUG) {
-      console.info(...args);
+      console.info(LOG_PREFIX, ...args);
     }
   }
 
@@ -53,19 +57,29 @@ export class Logger {
 
   info(...args: any[]) {
     if (this.level <= LogLevel.INFO) {
-      console.info(...args);
+      console.info(LOG_PREFIX, ...args);
     }
   }
 
   warn(...args: any[]) {
     if (this.level <= LogLevel.WARN) {
-      console.warn(...args);
+      console.warn(LOG_PREFIX, ...args);
     }
   }
 
   error(...args: any[]) {
     if (this.level <= LogLevel.ERROR) {
-      console.error(...args);
+      console.error(LOG_PREFIX, ...args);
+    }
+  }
+
+  setLogLevel(level: string | number | null) {
+    if (localStorage.getItem("CCC_LOG_LEVEL")) {
+      this.level = convertStringLogLevel(localStorage.getItem("CCC_LOG_LEVEL"));
+    } else if (typeof level === "number") {
+      this.level = level;
+    } else {
+      this.level = convertStringLogLevel(level);
     }
   }
 }