@financial-times/custom-code-component 1.11.1 → 2.0.1-alpha.10

package/src/custom-code-component.ts

@@ -3,15 +3,24 @@
  * Main component definition for custom-code-component
  */
 
-import { ContentTree } from "@financial-times/content-tree";
-import { BaseRenderer } from "../../ccc-sdk/src/renderers/AbstractBaseRenderer";
+import type { ContentTree } from "@financial-times/content-tree";
+import { BaseRenderer } from "../../ccc-sdk/src/renderers/BaseRenderer";
 import Tracking from "./tracking";
-
-class FTCustomCodeComponent extends HTMLElement {
-  app: typeof BaseRenderer.prototype.render;
-
-  mode: "closed" | "open";
-
+import { convertStringLogLevel, Logger } from "./logger";
+import {
+  CCCError,
+  CCCImportError,
+  CCCRenderError,
+  CCCTimeoutError,
+} from "./errors";
+import { CCCConnectedEvent } from "./events";
+import { ComponentPath } from "./path";
+import { kebabize } from "./util";
+import { assignTestURL, useComponentTestEnv } from "./environment";
+
+export class FTCustomCodeComponent extends HTMLElement {
+  app?: typeof BaseRenderer.prototype.render;
+  mode: "closed" | "open" = "open";
   RESERVED_ATTRS = new Set([
     "iframe",
     "path",
@@ -23,188 +32,271 @@ class FTCustomCodeComponent extends HTMLElement {
     "load-timeout",
   ]);
 
-  source: string;
-  tracking: Tracking;
-
-  async mount() {
-    if (!this.app) {
-      throw new Error("CCC mounted without App");
-    }
-
-    const shadow = this.shadowRoot ?? this.attachShadow({ mode: this.mode });
+  source?: string;
+  tracking?: Tracking;
+  lightRoot?: ChildNode[];
+  component?: ComponentPath;
 
-    const App = this.app;
+  log: Logger;
 
-    const data = JSON.parse(this.getAttribute("data-component-props")!);
+  constructor() {
+    super();
+    this.log = new Logger({
+      level: convertStringLogLevel(this.getAttribute("log")),
+    });
 
-    const extraProps = Object.fromEntries(
-      [...this.attributes]
-        .filter((attribute) => !this.RESERVED_ATTRS.has(attribute.name))
-        .map((attribute) => [attribute.name, attribute.value])
-    );
+    const supportsDeclarative =
+      HTMLElement.prototype.hasOwnProperty("attachInternals");
 
-    // Clear old children
-    // this.shadowRoot?.replaceChildren();
+    try {
+      const internals = supportsDeclarative && this.attachInternals();
+    } catch (e) {
+      this.log.error(e);
+    }
+  }
 
-    // Create tracking instance
-    this.tracking = new Tracking({
-      name: `${this.getAttribute("path")}@${this.getAttribute("version")}`,
-      subtype: "interactive",
-      teamName: "djd",
-      shadowRoot: this.shadowRoot,
-    });
+  async connectedCallback() {
+    try {
+      const path = this.getAttribute("path");
+      const versionRange = this.getAttribute("version");
+      this.component = ComponentPath.fromString(path, versionRange);
+      
+      // Backup the light root to restore in case of error
+      this.lightRoot = Array.from(this.childNodes);
+      this.app = await this.load();
+      await this.mount();
+      await this.initTracking();
+    } catch (e) {
+      if (e instanceof Error) {
+        requestAnimationFrame(() => {
+          this.emitError(e);
+        });
+      }
 
-    const { unmount, onmessage } =
-      App(
-        shadow,
-        {
-          ...extraProps,
-          data,
-          port: this.channel.port2,
-          tracking: this.tracking,
-        },
-        ...this.children
-      ) || {};
-
-    if (unmount) this.unmount = unmount;
-    if (onmessage) this.onmessage = onmessage;
+      this.unmount(e as Error);
+    }
   }
 
-  unmount = (root?: any) => {};
+  emitError(error: Error) {
+    let errorEvent;
 
-  async connectedCallback() {
-    const path = this.getAttribute("path");
-    const componentVersionRange = this.getAttribute("version");
-    const timeout = this.getAttribute("load-timeout") ?? 2000;
-    const useLocalVersion = this.getAttribute("env")
-      ?.toLowerCase()
-      .startsWith("d");
-
-    if (!path)
-      throw new Error(
-        "path attribute not specified in <custom-code-component>"
-      );
+    if (error instanceof CCCError && error.name?.startsWith("CCC")) {
+      errorEvent = error.name.replace(/^CCC/, "ccc:");
+    } else {
+      errorEvent = `ccc:${error?.name ?? "UnknownError"}`;
+    }
 
-    const [componentName, componentRepo, componentOrg] = path
-      .split("/")
-      .reverse();
+    if (!errorEvent) {
+      return this.log.debug(error);
+    }
 
-    if (!componentName || !componentRepo || !componentOrg) return;
+    this.dispatchEvent(
+      new ErrorEvent(errorEvent, {
+        bubbles: true,
+        cancelable: false,
+        composed: true,
+        error,
+        message: error.message,
+      })
+    );
+  }
 
-    const id = this.getAttribute('id');
+  disconnectedCallback() {
+    const path = this.getAttribute("path");
+    this.log.info(`<custom-code-component:${path}> disconnected`);
+    if (typeof this.onunmount === "function") this.onunmount();
+  }
 
-    // id querystring necessary to multiple allow components with the same source (same name and version number) to appear on the page correctly
-    this.source = useLocalVersion
-      ? `http://localhost:5173/src/${componentName}/index.jsx?id=${id}`
-      : `https://www.ft.com/__component/${componentOrg}/${componentRepo}${
-          componentVersionRange ? `@${componentVersionRange}` : "@latest"
-        }/${componentName}/${componentName}.js?id=${id}`;
-    
+  channel = new MessageChannel();
 
+  onmessage() {}
+  onunmount(root?: any) {}
+  async onready(app: Promise<void>) {
     try {
-      this.app = await new Promise((resolve, reject) => {
-        const to = setTimeout(() => {
-          this.dispatchEvent(
-            new CustomEvent("ccc-timeout", {
-              bubbles: true,
-              cancelable: true,
-              detail: {
-                component: `${path}@${componentVersionRange}`,
-                source: this.source,
-              },
-            })
-          );
-          this.dataset.cccError = "import-timeout";
-          delete this.dataset.cccReady;
-        }, Number(timeout));
-        import(/* webpackIgnore: true */ this.source /* @vite-ignore */)
-          .then(({ default: componentRenderFunction }) => {
-            if (componentRenderFunction) {
-              clearTimeout(to);
-              resolve(componentRenderFunction);
-            } else
-              throw new CCCImportError(
-                "No component renderer default export found"
-              );
-          })
-          .catch((e) => reject(new CCCImportError(e)));
-      });
+      await app;
     } catch (e) {
-      console.error(
-        `<custom-code-component> error during import from ${path}@${componentVersionRange}`
-      );
-
-      delete this.dataset.cccReady;
-      this.dataset.cccError = "import-failure";
-
-      this.dispatchEvent(new ErrorEvent("error", e));
-      console.error(e);
-
-      return; // prevent mounting on caught error
+      if (e instanceof Error) this.emitError(e);
     }
+  }
 
+  postMessage(event: any) {
+    this.channel.port1.postMessage(event);
+  }
+
+  async mount(prerendered?: ShadowRoot | null) {
     try {
       this.mode =
         this.getAttribute("shadow-open") == "false" ? "closed" : "open";
+      if (this.component) {
 
-      await this.mount();
-
-      this.dispatchEvent(
-        new CustomEvent("ccc-connected", {
-          bubbles: true,
-          cancelable: true,
-          detail: {
-            component: `${path}@${componentVersionRange}`,
+        this.dispatchEvent(
+          new CCCConnectedEvent({
+            component: this.component,
             source: this.source,
-          },
-        })
-      );
-
-      this.dataset.cccReady = "true";
-      delete this.dataset.cccError;
-    } catch (e) {
-      console.info(
-        `<custom-code-component> uncaught error during mount from ${path}@${componentVersionRange}`
+          })
+        );
+
+        this.dataset.cccReady = "true";
+        delete this.dataset.cccError;
+      
+
+        if (!this.app) {
+          throw new Error("CCC mounted without App");
+        }
+
+        const ssr = this.shadowRoot !== null;
+        const shadow = this.shadowRoot ?? this.attachShadow({ mode: this.mode });
+
+        const data = JSON.parse(this.getAttribute("data-component-props")!);
+
+        const extraProps = Object.fromEntries(
+          [...this.attributes]
+            .filter((attribute) => !this.RESERVED_ATTRS.has(attribute.name))
+            .map((attribute) => [attribute.name, attribute.value])
+        );
+
+        // Create tracking instance
+        this.tracking = new Tracking({
+          name: this.component?.toString(),
+          subtype: "interactive",
+          teamName: "djd",
+          shadowRoot: this.shadowRoot,
+          logger: this.log,
+        });
+
+        const { unmount, onmessage, ready } =
+          this.app(
+            shadow,
+            {
+              ...extraProps,
+              data,
+              port: this.channel.port2,
+              tracking: this.tracking,
+              prerendered: !!prerendered,
+              children: this.children,
+            },
+            ssr
+          ) || {};
+
+        if (unmount) this.onunmount = unmount;
+        if (onmessage) this.onmessage = onmessage;
+        if (ready) this.onready(ready);
+      }
+    } catch (err) {
+      this.log.info(
+        `<custom-code-component> uncaught error during mount from ${this.component?.toString()}`
       );
-      console.error(e);
-
-      this.dispatchEvent(new ErrorEvent("error", e));
-      this.dataset.cccError = "mount-error";
+      this.log.error(err);
 
-      delete this.dataset.cccReady;
+      throw err;
     }
+  }
 
-    try {
-      this.tracking.init(this.id);
-    } catch (e) {
-      console.info(
-        `Error initialising tracking on <custom-code-component> ${path}@${componentVersionRange}`
-      );
-      console.error(e);
+  // Called in top-level error handler
+  // Replace shadow root with light DOM children on error
+  unmount(e: Error) {
+    if (this.lightRoot) {
+      this.onunmount();
+      this.shadowRoot?.replaceChildren(...this.lightRoot);
+  
+      if (!this.dataset.cccError)
+        this.dataset.cccError = kebabize(e.name.replace("CCC", ""));
+      delete this.dataset.cccReady;
     }
   }
 
-  disconnectedCallback() {
+  async load() {
+    if (!this.component) {
+      throw new Error("No path found")
+    }
     const path = this.getAttribute("path");
-    console.info(`<custom-code-component:${path}> disconnected`);
-    if (typeof this.unmount === "function") this.unmount();
-  }
+    const componentVersionRange = this.getAttribute("version");
+    const timeout = Number(this.getAttribute("load-timeout") || 10000);
+    const testEnv = this.getAttribute("testEnv")
+    const testUrl = assignTestURL(testEnv)
+    const isTestEnv = await useComponentTestEnv(testUrl)
 
-  channel = new MessageChannel();
+    const id = this.getAttribute("id");
+    // id querystring necessary to multiple allow components with the same source (same name and version number) to appear on the page correctly
+    this.source = isTestEnv
+      ? `${testUrl?.origin}/src/${this.component.component}/index.jsx?id=${id}`
+      : `https://www.ft.com/__component/${this.component.org}/${this.component.repo}${
+          componentVersionRange ? `@${componentVersionRange}` : "@latest"
+        }/${this.component.component}/${this.component.component}.js?id=${id}`;
 
-  onmessage() {} // I'm honestly not sure what to do with this
+    try {
+      return await new Promise<typeof BaseRenderer.prototype.render>(
+        (resolve, reject) => {
+          const to = setTimeout(() => {
+            this.log.error("CCC import timeout error");
+            reject(
+              new CCCTimeoutError({
+                component: this.component!,
+                source: this.source,
+              })
+            );
+          }, Number(timeout));
+
+          if (this.source) {
+            import(/* webpackIgnore: true */ this.source /* @vite-ignore */)
+              .then(({ default: componentRenderFunction }) => {
+                if (componentRenderFunction) {
+                  clearTimeout(to);
+                  resolve(componentRenderFunction);
+                } else
+                  throw new CCCImportError(
+                    "No component renderer default export found",
+                    {
+                      component: this.component!,
+                      source: this.source,
+                    }
+                  );
+              })
+              .catch((e) => {
+                clearTimeout(to);
+                this.log.error(e);
+                if (e instanceof Error && !(e instanceof CCCImportError)) {
+                  reject(
+                    new CCCImportError(e.message, {
+                      component: this.component!,
+                      source: this.source,
+                    })
+                  );
+                } else {
+                  reject(e);
+                }
+              });
+          } else {
+            clearTimeout(to);
+            throw new CCCImportError(`Unable to mount ${path}`, {
+              component: this.component!,
+              source: this.source,
+            });
+          }
+        }
+      );
+    } catch (err) {
+      this.log.error(
+        `<custom-code-component> error during import from ${path}@${componentVersionRange}`
+      );
 
-  postMessage(event: any) {
-    this.channel.port1.postMessage(event);
+      throw err;
+    }
   }
-}
 
-// Register the custom element
-export const init = () =>
-  customElements.define("custom-code-component", FTCustomCodeComponent);
-
-// Allows module to be imported multiple times but custom element only registered once
-if (customElements && !customElements.get("custom-code-component")) init();
+  initTracking = async () => {
+    try {
+      this.tracking?.init(this.id);
+    } catch (e) {
+      const path = this.getAttribute("path");
+      const componentVersionRange = this.getAttribute("version");
+      this.log.info(
+        `Error initialising tracking on <custom-code-component> ${path}@${componentVersionRange}`
+      );
+      this.log.error(e);
+    }
+  };
+}
 
 export interface CustomCodeComponent extends ContentTree.Node {
   type: "CustomCodeComponent";
@@ -221,16 +313,4 @@ export interface CustomCodeComponent extends ContentTree.Node {
   } | { children?: CustomCodeComponent | Array<CustomCodeComponent> };
 }
 
-class CCCImportError extends Error {
-  constructor(...params) {
-    // Pass remaining arguments (including vendor specific ones) to parent constructor
-    super(...params);
-
-    // Maintains proper stack trace for where our error was thrown (only available on V8)
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, CCCImportError);
-    }
-
-    this.name = "CCCImportError";
-  }
-}
+export type { FTCustomCodeComponent as CCCHTMLElement };

package/src/environment.ts

@@ -0,0 +1,77 @@
+import { isLocalEnv, isSafeTestEnv, isSparkEnv } from "./util"
+
+
+/**
+ * Assigns a test URL based on the provided testEnv value.
+ *
+ * @param testEnv - A string indicating test environment setting
+ * @returns A `URL` object if valid and safe, or `undefined` if invalid.
+ */
+export function assignTestURL(testEnv: string | null): URL | undefined {
+  if (testEnv === null) {
+    return
+  }
+
+  let testUrl
+  const defaultTestUrl = new URL('http://localhost:5173')
+
+  try {
+    if (typeof testEnv === 'string') {
+      if ((testEnv === '' || testEnv.toLowerCase() === 'true') && isLocalEnv()) {
+        testUrl = defaultTestUrl
+      } else {
+        const hasProtocol = testEnv.startsWith('http://') || testEnv.startsWith('https://')
+        testUrl = hasProtocol ? new URL(testEnv) : undefined
+
+        // Prevent script injection
+        if (testUrl && !isSafeTestEnv(testUrl?.hostname)) {
+          throw new Error("Unsafe testing host override");
+        }
+      }
+    } else if (isSparkEnv()) {
+      testUrl = defaultTestUrl;
+    }
+  } catch (_) {
+    return testUrl
+  }
+
+  return testUrl
+}
+
+/**
+ * Checks whether the given test URL can establish a successful WebSocket connection,
+ * which indicates a live test environment (e.g., Vite HMR is active).
+ *
+ * @param testUrl - The test environment URL to check.
+ * @returns A promise that resolves to true if WebSocket connection is open, otherwise false.
+ */
+export async function useComponentTestEnv(testUrl?: URL): Promise<boolean> {
+  if (!testUrl) {
+    return false
+  }
+
+  function checkWebSocketOpen(host: string): Promise<boolean> {
+    try {
+      return new Promise<boolean>((res) => {
+        const socket = new WebSocket(`ws://${host}`, "vite-hmr");
+  
+        const timer = setTimeout(() => {
+          res(socket.readyState === WebSocket.OPEN);
+          socket.close();
+        }, 50);
+  
+        socket.addEventListener("error", () => {
+          clearTimeout(timer);
+          socket.close();
+          res(false);
+        }, { once: true });
+      });
+    } catch (err) {
+      return Promise.resolve(false);
+    }
+  }
+
+  const isWebSocketOpen = await checkWebSocketOpen(testUrl?.host);
+
+  return isWebSocketOpen
+}

package/src/errors.ts

@@ -0,0 +1,73 @@
+/**
+ * This is the base CCC component error class. These are raised when the component being loaded errors
+ */
+
+import { ComponentPath, DetailType, isValidComponentPathObject } from "./path";
+
+export class CCCError extends Error {
+  component: ComponentPath | null;
+  source?: string;
+  constructor(message: string | null, detail?: DetailType) {
+    if (!detail && message) {
+      super(message);
+      this.component = null;
+    } else if (typeof detail?.component === "string") {
+      super(
+        message ??
+          `${detail.cause ?? "Unknown error"} in ${detail.component} imported from ${detail.source ?? "an undefined source"}.`
+      );
+
+      this.component = ComponentPath.fromString(detail.component);
+    } else if (isValidComponentPathObject(detail?.component)) {
+      super(
+        message ??
+          `${detail.cause ?? "Unknown error"} in ${detail.component.org}/${detail.component.repo}/${detail.component.component}@${detail.component.versionRange} imported from ${detail.source ?? "an undefined source"}.`
+      );
+      this.component = new ComponentPath(detail.component);
+    } else {
+      super(
+        `${detail?.cause ?? "Unknown error"} in unknown component imported from ${detail?.source ?? "unknown source"}.`
+      );
+      this.component = null;
+    }
+
+    this.source = detail?.source;
+
+    // Maintains proper stack trace for where our error was thrown (only available on V8)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, CCCError);
+    }
+
+    this.name = "CCCError";
+  }
+}
+
+/**
+ * This class is used to raise errors that occur during the import of the CCC component app
+ */
+export class CCCImportError extends CCCError {
+  constructor(message: string, detail: DetailType) {
+    super(message, { ...detail, cause: "Import error" });
+    this.name = "CCCImportError";
+  }
+}
+
+/**
+ * This class is used to raise errors that occur during the rendering of the CCC component app
+ */
+export class CCCRenderError extends CCCError {
+  constructor(message: string, detail: DetailType) {
+    super(message, { ...detail, cause: "Render error" });
+    this.name = "CCCRenderError";
+  }
+}
+
+/**
+ * This class is used to raise errors that occur as a result of the CCC component app timing out
+ */
+export class CCCTimeoutError extends CCCError {
+  constructor(detail: DetailType) {
+    super(null, { ...detail, cause: "Timeout error" });
+    this.name = "CCCTimeoutError";
+  }
+}

package/src/events.ts

@@ -0,0 +1,22 @@
+import { ComponentPath } from "./path";
+
+export class CCCConnectedEvent extends Event {
+  static eventType = "ccc:ConnectedEvent";
+
+  component: ComponentPath;
+  source?: string;
+
+  constructor(
+    detail: { component: ComponentPath; source?: string },
+    opts?: EventInit
+  ) {
+    super(CCCConnectedEvent.eventType, {
+      bubbles: true,
+      cancelable: false,
+      composed: true,
+      ...opts,
+    });
+    this.component = detail.component;
+    this.source = detail.source;
+  }
+}