@finsweet/webflow-apps-utils 1.0.1

package/dist/utils/webflow-canvas/attributes/removeWebflowElementAttribute.js

@@ -0,0 +1,37 @@
+import { getLogger } from '../../logger';
+const logger = getLogger('webflow-apps-ui-utils');
+/**
+ *  Removes the specified attribute from the DOMElement.
+ *  @param {AnyElement} params.element - The data object of the element.
+ *  @param {String} params.attributeName - The name of the custom attribute to remove.
+ *  @param {Boolean} params.notify - Whether to show a notification after the attribute is removed.
+ */
+export const removeWebflowElementAttribute = async (element, attributeName, notify = true) => {
+    try {
+        if (element?.customAttributes) {
+            element?.removeCustomAttribute(attributeName);
+            if (notify) {
+                webflow.notify({
+                    type: 'Success',
+                    message: `The attribute "${attributeName}" was removed successfully.`
+                });
+            }
+            return;
+        }
+        if (element?.type === 'DOM') {
+            element?.removeAttribute(attributeName);
+            if (notify) {
+                webflow.notify({
+                    type: 'Success',
+                    message: `The attribute "${attributeName}" was removed successfully.`
+                });
+            }
+            return;
+        }
+        return;
+    }
+    catch (error) {
+        logger.error({}, 'Error in removeWebflowElementAttribute:', error);
+        return null;
+    }
+};

package/dist/utils/webflow-canvas/attributes/setStyles.d.ts

@@ -0,0 +1,10 @@
+export interface StyleProps {
+    name: string;
+    style: PropertyMap;
+}
+/**
+ * Create or Update style and apply it to the selected element
+ * @param styles
+ * @param element
+ */
+export declare const setStyles: (styles: StyleProps[], element: AnyElement) => Promise<void>;

package/dist/utils/webflow-canvas/attributes/setStyles.js

@@ -0,0 +1,36 @@
+/**
+ * Create or Update style and apply it to the selected element
+ * @param styles
+ * @param element
+ */
+export const setStyles = async (styles, element) => {
+    const promises = styles.map(async ({ name, style }) => {
+        if (!element?.styles)
+            return null;
+        const existingStyles = (await webflow.getAllStyles()) || [];
+        const filteredStyles = existingStyles?.filter((s) => !!s);
+        const matchPromises = filteredStyles.map(async (s) => {
+            const existingName = await s?.getName();
+            if (name === existingName) {
+                return s;
+            }
+        });
+        const match = (await Promise.all(matchPromises))?.find((s) => !!s) || null;
+        // Update existing style
+        if (match) {
+            // get existing props and update it
+            const existing = await match?.getProperties();
+            await match.setProperties({ ...existing, ...style });
+            return;
+        }
+        // Create new style
+        const newStyle = await webflow.createStyle(name);
+        if (newStyle) {
+            // Set properties for the style
+            newStyle?.setProperties({ ...style });
+            // Add the new style and Apply style to selected element
+            await element?.setStyles([...filteredStyles, newStyle]);
+        }
+    });
+    await Promise.all(promises);
+};

package/dist/utils/webflow-canvas/attributes/setWebflowElementAttribute.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Sets the value of a custom attribute to a Webflow element.
+ * If the attribute already exists, it will not be updated by default.
+ * To update the attribute, the existing value must be different from the new value.
+ * @param {AnyElement} params.element - The data object of the element.
+ * @param {String} params.attributeName - The name of the custom attribute to set.
+ * @param {String} params.attributeValue - The value of the custom attribute to set.
+ *  @param {Boolean} params.notify - Whether to show a notification after the attribute is removed.
+ * @returns
+ */
+export declare const setWebflowElementAttribute: (element: AnyElement, attributeName: string, attributeValue: string, notify?: boolean) => Promise<void>;

package/dist/utils/webflow-canvas/attributes/setWebflowElementAttribute.js

@@ -0,0 +1,61 @@
+import { getLogger } from '../../logger';
+import { getWebflowElementAttribute } from './getWebflowElementAttribute';
+const logger = getLogger('webflow-apps-ui-utils');
+/**
+ * Sets the value of a custom attribute to a Webflow element.
+ * If the attribute already exists, it will not be updated by default.
+ * To update the attribute, the existing value must be different from the new value.
+ * @param {AnyElement} params.element - The data object of the element.
+ * @param {String} params.attributeName - The name of the custom attribute to set.
+ * @param {String} params.attributeValue - The value of the custom attribute to set.
+ *  @param {Boolean} params.notify - Whether to show a notification after the attribute is removed.
+ * @returns
+ */
+export const setWebflowElementAttribute = async (element, attributeName, attributeValue, notify = true) => {
+    try {
+        const attributeExists = await checkAttribute(element, attributeName, attributeValue);
+        if (attributeExists) {
+            logger.error({}, `Attribute ${attributeName}="${attributeValue}" already exists on the element. Exiting`);
+            return;
+        }
+        if (element?.customAttributes) {
+            await element?.setCustomAttribute(attributeName, attributeValue);
+            if (notify) {
+                webflow.notify({
+                    type: 'Success',
+                    message: `Attribute ${attributeName}="${attributeValue}" has been updated successfully.`
+                });
+            }
+            return;
+        }
+        if (element?.type === 'DOM') {
+            await element.setAttribute(attributeName, attributeValue);
+            if (notify) {
+                webflow.notify({
+                    type: 'Success',
+                    message: `Attribute ${attributeName}="${attributeValue}" has been updated successfully.`
+                });
+            }
+            return;
+        }
+        return;
+    }
+    catch (error) {
+        logger.error({}, 'Error in setWebflowElementAttribute:', error);
+        return;
+    }
+};
+/**
+ * Checks if the specified attribute exists on a Webflow element and matches the provided value.
+ *
+ * @param {AnyElement} element - The Webflow element to check.
+ * @param {string} attributeName - The name of the attribute to find.
+ * @param {string} attributeValue - The value to compare against the found attribute.
+ * @return {boolean} - Returns true if the attribute exists and matches the provided value, otherwise false.
+ */
+const checkAttribute = async (element, attributeName, attributeValue) => {
+    const elementAttribute = await getWebflowElementAttribute(element, attributeName);
+    const attr = elementAttribute?.toLowerCase()?.trim();
+    const comparisonValue = attributeValue?.toLowerCase()?.trim();
+    return attr === comparisonValue;
+};

package/dist/utils/webflow-canvas/findInstanceElement.d.ts

@@ -0,0 +1,32 @@
+export interface ElementFromComponentMatch {
+    element: AnyElement;
+    component: ComponentElement | null;
+    globalIndex: number;
+    selected: boolean;
+}
+export interface GetElementFromComponentProps {
+    targetIndex: number;
+    instance: string;
+    component: string;
+    allElements?: AnyElement[];
+    signal?: AbortSignal;
+    selectElement?: boolean;
+}
+export interface FindElementByReferenceProps {
+    element: AnyElement;
+    allElements: AnyElement[];
+    attribute: {
+        name: string;
+        value: string;
+    };
+}
+/**
+ * Searches for an instance inside or outside a component by its index.
+ * @param targetIndex - The index of the instance to get.
+ * @param instance - The instance to search for.
+ * @param allElements - The elements to search through.
+ * @param signal - AbortSignal for cancelling the operation.
+ * @param selectElement - Whether to select the element when found.
+ * @returns The element match with its component if applicable.
+ */
+export declare const findInstanceElement: ({ targetIndex, instance, component, allElements, signal, selectElement }: GetElementFromComponentProps) => Promise<ElementFromComponentMatch | null>;

package/dist/utils/webflow-canvas/findInstanceElement.js

@@ -0,0 +1,144 @@
+import { noop } from '../helpers';
+import { getLogger } from '../logger';
+import { getWebflowElementAttribute } from './attributes';
+const logger = getLogger('utils');
+/**
+ * Exit the current component
+ */
+const exitComponent = async () => {
+    try {
+        await webflow.exitComponent();
+    }
+    catch (error) {
+        noop(error);
+    }
+};
+/**
+ * Searches for an instance inside or outside a component by its index.
+ * @param targetIndex - The index of the instance to get.
+ * @param instance - The instance to search for.
+ * @param allElements - The elements to search through.
+ * @param signal - AbortSignal for cancelling the operation.
+ * @param selectElement - Whether to select the element when found.
+ * @returns The element match with its component if applicable.
+ */
+export const findInstanceElement = async ({ targetIndex, instance, component, allElements, signal, selectElement = false }) => {
+    if (signal?.aborted)
+        return null;
+    let attribute = {
+        name: '',
+        value: ''
+    };
+    if (component === 'consent') {
+        // for cookie consent, just selecting the banner should be enough
+        attribute = {
+            name: 'fs-consent-element',
+            value: 'banner'
+        };
+    }
+    else {
+        attribute = {
+            name: `fs-${component}-instance`,
+            value: instance
+        };
+    }
+    try {
+        // Ensure we start at the root level
+        await webflow.exitComponent();
+        if (signal?.aborted)
+            return null;
+        const all = allElements || (await webflow.getAllElements());
+        if (signal?.aborted)
+            return null;
+        let currentIndex = 0;
+        const componentInstancesMap = new Map();
+        for (const element of all) {
+            if (signal?.aborted) {
+                await exitComponent();
+                return null;
+            }
+            if (element.type === 'ComponentInstance') {
+                const component = await element.getComponent();
+                if (component) {
+                    componentInstancesMap.set(element.id.toString(), component);
+                }
+            }
+            // Check elements outside components first
+            const elementAttribute = await getWebflowElementAttribute(element, attribute.name);
+            if (signal?.aborted) {
+                await exitComponent();
+                return null;
+            }
+            if (elementAttribute === attribute.value) {
+                currentIndex += 1;
+                if (currentIndex === targetIndex) {
+                    if (selectElement) {
+                        await webflow.setSelectedElement(element);
+                    }
+                    return {
+                        element,
+                        component: null,
+                        globalIndex: currentIndex,
+                        selected: selectElement
+                    };
+                }
+            }
+            // If it's a component, we might need to enter it
+            if (element.type === 'ComponentInstance') {
+                const component = componentInstancesMap.get(element.id.toString());
+                if (!component)
+                    continue;
+                await webflow.enterComponent(element);
+                // Check for cancellation after entering component
+                if (signal?.aborted) {
+                    await exitComponent();
+                    return null;
+                }
+                const componentElements = await webflow.getAllElements();
+                // Check for cancellation after getting component elements
+                if (signal?.aborted) {
+                    await exitComponent();
+                    return null;
+                }
+                for (const innerElement of componentElements) {
+                    // Check for cancellation in inner loop
+                    if (signal?.aborted) {
+                        await exitComponent();
+                        return null;
+                    }
+                    const innerAttribute = await getWebflowElementAttribute(innerElement, attribute.name);
+                    // Check for cancellation after async operation
+                    if (signal?.aborted) {
+                        await exitComponent();
+                        return null;
+                    }
+                    if (innerAttribute === attribute.value) {
+                        currentIndex += 1;
+                        if (currentIndex === targetIndex) {
+                            if (selectElement) {
+                                // We're already inside the component, so just select the element
+                                await webflow.setSelectedElement(innerElement);
+                            }
+                            else {
+                                // Exit component if we're not selecting the element
+                                await webflow.exitComponent();
+                            }
+                            return {
+                                element: innerElement,
+                                component: element,
+                                globalIndex: currentIndex,
+                                selected: selectElement
+                            };
+                        }
+                    }
+                }
+                await webflow.exitComponent();
+            }
+        }
+        return null;
+    }
+    catch (error) {
+        logger.error({}, 'Error in findInstanceInsideOrOutsideComponent:', error);
+        throw error;
+    }
+};

package/dist/utils/webflow-canvas/getAllPages.d.ts

@@ -0,0 +1,29 @@
+export type PageWithProps = {
+    slug: string;
+    page: Page | Folder;
+    parent: Folder | null;
+    name: string;
+    kind: 'static' | 'ecommerce' | 'cms' | 'userSystems' | 'utility' | 'staticTemplate';
+    url: URL;
+    isDraft: boolean;
+    isPasswordProtected: boolean;
+};
+/**
+ * Generates a slug for a page or folder
+ * @param page - The page or folder to generate a slug for
+ * @returns The slug for the page or folder
+ */
+export declare const getPathname: (page: Page | Folder) => Promise<string>;
+/**
+ * Returns a single page with all its properties
+ * @param page - The page to get
+ * @param stagingUrl - The staging URL
+ * @returns The page with all its properties
+ */
+export declare const getPageMetadata: (page: Page) => Promise<PageWithProps>;
+/**
+ * Returns all pages and folders from the Webflow project
+ * @param pagesAndFolders - If true, returns both pages and folders, else only pages
+ * @param kind - Filter pages by kind
+ */
+export declare const getAllPages: (pagesAndFolders?: boolean, kind?: PageWithProps["kind"]) => Promise<PageWithProps[]>;

package/dist/utils/webflow-canvas/getAllPages.js

@@ -0,0 +1,93 @@
+import { getLogger } from '../logger';
+const logger = getLogger('webflow-apps-ui-utils');
+let pageStagingUrl;
+/**
+ * Generates a slug for a page or folder
+ * @param page - The page or folder to generate a slug for
+ * @returns The slug for the page or folder
+ */
+export const getPathname = async (page) => {
+    const parent = await page.getParent();
+    const slug = await page.getSlug();
+    let fullSlug;
+    if (parent) {
+        fullSlug = `${await getPathname(parent)}/${slug}`;
+    }
+    else {
+        fullSlug = slug;
+    }
+    // Ensure the slug starts with a forward slash
+    return fullSlug.startsWith('/') ? fullSlug : `/${fullSlug}`;
+};
+/**
+ * Returns a single page with all its properties
+ * @param page - The page to get
+ * @param stagingUrl - The staging URL
+ * @returns The page with all its properties
+ */
+export const getPageMetadata = async (page) => {
+    if (!pageStagingUrl) {
+        const { shortName } = await webflow.getSiteInfo();
+        pageStagingUrl = `https://${shortName}.webflow.io`;
+    }
+    const [fullPath, parent, name, kind, isDraft, isPasswordProtected, generatedPathname] = await Promise.all([
+        page?.getPublishPath(),
+        page?.getParent(),
+        page?.getName(),
+        page?.getKind(),
+        page?.isDraft(),
+        page?.isPasswordProtected(),
+        getPathname(page)
+    ]);
+    // Create a full URL for the page
+    const fullUrl = new URL(pageStagingUrl);
+    if (fullPath)
+        fullUrl.pathname = generatedPathname;
+    return {
+        slug: generatedPathname,
+        page,
+        parent,
+        name: name || 'Homepage',
+        kind,
+        url: fullUrl,
+        isDraft,
+        isPasswordProtected
+    };
+};
+/**
+ * Returns all pages and folders from the Webflow project
+ * @param pagesAndFolders - If true, returns both pages and folders, else only pages
+ * @param kind - Filter pages by kind
+ */
+export const getAllPages = async (pagesAndFolders, kind) => {
+    try {
+        const allPages = await webflow?.getAllPagesAndFolders();
+        const pagesWithPropsPromises = [];
+        if (allPages) {
+            for (const page of allPages) {
+                if (page.type === 'PageFolder')
+                    continue;
+                pagesWithPropsPromises.push(getPageMetadata(page));
+            }
+        }
+        const list = await Promise.all(pagesWithPropsPromises);
+        if (list?.length === 0)
+            return [];
+        if (pagesAndFolders)
+            return list;
+        const pagesOnly = list.filter(({ page }) => {
+            if (page.type === 'Page')
+                return true;
+            return false;
+        });
+        // return pages that match the kind
+        if (kind) {
+            return pagesOnly.filter((page) => page.kind === kind);
+        }
+        return pagesOnly;
+    }
+    catch (error) {
+        logger.error({}, 'getAllPages failed with an error:', error);
+        return [];
+    }
+};

package/dist/utils/webflow-canvas/getSiteStagingUrl.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns a valid webflow project staging URL.
+ * @param {boolean} origin - If true, returns the origin URL (without https:// and without trailing slash).
+ * @param {boolean} stagingName - If true, returns the staging name (without .webflow.io).
+ * @returns {string}
+ */
+export declare const getSiteStagingUrl: (origin?: boolean, stagingName?: boolean) => Promise<string>;

package/dist/utils/webflow-canvas/getSiteStagingUrl.js

@@ -0,0 +1,14 @@
+/**
+ * Returns a valid webflow project staging URL.
+ * @param {boolean} origin - If true, returns the origin URL (without https:// and without trailing slash).
+ * @param {boolean} stagingName - If true, returns the staging name (without .webflow.io).
+ * @returns {string}
+ */
+export const getSiteStagingUrl = async (origin, stagingName) => {
+    const { shortName } = await webflow.getSiteInfo();
+    if (stagingName)
+        return shortName;
+    if (origin)
+        return `${shortName}.webflow.io`;
+    return `https://${shortName}.webflow.io`;
+};

package/dist/utils/webflow-canvas/index.d.ts

@@ -0,0 +1,3 @@
+export * from './attributes';
+export * from './getAllPages';
+export * from './getSiteStagingUrl';

package/dist/utils/webflow-canvas/index.js

@@ -0,0 +1,3 @@
+export * from './attributes';
+export * from './getAllPages';
+export * from './getSiteStagingUrl';

package/package.json

@@ -0,0 +1,107 @@
+{
+  "name": "@finsweet/webflow-apps-utils",
+  "version": "1.0.1",
+  "description": "Shared utilities for Webflow apps",
+  "homepage": "https://github.com/finsweet/webflow-apps-utils",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/finsweet/webflow-apps-utils.git"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/**/*.spec.*"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "svelte": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js"
+    },
+    "./index.css": "./dist/ui/index.css"
+  },
+  "peerDependencies": {
+    "svelte": "^5.0.0"
+  },
+  "devDependencies": {
+    "@changesets/changelog-git": "^0.1.14",
+    "@changesets/cli": "^2.27.1",
+    "@chromatic-com/storybook": "^4",
+    "@eslint/compat": "^1.2.5",
+    "@eslint/js": "^9.18.0",
+    "@playwright/test": "^1.49.1",
+    "@storybook/addon-a11y": "^9.0.10",
+    "@storybook/addon-docs": "^9.0.10",
+    "@storybook/addon-svelte-csf": "^5.0.3",
+    "@storybook/addon-vitest": "^9.0.10",
+    "@storybook/sveltekit": "^9.0.10",
+    "@sveltejs/adapter-auto": "^6.0.0",
+    "@sveltejs/kit": "^2.16.0",
+    "@sveltejs/package": "^2.0.0",
+    "@sveltejs/vite-plugin-svelte": "^5.0.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/svelte": "^5.2.4",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/js-cookie": "^3.0.6",
+    "@types/node": "^22",
+    "@vitest/browser": "3.2.3",
+    "@vitest/coverage-v8": "3.2.3",
+    "@webflow/designer-extension-typings": "^2.0.12",
+    "eslint": "^9.18.0",
+    "eslint-config-prettier": "^10.0.1",
+    "eslint-plugin-simple-import-sort": "^12.1.1",
+    "eslint-plugin-storybook": "^9.0.10",
+    "eslint-plugin-svelte": "^3.0.0",
+    "globals": "^16.0.0",
+    "jsdom": "^26.0.0",
+    "prettier": "^3.4.2",
+    "prettier-plugin-svelte": "^3.3.3",
+    "publint": "^0.3.2",
+    "storybook": "^9.0.10",
+    "svelte": "^5.0.0",
+    "svelte-check": "^4.0.0",
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.20.0",
+    "vite": "^6.2.6",
+    "vitest": "^3.2.3"
+  },
+  "keywords": [
+    "svelte"
+  ],
+  "dependencies": {
+    "@floating-ui/dom": "^1.7.1",
+    "clipboard": "^2.0.11",
+    "js-cookie": "^3.0.5",
+    "just-debounce": "^1.1.0",
+    "logrocket": "^10.1.0",
+    "simplebar": "^6.3.1",
+    "svelte-routing": "^2.13.0",
+    "swiper": "^11.2.8",
+    "uuid": "^11.1.0",
+    "zod": "^3.25.64"
+  },
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build && npm run prepack",
+    "preview": "vite preview",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+    "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
+    "format": "prettier --write .",
+    "lint": "prettier --check ./src && eslint ./src",
+    "lint:fix": "eslint ./src --fix && prettier --write ./src",
+    "release": "changeset publish",
+    "test:unit": "vitest --run",
+    "test:unit:watch": "vitest",
+    "test:storybook": "vitest --run --project=storybook",
+    "test:storybook:watch": "vitest --project=storybook",
+    "test": "pnpm test:unit",
+    "test:e2e": "playwright test",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build"
+  }
+}