@financial-times/custom-code-component 0.0.1-THIS-IS-UPDATED-BY-CI

package/dist/webcomponent/src/environment.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 declare function assignTestURL(testEnv: string | null): URL | undefined;
+/**
+ * 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 declare function useComponentTestEnv(testUrl?: URL): Promise<boolean>;

package/dist/webcomponent/src/errors.d.ts

@@ -0,0 +1,27 @@
+/**
+ * This is the base CCC component error class. These are raised when the component being loaded errors
+ */
+import { ComponentPath, DetailType } from "./path";
+export declare class CCCError extends Error {
+    component: ComponentPath | null;
+    source?: string;
+    constructor(message: string | null, detail?: DetailType);
+}
+/**
+ * This class is used to raise errors that occur during the import of the CCC component app
+ */
+export declare class CCCImportError extends CCCError {
+    constructor(message: string, detail: DetailType);
+}
+/**
+ * This class is used to raise errors that occur during the rendering of the CCC component app
+ */
+export declare class CCCRenderError extends CCCError {
+    constructor(message: string, detail: DetailType);
+}
+/**
+ * This class is used to raise errors that occur as a result of the CCC component app timing out
+ */
+export declare class CCCTimeoutError extends CCCError {
+    constructor(detail: DetailType);
+}

package/dist/webcomponent/src/events.d.ts

@@ -0,0 +1,10 @@
+import { ComponentPath } from "./path";
+export declare class CCCConnectedEvent extends Event {
+    static eventType: string;
+    component: ComponentPath;
+    source?: string;
+    constructor(detail: {
+        component: ComponentPath;
+        source?: string;
+    }, opts?: EventInit);
+}

package/dist/webcomponent/src/get-trace.d.ts

@@ -0,0 +1,8 @@
+type PropMap = {
+    [k: string]: any;
+};
+export declare function getTrace(el: Element, rootEl: Element): {
+    trace: PropMap[];
+    customContext: {};
+};
+export {};

package/dist/webcomponent/src/index.d.ts

@@ -0,0 +1 @@
+export declare const init: () => void;

package/dist/webcomponent/src/logger.d.ts

@@ -0,0 +1,20 @@
+export declare const LogLevel: Readonly<{
+    DEBUG: 0;
+    INFO: 1;
+    WARN: 2;
+    ERROR: 3;
+    TEST: 4;
+    DEFAULT: 2;
+}>;
+export declare function convertStringLogLevel(value: string | null): 0 | 2 | 1 | 3 | 4;
+export declare class Logger {
+    level: number;
+    constructor({ level }?: {
+        level: number;
+    });
+    debug(...args: any[]): void;
+    log: (...args: any[]) => void;
+    info(...args: any[]): void;
+    warn(...args: any[]): void;
+    error(...args: any[]): void;
+}

package/dist/webcomponent/src/path.d.ts

@@ -0,0 +1,23 @@
+export type ComponentPathType = {
+    org: string;
+    repo: string;
+    component: string;
+    versionRange: string;
+};
+export declare class ComponentPath {
+    org: string;
+    repo: string;
+    component: string;
+    versionRange: string;
+    constructor(path: ComponentPathType | string);
+    set path(path: ComponentPathType | string);
+    get path(): string;
+    toString(): string;
+    static fromString(path: string | null, v?: string | null): ComponentPath;
+}
+export type DetailType = {
+    component: ComponentPath;
+    source?: string;
+    cause?: string;
+};
+export declare function isValidComponentPathObject(value: unknown): value is ComponentPathType;

package/dist/webcomponent/src/tracking.d.ts

@@ -0,0 +1,32 @@
+import { Logger } from "./logger";
+declare class Tracking {
+    cccId: string;
+    cccName: string;
+    subtype: string;
+    teamName: string;
+    shadowRoot: ShadowRoot | null;
+    category: string;
+    elements: string | string[];
+    isInitialised: boolean;
+    log: Logger;
+    constructor({ id, name, subtype, teamName, shadowRoot, category, elements, logger, }: {
+        id?: string;
+        name: string;
+        subtype: string;
+        teamName?: string;
+        shadowRoot: ShadowRoot | null;
+        category?: string;
+        elements?: string | string[];
+        logger: Logger;
+    });
+    getEventProperties(event: any): {
+        [k: string]: any;
+    };
+    handleClickEvent(eventData: {
+        action: string;
+        category: string;
+    }, root: Element): (clickEvent: Event, clickElement: HTMLElement) => void;
+    sendSpoorEvent(triggerAction: any, extraDetail: any): void;
+    init(id: string): void;
+}
+export default Tracking;

package/dist/webcomponent/src/util.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Used to convert camelCase to kebab-case
+ * @param str
+ * @returns
+ */
+export declare const kebabize: (str: string) => string;
+/**
+ * Checks if the provided host is part of the allowed test environments.
+ *
+ * @param host - The hostname to check.
+ * @returns True if the hostname is a safe test environment, false otherwise.
+ */
+export declare function isSafeTestEnv(host: string | undefined): boolean;
+/**
+ * Checks if the current window location hostname is considered a local environment.
+ *
+ * @returns True if the hostname is local, false otherwise.
+ */
+export declare function isLocalEnv(): boolean;
+/**
+ * Checks if the current window location host is one of the Spark environments.
+ *
+ * @returns True if the host is spark.ft.com or spark-staging.ft.com, false otherwise.
+ */
+export declare function isSparkEnv(): boolean;
+/**
+ * Checks if the given hostname is in the provided allowlist.
+ *
+ * @param allowlist - A list of allowed hostnames or RegExp matchers.
+ * @param hostname - The hostname to validate.
+ * @returns True if the hostname matches any item in the allowlist, false otherwise.
+ */
+export declare function isAllowed(allowlist: (string | RegExp)[], hostname: string | undefined): boolean;

package/dist/webcomponent/test/environment.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/webcomponent/test/error-handling.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @file
+ * Unit test for web component error handling
+ */
+export declare const worker: import("msw/browser").SetupWorker;
+export declare const it: import("vitest").TestAPI<{
+    worker: import("msw/browser").SetupWorker;
+}>;

package/dist/webcomponent/test/example.d.ts

@@ -0,0 +1,11 @@
+import { ReactRenderer } from "../../ccc-sdk/src/renderers/react/ReactRenderer";
+export declare const renderer: ReactRenderer;
+declare const _default: (shadowRoot: ShadowRoot, attrs: any, ssr?: boolean) => {
+    unmount: (root: any) => void;
+    onmessage: {
+        (...data: any[]): void;
+        (message?: any, ...optionalParams: any[]): void;
+    };
+    ready: Promise<void>;
+};
+export default _default;

package/dist/webcomponent/test/generate-readable-stream.d.ts

@@ -0,0 +1,8 @@
+import { BaseRenderer } from "~sdk/renderers/BaseRenderer";
+export declare const generateReadableStream: ({ framework, props, renderer, }: {
+    framework: string;
+    renderer: BaseRenderer;
+    props: {
+        [key: string]: any;
+    };
+}) => Promise<Response>;

package/dist/webcomponent/test/path.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @file
+ * Unit tests for the ComponentPath module
+ */
+export {};

package/dist/webcomponent/test/ssr.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @file
+ * Integration testing for server-side rendering
+ */

package/dist/webcomponent/test/utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/webcomponent/vite.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vite").UserConfig;
+export default _default;

package/dist/webcomponent/vitest.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vite").UserConfig;
+export default _default;

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@financial-times/custom-code-component",
+  "version": "0.0.1-THIS-IS-UPDATED-BY-CI",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/custom-code-component.js",
+      "types": "./dist/custom-code-component.d.ts"
+    }
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@datastream/core": "^0.0.36",
+    "@financial-times/content-tree": "github:financial-times/content-tree",
+    "@open-wc/testing-helpers": "^3.0.1",
+    "@testing-library/jest-dom": "^6.4.8",
+    "@testing-library/react": "^16.0.0",
+    "@vitejs/plugin-react": "^4.0.4",
+    "@vitest/browser": "^3.0.6",
+    "eslint": "^8.47.0",
+    "eslint-plugin-react": "^7.33.1",
+    "jsdom": "^24.1.1",
+    "local-pkg": "^1.0.0",
+    "msw": "^2.7.3",
+    "playwright": "^1.50.1",
+    "typescript": "^5.2.2",
+    "vite": "^4.4.9",
+    "vite-plugin-dts": "^3.6.0",
+    "vitest": "^3.0.6"
+  },
+  "dependencies": {
+    "@webcomponents/scoped-custom-element-registry": "^0.0.9",
+    "ftdomdelegate": "^5.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "ws": "^8.18.1"
+  },
+  "peerDependencies": {
+    "@financial-times/o-tracking": "4.x"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "overrides": {
+    "vitest": {
+      "happy-dom": "latest"
+    }
+  }
+}

package/src/custom-code-component.ts

@@ -0,0 +1,310 @@
+/**
+ * @file
+ * Main component definition for custom-code-component
+ */
+
+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 {
+  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",
+    "version",
+    "data-component-props",
+    "data-asset-type",
+    "shadow-open",
+    "env",
+    "load-timeout",
+  ]);
+
+  source?: string;
+  tracking?: Tracking;
+  lightRoot: ChildNode[];
+  component: ComponentPath;
+
+  log: Logger;
+
+  constructor() {
+    super();
+
+    this.log = new Logger({
+      level: convertStringLogLevel(this.getAttribute("log")),
+    });
+
+    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);
+
+    const supportsDeclarative =
+      HTMLElement.prototype.hasOwnProperty("attachInternals");
+
+    try {
+      const internals = supportsDeclarative && this.attachInternals();
+    } catch (e) {
+      this.log.error(e);
+    }
+  }
+
+  async connectedCallback() {
+    try {
+      this.app = await this.load();
+      await this.mount();
+      await this.initTracking();
+    } catch (e) {
+      if (e instanceof Error) {
+        requestAnimationFrame(() => {
+          this.emitError(e);
+        });
+      }
+
+      this.unmount(e as Error);
+    }
+  }
+
+  emitError(error: Error) {
+    let errorEvent;
+
+    if (error instanceof CCCError && error.name?.startsWith("CCC")) {
+      errorEvent = error.name.replace(/^CCC/, "ccc:");
+    } else {
+      errorEvent = `ccc:${error?.name ?? "UnknownError"}`;
+    }
+
+    if (!errorEvent) {
+      return this.log.debug(error);
+    }
+
+    this.dispatchEvent(
+      new ErrorEvent(errorEvent, {
+        bubbles: true,
+        cancelable: false,
+        composed: true,
+        error,
+        message: error.message,
+      })
+    );
+  }
+
+  disconnectedCallback() {
+    const path = this.getAttribute("path");
+    this.log.info(`<custom-code-component:${path}> disconnected`);
+    if (typeof this.onunmount === "function") this.onunmount();
+  }
+
+  channel = new MessageChannel();
+
+  onmessage() {}
+  onunmount(root?: any) {}
+  async onready(app: Promise<void>) {
+    try {
+      await app;
+    } catch (e) {
+      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";
+
+      this.dispatchEvent(
+        new CCCConnectedEvent({
+          component: this.component,
+          source: this.source,
+        })
+      );
+
+      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()}`
+      );
+      this.log.error(err);
+
+      throw err;
+    }
+  }
+
+  // Called in top-level error handler
+  // Replace shadow root with light DOM children on error
+  unmount(e: Error) {
+    this.onunmount();
+    this.shadowRoot?.replaceChildren(...this.lightRoot);
+
+    if (!this.dataset.cccError)
+      this.dataset.cccError = kebabize(e.name.replace("CCC", ""));
+    delete this.dataset.cccReady;
+  }
+
+  async load() {
+    const path = this.getAttribute("path");
+    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)
+
+    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}`;
+
+    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}`
+      );
+
+      throw err;
+    }
+  }
+
+  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";
+  path: string;
+  versionRange: string;
+  altText: string;
+  lastModified: string;
+  fallbackImage?: ContentTree.Image;
+  displayFallbackText: boolean;
+  layout: "in-line" | "mid-grid" | "full-grid" | "full-bleed";
+  /* prettier-ignore */
+  attributes: { 
+    [key: string]: string | boolean | undefined;
+  } | { children?: CustomCodeComponent | Array<CustomCodeComponent> };
+}
+
+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) {
+    return
+  }
+  let testUrl
+  const defaultTestUrl = new URL('http://localhost:5173')
+
+  try {
+    if (typeof testEnv === 'string') {
+      if (testEnv === '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) {
+      console.error("WebSocket creation failed:", err);
+      return Promise.resolve(false);
+    }
+  }
+
+  const isWebSocketOpen = await checkWebSocketOpen(testUrl?.host);
+
+  return isWebSocketOpen
+}