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

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;
+  }
+}

package/src/get-trace.ts

@@ -0,0 +1,144 @@
+// Trace the element and all of its parents, collecting properties as we go
+import {
+  sanitise,
+  assignIfUndefined,
+} from "@financial-times/o-tracking/src/javascript/utils";
+
+type PropMap = { [k: string]: any };
+// For a given container element, get the number of elements that match the
+// original element (siblings); and the index of the original element (position).
+const getSiblingsAndPosition = (
+  el: Element | null,
+  originalEl: Element,
+  selector: string
+) => {
+  const siblings = Array.from(el?.querySelectorAll(selector) ?? []);
+  const position = siblings.findIndex((item) => item === originalEl);
+  if (position === -1) {
+    return;
+  }
+  return {
+    siblings: siblings.length,
+    position,
+  };
+};
+
+const elementPropertiesToCollect = [
+  "nodeName",
+  "className",
+  "id",
+  "href",
+  "text",
+  "role",
+];
+// Get all (sanitised) properties of a given element.
+const getAllElementProperties = (element: any) => {
+  const properties: PropMap = {};
+  for (const property of elementPropertiesToCollect) {
+    const value =
+      element[property] ||
+      element.getAttribute(property) ||
+      element.hasAttribute(property);
+    if (value !== undefined) {
+      if (typeof value === "boolean") {
+        properties[property] = value;
+      } else {
+        properties[property] = sanitise(value);
+      }
+    }
+  }
+
+  return properties;
+};
+
+const parseRawValue = (rawValue: string) => {
+  try {
+    const parsedValue = JSON.parse(rawValue);
+    const type = Object.prototype.toString.call(parsedValue);
+    const isJSON = type === "[object Object]" || type === "[object Array]";
+
+    return [isJSON, parsedValue];
+  } catch (error) {
+    return [false, null];
+  }
+};
+
+const getAttributeValue = (rawValue: string) => {
+  const [isJSON, value] = parseRawValue(rawValue);
+
+  return isJSON ? value : rawValue;
+};
+
+// Get some properties of a given element.
+const getDomPathProps = (attrs: Attr[], props: PropMap) => {
+  // Collect any attribute that matches given strings.
+  attrs
+    .filter((attribute) =>
+      attribute.name.match(/^data-trackable|^data-o-|^aria-/i)
+    )
+    .forEach((attribute) => {
+      props[attribute.name] = attribute.value;
+    });
+
+  return props;
+};
+
+// Get only the custom data-trackable-context-? properties of a given element
+const getContextProps = (
+  attrs: Attr[],
+  props: PropMap,
+  isOriginalEl: boolean
+) => {
+  const customProps: { [k: string]: any } = {};
+
+  // for the original element collect properties like className, nodeName
+  if (isOriginalEl) {
+    elementPropertiesToCollect.forEach((name) => {
+      if (typeof props[name] !== "undefined" && name !== "id") {
+        customProps[name] = props[name];
+      }
+    });
+  }
+
+  // Collect any attribute that matches given strings.
+  attrs
+    .filter((attribute) => attribute.name.match(/^data-trackable-context-/i))
+    .forEach((attribute) => {
+      customProps[attribute.name.replace("data-trackable-context-", "")] =
+        getAttributeValue(attribute.value);
+    });
+
+  return customProps;
+};
+
+export function getTrace(el: Element, rootEl: Element) {
+  const originalEl = el;
+  const selector = originalEl?.getAttribute("data-trackable")
+    ? `[data-trackable="${originalEl.getAttribute("data-trackable")}"]`
+    : originalEl?.nodeName;
+  const trace = [];
+  const customContext = {};
+  while (el && el !== rootEl) {
+    const props = getAllElementProperties(el);
+    const attrs = Array.from(el.attributes);
+    let domPathProps = getDomPathProps(attrs, props);
+
+    // If the element happens to have a data-trackable attribute, get the siblings
+    // and position of the element (relative to the current element).
+    if (domPathProps["data-trackable"]) {
+      domPathProps = Object.assign(
+        domPathProps,
+        getSiblingsAndPosition(el, originalEl, selector)
+      );
+    }
+
+    trace.push(domPathProps);
+
+    const contextProps = getContextProps(attrs, props, el === originalEl);
+
+    assignIfUndefined(contextProps, customContext);
+
+    el = el.parentNode as Element;
+  }
+  return { trace, customContext };
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+import { FTCustomCodeComponent } from "./custom-code-component";
+
+// 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();

package/src/logger.ts

@@ -0,0 +1,71 @@
+export const LogLevel = Object.freeze({
+  DEBUG: 0,
+  INFO: 1,
+  WARN: 2,
+  ERROR: 3,
+  TEST: 4,
+  DEFAULT: 2,
+});
+
+export function convertStringLogLevel(value: string | null) {
+  const level = value?.toLowerCase();
+
+  if (level === "debug") {
+    return LogLevel.DEBUG;
+  }
+
+  if (level === "info") {
+    return LogLevel.INFO;
+  }
+
+  if (level === "warn") {
+    return LogLevel.WARN;
+  }
+
+  if (level === "error") {
+    return LogLevel.ERROR;
+  }
+
+  if (level === "test") {
+    return LogLevel.TEST;
+  }
+
+  return LogLevel.DEFAULT;
+}
+
+export class Logger {
+  level: number;
+  constructor(
+    { level = LogLevel.DEFAULT }: { level: number } = {
+      level: LogLevel.DEFAULT,
+    }
+  ) {
+    this.level = level;
+  }
+
+  debug(...args: any[]) {
+    if (this.level <= LogLevel.DEBUG) {
+      console.info(...args);
+    }
+  }
+
+  log = this.debug;
+
+  info(...args: any[]) {
+    if (this.level <= LogLevel.INFO) {
+      console.info(...args);
+    }
+  }
+
+  warn(...args: any[]) {
+    if (this.level <= LogLevel.WARN) {
+      console.warn(...args);
+    }
+  }
+
+  error(...args: any[]) {
+    if (this.level <= LogLevel.ERROR) {
+      console.error(...args);
+    }
+  }
+}

package/src/path.ts

@@ -0,0 +1,83 @@
+import { CCCError } from "./errors";
+
+export type ComponentPathType = {
+  org: string;
+  repo: string;
+  component: string;
+  versionRange: string;
+};
+export class ComponentPath {
+  org: string;
+  repo: string;
+  component: string;
+  versionRange: string;
+
+  constructor(path: ComponentPathType | string) {
+    const { org, repo, component, versionRange } = isValidComponentPathObject(
+      path
+    )
+      ? path
+      : ComponentPath.fromString(path);
+    this.org = org;
+    this.repo = repo;
+    this.component = component;
+    this.versionRange = versionRange;
+  }
+
+  set path(path: ComponentPathType | string) {
+    const { org, repo, component, versionRange } = isValidComponentPathObject(
+      path
+    )
+      ? path
+      : ComponentPath.fromString(path);
+    this.org = org;
+    this.repo = repo;
+    this.component = component;
+    this.versionRange = versionRange;
+  }
+
+  get path(): string {
+    return `${this.org}/${this.repo}@${this.versionRange}/${this.component}`;
+  }
+
+  toString(): string {
+    return this.path;
+  }
+
+  static fromString(path: string | null, v?: string | null): ComponentPath {
+    if (!path) throw new CCCError("No path specified");
+
+    const versionRange =
+      v ??
+      path
+        .match(/@[^\/]+/)
+        ?.toString()
+        .replace("@", "") ??
+      "unknown";
+
+    if (!versionRange) throw new CCCError("No version specified");
+
+    const [component, repo, org] = path
+      .replace(/@[^\/]+/, "")
+      .split("/")
+      .reverse();
+
+    return new ComponentPath({ org, repo, component, versionRange });
+  }
+}
+
+export type DetailType = {
+  component: ComponentPath;
+  source?: string;
+  cause?: string;
+};
+
+export function isValidComponentPathObject(
+  value: unknown
+): value is ComponentPathType {
+  if (typeof value === "object" && value !== null) {
+    return "org" in value && "repo" in value && "component" in value;
+  }
+
+  return false;
+}

package/src/tracking.ts

@@ -0,0 +1,157 @@
+import Delegate from "ftdomdelegate/main";
+
+import {
+  sanitise,
+  assignIfUndefined,
+} from "@financial-times/o-tracking/src/javascript/utils";
+import { Logger } from "./logger";
+import { getTrace } from "./get-trace";
+
+const eventPropertiesToCollect = ["ctrlKey", "altKey", "shiftKey", "metaKey"];
+
+class Tracking {
+  cccId: string;
+  cccName: string;
+  subtype: string;
+  teamName: string;
+  shadowRoot: ShadowRoot | null;
+  category: string;
+  elements: string | string[];
+  isInitialised: boolean;
+  log: Logger;
+
+  constructor({
+    id = "00000000-0000-0000-0000-000000000000",
+    name = "ccc-component",
+    subtype = "interactive",
+    teamName = "djd",
+    shadowRoot = null,
+    category = "cta",
+    elements = 'a, button, input, [role="button"]',
+    logger,
+  }: {
+    id?: string;
+    name: string;
+    subtype: string;
+    teamName?: string;
+    shadowRoot: ShadowRoot | null;
+    category?: string;
+    elements?: string | string[];
+    logger: Logger;
+  }) {
+    this.cccId = id;
+    this.cccName = name;
+    this.subtype = subtype;
+    this.teamName = teamName;
+    this.shadowRoot = shadowRoot;
+    this.category = category;
+    this.elements = elements;
+    this.isInitialised = false;
+    this.log = logger ?? new Logger();
+  }
+
+  // Get properties for the event (as opposed to properties of the clicked element)
+  getEventProperties(event: any) {
+    const eventProperties: { [k: string]: any } = {};
+    for (const property of eventPropertiesToCollect) {
+      if (event[property]) {
+        try {
+          eventProperties[property] = sanitise(event[property]);
+        } catch (e) {
+          this.log.info(e);
+        }
+      }
+    }
+    return eventProperties;
+  }
+
+  // Controller for handling click events
+  handleClickEvent(
+    eventData: { action: string; category: string },
+    root: Element
+  ) {
+    return (clickEvent: Event, clickElement: HTMLElement) => {
+      const context: any = this.getEventProperties(clickEvent);
+      const { trace, customContext } = getTrace(clickElement, root);
+      context.custom =
+        clickElement.dataset && clickElement.dataset.custom
+          ? JSON.parse(clickElement.dataset.custom)
+          : null;
+      context.domPathTokens = trace;
+      context.component = {
+        id: this.cccId,
+        name: this.cccName,
+        type: "custom-code-component",
+        subtype: this.subtype,
+      };
+      context.teamName = this.teamName;
+      context.url = document.URL;
+
+      assignIfUndefined(customContext, context);
+
+      context.method = "ftCustomAnalytics";
+      eventData = { ...eventData, ...context };
+
+      // send spoor event
+      document.body.dispatchEvent(
+        new CustomEvent("oTracking.event", {
+          detail: eventData,
+          bubbles: true,
+          composed: true,
+        })
+      );
+    };
+  }
+
+  sendSpoorEvent(triggerAction: any, extraDetail: any) {
+    const eventData = {
+      category: "component",
+      action: "act",
+      component: {
+        id: this.cccId,
+        name: this.cccName,
+        type: "custom-code-component",
+        subtype: this.subtype,
+      },
+      teamName: this.teamName,
+      trigger_action: triggerAction,
+      custom: extraDetail,
+      method: "ftCustomAnalytics",
+    };
+
+    // send spoor event
+    document.body.dispatchEvent(
+      new CustomEvent("oTracking.event", {
+        detail: eventData,
+        bubbles: true,
+        composed: true,
+      })
+    );
+  }
+
+  init(id: string) {
+    if (!this.isInitialised) {
+      this.isInitialised = true;
+      this.cccId = id ? id : this.cccId;
+
+      const eventData = {
+        action: "click",
+        category: this.category,
+      };
+
+      const root = this.shadowRoot?.querySelector("[data-component-root]");
+
+      if (root) {
+        const shadowDelegate = new Delegate(root);
+        shadowDelegate.on(
+          "click",
+          this.elements,
+          this.handleClickEvent(eventData, root),
+          true
+        );
+      }
+    }
+  }
+}
+
+export default Tracking;

package/src/util.ts

@@ -0,0 +1,66 @@
+/**
+ * Used to convert camelCase to kebab-case
+ * @param str
+ * @returns
+ */
+export const kebabize = (str: string) =>
+  str.replace(
+    /[A-Z]+(?![a-z])|[A-Z]/g,
+    ($, ofs) => (ofs ? "-" : "") + $.toLowerCase()
+  );
+
+/**
+ * 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 function isSafeTestEnv(host: string | undefined) {
+  return isAllowed([
+    'localhost',
+    'local.ft.com',
+    /^.*\.apps\.in\.ft\.com$/,
+  ], host);
+}
+
+/**
+ * Checks if the current window location hostname is considered a local environment.
+ *
+ * @returns True if the hostname is local, false otherwise.
+ */
+export function isLocalEnv() {
+  return isAllowed([
+    'localhost',
+    'local.ft.com',
+    /^.*\.in\.ft\.com$/,
+  ], window.location.hostname);
+}
+
+/**
+ * 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 function isSparkEnv() {
+  return isAllowed([
+    'spark.ft.com',
+    'spark-staging.ft.com',
+  ], window.location.host);
+}
+
+/**
+ * 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 function isAllowed(allowlist: (string|RegExp)[], hostname: string | undefined) {
+  if (!hostname) return false;
+  return allowlist.some(item => {
+    if (typeof item === 'string') {
+      return item === hostname;
+    }
+    return item.test(hostname);
+  });
+}