@financial-times/custom-code-component 2.0.1-alpha.11 → 2.0.1-alpha.5

package/dist/webcomponent/src/custom-code-component.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @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 { Logger } from "./logger";
+import { ComponentPath } from "./path";
+export declare class FTCustomCodeComponent extends HTMLElement {
+    app?: typeof BaseRenderer.prototype.render;
+    mode: "closed" | "open";
+    RESERVED_ATTRS: Set<string>;
+    source?: string;
+    tracking?: Tracking;
+    lightRoot: ChildNode[];
+    component: ComponentPath;
+    log: Logger;
+    constructor();
+    connectedCallback(): Promise<void>;
+    emitError(error: Error): void;
+    disconnectedCallback(): void;
+    channel: MessageChannel;
+    onmessage(): void;
+    onunmount(root?: any): void;
+    onready(app: Promise<void>): Promise<void>;
+    postMessage(event: any): void;
+    mount(prerendered?: ShadowRoot | null): Promise<void>;
+    unmount(e: Error): void;
+    load(): Promise<(shadowRoot: ShadowRoot, attrs: any, ssr?: boolean) => {
+        unmount: (root: any) => void;
+        onmessage: {
+            (...data: any[]): void;
+            (message?: any, ...optionalParams: any[]): void;
+        };
+        ready: Promise<void>;
+    }>;
+    initTracking: () => Promise<void>;
+}
+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";
+    attributes: {
+        [key: string]: string | boolean | undefined;
+    } | {
+        children?: CustomCodeComponent | Array<CustomCodeComponent>;
+    };
+}
+export type { FTCustomCodeComponent as CCCHTMLElement };

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/{CustomCodeComponent.d.ts → webcomponent/src/index.d.ts}

@@ -1,3 +1 @@
-export declare const init: () => void;
-
-export { }
+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

@@ -1,11 +1,11 @@
 {
   "name": "@financial-times/custom-code-component",
-  "version": "2.0.1-alpha.11",
+  "version": "2.0.1-alpha.5",
   "type": "module",
   "exports": {
     ".": {
-      "types": "./dist/CustomCodeComponent.d.ts",
-      "default": "./dist/CustomCodeComponent.js"
+      "import": "./dist/custom-code-component.js",
+      "types": "./dist/custom-code-component.d.ts"
     }
   },
   "scripts": {
@@ -30,8 +30,8 @@
     "msw": "^2.7.3",
     "playwright": "^1.50.1",
     "typescript": "^5.2.2",
-    "vite": "^6.3.5",
-    "vite-plugin-dts": "^4.5.3",
+    "vite": "^4.4.9",
+    "vite-plugin-dts": "^3.6.0",
     "vitest": "^3.0.6"
   },
   "dependencies": {

package/src/custom-code-component.ts

@@ -34,17 +34,25 @@ export class FTCustomCodeComponent extends HTMLElement {
 
   source?: string;
   tracking?: Tracking;
-  lightRoot?: ChildNode[];
-  component?: ComponentPath;
+  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");
 
@@ -57,12 +65,6 @@ export class FTCustomCodeComponent extends HTMLElement {
 
   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();
@@ -127,64 +129,61 @@ export class FTCustomCodeComponent extends HTMLElement {
     try {
       this.mode =
         this.getAttribute("shadow-open") == "false" ? "closed" : "open";
-      if (this.component) {
-
-        this.dispatchEvent(
-          new CCCConnectedEvent({
-            component: this.component,
-            source: this.source,
-          })
-        );
 
-        this.dataset.cccReady = "true";
-        delete this.dataset.cccError;
-      
+      this.dispatchEvent(
+        new CCCConnectedEvent({
+          component: this.component,
+          source: this.source,
+        })
+      );
 
-        if (!this.app) {
-          throw new Error("CCC mounted without App");
-        }
+      this.dataset.cccReady = "true";
+      delete this.dataset.cccError;
 
-        const ssr = this.shadowRoot !== null;
-        const shadow = this.shadowRoot ?? this.attachShadow({ mode: this.mode });
+      if (!this.app) {
+        throw new Error("CCC mounted without App");
+      }
 
-        const data = JSON.parse(this.getAttribute("data-component-props")!);
+      const ssr = this.shadowRoot !== null;
+      const shadow = this.shadowRoot ?? this.attachShadow({ mode: this.mode });
 
-        const extraProps = Object.fromEntries(
-          [...this.attributes]
-            .filter((attribute) => !this.RESERVED_ATTRS.has(attribute.name))
-            .map((attribute) => [attribute.name, attribute.value])
-        );
+      const data = JSON.parse(this.getAttribute("data-component-props")!);
 
-        // Create tracking instance
-        this.tracking = new Tracking({
-          name: this.component?.toString(),
-          subtype: "interactive",
-          teamName: "djd",
-          shadowRoot: this.shadowRoot,
-          logger: this.log,
-        });
+      const extraProps = Object.fromEntries(
+        [...this.attributes]
+          .filter((attribute) => !this.RESERVED_ATTRS.has(attribute.name))
+          .map((attribute) => [attribute.name, attribute.value])
+      );
 
-        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);
-      }
+      // 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()}`
+        `<custom-code-component> uncaught error during mount from ${this.component.toString()}`
       );
       this.log.error(err);
 
@@ -195,20 +194,15 @@ export class FTCustomCodeComponent extends HTMLElement {
   // 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;
-    }
+    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() {
-    if (!this.component) {
-      throw new Error("No path found")
-    }
     const path = this.getAttribute("path");
     const componentVersionRange = this.getAttribute("version");
     const timeout = Number(this.getAttribute("load-timeout") || 10000);
@@ -231,7 +225,7 @@ export class FTCustomCodeComponent extends HTMLElement {
             this.log.error("CCC import timeout error");
             reject(
               new CCCTimeoutError({
-                component: this.component!,
+                component: this.component,
                 source: this.source,
               })
             );
@@ -247,7 +241,7 @@ export class FTCustomCodeComponent extends HTMLElement {
                   throw new CCCImportError(
                     "No component renderer default export found",
                     {
-                      component: this.component!,
+                      component: this.component,
                       source: this.source,
                     }
                   );
@@ -258,7 +252,7 @@ export class FTCustomCodeComponent extends HTMLElement {
                 if (e instanceof Error && !(e instanceof CCCImportError)) {
                   reject(
                     new CCCImportError(e.message, {
-                      component: this.component!,
+                      component: this.component,
                       source: this.source,
                     })
                   );
@@ -269,7 +263,7 @@ export class FTCustomCodeComponent extends HTMLElement {
           } else {
             clearTimeout(to);
             throw new CCCImportError(`Unable to mount ${path}`, {
-              component: this.component!,
+              component: this.component,
               source: this.source,
             });
           }

package/src/environment.ts

@@ -8,16 +8,15 @@ import { isLocalEnv, isSafeTestEnv, isSparkEnv } from "./util"
  * @returns A `URL` object if valid and safe, or `undefined` if invalid.
  */
 export function assignTestURL(testEnv: string | null): URL | undefined {
-  if (testEnv === null) {
+  if (!testEnv) {
     return
   }
-
   let testUrl
   const defaultTestUrl = new URL('http://localhost:5173')
 
   try {
     if (typeof testEnv === 'string') {
-      if ((testEnv === '' || testEnv.toLowerCase() === 'true') && isLocalEnv()) {
+      if (testEnv === 'true' && isLocalEnv()) {
         testUrl = defaultTestUrl
       } else {
         const hasProtocol = testEnv.startsWith('http://') || testEnv.startsWith('https://')
@@ -67,6 +66,7 @@ export async function useComponentTestEnv(testUrl?: URL): Promise<boolean> {
         }, { once: true });
       });
     } catch (err) {
+      console.error("WebSocket creation failed:", err);
       return Promise.resolve(false);
     }
   }