@finsweet/webflow-apps-utils 1.0.7 → 1.0.9

package/dist/{stores/forms.js → ui/stores/form.js}

@@ -3,8 +3,280 @@ import { z } from 'zod';
 // Registry to track all form states by identifier
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const formsRegistry = writable({});
+// Registry to track field registrations per form
+const fieldRegistrations = writable({});
 // Validates class name according to HTML class name rules
 const classNameRegex = /^[a-zA-Z0-9_-]+$/;
+/**
+ * Generic Form Manager for any Zod schema with cross-component field support
+ */
+export class FormManager {
+    schema;
+    _store;
+    initialValues;
+    identifier;
+    fieldRegistrations = new Map();
+    // Public reactive stores that components can directly use
+    values;
+    errors;
+    touched;
+    isValid;
+    isDirty;
+    isSubmitting;
+    constructor(identifier, schema, initialValues) {
+        this.identifier = identifier;
+        this.schema = schema;
+        this.initialValues = initialValues;
+        // Create the internal form state store
+        this._store = writable({
+            values: initialValues,
+            errors: {},
+            touched: {},
+            isValid: false,
+            isDirty: false,
+            isSubmitting: false
+        });
+        // Create derived stores
+        this.values = derived(this._store, ($store) => $store.values);
+        this.errors = derived(this._store, ($store) => $store.errors);
+        this.touched = derived(this._store, ($store) => $store.touched);
+        this.isValid = derived(this._store, ($store) => $store.isValid);
+        this.isDirty = derived(this._store, ($store) => $store.isDirty);
+        this.isSubmitting = derived(this._store, ($store) => $store.isSubmitting);
+        // Register this form with the global registry
+        formsRegistry.update((registry) => {
+            registry[identifier] = this;
+            return registry;
+        });
+        // Initialize field registrations for this form
+        fieldRegistrations.update((registrations) => {
+            registrations[identifier] = {};
+            return registrations;
+        });
+        // Initial validation
+        this.validate();
+    }
+    /**
+     * Register a field with the form for cross-component management
+     */
+    registerField(fieldName, options) {
+        const registration = {
+            name: fieldName,
+            validate: options?.validate,
+            transform: options?.transform
+        };
+        this.fieldRegistrations.set(fieldName, registration);
+        // Update global field registrations
+        fieldRegistrations.update((registrations) => {
+            registrations[this.identifier][fieldName] =
+                registration;
+            return registrations;
+        });
+        return {
+            // Return field-specific reactive stores
+            value: derived(this.values, ($values) => $values[fieldName]),
+            error: derived(this.errors, ($errors) => $errors[fieldName] || []),
+            touched: derived(this.touched, ($touched) => $touched[fieldName] || false),
+            // Field-specific methods
+            setValue: (value) => this.setField(fieldName, value),
+            setTouched: () => this.setTouched(fieldName),
+            validate: () => this.validateField(fieldName)
+        };
+    }
+    /**
+     * Set the value of a specific field
+     */
+    setField(field, value) {
+        this._store.update((state) => {
+            const newState = {
+                ...state,
+                values: {
+                    ...state.values,
+                    [field]: value
+                },
+                touched: {
+                    ...state.touched,
+                    [field]: true
+                },
+                isDirty: true
+            };
+            return newState;
+        });
+        this.validate();
+    }
+    /**
+     * Set multiple field values at once
+     */
+    setFields(values) {
+        this._store.update((state) => {
+            const newTouched = { ...state.touched };
+            // Mark all updated fields as touched
+            Object.keys(values).forEach((key) => {
+                newTouched[key] = true;
+            });
+            return {
+                ...state,
+                values: {
+                    ...state.values,
+                    ...values
+                },
+                touched: newTouched,
+                isDirty: true
+            };
+        });
+        this.validate();
+    }
+    /**
+     * Set a field as touched without changing its value
+     */
+    setTouched(field) {
+        this._store.update((state) => ({
+            ...state,
+            touched: {
+                ...state.touched,
+                [field]: true
+            }
+        }));
+    }
+    /**
+     * Validate a specific field
+     */
+    validateField(field) {
+        const currentState = get(this._store);
+        const fieldValue = currentState.values[field];
+        const errors = [];
+        // Check custom field validation
+        const registration = this.fieldRegistrations.get(field);
+        if (registration?.validate) {
+            const customError = registration.validate(fieldValue);
+            if (customError) {
+                errors.push(customError);
+            }
+        }
+        // Run Zod validation on the entire form to get field-specific errors
+        const result = this.schema.safeParse(currentState.values);
+        if (!result.success) {
+            const zodErrors = result.error.format();
+            const fieldErrors = zodErrors[field]?._errors || [];
+            errors.push(...fieldErrors);
+        }
+        return errors;
+    }
+    /**
+     * Reset the form to initial values
+     */
+    reset() {
+        this._store.set({
+            values: { ...this.initialValues },
+            errors: {},
+            touched: {},
+            isValid: false,
+            isDirty: false,
+            isSubmitting: false
+        });
+        this.validate();
+    }
+    /**
+     * Set the form as submitting
+     */
+    setSubmitting(isSubmitting) {
+        this._store.update((state) => ({
+            ...state,
+            isSubmitting
+        }));
+    }
+    /**
+     * Update the schema (useful for dynamic forms)
+     */
+    updateSchema(newSchema) {
+        this.schema = newSchema;
+        this.validate();
+    }
+    /**
+     * Validate the entire form
+     */
+    validate() {
+        this._store.update((state) => {
+            const result = this.schema.safeParse(state.values);
+            const errors = {};
+            let isValid = true;
+            if (!result.success) {
+                isValid = false;
+                // Convert Zod errors to our error format
+                Object.keys(state.values).forEach((key) => {
+                    const fieldKey = key;
+                    const fieldErrors = result.error.format()[fieldKey]
+                        ?._errors || [];
+                    // Add custom field validation errors
+                    const registration = this.fieldRegistrations.get(key);
+                    if (registration?.validate) {
+                        const customError = registration.validate(state.values[fieldKey]);
+                        if (customError) {
+                            fieldErrors.push(customError);
+                        }
+                    }
+                    if (fieldErrors.length > 0) {
+                        errors[fieldKey] = fieldErrors;
+                    }
+                });
+            }
+            return {
+                ...state,
+                errors,
+                isValid
+            };
+        });
+    }
+    /**
+     * Get the current state of the form
+     */
+    getState() {
+        return get(this._store);
+    }
+    /**
+     * Destroy the form and clean up resources
+     */
+    destroy() {
+        // Remove from registries
+        formsRegistry.update((registry) => {
+            delete registry[this.identifier];
+            return registry;
+        });
+        fieldRegistrations.update((registrations) => {
+            delete registrations[this.identifier];
+            return registrations;
+        });
+        // Clear field registrations
+        this.fieldRegistrations.clear();
+    }
+}
+/**
+ * Creates a generic form with Zod validation
+ */
+export function createGenericForm(identifier, schema, initialValues) {
+    const form = new FormManager(identifier, schema, initialValues);
+    return {
+        // Reactive stores that components can directly subscribe to
+        values: form.values,
+        errors: form.errors,
+        touched: form.touched,
+        isValid: form.isValid,
+        isDirty: form.isDirty,
+        isSubmitting: form.isSubmitting,
+        // Helper methods
+        setField: form.setField.bind(form),
+        setFields: form.setFields.bind(form),
+        setTouched: form.setTouched.bind(form),
+        reset: form.reset.bind(form),
+        setSubmitting: form.setSubmitting.bind(form),
+        updateSchema: form.updateSchema.bind(form),
+        registerField: form.registerField.bind(form),
+        validateField: form.validateField.bind(form),
+        // For advanced use cases
+        getState: form.getState.bind(form),
+        destroy: form.destroy.bind(form)
+    };
+}
 /**
  * Creates a form validation utility with Svelte 5 reactive stores
  * @param identifier - Unique identifier for the form
@@ -265,7 +537,7 @@ export class FormValidator {
         }));
     }
     /**
-     * Get the current state of the form (for legacy compatibility)
+     * Get the current state of the form
      */
     getState() {
         return get(this._store);
@@ -302,7 +574,6 @@ export function createForm(identifier, initialValues, options) {
 /**
  * Get a form by its identifier
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function getFormById(identifier) {
     const registry = get(formsRegistry);
     return registry[identifier];
@@ -354,6 +625,43 @@ export function createFormSubscription(identifier) {
         destroy: () => clearInterval(intervalId)
     };
 }
+/**
+ * Helper to get field state for a specific form and field
+ */
+export function getFieldState(formId, fieldName) {
+    const form = getFormById(formId);
+    if (!form) {
+        return {
+            value: undefined,
+            error: [],
+            touched: false,
+            isValid: true
+        };
+    }
+    const state = form.getState();
+    return {
+        value: state.values[fieldName],
+        error: state.errors[fieldName] || [],
+        touched: state.touched[fieldName] || false,
+        isValid: !state.errors[fieldName] || state.errors[fieldName].length === 0
+    };
+}
+/**
+ * Helper to update a field value for a specific form
+ */
+export function updateFieldValue(formId, fieldName, value) {
+    const form = getFormById(formId);
+    if (form && 'setField' in form) {
+        form.setField(fieldName, value);
+    }
+}
+/**
+ * Helper to get all registered field names for a form
+ */
+export function getFormFieldNames(formId) {
+    const registrations = get(fieldRegistrations);
+    return Object.keys(registrations[formId] || {});
+}
 /**
  * Store to track if the form is adding or updating to the Canvas
  */

package/dist/{stores → ui/stores}/forms/Form.stories.js

@@ -35,7 +35,7 @@ The form validation system provides:
 The main class for creating and managing form validation state.
 
 \`\`\`typescript
-import { FormValidator } from './';
+import { FormValidator } from '../../../stores/forms';
 
 // Define your form data structure
 interface MyFormData {
@@ -196,7 +196,7 @@ The system maintains a global registry of all forms for cross-component access.
 Retrieve a form instance by its identifier:
 
 \`\`\`typescript
-import { getFormById } from './';
+import { getFormById } from '../../../stores/forms';
 
 const form = getFormById('my-form-id');
 if (form) {
@@ -209,7 +209,7 @@ if (form) {
 Check if a specific form is valid:
 
 \`\`\`typescript
-import { isFormValid } from './';
+import { isFormValid } from '../../../stores/forms';
 
 if (isFormValid('my-form-id')) {
 	console.log('Form is valid!');
@@ -221,7 +221,7 @@ if (isFormValid('my-form-id')) {
 Get error messages for a specific form:
 
 \`\`\`typescript
-import { getFormErrors } from './';
+import { getFormErrors } from '../../../stores/forms';
 
 const errors = getFormErrors('my-form-id');
 console.log(errors);
@@ -232,7 +232,7 @@ console.log(errors);
 Reset a form by its identifier:
 
 \`\`\`typescript
-import { resetForm } from './';
+import { resetForm } from '../../../stores/forms';
 
 resetForm('my-form-id');
 \`\`\`

package/dist/{stores → ui/stores}/forms/FormDemo.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-	import { FormValidator } from '../forms';
+	import { FormValidator } from '../form';
 
 	interface DemoFormData {
 		name: string;

package/dist/{stores → ui/stores}/index.d.ts

@@ -1,7 +1,5 @@
 export * from './breakpoints';
-export * from './forms';
+export * from './form';
 export * from './componentInjectErrors';
-export * from './isPreviewMode';
-export * from './router';
 export * from './showConfirmActionModal';
 export * from './siteInfo';

package/dist/{stores → ui/stores}/index.js

@@ -1,7 +1,5 @@
 export * from './breakpoints';
-export * from './forms';
+export * from './form';
 export * from './componentInjectErrors';
-export * from './isPreviewMode';
-export * from './router';
 export * from './showConfirmActionModal';
 export * from './siteInfo';

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

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

package/dist/ui/utils/api/checkIfAppModeIsDesign.js

@@ -0,0 +1,19 @@
+/**
+ * Checks if the app mode is design and shows error notification if not.
+ */
+export const checkIfAppModeIsDesign = async () => {
+    const capabilities = await webflow.canForAppMode([
+        webflow.appModes.canDesign,
+        webflow.appModes.canEdit
+    ]);
+    if (capabilities.canDesign) {
+        // Proceed with the action
+        return true;
+    }
+    // Provide feedback to the user
+    await webflow.notify({
+        type: 'Error',
+        message: 'This action cannot be performed right now. Ensure you are working in the Primary Locale, on the Main Branch, and in design mode.'
+    });
+    return false;
+};

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

@@ -0,0 +1,15 @@
+import type { XSCPMetadata } from '../../../../types';
+/**
+ * Processes pasted component data to validate Finsweet components.
+ */
+export declare const processPastedComponent: (pasteData: XSCPMetadata, component: string) => {
+    data: XSCPMetadata;
+    key: string;
+} | undefined;
+/**
+ * Handles pasting of Webflow components from clipboard.
+ */
+export declare const handlePasteXSCP: (e: ClipboardEvent, component: string) => {
+    data: XSCPMetadata;
+    key: string;
+} | undefined;

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

@@ -0,0 +1,49 @@
+import { getLogger } from '../../../../utils/logger';
+const logger = getLogger('webflow-apps-ui-utils');
+/**
+ * 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) => {
+        if (component === 'consent') {
+            // consent is kinda different
+            const bannerFound = attr.name.includes(`fs-consent-element`) && attr.value === 'banner';
+            const wrapperFound = attr.name.includes(`fs-consent-element`) && attr.value === 'wrapper';
+            return bannerFound || wrapperFound;
+        }
+        return attr.name.includes(`fs-${component}-instance`);
+    }));
+    if (valid) {
+        return { data: pasteData, key: component };
+    }
+};
+/**
+ * Handles pasting of Webflow components from clipboard.
+ */
+export const handlePasteXSCP = (e, component) => {
+    if (!e.clipboardData?.types.includes('application/json'))
+        return;
+    const data = e.clipboardData?.getData('application/json');
+    const clipboard = JSON.parse(data);
+    if (clipboard?.type === '@webflow/XscpData') {
+        try {
+            const data = e.clipboardData.getData('application/json');
+            const clipboard = JSON.parse(data);
+            if (clipboard?.type === '@webflow/XscpData') {
+                return processPastedComponent(clipboard, component);
+            }
+            webflow.notify({
+                type: 'Error',
+                message: 'Invalid! You can only paste valid Finsweet Components.'
+            });
+        }
+        catch (error) {
+            logger.error({}, 'handlePasteXSCP', error);
+            webflow.notify({
+                type: 'Error',
+                message: 'Invalid! You can only paste valid Finsweet Components.'
+            });
+            return;
+        }
+    }
+};

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

@@ -0,0 +1 @@
+export * from './handlePaste';

package/dist/ui/utils/api/clipboard/index.js

@@ -0,0 +1 @@
+export * from './handlePaste';

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

@@ -0,0 +1,11 @@
+export interface AllAssets {
+    name: string;
+    url: string;
+    mimeType: string;
+    altText: string;
+    asset: Asset;
+}
+/**
+ * Gets all assets from the Webflow Canvas with their metadata.
+ */
+export declare const getAllAssets: () => Promise<AllAssets[]>;

package/dist/ui/utils/api/getAllAssets.js

@@ -0,0 +1,20 @@
+/**
+ * Gets all assets from the Webflow Canvas with their metadata.
+ */
+export const getAllAssets = async () => {
+    const assets = await webflow.getAllAssets();
+    const assetPromises = assets.map(async (asset) => {
+        const url = await asset.getUrl();
+        const name = await asset.getName();
+        const mimeType = await asset.getMimeType();
+        const altText = (await asset.getAltText()) ?? '';
+        return {
+            name,
+            url,
+            mimeType,
+            altText,
+            asset
+        };
+    });
+    return await Promise.all(assetPromises);
+};

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

@@ -0,0 +1,8 @@
+/**
+ * Gets the Finsweet components environment configuration.
+ */
+export declare const getFinsweetComponentsEnvironment: () => {
+    development: boolean;
+    coreScript: string;
+    api: string;
+};

package/dist/ui/utils/api/getFinsweetComponentsEnvironment.js

@@ -0,0 +1,66 @@
+import { COMPONENTS_CORE_SCRIPT, COMPONENTS_CORE_SCRIPT_LOCAL, COMPONENTS_SERVER_DEV_ENDPOINT, COMPONENTS_SERVER_DEV_ENDPOINT_LOCAL, COMPONENTS_SERVER_PROD_ENDPOINT, getLocalStorage } from '../../../utils';
+const DEV_MODE_KEY = 'fsComponentsDevMode';
+const DEV_MODE_SCRIPT_KEY = 'fsComponentsDevModeScript';
+const DEV_MODE_API_KEY = 'fsComponentsDevModeApi';
+const URL_DEV_MODE_KEY = 'dev';
+const URL_DEV_MODE_SCRIPT_KEY = 'script';
+const URL_DEV_MODE_API_KEY = 'api';
+let lastLogTime = 0;
+const LOG_THROTTLE_MS = 3000;
+/**
+ * Gets a parameter value from the URL search params.
+ */
+const getUrlParam = (key) => {
+    if (typeof window === 'undefined')
+        return null;
+    try {
+        const urlParams = new URLSearchParams(window.location.search);
+        return urlParams.get(key);
+    }
+    catch (e) {
+        console.error('Error getting URL parameter:', e);
+        return null;
+    }
+};
+/**
+ * Throttled console log that only logs once within the throttle interval.
+ */
+const throttledLog = (message, data) => {
+    const now = Date.now();
+    if (now - lastLogTime >= LOG_THROTTLE_MS) {
+        console.log(message, data || '');
+        lastLogTime = now;
+    }
+};
+/**
+ * Gets the Finsweet components environment configuration.
+ */
+export const getFinsweetComponentsEnvironment = () => {
+    const devFromUrl = getUrlParam(URL_DEV_MODE_KEY);
+    const scriptFromUrl = getUrlParam(URL_DEV_MODE_SCRIPT_KEY);
+    const apiFromUrl = getUrlParam(URL_DEV_MODE_API_KEY);
+    const dev = devFromUrl !== null ? devFromUrl === 'true' : getLocalStorage(DEV_MODE_KEY) === 'true';
+    let script = scriptFromUrl || getLocalStorage(DEV_MODE_SCRIPT_KEY) || COMPONENTS_CORE_SCRIPT;
+    let api = dev
+        ? apiFromUrl || getLocalStorage(DEV_MODE_API_KEY) || COMPONENTS_SERVER_DEV_ENDPOINT
+        : COMPONENTS_SERVER_PROD_ENDPOINT;
+    const isBrowser = typeof window !== 'undefined';
+    const isLocalhost = isBrowser && window?.location?.hostname?.includes('localhost');
+    //if localhost then use local scripts
+    if (isLocalhost) {
+        script = COMPONENTS_CORE_SCRIPT_LOCAL;
+        api = COMPONENTS_SERVER_DEV_ENDPOINT_LOCAL;
+    }
+    const development = !!dev || isLocalhost;
+    if (development) {
+        throttledLog(`\n\nFinsweet Components Environment: 
+      - API: ${api}
+      - Core script: ${script}
+      - Development mode: ${development ? 'Yes' : 'No'}\n\n`);
+    }
+    return {
+        development,
+        coreScript: script,
+        api
+    };
+};

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

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

package/dist/ui/utils/api/index.js

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

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

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

package/dist/ui/utils/api/insertWithXSCP.js

@@ -0,0 +1,12 @@
+/**
+ * Inserts a template into the Designer Canvas using XSCP APIs.
+ */
+export const insertWithXSCP = async (template) => {
+    try {
+        // @ts-expect-error - typings not available for xscp
+        await webflow._internal.xscp(template);
+    }
+    catch (error) {
+        throw new Error(`Failed to insert template with XSCP: ${error}`);
+    }
+};

package/dist/{utils → ui/utils}/auth/crossWindowLogin.d.ts

@@ -1,4 +1,4 @@
-import type { FinsweetAuth } from '../../types';
+import type { FinsweetAuth } from '../../../types';
 /**
  * Opens a popup window for cross-window authentication with Auth0.
  */

package/dist/{utils → ui/utils}/auth/crossWindowLogin.js

@@ -1,4 +1,4 @@
-import { AUTH0_AUDIENCE, AUTH0_CLIENT_ID, AUTH0_LOGIN_URL, AUTH0_REDIRECT_URL, AUTH0_SCOPE, PROD_FINSWEEET_ACCOUNTS_ORIGIN } from '../constants';
+import { AUTH0_AUDIENCE, AUTH0_CLIENT_ID, AUTH0_LOGIN_URL, AUTH0_REDIRECT_URL, AUTH0_SCOPE, PROD_FINSWEEET_ACCOUNTS_ORIGIN } from '../../../utils/constants';
 /**
  * Opens a popup window for cross-window authentication with Auth0.
  */

package/dist/{utils → ui/utils}/auth/index.d.ts

@@ -1,4 +1,4 @@
-import type { FinsweetAuth } from '../../types';
+import type { FinsweetAuth } from '../../../types';
 /**
  * Store for the Finsweet user data.
  */