@hubspot/ui-extensions 0.11.0 → 0.11.2

package/dist/experimental/testing/internal/document.d.ts

@@ -0,0 +1,14 @@
+import type { RenderedDocumentInternal, RenderedRootNodeInternal } from './types-internal';
+export interface CreateDocumentOptions {
+    /**
+     * A function that can be called to get the latest rendered root node.
+     */
+    getLatestRootNode: () => RenderedRootNodeInternal;
+}
+/**
+ * Creates a rendered document.
+ *
+ * @param options Options for creating the document.
+ * @returns A rendered document.
+ */
+export declare const createDocument: (options: CreateDocumentOptions) => RenderedDocumentInternal;

package/dist/experimental/testing/internal/document.js

@@ -0,0 +1,37 @@
+import { act as reactAct } from 'react';
+import { InvalidComponentsError } from './errors';
+/**
+ * Creates a rendered document.
+ *
+ * @param options Options for creating the document.
+ * @returns A rendered document.
+ */
+export const createDocument = (options) => {
+    const { getLatestRootNode } = options;
+    const invalidComponentNames = new Set();
+    const document = {
+        rootNode: null,
+        batchUpdate: (run) => {
+            reactAct(run);
+            const latestRootNode = getLatestRootNode();
+            if (latestRootNode.document.hasInvalidComponentNames()) {
+                throw new InvalidComponentsError(latestRootNode);
+            }
+        },
+        addInvalidComponentName: (name) => {
+            invalidComponentNames.add(name);
+        },
+        getInvalidComponentNames: () => {
+            if (invalidComponentNames.size === 0) {
+                return [];
+            }
+            const invalidComponentNamesArray = [...invalidComponentNames];
+            invalidComponentNamesArray.sort();
+            return invalidComponentNamesArray;
+        },
+        hasInvalidComponentNames: () => {
+            return invalidComponentNames.size > 0;
+        },
+    };
+    return document;
+};

package/dist/experimental/testing/internal/element.d.ts

@@ -0,0 +1,11 @@
+import type { UnknownComponentProps } from '../../../__synced__/types/shared.synced';
+import type { RenderedDocumentInternal, RenderedElementNodeInternal } from './types-internal';
+/**
+ * Creates a rendered element node.
+ *
+ * @param document The document that the element belongs to.
+ * @param name The name of the element.
+ * @param props The props of the element.
+ * @returns A rendered element node.
+ */
+export declare const createElementNode: (document: RenderedDocumentInternal, name: string, props: UnknownComponentProps) => RenderedElementNodeInternal;

package/dist/experimental/testing/internal/element.js

@@ -0,0 +1,67 @@
+import { RenderedNodeType } from '../types';
+import { EMPTY_CHILDREN } from './constants';
+import { debugLog } from './debug';
+import { InvalidEventFunctionError, MissingEventFunctionError } from './errors';
+import { printNode } from './print';
+import { find, findAll, findAllChildren, findChild, maybeFind, maybeFindChild, } from './query';
+/**
+ * Creates a rendered element node.
+ *
+ * @param document The document that the element belongs to.
+ * @param name The name of the element.
+ * @param props The props of the element.
+ * @returns A rendered element node.
+ */
+export const createElementNode = (document, name, props) => {
+    const elementNode = {
+        nodeType: RenderedNodeType.Element,
+        name,
+        props,
+        text: null,
+        children: EMPTY_CHILDREN,
+        document,
+        debugLog: (label) => {
+            debugLog(elementNode, label);
+        },
+        find: (targetComponent, matcher) => {
+            return find(elementNode, targetComponent, matcher);
+        },
+        findAll: (targetComponent, matcher) => {
+            return findAll(elementNode, targetComponent, matcher);
+        },
+        findChild: (targetComponent, matcher) => {
+            return findChild(elementNode, targetComponent, matcher);
+        },
+        findAllChildren: (targetComponent, matcher) => {
+            return findAllChildren(elementNode, targetComponent, matcher);
+        },
+        maybeFind: (targetComponent, matcher) => {
+            return maybeFind(elementNode, targetComponent, matcher);
+        },
+        maybeFindChild: (targetComponent, matcher) => {
+            return maybeFindChild(elementNode, targetComponent, matcher);
+        },
+        toString: () => {
+            return printNode(elementNode);
+        },
+        trigger: (eventPropName, eventArg) => {
+            const eventFunction = elementNode.props[eventPropName];
+            if (!eventFunction) {
+                throw new MissingEventFunctionError({
+                    componentName: name,
+                    eventPropName,
+                });
+            }
+            if (typeof eventFunction !== 'function') {
+                throw new InvalidEventFunctionError({
+                    componentName: name,
+                    eventPropName,
+                });
+            }
+            document.batchUpdate(() => {
+                eventFunction(eventArg);
+            });
+        },
+    };
+    return elementNode;
+};

package/dist/experimental/testing/internal/errors.d.ts

@@ -0,0 +1,56 @@
+import { RenderedParentNode } from '../types';
+import { RenderedRootNodeInternal } from './types-internal';
+/**
+ * Thrown when trying to trigger an event that has a handler prop that is not a function.
+ */
+export declare class InvalidEventFunctionError extends Error {
+    constructor({ componentName, eventPropName, }: {
+        componentName: string;
+        eventPropName: string;
+    });
+}
+/**
+ * Thrown when trying to trigger an event that has no corresponding handler function in the props object.
+ */
+export declare class MissingEventFunctionError extends Error {
+    constructor({ componentName, eventPropName, }: {
+        componentName: string;
+        eventPropName: string;
+    });
+}
+/**
+ * Thrown when a component is not found in the rendered output.
+ */
+export declare class ComponentNotFoundError extends Error {
+    constructor({ findMethodName, parentNode, componentName, }: {
+        findMethodName: string;
+        parentNode: RenderedParentNode;
+        componentName: string;
+    });
+}
+/**
+ * Thrown when invalid components are detected in the rendered output.
+ */
+export declare class InvalidComponentsError extends Error {
+    constructor(rootNode: RenderedRootNodeInternal);
+}
+/**
+ * Thrown when the target component passed to the find operation is not a valid HubSpot-provided React component.
+ */
+export declare class FindInvalidComponentError extends Error {
+    constructor({ findMethodName }: {
+        findMethodName: string;
+    });
+}
+/**
+ * Thrown when a fragment prop array is detected in the rendered output.
+ */
+export declare class InvalidFragmentPropArrayError extends Error {
+    constructor(componentName: string, propName: string);
+}
+/**
+ * Thrown when a waitFor() check doesn't pass within the timeout period.
+ */
+export declare class WaitForTimeoutError extends Error {
+    constructor(timeout: number);
+}

package/dist/experimental/testing/internal/errors.js

@@ -0,0 +1,70 @@
+import { printNode } from './print';
+/**
+ * Thrown when trying to trigger an event that has a handler prop that is not a function.
+ */
+export class InvalidEventFunctionError extends Error {
+    constructor({ componentName, eventPropName, }) {
+        super(`trigger("${String(eventPropName)}", ...) failed. Event function for prop "${String(eventPropName)}" in component "${componentName}" props is not a function`);
+        this.name = 'InvalidEventFunctionError';
+    }
+}
+/**
+ * Thrown when trying to trigger an event that has no corresponding handler function in the props object.
+ */
+export class MissingEventFunctionError extends Error {
+    constructor({ componentName, eventPropName, }) {
+        super(`trigger("${String(eventPropName)}", ...) failed. Event function for prop "${String(eventPropName)}" not found in component "${componentName}" props`);
+        this.name = 'MissingEventFunctionError';
+    }
+}
+/**
+ * Thrown when a component is not found in the rendered output.
+ */
+export class ComponentNotFoundError extends Error {
+    constructor({ findMethodName, parentNode, componentName, }) {
+        super(`${findMethodName}() failed. <${componentName}> not found in rendered output: ${parentNode.toString()}`);
+        this.name = 'ComponentNotFoundError';
+    }
+}
+/**
+ * Thrown when invalid components are detected in the rendered output.
+ */
+export class InvalidComponentsError extends Error {
+    constructor(rootNode) {
+        super(`Invalid rendered output. Found invalid components (${rootNode.document
+            .getInvalidComponentNames()
+            .map((name) => `"${name}"`)
+            .join(', ')}) in rendered output: ${printNode(rootNode, {
+            markInvalidComponents: true,
+            listInvalidComponents: true,
+        })}`);
+        this.name = 'InvalidComponentsError';
+    }
+}
+/**
+ * Thrown when the target component passed to the find operation is not a valid HubSpot-provided React component.
+ */
+export class FindInvalidComponentError extends Error {
+    constructor({ findMethodName }) {
+        super(`${findMethodName}() failed. The provided target component is not a HubSpot-provided React component`);
+        this.name = 'FindInvalidComponentError';
+    }
+}
+/**
+ * Thrown when a fragment prop array is detected in the rendered output.
+ */
+export class InvalidFragmentPropArrayError extends Error {
+    constructor(componentName, propName) {
+        super(`Invalid rendered output. Invalid fragment prop array ${propName} for component ${componentName}. Arrays are not allowed for fragment props.`);
+        this.name = 'InvalidFragmentPropArrayError';
+    }
+}
+/**
+ * Thrown when a waitFor() check doesn't pass within the timeout period.
+ */
+export class WaitForTimeoutError extends Error {
+    constructor(timeout) {
+        super(`waitFor() failed. Timeout of ${timeout}ms exceeded waiting for check to pass`);
+        this.name = 'WaitForTimeoutError';
+    }
+}

package/dist/experimental/testing/internal/fragment.d.ts

@@ -0,0 +1,8 @@
+import type { RenderedDocumentInternal, RenderedFragmentNodeInternal } from './types-internal';
+/**
+ * Creates a rendered fragment node.
+ *
+ * @param document The document that the fragment belongs to.
+ * @returns A rendered fragment node.
+ */
+export declare const createFragmentNode: (document: RenderedDocumentInternal) => RenderedFragmentNodeInternal;

package/dist/experimental/testing/internal/fragment.js

@@ -0,0 +1,44 @@
+import { RenderedNodeType } from '../types';
+import { EMPTY_CHILDREN } from './constants';
+import { debugLog } from './debug';
+import { printNode } from './print';
+import { find, findAll, findAllChildren, findChild, maybeFind, maybeFindChild, } from './query';
+/**
+ * Creates a rendered fragment node.
+ *
+ * @param document The document that the fragment belongs to.
+ * @returns A rendered fragment node.
+ */
+export const createFragmentNode = (document) => {
+    const fragmentNode = {
+        nodeType: RenderedNodeType.Fragment,
+        text: null,
+        children: EMPTY_CHILDREN,
+        document,
+        debugLog: (label) => {
+            debugLog(fragmentNode, label);
+        },
+        find: (targetComponent, matcher) => {
+            return find(fragmentNode, targetComponent, matcher);
+        },
+        findAll: (targetComponent, matcher) => {
+            return findAll(fragmentNode, targetComponent, matcher);
+        },
+        findChild: (targetComponent, matcher) => {
+            return findChild(fragmentNode, targetComponent, matcher);
+        },
+        findAllChildren: (targetComponent, matcher) => {
+            return findAllChildren(fragmentNode, targetComponent, matcher);
+        },
+        maybeFind: (targetComponent, matcher) => {
+            return maybeFind(fragmentNode, targetComponent, matcher);
+        },
+        maybeFindChild: (targetComponent, matcher) => {
+            return maybeFindChild(fragmentNode, targetComponent, matcher);
+        },
+        toString: () => {
+            return printNode(fragmentNode);
+        },
+    };
+    return fragmentNode;
+};

package/dist/experimental/testing/internal/match.d.ts

@@ -0,0 +1,19 @@
+import { HubSpotReactComponent, UnknownComponentProps } from '../../../__synced__/types/shared.synced';
+import { ElementMatcher, RenderedElementNode, RenderedNode } from '../types';
+/**
+ * Checks if the element matches the matcher.
+ *
+ * @param element The element to check.
+ * @param matcher An optional matcher to filter the elements.
+ * @returns `true` if the element matches the matcher, `false` otherwise.
+ */
+export declare const checkElementMatches: <TProps extends UnknownComponentProps>(element: RenderedElementNode<TProps>, matcher?: ElementMatcher<TProps> | undefined) => boolean;
+/**
+ * Checks if the node matches the component and matcher.
+ *
+ * @param node The node to check.
+ * @param component The component to check.
+ * @param matcher An optional matcher to filter the elements.
+ * @returns Whether the node matches the component and matcher.
+ */
+export declare const isMatch: <TComponentProps extends UnknownComponentProps>(node: RenderedNode | null | undefined, component: HubSpotReactComponent<TComponentProps>, matcher?: ElementMatcher<TComponentProps> | undefined) => node is RenderedElementNode<TComponentProps>;

package/dist/experimental/testing/internal/match.js

@@ -0,0 +1,42 @@
+import { RenderedNodeType, } from '../types';
+import { __hubSpotComponentRegistry } from '../../../__synced__/remoteComponents.synced';
+/**
+ * Checks if the element matches the matcher.
+ *
+ * @param element The element to check.
+ * @param matcher An optional matcher to filter the elements.
+ * @returns `true` if the element matches the matcher, `false` otherwise.
+ */
+export const checkElementMatches = (element, matcher) => {
+    // If no matcher is provided, the element matches
+    if (!matcher) {
+        return true;
+    }
+    // Check if the matcher is a predicate function
+    if (typeof matcher === 'function') {
+        return matcher(element);
+    }
+    // Check if all the props in the matcher match the props in the element
+    return Object.keys(matcher).every((key) => element.props[key] === matcher[key]);
+};
+/**
+ * Checks if the node matches the component and matcher.
+ *
+ * @param node The node to check.
+ * @param component The component to check.
+ * @param matcher An optional matcher to filter the elements.
+ * @returns Whether the node matches the component and matcher.
+ */
+export const isMatch = (node, component, matcher) => {
+    if (node == null) {
+        return false;
+    }
+    if (node.nodeType !== RenderedNodeType.Element) {
+        return false;
+    }
+    const targetComponentName = __hubSpotComponentRegistry.getComponentName(component);
+    if (node.name !== targetComponentName) {
+        return false;
+    }
+    return checkElementMatches(node, matcher);
+};

package/dist/experimental/testing/internal/print.d.ts

@@ -0,0 +1,6 @@
+import type { RenderedParentNode } from '../types';
+export interface PrintOptions {
+    markInvalidComponents: boolean;
+    listInvalidComponents: boolean;
+}
+export declare const printNode: (rootNode: RenderedParentNode, options?: PrintOptions) => string;

package/dist/experimental/testing/internal/print.js

@@ -0,0 +1,114 @@
+import { __hubSpotComponentRegistry } from '../../../__synced__/remoteComponents.synced';
+import { isRenderedElementNode, isRenderedFragmentNode, isRenderedRootNode, isRenderedTextNode, } from '../type-utils';
+const INDENT_STRING = '  ';
+const printTextNode = (node, indent, printContext) => {
+    printContext.append(`${indent}${JSON.stringify(node.text)}\n`);
+};
+const propValueToString = (value) => {
+    if (typeof value === 'function') {
+        return '={function}';
+    }
+    else if (typeof value === 'number') {
+        return `={${value}}`;
+    }
+    else if (typeof value === 'string') {
+        return `=${JSON.stringify(value)}`;
+    }
+    else if (typeof value === 'boolean') {
+        return value === true ? '' : '={false}';
+    }
+    return `={${JSON.stringify(value)}}`;
+};
+const printElementProps = (name, props, indent, printContext) => {
+    for (const [propName, propValue] of Object.entries(props)) {
+        if (__hubSpotComponentRegistry.isComponentFragmentProp(name, propName)) {
+            printContext.append(` ${propName}={`);
+            printFragmentNode(propValue, indent, printContext);
+            printContext.append(`}`);
+        }
+        else {
+            printContext.append(` ${propName}${propValueToString(propValue)}`);
+        }
+    }
+};
+const printElementStart = (node, indent, printContext) => {
+    const { name } = node;
+    printContext.append(indent);
+    printContext.append(`<${name}`);
+    if (!__hubSpotComponentRegistry.isAllowedComponentName(name)) {
+        printContext.foundInvalidComponents.add(name);
+        if (printContext.options.markInvalidComponents) {
+            printContext.append('⚠️');
+        }
+    }
+};
+const printElementNode = (node, indent, printContext) => {
+    const hasChildren = node.children.length > 0;
+    const { name, props } = node;
+    if (hasChildren) {
+        printElementStart(node, indent, printContext);
+        printElementProps(name, props, indent + INDENT_STRING, printContext);
+        printContext.append(`>\n`);
+        printChildren(node, indent + INDENT_STRING, printContext);
+        printContext.append(`${indent}</${name}>\n`);
+    }
+    else {
+        printElementStart(node, indent, printContext);
+        printElementProps(name, props, indent + INDENT_STRING, printContext);
+        printContext.append(`/>\n`);
+    }
+};
+const printChildren = (node, indent, printContext) => {
+    const { children } = node;
+    for (const child of children) {
+        if (isRenderedTextNode(child)) {
+            printTextNode(child, indent, printContext);
+        }
+        else if (isRenderedElementNode(child)) {
+            printElementNode(child, indent, printContext);
+        }
+        else {
+            throw new Error(`Illegal State. Invalid rendered node type: ${child.nodeType}`);
+        }
+    }
+};
+const DEFAULT_PRINT_OPTIONS = {
+    markInvalidComponents: true,
+    listInvalidComponents: false,
+};
+const printFragmentNode = (node, indent, printContext) => {
+    printContext.append(`<>\n`);
+    printChildren(node, indent + INDENT_STRING, printContext);
+    printContext.append(`${indent}</>`);
+};
+export const printNode = (rootNode, options = DEFAULT_PRINT_OPTIONS) => {
+    const { listInvalidComponents } = options;
+    let output = '';
+    const printContext = {
+        append: (str) => {
+            output += str;
+        },
+        options,
+        foundInvalidComponents: new Set(),
+    };
+    if (isRenderedRootNode(rootNode)) {
+        printContext.append(`<>\n`);
+        printChildren(rootNode, INDENT_STRING, printContext);
+        printContext.append(`</>`);
+    }
+    else if (isRenderedFragmentNode(rootNode)) {
+        printFragmentNode(rootNode, '', printContext);
+    }
+    else {
+        printElementNode(rootNode, '', printContext);
+    }
+    if (listInvalidComponents && printContext.foundInvalidComponents.size > 0) {
+        printContext.append(`\n⚠️  Invalid components:\n`);
+        const foundInvalidComponents = [...printContext.foundInvalidComponents];
+        foundInvalidComponents.sort();
+        for (const invalidComponentName of foundInvalidComponents) {
+            printContext.append(`- ${invalidComponentName}\n`);
+        }
+    }
+    return output.replace(/\n$/, '');
+};

package/dist/experimental/testing/internal/query.d.ts

@@ -0,0 +1,57 @@
+import type { HubSpotReactComponent, UnknownComponentProps } from '../../../__synced__/types/shared.synced';
+import type { ElementMatcher, RenderedElementNode } from '../types';
+import type { RenderedParentNodeInternal } from './types-internal';
+/**
+ * Finds the first descendant element node that matches the given component.
+ *
+ * @param parentNode The parent node to search in.
+ * @param targetComponent The component to find.
+ * @param matcher An optional matcher to filter the elements.
+ * @returns The first element node that matches the given component or `null` if no match is found.
+ */
+export declare const maybeFind: <TProps extends UnknownComponentProps>(parentNode: RenderedParentNodeInternal, targetComponent: HubSpotReactComponent<TProps>, matcher?: ElementMatcher<TProps> | undefined) => RenderedElementNode<TProps> | null;
+/**
+ * Finds the first descendant element node that matches the given component.
+ *
+ * @param parentNode The parent node to search in.
+ * @param targetComponent The component to find.
+ * @param matcher An optional matcher to filter the elements.
+ * @returns The first element node that matches the given component.
+ */
+export declare const find: <TProps extends UnknownComponentProps>(parentNode: RenderedParentNodeInternal, targetComponent: HubSpotReactComponent<TProps>, matcher?: ElementMatcher<TProps> | undefined) => RenderedElementNode<TProps>;
+/**
+ * Finds all descendant element nodes that match the given component.
+ *
+ * @param parentNode The parent node to search in.
+ * @param targetComponent The component to find.
+ * @param matcher An optional matcher to filter the elements.
+ * @returns An array of element nodes that match the given component.
+ */
+export declare const findAll: <TProps extends UnknownComponentProps>(parentNode: RenderedParentNodeInternal, targetComponent: HubSpotReactComponent<TProps>, matcher?: ElementMatcher<TProps> | undefined) => RenderedElementNode<TProps>[];
+/**
+ * Finds the first direct child element node that matches the given component.
+ *
+ * @param parentNode The parent node to search in.
+ * @param targetComponent The component to find.
+ * @param matcher An optional matcher to filter the elements.
+ * @returns The first child element node that matches the given component.
+ */
+export declare const findChild: <TProps extends UnknownComponentProps>(parentNode: RenderedParentNodeInternal, targetComponent: HubSpotReactComponent<TProps>, matcher?: ElementMatcher<TProps> | undefined) => RenderedElementNode<TProps>;
+/**
+ * Finds the first direct child element node that matches the given component.
+ *
+ * @param parentNode The parent node to search in.
+ * @param targetComponent The component to find.
+ * @param matcher An optional matcher to filter the elements.
+ * @returns The first child element node that matches the given component.
+ */
+export declare const maybeFindChild: <TProps extends UnknownComponentProps>(parentNode: RenderedParentNodeInternal, targetComponent: HubSpotReactComponent<TProps>, matcher?: ElementMatcher<TProps> | undefined) => RenderedElementNode<TProps> | null;
+/**
+ * Finds all direct child element nodes that match the given component.
+ *
+ * @param parentNode The parent node to search in.
+ * @param targetComponent The component to find.
+ * @param matcher An optional matcher to filter the elements.
+ * @returns An array of child element nodes that match the given component.
+ */
+export declare const findAllChildren: <TProps extends UnknownComponentProps>(parentNode: RenderedParentNodeInternal, targetComponent: HubSpotReactComponent<TProps>, matcher?: ElementMatcher<TProps> | undefined) => RenderedElementNode<TProps>[];