@finsweet/webflow-apps-utils 1.0.5 → 1.0.7

package/dist/utils/helpers/guards.d.ts

@@ -0,0 +1,124 @@
+import type { FormField } from '../../types';
+/**
+ * Defines a typed object entry
+ */
+export type Entry<T> = {
+    [K in keyof T]: [K, T[K]];
+}[keyof T];
+/**
+ * Converts a `Map<K, V>` type to its equivalent when performing `[...map.entries()]`.
+ * @example ```typescript
+ * const map: MapType = new Map(['key', 'value']);
+ * const entries = [...map.entries()]; // Same type as MapEntries<MapType>
+ *
+ * typeof entries === MapEntries<MapType>
+ * ```
+ */
+export type MapEntries<MapToConvert> = MapToConvert extends Map<infer Key, infer Value> ? [Key, Value][] : never;
+/**
+ * Check if value is a string
+ */
+export declare const isString: (value: unknown) => value is string;
+/**
+ * Check if value is a number
+ */
+export declare const isNumber: (value: unknown) => value is number;
+/**
+ * Check if value is a boolean
+ */
+export declare const isBoolean: (value: unknown) => value is boolean;
+/**
+ * Check if value undefined
+ */
+export declare const isUndefined: (value: unknown) => value is undefined;
+/**
+ * Makes sure a value is not `null` or `undefined`.
+ * Useful for type safety when filtering empty elements from an array. Check out the example for more in-depth explanation.
+ * @param value The value to type-check.
+ * @example ```typescript
+ * const items = [1, null, 4, undefined, 8];
+ *
+ * const filteredItemsError: number[] = items.filter((item) => value !== undefined && value !== null); // Type '(number | null | undefined)[]' is not assignable to type 'number[]'.
+ *
+ * const filteredItemsSuccess: number[] = items.filter(isNotEmpty); // Success!
+ * ```
+ */
+export declare const isNotEmpty: <T>(value: T | null | undefined) => value is T;
+/**
+ * Check if a key is included in a readonly array
+ * @param key
+ * @param source readonly array of strings
+ * @returns True/false
+ */
+export declare const isKeyOf: <T extends string>(key: string | null | undefined, source: readonly T[]) => key is (typeof source)[number];
+/**
+ * Gets the keys of an object with inferred typing.
+ * @param object
+ * @returns
+ */
+export declare const getObjectKeys: <T extends Record<string, unknown>>(object: T) => (keyof T)[];
+/**
+ * Gets type safe `Object.entries()`.
+ * @param object
+ */
+export declare const getObjectEntries: <T extends Readonly<Record<string, unknown>>>(object: T) => Entry<T>[];
+/**
+ * @returns `true` if the target is an instance of Element type.
+ * @param target
+ */
+export declare const isElement: (target: unknown) => target is Element;
+/**
+ * @returns `true` if the target is an instance of HTMLElement type.
+ * @param target
+ */
+export declare const isHTMLElement: (target: unknown) => target is HTMLElement;
+/**
+ * @returns `true` if the target is an instance of HTMLVideoElement type.
+ * @param target
+ */
+export declare const isHTMLVideoElement: (target: unknown) => target is HTMLVideoElement;
+/**
+ * @returns `true` if the target is an instance of HTMLInputElement type.
+ * @param target
+ */
+export declare const isHTMLInputElement: (target: unknown) => target is HTMLInputElement;
+/**
+ * @returns `true` if the target is an instance of HTMLSelectElement type.
+ * @param target
+ */
+export declare const isHTMLSelectElement: (target: unknown) => target is HTMLSelectElement;
+/**
+ * @returns `true` if the target is an instance of HTMLTextAreaElement type.
+ * @param target
+ */
+export declare const isHTMLTextAreaElement: (target: unknown) => target is HTMLTextAreaElement;
+/**
+ * Checks if an element is a form field element
+ * @param element
+ */
+export declare const isFormField: (element: Element | EventTarget | null) => element is FormField;
+/**
+ * @returns `true` if the target is an instance of HTMLAnchorElement type.
+ * @param target
+ */
+export declare const isHTMLAnchorElement: (target: unknown) => target is HTMLAnchorElement;
+/**
+ * @returns `true` if the target is an instance of HTMLOptionElement type.
+ * @param target
+ */
+export declare const isHTMLOptionElement: (target: unknown) => target is HTMLOptionElement;
+/**
+ * @returns `true` if the target is an instance of HTMLImageElement type.
+ * @param target
+ */
+export declare const isHTMLImageElement: (target: unknown) => target is HTMLImageElement;
+/**
+ * @returns `true` if the target is an instance of HTMLButtonElement type.
+ * @param target
+ */
+export declare const isHTMLButtonElement: (target: unknown) => target is HTMLButtonElement;
+/**
+ * @returns `true` if the target is an instance of File type.
+ * @param target
+ */
+export declare const isFile: (target: unknown) => target is File;

package/dist/utils/helpers/guards.js

@@ -0,0 +1,107 @@
+/**
+ * Check if value is a string
+ */
+export const isString = (value) => typeof value === 'string';
+/**
+ * Check if value is a number
+ */
+export const isNumber = (value) => typeof value === 'number';
+/**
+ * Check if value is a boolean
+ */
+export const isBoolean = (value) => typeof value === 'boolean';
+/**
+ * Check if value undefined
+ */
+export const isUndefined = (value) => value === undefined;
+/**
+ * Makes sure a value is not `null` or `undefined`.
+ * Useful for type safety when filtering empty elements from an array. Check out the example for more in-depth explanation.
+ * @param value The value to type-check.
+ * @example ```typescript
+ * const items = [1, null, 4, undefined, 8];
+ *
+ * const filteredItemsError: number[] = items.filter((item) => value !== undefined && value !== null); // Type '(number | null | undefined)[]' is not assignable to type 'number[]'.
+ *
+ * const filteredItemsSuccess: number[] = items.filter(isNotEmpty); // Success!
+ * ```
+ */
+export const isNotEmpty = (value) => value !== undefined && value !== null;
+/**
+ * Check if a key is included in a readonly array
+ * @param key
+ * @param source readonly array of strings
+ * @returns True/false
+ */
+export const isKeyOf = (key, source) => !!key && source.includes(key);
+/**
+ * Gets the keys of an object with inferred typing.
+ * @param object
+ * @returns
+ */
+export const getObjectKeys = (object) => Object.keys(object);
+/**
+ * Gets type safe `Object.entries()`.
+ * @param object
+ */
+export const getObjectEntries = (object) => Object.entries(object);
+/**
+ * @returns `true` if the target is an instance of Element type.
+ * @param target
+ */
+export const isElement = (target) => target instanceof Element;
+/**
+ * @returns `true` if the target is an instance of HTMLElement type.
+ * @param target
+ */
+export const isHTMLElement = (target) => target instanceof HTMLElement;
+/**
+ * @returns `true` if the target is an instance of HTMLVideoElement type.
+ * @param target
+ */
+export const isHTMLVideoElement = (target) => target instanceof HTMLVideoElement;
+/**
+ * @returns `true` if the target is an instance of HTMLInputElement type.
+ * @param target
+ */
+export const isHTMLInputElement = (target) => target instanceof HTMLInputElement;
+/**
+ * @returns `true` if the target is an instance of HTMLSelectElement type.
+ * @param target
+ */
+export const isHTMLSelectElement = (target) => target instanceof HTMLSelectElement;
+/**
+ * @returns `true` if the target is an instance of HTMLTextAreaElement type.
+ * @param target
+ */
+export const isHTMLTextAreaElement = (target) => target instanceof HTMLTextAreaElement;
+/**
+ * Checks if an element is a form field element
+ * @param element
+ */
+export const isFormField = (element) => isHTMLInputElement(element) || isHTMLSelectElement(element) || isHTMLTextAreaElement(element);
+/**
+ * @returns `true` if the target is an instance of HTMLAnchorElement type.
+ * @param target
+ */
+export const isHTMLAnchorElement = (target) => target instanceof HTMLAnchorElement;
+/**
+ * @returns `true` if the target is an instance of HTMLOptionElement type.
+ * @param target
+ */
+export const isHTMLOptionElement = (target) => target instanceof HTMLOptionElement;
+/**
+ * @returns `true` if the target is an instance of HTMLImageElement type.
+ * @param target
+ */
+export const isHTMLImageElement = (target) => target instanceof HTMLImageElement;
+/**
+ * @returns `true` if the target is an instance of HTMLButtonElement type.
+ * @param target
+ */
+export const isHTMLButtonElement = (target) => target instanceof HTMLButtonElement;
+/**
+ * @returns `true` if the target is an instance of File type.
+ * @param target
+ */
+export const isFile = (target) => target instanceof File;

package/dist/utils/helpers/index.d.ts

@@ -1,10 +1,18 @@
 export * from './capitalizeFirstLetter';
 export * from './cleanupTooltipMessage';
+export * from './encodeDecodeConfigs';
 export * from './goto';
+export * from './dom';
+export * from './events';
+export * from './forms';
 export * from './getTimeNow';
 export * from './minifyCode';
 export * from './noop';
+export * from './guards';
 export * from './numbers';
+export * from './parseCSV';
+export * from './string';
 export * from './objectsToModuleExports';
 export * from './trimText';
 export * from './toHumanReadableList';
+export * from './wait';

package/dist/utils/helpers/index.js

@@ -1,10 +1,18 @@
 export * from './capitalizeFirstLetter';
 export * from './cleanupTooltipMessage';
+export * from './encodeDecodeConfigs';
 export * from './goto';
+export * from './dom';
+export * from './events';
+export * from './forms';
 export * from './getTimeNow';
 export * from './minifyCode';
 export * from './noop';
+export * from './guards';
 export * from './numbers';
+export * from './parseCSV';
+export * from './string';
 export * from './objectsToModuleExports';
 export * from './trimText';
 export * from './toHumanReadableList';
+export * from './wait';

package/dist/utils/helpers/parseCSV.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Parse CSV data
+ * @param csvText CSV data as string
+ * @returns Parsed CSV data as an array of objects
+ */
+export declare const parseCSV: <Result extends Record<string, string>>(csvText: string) => Promise<Result[]>;

package/dist/utils/helpers/parseCSV.js

@@ -0,0 +1,29 @@
+import { parse } from 'csv-parse/browser/esm';
+/**
+ * Parse CSV data
+ * @param csvText CSV data as string
+ * @returns Parsed CSV data as an array of objects
+ */
+export const parseCSV = async (csvText) => {
+    return new Promise((resolve, reject) => {
+        const results = [];
+        parse(csvText, {
+            columns: true,
+            skip_empty_lines: true,
+            trim: true
+        })
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            .on('readable', function () {
+            let record;
+            while ((record = this.read()) !== null) {
+                results.push(record);
+            }
+        })
+            .on('error', (error) => {
+            reject(error);
+        })
+            .on('end', () => {
+            resolve(results);
+        });
+    });
+};

package/dist/utils/helpers/string.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Removes the trailing slash from a URL string.
+ *
+ * @example
+ * ```
+ * This:
+ * https://www.finsweet.com/attributes/attractions/capri-island/
+ *
+ * Becomes:
+ * https://www.finsweet.com/attributes/attractions/capri-island
+ * ```
+ *
+ * @param value The value to mutate.
+ * @returns A new string without a trailing slash.
+ */
+export declare const removeTrailingSlash: (value: string) => string;
+/**
+ * Convert a string of comma separated values to an array of values.
+ *
+ * @param string Comma separated string.
+ * @param filterEmpty Defines if empty values should be filtered out of the returned array. Defaults to `true`.
+ */
+export declare const extractCommaSeparatedValues: (string: string | null | undefined, filterEmpty?: boolean) => string[];

package/dist/utils/helpers/string.js

@@ -0,0 +1,33 @@
+/**
+ * Removes the trailing slash from a URL string.
+ *
+ * @example
+ * ```
+ * This:
+ * https://www.finsweet.com/attributes/attractions/capri-island/
+ *
+ * Becomes:
+ * https://www.finsweet.com/attributes/attractions/capri-island
+ * ```
+ *
+ * @param value The value to mutate.
+ * @returns A new string without a trailing slash.
+ */
+export const removeTrailingSlash = (value) => value.replace(/\/+$/, '');
+/**
+ * Convert a string of comma separated values to an array of values.
+ *
+ * @param string Comma separated string.
+ * @param filterEmpty Defines if empty values should be filtered out of the returned array. Defaults to `true`.
+ */
+export const extractCommaSeparatedValues = (string, filterEmpty = true) => {
+    if (!string)
+        return [];
+    const items = string.split(',').reduce((accumulatedValue, currentValue) => {
+        const value = currentValue.trim();
+        if (!filterEmpty || value)
+            accumulatedValue.push(value);
+        return accumulatedValue;
+    }, []);
+    return items;
+};

package/dist/utils/helpers/wait.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @returns Awaitable promise for waiting X time.
+ * @param time
+ */
+export declare const wait: (time: number) => Promise<unknown>;
+/**
+ * @returns A promise that resolves once Webflow has fully loaded.
+ */
+export declare const waitWebflowReady: () => Promise<unknown>;
+/**
+ * @returns A promise that resolves once the DOM is ready.
+ */
+export declare const waitDOMReady: () => Promise<unknown>;

package/dist/utils/helpers/wait.js

@@ -0,0 +1,27 @@
+/**
+ * @returns Awaitable promise for waiting X time.
+ * @param time
+ */
+export const wait = (time) => new Promise((resolve) => setTimeout(resolve, time));
+/**
+ * @returns A promise that resolves once Webflow has fully loaded.
+ */
+export const waitWebflowReady = async () => {
+    return new Promise((resolve) => {
+        window.Webflow ||= [];
+        window.Webflow.push(resolve);
+    });
+};
+/**
+ * @returns A promise that resolves once the DOM is ready.
+ */
+export const waitDOMReady = async () => {
+    return new Promise((resolve) => {
+        if (document.readyState === 'loading') {
+            document.addEventListener('DOMContentLoaded', resolve);
+        }
+        else {
+            resolve(undefined);
+        }
+    });
+};

package/dist/utils/index.d.ts

@@ -7,4 +7,5 @@ export * from './custom-code';
 export * from './diff-mapper';
 export * from './helpers';
 export * from './logger';
+export * from './webflow';
 export * from './webflow-canvas';

package/dist/utils/index.js

@@ -7,4 +7,5 @@ export * from './custom-code';
 export * from './diff-mapper';
 export * from './helpers';
 export * from './logger';
+export * from './webflow';
 export * from './webflow-canvas';

package/dist/utils/webflow/CopyJSONButton.d.ts

@@ -0,0 +1,54 @@
+export declare class CopyJSONButton {
+    private readonly element;
+    private readonly hiddenTrigger;
+    private readonly successCSSClass?;
+    private readonly textNode;
+    private copyData;
+    private successText;
+    private errorText;
+    private notificationDuration;
+    private notificationActive;
+    private originalText;
+    constructor({ element, copyData, successText, errorText, notificationDuration, successCSSClass }: {
+        element: HTMLElement;
+        copyData: Record<string, unknown>;
+        successText?: string;
+        errorText?: string;
+        notificationDuration?: number;
+        successCSSClass?: string;
+    });
+    /**
+     * Inits the component.
+     */
+    private init;
+    /**
+     * Creates a hidden button that will serve as the copy trigger.
+     * @returns The new button element.
+     */
+    private createHiddenTrigger;
+    /**
+     * Handles click events: triggers a copy command on the element.
+     */
+    private handleClick;
+    /**
+     * Handles the copy event, transfers the JSON data to the user's clipboard.
+     * @param e
+     */
+    private handleCopy;
+    /**
+     * Triggers a `success`/`error` notification on the button.
+     * If the `successCSSClass` is specific, it adds/removes on the button.
+     * @param state `success` or `error`
+     */
+    private triggerNotification;
+    /**
+     * Updates the JSON data to be copied.
+     * @param newCopyData
+     */
+    updateCopyData(newCopyData: Record<string, unknown>): void;
+    /**
+     * Updates the button's text content.
+     * @param newText The new text to be displayed.
+     */
+    updateTextContent(newText: string): void;
+}

package/dist/utils/webflow/CopyJSONButton.js

@@ -0,0 +1,117 @@
+import { findTextNode } from '../helpers';
+export class CopyJSONButton {
+    element;
+    hiddenTrigger;
+    successCSSClass;
+    textNode;
+    copyData;
+    successText = 'Copied!';
+    errorText = 'Something went wrong';
+    notificationDuration = 500;
+    notificationActive = false;
+    originalText;
+    constructor({ element, copyData, successText, errorText, notificationDuration, successCSSClass }) {
+        this.element = element;
+        this.copyData = copyData;
+        if (successText)
+            this.successText = successText;
+        if (errorText)
+            this.errorText = errorText;
+        if (notificationDuration)
+            this.notificationDuration = notificationDuration;
+        if (successCSSClass)
+            this.successCSSClass = successCSSClass;
+        this.textNode = findTextNode(element) || element;
+        this.originalText = this.textNode.textContent || '';
+        this.hiddenTrigger = this.createHiddenTrigger();
+        this.init();
+    }
+    /**
+     * Inits the component.
+     */
+    init() {
+        const { element, hiddenTrigger } = this;
+        element.addEventListener('click', (e) => this.handleClick(e));
+        hiddenTrigger.addEventListener('copy', (e) => this.handleCopy(e));
+    }
+    /**
+     * Creates a hidden button that will serve as the copy trigger.
+     * @returns The new button element.
+     */
+    createHiddenTrigger() {
+        const { element } = this;
+        const button = document.createElement('button');
+        button.contentEditable = 'true';
+        Object.assign(button.style, {
+            position: 'absolute',
+            clip: 'rect(1px, 1px, 1px, 1px)',
+            clipPath: 'inset(0px 0px 99.9% 99.9%)',
+            overflow: 'hidden',
+            height: '1px',
+            width: '1px',
+            padding: '0',
+            border: '0'
+        });
+        (element.parentElement || document.body).appendChild(button);
+        return button;
+    }
+    /**
+     * Handles click events: triggers a copy command on the element.
+     */
+    handleClick(e) {
+        e.preventDefault();
+        this.hiddenTrigger.focus();
+        document.execCommand('copy');
+    }
+    /**
+     * Handles the copy event, transfers the JSON data to the user's clipboard.
+     * @param e
+     */
+    handleCopy(e) {
+        try {
+            // Copy starter form JSON to clipboard
+            e.clipboardData?.setData('application/json', JSON.stringify(this.copyData).trim());
+            e.preventDefault();
+            // Trigger notification
+            this.triggerNotification('success');
+        }
+        catch {
+            this.triggerNotification('error');
+        }
+    }
+    /**
+     * Triggers a `success`/`error` notification on the button.
+     * If the `successCSSClass` is specific, it adds/removes on the button.
+     * @param state `success` or `error`
+     */
+    triggerNotification(state) {
+        const { notificationActive, notificationDuration, originalText, element, successCSSClass, successText, errorText } = this;
+        if (notificationActive)
+            return;
+        this.notificationActive = true;
+        this.textNode.textContent = state === 'success' ? successText : errorText;
+        if (successCSSClass)
+            element.classList.add(successCSSClass);
+        window.setTimeout(() => {
+            this.textNode.textContent = originalText;
+            if (successCSSClass)
+                element.classList.remove(successCSSClass);
+            this.notificationActive = false;
+        }, notificationDuration);
+    }
+    /**
+     * Updates the JSON data to be copied.
+     * @param newCopyData
+     */
+    updateCopyData(newCopyData) {
+        this.copyData = newCopyData;
+    }
+    /**
+     * Updates the button's text content.
+     * @param newText The new text to be displayed.
+     */
+    updateTextContent(newText) {
+        this.textNode.textContent = newText;
+        this.originalText = newText;
+    }
+}

package/dist/utils/webflow/DisplayController.d.ts

@@ -0,0 +1,55 @@
+import { animations, type Easings } from '../animations';
+import { type InteractionParams } from './Interaction';
+export interface DisplayControllerParams {
+    /**
+     * The main element. Accepts both an HTMLElement or a string selector.
+     */
+    element: HTMLElement;
+    /**
+     * If the display must be controlled through a Webflow interaction.
+     */
+    interaction?: InteractionParams;
+    /**
+     * Defines a custom animation to be used when showing/hiding the element.
+     */
+    animation?: keyof typeof animations;
+    /**
+     * If set to true, the element will be set to `display: none`.
+     */
+    startsHidden?: boolean;
+    /**
+     * The duration of the animation in milliseconds.
+     */
+    animationDuration?: number;
+    /**
+     * The easing of the animation.
+     */
+    animationEasing: Easings[number];
+}
+/**
+ * Controls showing/hiding an element.
+ * Works with Webflow interactions, built-in fade animations or no animations at all.
+ */
+export declare class DisplayController {
+    private readonly interaction;
+    private readonly animation;
+    private readonly animationEasing;
+    private readonly animationDuration;
+    private visible;
+    readonly element: HTMLElement;
+    constructor({ element, interaction, animation, startsHidden, animationEasing, animationDuration }: DisplayControllerParams);
+    /**
+     * @returns If the element is visible
+     */
+    isVisible: () => boolean;
+    /**
+     * Displays the element
+     * @returns An awaitable promise
+     */
+    show(): Promise<void>;
+    /**
+     * Hides the element
+     * @returns An awaitable promise
+     */
+    hide(): Promise<void>;
+}