@finsweet/webflow-apps-utils 1.0.2 → 1.0.4

package/dist/utils/animations/factory.js

@@ -0,0 +1,101 @@
+import { animate, stagger as staggerDelay } from 'motion';
+/**
+ * Creates a new Animation.
+ * @param props The animaiton props.
+ * @returns A new `in` and `out` Animation functions.
+ */
+export const createAnimation = ({ initialStyles, keyframes }) => {
+    const isBrowser = typeof window !== 'undefined';
+    /**
+     * Prepares the {@link animateIn} elements by setting the initial styles and rendering them to the DOM.
+     * @param elements The elements to prepare.
+     * @param options.target If defined, the element will be appended to the target.
+     * @param options.insertAfter A child of the target. If defined, the element will be appended right after this anchor element.
+     */
+    const prepareIn = (elements, options = {}) => {
+        const { target, insertAfter, display = '' } = options;
+        if (!Array.isArray(elements))
+            elements = [elements];
+        for (const element of elements) {
+            element.style.display = display;
+            Object.assign(element.style, initialStyles);
+            if (target && insertAfter !== undefined) {
+                if (insertAfter)
+                    target.insertBefore(element, insertAfter.nextSibling);
+                else {
+                    if (isBrowser && target instanceof HTMLElement) {
+                        target.insertBefore(element, target.firstChild);
+                    }
+                }
+            }
+            else if (target)
+                target.appendChild(element);
+        }
+    };
+    /**
+     * In animation.
+     * @param elements The elements to animate.
+     * @param options.target If defined, the element will be appended to the target.
+     * @param options.insertAfter A child of the target. If defined, the element will be appended right after this anchor element.
+     * @param options.prepared Defines if the animation has been prepared beforehand, useful to avoid performing double preparation.
+     * @param options.stagger If defined, the animation will be staggered using this time value.
+     * @param options.animationOptions The main options of the animation. Reference: {@link [Motion One](https://motion.dev/dom/animate#options)}.
+     * @returns An awaitable promise.
+     */
+    const animateIn = async (elements, options = {}) => {
+        //TODO: probably display can be used also?
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const { prepared, stagger, display, duration, ...animationOptions } = options;
+        const durationInSeconds = duration ? duration / 1000 : undefined;
+        if (!prepared)
+            prepareIn(elements, options);
+        const { finished } = animate(elements, keyframes, {
+            ...animationOptions,
+            delay: stagger ? staggerDelay(stagger / 1000) : undefined,
+            duration: durationInSeconds
+        });
+        return await finished;
+    };
+    /**
+     * Out animation.
+     * @param elements The elements to animate.
+     * @param options.remove If defined, the element will be removed from the DOM after the animation ends.
+     * @param options.stagger If defined, the animation will be staggered using this time value.
+     * @param options.animationOptions The main options of the animation. Reference: {@link [Motion One](https://motion.dev/dom/animate#options)}.
+     * @returns An awaitable promise.
+     */
+    const animateOut = async (elements, options = {}) => {
+        const { remove, stagger, target, insertAfter, display = 'none', duration, ...animationOptions } = options;
+        const durationInSeconds = duration ? duration / 1000 : undefined;
+        if (!Array.isArray(elements))
+            elements = [elements];
+        elements = elements.filter((element) => document.body.contains(element));
+        if (!elements.length)
+            return;
+        const { finished } = animate(elements, keyframes, {
+            ...animationOptions,
+            duration: durationInSeconds,
+            delay: stagger ? staggerDelay(stagger / 1000) : undefined,
+            direction: 'reverse'
+        });
+        await finished;
+        for (const element of elements) {
+            if (target && insertAfter !== undefined) {
+                if (insertAfter)
+                    target.insertBefore(element, insertAfter.nextSibling);
+                else {
+                    if (isBrowser && target instanceof HTMLElement) {
+                        target.insertBefore(element, target.firstChild);
+                    }
+                }
+            }
+            else if (target)
+                target.appendChild(element);
+            if (remove)
+                element.remove();
+            else
+                element.style.display = display;
+        }
+    };
+    return { prepareIn, animateIn, animateOut };
+};

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

@@ -0,0 +1,7 @@
+import type { AnimationsObject } from './types';
+export * from './types';
+export declare const easings: readonly ["linear", "ease", "ease-in", "ease-out", "ease-in-out"];
+/**
+ * Contains all animation functions.
+ */
+export declare const animations: AnimationsObject;

package/dist/utils/animations/index.js

@@ -0,0 +1,62 @@
+import { createAnimation } from './factory';
+export * from './types';
+// Constants
+export const easings = ['linear', 'ease', 'ease-in', 'ease-out', 'ease-in-out'];
+/**
+ * Contains all animation functions.
+ */
+export const animations = {
+    /**
+     * Fade
+     */
+    fade: createAnimation({ keyframes: { opacity: [0, 1] }, initialStyles: { opacity: '0' } }),
+    /**
+     * Slide Up
+     */
+    'slide-up': createAnimation({
+        keyframes: { y: [100, 0], opacity: [0, 1] },
+        initialStyles: { transform: 'translateY(100px)', opacity: '0' }
+    }),
+    /**
+     * Slide Down
+     */
+    'slide-down': createAnimation({
+        keyframes: { y: [-100, 0], opacity: [0, 1] },
+        initialStyles: { transform: 'translateY(-100px)', opacity: '0' }
+    }),
+    /**
+     * Slide Right
+     */
+    'slide-right': createAnimation({
+        keyframes: { x: [-100, 0], opacity: [0, 1] },
+        initialStyles: { transform: 'translateX(-100px)', opacity: '0' }
+    }),
+    /**
+     * Slide Left
+     */
+    'slide-left': createAnimation({
+        keyframes: { x: [100, 0], opacity: [0, 1] },
+        initialStyles: { transform: 'translateX(100px)', opacity: '0' }
+    }),
+    /**
+     * Grow
+     */
+    grow: createAnimation({
+        keyframes: { scale: [0, 1], opacity: [0, 1] },
+        initialStyles: { transform: 'scale(0)', opacity: '0' }
+    }),
+    /**
+     * Shrink
+     */
+    shrink: createAnimation({
+        keyframes: { scale: [1.25, 1], opacity: [0, 1] },
+        initialStyles: { transform: 'scale(1.25)', opacity: '0' }
+    }),
+    /**
+     * Spin
+     */
+    spin: createAnimation({
+        keyframes: { rotate: [900, 0], opacity: [0, 1] },
+        initialStyles: { transform: 'rotate(900deg)', opacity: '0' }
+    })
+};

package/dist/utils/animations/types.d.ts

@@ -0,0 +1,39 @@
+import type { AnimationOptions, MotionKeyframesDefinition } from 'motion';
+import type { easings } from '.';
+export interface AnimationProps {
+    keyframes: MotionKeyframesDefinition;
+    initialStyles: {
+        [key: string]: string;
+    };
+}
+type FilteredAnimationOptions = Pick<AnimationOptions, 'duration' | 'easing'> & {
+    stagger?: number;
+};
+type AnimationPrepare<T> = (element: HTMLElement | HTMLElement[], options?: T) => void;
+type AnimationBase<T> = (element: HTMLElement | HTMLElement[], options?: T & FilteredAnimationOptions) => Promise<void>;
+type PrepareProps = {
+    target?: Element;
+    insertAfter?: Node | null;
+    display?: string;
+};
+type AnimationInProps = PrepareProps & {
+    prepared?: true;
+};
+type AnimationOutProps = PrepareProps & {
+    remove?: boolean;
+};
+type PrepareIn = AnimationPrepare<PrepareProps>;
+type AnimationIn = AnimationBase<AnimationInProps>;
+type AnimationOut = AnimationBase<AnimationOutProps>;
+export type AnimationFunctions = {
+    prepareIn: PrepareIn;
+    animateIn: AnimationIn;
+    animateOut: AnimationOut;
+};
+export type Animation = AnimationFunctions & {
+    options?: FilteredAnimationOptions;
+};
+export type AnimationsObject = Readonly<Record<'fade' | 'slide-up' | 'slide-down' | 'slide-right' | 'slide-left' | 'grow' | 'shrink' | 'spin', AnimationFunctions>>;
+export type Easings = typeof easings;
+export type AnimationOptionsCustom = Readonly<Record<'fade' | 'slide-up' | 'slide-down' | 'slide-right' | 'slide-left' | 'grow' | 'shrink' | 'spin', string>>;
+export {};

package/dist/utils/animations/types.js

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

package/dist/utils/api/checkIfAppModeIsDesign.d.ts

@@ -1,5 +1,4 @@
 /**
- * Check if the app mode is design
- * @returns {Promise<boolean>}
+ * Checks if the app mode is design and shows error notification if not.
  */
 export declare const checkIfAppModeIsDesign: () => Promise<boolean>;

package/dist/utils/api/checkIfAppModeIsDesign.js

@@ -1,6 +1,5 @@
 /**
- * Check if the app mode is design
- * @returns {Promise<boolean>}
+ * Checks if the app mode is design and shows error notification if not.
  */
 export const checkIfAppModeIsDesign = async () => {
     const capabilities = await webflow.canForAppMode([

package/dist/utils/api/clipboard/handlePaste.d.ts

@@ -1,46 +1,15 @@
-export type FsCopyPasteComponent = {
-    meta: {
-        droppedLinks: number;
-        dynBindRemovedCount: number;
-        dynListBindRemovedCount: number;
-        paginationRemovedCount: number;
-        universalBindingsRemovedCount: number;
-        unlinkedSymbolCount: number;
-    };
-    type: string;
-    payload: {
-        nodes: PastedNodes[];
-        styles: {
-            name: string;
-            type: string | 'class';
-        }[];
-    };
-};
-type PastedNodes = {
-    children: string[];
-    classes: string[];
-    tag: string;
-    type: string;
-    data: {
-        xattr: Attr[];
-    };
-};
+import type { XSCPMetadata } from '../../../types';
 /**
- * Process pasted component
- * @param component
- * @param strict - if true, check for exact match, else check for any child
+ * Processes pasted component data to validate Finsweet components.
  */
-export declare const processPastedComponent: (pasteData: FsCopyPasteComponent, component: string) => {
-    data: FsCopyPasteComponent;
+export declare const processPastedComponent: (pasteData: XSCPMetadata, component: string) => {
+    data: XSCPMetadata;
     key: string;
 } | undefined;
 /**
- * Handle pasting of Webflow components
- * @param e
- * @param strict - if true, check for exact match, else check for any child
+ * Handles pasting of Webflow components from clipboard.
  */
 export declare const handlePasteXSCP: (e: ClipboardEvent, component: string) => {
-    data: FsCopyPasteComponent;
+    data: XSCPMetadata;
     key: string;
 } | undefined;
-export {};

package/dist/utils/api/clipboard/handlePaste.js

@@ -1,9 +1,7 @@
 import { getLogger } from '../../logger';
 const logger = getLogger('webflow-apps-ui-utils');
 /**
- * Process pasted component
- * @param component
- * @param strict - if true, check for exact match, else check for any child
+ * Processes pasted component data to validate Finsweet components.
  */
 export const processPastedComponent = (pasteData, component) => {
     const valid = pasteData?.payload?.nodes?.some((node) => node?.data?.xattr?.some((attr) => {
@@ -20,9 +18,7 @@ export const processPastedComponent = (pasteData, component) => {
     }
 };
 /**
- * Handle pasting of Webflow components
- * @param e
- * @param strict - if true, check for exact match, else check for any child
+ * Handles pasting of Webflow components from clipboard.
  */
 export const handlePasteXSCP = (e, component) => {
     if (!e.clipboardData?.types.includes('application/json'))

package/dist/utils/api/getAllAssets.d.ts

@@ -6,7 +6,6 @@ export interface AllAssets {
     asset: Asset;
 }
 /**
- * Get all assets from the Webflow Canvas
- * @returns
+ * Gets all assets from the Webflow Canvas with their metadata.
  */
 export declare const getAllAssets: () => Promise<AllAssets[]>;

package/dist/utils/api/getAllAssets.js

@@ -1,6 +1,5 @@
 /**
- * Get all assets from the Webflow Canvas
- * @returns
+ * Gets all assets from the Webflow Canvas with their metadata.
  */
 export const getAllAssets = async () => {
     const assets = await webflow.getAllAssets();

package/dist/utils/api/getFinsweetComponentsEnvironment.d.ts

@@ -1,6 +1,5 @@
 /**
- * Get the Finsweet components environment.
- * @returns
+ * Gets the Finsweet components environment configuration.
  */
 export declare const getFinsweetComponentsEnvironment: () => {
     development: boolean;

package/dist/utils/api/getFinsweetComponentsEnvironment.js

@@ -9,9 +9,7 @@ const URL_DEV_MODE_API_KEY = 'api';
 let lastLogTime = 0;
 const LOG_THROTTLE_MS = 3000;
 /**
- * Gets a parameter value from the URL search params
- * @param key The key to search for in URL parameters
- * @returns The value of the parameter or null if not found
+ * Gets a parameter value from the URL search params.
  */
 const getUrlParam = (key) => {
     if (typeof window === 'undefined')
@@ -26,7 +24,7 @@ const getUrlParam = (key) => {
     }
 };
 /**
- * Simple throttled console log that only logs once within the throttle interval
+ * Throttled console log that only logs once within the throttle interval.
  */
 const throttledLog = (message, data) => {
     const now = Date.now();
@@ -36,8 +34,7 @@ const throttledLog = (message, data) => {
     }
 };
 /**
- * Get the Finsweet components environment.
- * @returns
+ * Gets the Finsweet components environment configuration.
  */
 export const getFinsweetComponentsEnvironment = () => {
     const devFromUrl = getUrlParam(URL_DEV_MODE_KEY);

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

@@ -1,6 +1,5 @@
 export * from './checkIfAppModeIsDesign';
 export * from './clipboard';
-export * from './copyPaste';
 export * from './getAllAssets';
 export * from './getFinsweetComponentsEnvironment';
 export * from './insertWithXSCP';

package/dist/utils/api/index.js

@@ -1,6 +1,5 @@
 export * from './checkIfAppModeIsDesign';
 export * from './clipboard';
-export * from './copyPaste';
 export * from './getAllAssets';
 export * from './getFinsweetComponentsEnvironment';
 export * from './insertWithXSCP';

package/dist/utils/api/insertWithXSCP.d.ts

@@ -1,5 +1,4 @@
 /**
- * Insert a template into the Designer Canvas using XSCP APIs
- * @param template - the template to insert, should be a string
+ * Inserts a template into the Designer Canvas using XSCP APIs.
  */
 export declare const insertWithXSCP: (template: string) => Promise<void>;

package/dist/utils/api/insertWithXSCP.js

@@ -1,6 +1,5 @@
 /**
- * Insert a template into the Designer Canvas using XSCP APIs
- * @param template - the template to insert, should be a string
+ * Inserts a template into the Designer Canvas using XSCP APIs.
  */
 export const insertWithXSCP = async (template) => {
     try {

package/dist/utils/auth/crossWindowLogin.d.ts

@@ -1,2 +1,5 @@
 import type { FinsweetAuth } from '../../types';
+/**
+ * Opens a popup window for cross-window authentication with Auth0.
+ */
 export declare const crossWindowLogin: () => Promise<FinsweetAuth>;

package/dist/utils/auth/crossWindowLogin.js

@@ -1,4 +1,7 @@
 import { AUTH0_AUDIENCE, AUTH0_CLIENT_ID, AUTH0_LOGIN_URL, AUTH0_REDIRECT_URL, AUTH0_SCOPE, PROD_FINSWEEET_ACCOUNTS_ORIGIN } from '../constants';
+/**
+ * Opens a popup window for cross-window authentication with Auth0.
+ */
 export const crossWindowLogin = () => {
     return new Promise((resolve, reject) => {
         const timeout = setTimeout(() => {

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

@@ -5,55 +5,39 @@ import type { FinsweetAuth } from '../../types';
 export declare const finsweetUser: import("svelte/store").Writable<FinsweetAuth | null>;
 export declare const isLoggingIn: import("svelte/store").Writable<boolean>;
 /**
- * Fetches subscriptions from the server.
- * @param token
- * @returns
+ * Fetches user subscriptions from the server.
  */
 export declare const getSubscriptions: (token: string) => Promise<any>;
 /**
- * Fetches user data from the server.
- * @param token
- * @returns
+ * Fetches user data from the authentication server.
  */
 export declare const getUser: (token: string) => Promise<FinsweetAuth["user"]>;
 /**
- * Handles login
- * @returns void
+ * Handles user login authentication flow.
  */
 export declare const handleLogin: () => Promise<void>;
 /**
- * Handles logout
+ * Handles user logout and cleanup.
  */
 export declare const handleLogout: () => Promise<void>;
 /**
- * Checks if the user is logged in by checking the cookie for a valid token.
+ * Checks if the user is logged in by validating stored session.
  */
 export declare const checkInitialLoginState: () => Promise<void>;
 /**
- * Sets a cookie
- * @param {string} name - Name of the cookie
- * @param {string} value - Value of the cookie
- * @param {Object} options - Options for the cookie (expires, path, etc.)
+ * Sets a cookie with security options.
  */
 export declare const setCookie: (name: string, value: string, options?: {}) => void;
 /**
- * Gets a cookie
- * @param {string} name - Name of the cookie to retrieve
- * @returns {string | undefined} - Value of the cookie, if found
+ * Gets a cookie value by name.
  */
 export declare const getCookie: (name: string) => string | undefined;
 /**
- * Deletes a cookie
- * @param {string} name - Name of the cookie to delete
- * @param {Object} options - Options for the cookie (path, etc.)
+ * Deletes a cookie by name.
  */
 export declare const deleteCookie: (name: string, options?: {}) => void;
 /**
- * Checks if the user has access to a feature
- * @param loggedIn
- * @param access
- * @param required
- * @returns
+ * Checks if the user has access to a specific feature.
  */
 export declare const canAccessFeature: (loggedIn: boolean, access: FinsweetAuth["user"]["libraryAccess"] | null | undefined, required: FinsweetAuth["user"]["libraryAccess"]) => {
     granted: boolean;

package/dist/utils/auth/index.js

@@ -34,9 +34,7 @@ const checkLibraryAccess = (user, subscriptions) => {
     return ['canFavourite'];
 };
 /**
- * Fetches subscriptions from the server.
- * @param token
- * @returns
+ * Fetches user subscriptions from the server.
  */
 export const getSubscriptions = async (token) => {
     try {
@@ -58,9 +56,7 @@ export const getSubscriptions = async (token) => {
     }
 };
 /**
- * Fetches user data from the server.
- * @param token
- * @returns
+ * Fetches user data from the authentication server.
  */
 export const getUser = async (token) => {
     const response = await fetch('/auth0/verify', {
@@ -73,8 +69,7 @@ export const getUser = async (token) => {
     return data;
 };
 /**
- * Handles login
- * @returns void
+ * Handles user login authentication flow.
  */
 export const handleLogin = async () => {
     if (get(isLoggingIn))
@@ -112,7 +107,7 @@ export const handleLogin = async () => {
     }
 };
 /**
- * Handles logout
+ * Handles user logout and cleanup.
  */
 export const handleLogout = async () => {
     removeLocalStorage('finsweetComponentsAuth');
@@ -124,7 +119,7 @@ export const handleLogout = async () => {
     await new Promise((resolve) => setTimeout(resolve, 1000));
 };
 /**
- * Checks if the user is logged in by checking the cookie for a valid token.
+ * Checks if the user is logged in by validating stored session.
  */
 export const checkInitialLoginState = async () => {
     const session = getLocalStorage('finsweetComponentsAuth');
@@ -150,36 +145,25 @@ export const checkInitialLoginState = async () => {
     await handleLogout();
 };
 /**
- * Sets a cookie
- * @param {string} name - Name of the cookie
- * @param {string} value - Value of the cookie
- * @param {Object} options - Options for the cookie (expires, path, etc.)
+ * Sets a cookie with security options.
  */
 export const setCookie = (name, value, options = {}) => {
     Cookies.set(name, value, { sameSite: 'None', secure: true, ...options });
 };
 /**
- * Gets a cookie
- * @param {string} name - Name of the cookie to retrieve
- * @returns {string | undefined} - Value of the cookie, if found
+ * Gets a cookie value by name.
  */
 export const getCookie = (name) => {
     return Cookies.get(name);
 };
 /**
- * Deletes a cookie
- * @param {string} name - Name of the cookie to delete
- * @param {Object} options - Options for the cookie (path, etc.)
+ * Deletes a cookie by name.
  */
 export const deleteCookie = (name, options = {}) => {
     Cookies.remove(name, options);
 };
 /**
- * Checks if the user has access to a feature
- * @param loggedIn
- * @param access
- * @param required
- * @returns
+ * Checks if the user has access to a specific feature.
  */
 export const canAccessFeature = (loggedIn, access, required) => {
     if (!loggedIn) {

package/dist/utils/browser-storage/localStorage.d.ts

@@ -1,24 +1,16 @@
 /**
- * Check if localStorage is available in the current environment.
- * @returns {boolean} True if localStorage is accessible, false otherwise.
+ * Checks if localStorage is available in the current environment.
  */
 export declare const isLocalStorageAvailable: () => boolean;
 /**
- * A utility function for getting a value from localStorage.
- * @param {string} key - The key to retrieve the value for.
- * @returns {string | null} The value associated with the key, or null if not found or localStorage is not available.
+ * Gets a value from localStorage.
  */
 export declare const getLocalStorage: (key: string) => string | null;
 /**
- * A utility function for setting a value in localStorage.
- * @param {string} key - The key to set the value for.
- * @param {string} value - The value to be stored.
- * @returns {boolean} True if the operation succeeded, false otherwise (or if localStorage is not available).
+ * Sets a value in localStorage.
  */
 export declare const setLocalStorage: (key: string, value: string) => boolean;
 /**
- * A utility function for removing a value from localStorage.
- * @param key - The key to remove the value for.
- * @returns {boolean} True if the operation succeeded, false otherwise (or if localStorage is not available).
+ * Removes a value from localStorage.
  */
 export declare const removeLocalStorage: (key: string) => boolean;

package/dist/utils/browser-storage/localStorage.js

@@ -1,6 +1,5 @@
 /**
- * Check if localStorage is available in the current environment.
- * @returns {boolean} True if localStorage is accessible, false otherwise.
+ * Checks if localStorage is available in the current environment.
  */
 export const isLocalStorageAvailable = () => {
     if (typeof window === 'undefined')
@@ -18,9 +17,7 @@ export const isLocalStorageAvailable = () => {
     }
 };
 /**
- * A utility function for getting a value from localStorage.
- * @param {string} key - The key to retrieve the value for.
- * @returns {string | null} The value associated with the key, or null if not found or localStorage is not available.
+ * Gets a value from localStorage.
  */
 export const getLocalStorage = (key) => {
     if (isLocalStorageAvailable()) {
@@ -30,10 +27,7 @@ export const getLocalStorage = (key) => {
     return null;
 };
 /**
- * A utility function for setting a value in localStorage.
- * @param {string} key - The key to set the value for.
- * @param {string} value - The value to be stored.
- * @returns {boolean} True if the operation succeeded, false otherwise (or if localStorage is not available).
+ * Sets a value in localStorage.
  */
 export const setLocalStorage = (key, value) => {
     if (isLocalStorageAvailable()) {
@@ -43,9 +37,7 @@ export const setLocalStorage = (key, value) => {
     return false;
 };
 /**
- * A utility function for removing a value from localStorage.
- * @param key - The key to remove the value for.
- * @returns {boolean} True if the operation succeeded, false otherwise (or if localStorage is not available).
+ * Removes a value from localStorage.
  */
 export const removeLocalStorage = (key) => {
     if (isLocalStorageAvailable()) {