@myissue/vue-website-page-builder 3.4.96 → 3.4.97

package/dist/services/PageBuilderService.d.ts

@@ -0,0 +1,587 @@
+import { BuilderResourceData, ComponentObject, ImageObject, PageBuilderConfig, PageSettings, SEOSummary, StartBuilderResult } from '../types';
+import { usePageBuilderStateStore } from '../stores/page-builder-state';
+export type AvailableLanguage = 'en' | 'zh-Hans' | 'fr' | 'ja' | 'ru' | 'es' | 'pt' | 'de' | 'ar' | 'hi' | 'da' | 'it';
+export declare const AVAILABLE_LANGUAGES: AvailableLanguage[];
+export declare class PageBuilderService {
+    private fontSizeRegex;
+    protected pageBuilderStateStore: ReturnType<typeof usePageBuilderStateStore>;
+    private getLocalStorageItemName;
+    private getApplyImageToSelection;
+    private getHyberlinkEnable;
+    private getComponents;
+    private getComponent;
+    private getElement;
+    private getComponentArrayAddMethod;
+    private NoneListernesTags;
+    private hasStartedEditing;
+    private originalComponents;
+    private savedMountComponents;
+    private pendingMountComponents;
+    private globalStylesObserver;
+    private _pendingPageSettings;
+    private isPageBuilderMissingOnStart;
+    private elementsWithListeners;
+    private translate;
+    constructor(pageBuilderStateStore: ReturnType<typeof usePageBuilderStateStore>);
+    /**
+     * Returns an array of available languages.
+     * @returns {AvailableLanguage[]} An array of available language codes.
+     */
+    availableLanguage(): AvailableLanguage[];
+    /**
+     * Sets the current language in the page builder state.
+     * @param {string} lang - The language code to set.
+     */
+    changeLanguage(lang: string): void;
+    /**
+     * Deselects any selected or hovered elements in the builder UI.
+     * @returns {Promise<void>}
+     */
+    clearHtmlSelection(): Promise<void>;
+    /**
+     * Ensures that the `updateOrCreate` configuration is valid and sets default values if necessary.
+     * @param {PageBuilderConfig} config - The page builder configuration.
+     * @private
+     */
+    private ensureUpdateOrCreateConfig;
+    /**
+     * Validates the user-provided components array.
+     * @param {unknown} components - The components data to validate.
+     * @returns {{error: true, warning: string, status: string} | {error: true, reason: string} | undefined} An error object if validation fails, otherwise undefined.
+     * @private
+     */
+    private validateUserProvidedComponents;
+    /**
+     * Ensures that the language configuration is valid and sets default values if necessary.
+     * @param {PageBuilderConfig} config - The page builder configuration.
+     * @private
+     */
+    private ensureLanguage;
+    /**
+     * Validates the entire page builder configuration.
+     * @param {PageBuilderConfig} config - The page builder configuration.
+     * @private
+     */
+    private validateConfig;
+    /**
+     * Saves user settings to local storage.
+     * @param {string} newLang - The new language to save.
+     */
+    saveUserSettingsStorage(newLang: string): void;
+    /**
+     * Initializes the Page Builder.
+     * @param {PageBuilderConfig} config - The configuration object for the Page Builder.
+     * @param {BuilderResourceData} [passedComponentsArray] - Optional array of components to load.
+     * @returns {Promise<StartBuilderResult>} A result object indicating success or failure.
+     */
+    startBuilder(config: PageBuilderConfig, passedComponentsArray?: BuilderResourceData): Promise<StartBuilderResult>;
+    /**
+     * Completes the builder initialization process once the DOM is ready.
+     * @param {BuilderResourceData} [passedComponentsArray] - Optional array of components to load.
+     * @returns {Promise<void>}
+     */
+    completeBuilderInitialization(passedComponentsArray?: BuilderResourceData): Promise<void>;
+    /**
+     * Converts an array of ComponentObject into a single HTML string.
+     *
+     * @returns {string} A single HTML string containing all components.
+     */
+    private renderComponentsToHtml;
+    /**
+     * Completes the mounting process by loading components into the DOM and setting up listeners.
+     * @param {string} html - The HTML string of components to mount.
+     * @param {boolean} [useConfigPageSettings] - Whether to use page settings from the passed data.
+     * @private
+     */
+    private completeMountProcess;
+    /**
+     * Applies CSS class changes to the currently selected element.
+     * @param {string | undefined} cssUserSelection - The user's CSS class selection.
+     * @param {string[]} CSSArray - The array of possible CSS classes for this property.
+     * @param {string} mutationName - The name of the store mutation to call.
+     * @returns {string | undefined} The previously applied CSS class.
+     * @private
+     */
+    private applyElementClassChanges;
+    /**
+     * Removes all CSS classes from the main page builder container.
+     * @returns {Promise<void>}
+     */
+    clearClassesFromPage(): Promise<void>;
+    /**
+     * Removes all inline styles from the main page builder container.
+     * @returns {Promise<void>}
+     */
+    clearInlineStylesFromPage(): Promise<void>;
+    /**
+     * Selects the main page builder container for global styling.
+     * @returns {Promise<void>}
+     */
+    globalPageStyles(): Promise<void>;
+    /**
+     * Disconnects the MutationObserver that syncs global page style changes across
+     * all [data-pagebuilder-content] section wrappers. Call when closing the global
+     * styles editor panel.
+     */
+    stopGlobalStylesSync(): void;
+    /**
+     * Handles changes to the font weight of the selected element.
+     * @param {string} [userSelectedFontWeight] - The selected font weight class.
+     */
+    handleFontWeight(userSelectedFontWeight?: string): void;
+    /**
+     * Handles changes to the base font size of the selected element.
+     * @param {string} [userSelectedFontSize] - The selected font size class.
+     */
+    handleFontSizeBase(userSelectedFontSize?: string): void;
+    /**
+     * Handles changes to the desktop font size of the selected element.
+     * @param {string} [userSelectedFontSize] - The selected font size class for desktop.
+     */
+    handleFontSizeDesktop(userSelectedFontSize?: string): void;
+    /**
+     * Applies helper CSS classes to elements, such as wrapping them or adding responsive text classes.
+     * @param {HTMLElement} element - The element to process.
+     * @private
+     */
+    private ensureImagesHaveAltText;
+    private applyHelperCSSToElements;
+    /**
+     * Toggles the visibility of the TipTap modal for rich text editing.
+     * @param {boolean} status - Whether to show or hide the modal.
+     * @returns {Promise<void>}
+     */
+    toggleTipTapModal(status: boolean): Promise<void>;
+    /**
+     * Wraps an element in a div if it's an excluded tag and adjacent to an image.
+     * @param {HTMLElement} element - The element to potentially wrap.
+     * @private
+     */
+    private wrapElementInDivIfExcluded;
+    /**
+     * Handles the mouseover event for editable elements, showing a hover state.
+     * @param {Event} e - The mouse event.
+     * @param {HTMLElement} element - The element being hovered over.
+     * @private
+     */
+    private handleMouseOver;
+    /**
+     * Handles the mouseleave event for editable elements, removing the hover state.
+     * @param {Event} e - The mouse event.
+     * @private
+     */
+    private handleMouseLeave;
+    /**
+     * Checks if an element is editable based on its tag name.
+     * @param {Element | null} el - The element to check.
+     * @returns {boolean} True if the element is editable, false otherwise.
+     */
+    isEditableElement(el: Element | null): boolean;
+    /**
+     * Attaches click, mouseover, and mouseleave event listeners to all editable elements in the page builder.
+     * @private
+     */
+    private addListenersToEditableElements;
+    /**
+     * Handles the click event for editable elements, setting the element as selected.
+     * @param {Event} e - The click event.
+     * @param {HTMLElement} element - The clicked element.
+     * @private
+     */
+    private handleElementClick;
+    private getHistoryBaseKey;
+    private initializeHistory;
+    /**
+     * Triggers an auto-save of the current page builder content to local storage if enabled.
+     */
+    handleAutoSave: () => Promise<void>;
+    /**
+     * Manually saves the current page builder content to local storage.
+     */
+    handleManualSave: (doNoClearHTML?: boolean) => Promise<void>;
+    /**
+     * Clones a component object and prepares it for insertion into the DOM by adding unique IDs and prefixes.
+     * @param {ComponentObject} componentObject - The component object to clone.
+     * @returns {ComponentObject} The cloned and prepared component object.
+     */
+    cloneCompObjForDOMInsertion(componentObject: ComponentObject): ComponentObject;
+    /**
+     * Removes the 'hovered' and 'selected' attributes from all elements in the page builder.
+     * @private
+     */
+    private removeHoveredAndSelected;
+    /**
+     * Syncs the CSS classes of the currently selected element to the state store.
+     * @private
+     */
+    private syncCurrentClasses;
+    /**
+     * Syncs the inline styles of the currently selected element to the state store.
+     * @private
+     */
+    private syncCurrentStyles;
+    /**
+     * Adds a CSS class to the currently selected element.
+     * @param {string} userSelectedClass - The class to add.
+     */
+    handleAddClasses(userSelectedClass: string): void;
+    /**
+     * Adds or updates an inline style property on the currently selected element.
+     * @param {string} property - The CSS property to add/update.
+     * @param {string} value - The value of the CSS property.
+     */
+    handleAddStyle(property: string, value: string): void;
+    /**
+     * Removes an inline style property from the currently selected element.
+     * @param {string} property - The CSS property to remove.
+     */
+    handleRemoveStyle(property: string): void;
+    /**
+     * Handles changes to the font family of the selected element.
+     * @param {string} [userSelectedFontFamily] - The selected font family class.
+     */
+    handleFontFamily(userSelectedFontFamily?: string): void;
+    /**
+     * Handles changes to the font style of the selected element.
+     * @param {string} [userSelectedFontStyle] - The selected font style class.
+     */
+    handleFontStyle(userSelectedFontStyle?: string): void;
+    /**
+     * Handles changes to the vertical padding of the selected element.
+     * @param {string} [userSelectedVerticalPadding] - The selected vertical padding class.
+     */
+    handleVerticalPadding(userSelectedVerticalPadding?: string): void;
+    /**
+     * Handles changes to the horizontal padding of the selected element.
+     * @param {string} [userSelectedHorizontalPadding] - The selected horizontal padding class.
+     */
+    handleHorizontalPadding(userSelectedHorizontalPadding?: string): void;
+    /**
+     * Handles changes to the vertical margin of the selected element.
+     * @param {string} [userSelectedVerticalMargin] - The selected vertical margin class.
+     */
+    handleVerticalMargin(userSelectedVerticalMargin?: string): void;
+    /**
+     * Handles changes to the horizontal margin of the selected element.
+     * @param {string} [userSelectedHorizontalMargin] - The selected horizontal margin class.
+     */
+    handleHorizontalMargin(userSelectedHorizontalMargin?: string): void;
+    /**
+     * Handles changes to the border style of the selected element.
+     * @param {string} [borderStyle] - The selected border style class.
+     */
+    handleBorderStyle(borderStyle?: string): void;
+    /**
+     * Handles changes to the border width of the selected element.
+     * @param {string} [borderWidth] - The selected border width class.
+     */
+    handleBorderWidth(borderWidth?: string): void;
+    /**
+     * Handles changes to the border color of the selected element.
+     * @param {string} [borderColor] - The selected border color class.
+     */
+    handleBorderColor(borderColor?: string): void;
+    /**
+     * Handles changes to the background color of the selected element.
+     * @param {string} [color] - The selected background color class.
+     */
+    handleBackgroundColor(color?: string): void;
+    /**
+     * Handles changes to the text color of the selected element.
+     * @param {string} [color] - The selected text color class.
+     */
+    handleTextColor(color?: string): void;
+    /**
+     * Handles changes to the global border radius of the selected element.
+     * @param {string} [borderRadiusGlobal] - The selected global border radius class.
+     */
+    handleBorderRadiusGlobal(borderRadiusGlobal?: string): void;
+    /**
+     * Handles changes to the top-left border radius of the selected element.
+     * @param {string} [borderRadiusTopLeft] - The selected top-left border radius class.
+     */
+    handleBorderRadiusTopLeft(borderRadiusTopLeft?: string): void;
+    /**
+     * Handles changes to the top-right border radius of the selected element.
+     * @param {string} [borderRadiusTopRight] - The selected top-right border radius class.
+     */
+    handleBorderRadiusTopRight(borderRadiusTopRight?: string): void;
+    /**
+     * Handles changes to the bottom-left border radius of the selected element.
+     * @param {string} [borderRadiusBottomleft] - The selected bottom-left border radius class.
+     */
+    handleBorderRadiusBottomleft(borderRadiusBottomleft?: string): void;
+    /**
+     * Handles changes to the bottom-right border radius of the selected element.
+     * @param {string} [borderRadiusBottomRight] - The selected bottom-right border radius class.
+     */
+    handleBorderRadiusBottomRight(borderRadiusBottomRight?: string): void;
+    /**
+     * Handles changes to the tablet font size of the selected element.
+     * @param {string} [userSelectedFontSize] - The selected font size class for tablet.
+     */
+    handleFontSizeTablet(userSelectedFontSize?: string): void;
+    /**
+     * Handles changes to the mobile font size of the selected element.
+     * @param {string} [userSelectedFontSize] - The selected font size class for mobile.
+     */
+    handleFontSizeMobile(userSelectedFontSize?: string): void;
+    /**
+     * Handles changes to the background opacity of the selected element.
+     * @param {string} [opacity] - The selected background opacity class.
+     */
+    handleBackgroundOpacity(opacity?: string): void;
+    /**
+     * Handles changes to the opacity of the selected element.
+     * @param {string} [opacity] - The selected opacity class.
+     */
+    handleOpacity(opacity?: string): void;
+    /**
+     * Removes all components from both the builder state and the DOM.
+     * @private
+     */
+    private deleteAllComponentsFromDOM;
+    undo(): Promise<void>;
+    redo(): Promise<void>;
+    private hasVisibleContent;
+    private isSectionEmpty;
+    /**
+     * Duplicate the currently selected component from the DOM and the state.
+     * @returns {Promise<void>}
+     */
+    duplicateComponent(): Promise<void>;
+    /**
+     * Deletes the currently selected component from the DOM and the state.
+     * @returns {Promise<void>}
+     */
+    deleteComponentFromDOM(): Promise<void>;
+    /**
+     * Deletes the currently selected element from the DOM and stores it for potential restoration.
+     * @returns {Promise<void>}
+     */
+    deleteElementFromDOM(): Promise<void>;
+    /**
+     * Removes a CSS class from the currently selected element.
+     * @param {string} userSelectedClass - The class to remove.
+     */
+    handleRemoveClasses(userSelectedClass: string): void;
+    /**
+     * Reorders the currently selected component up or down in the component list.
+     * @param {number} direction - The direction to move the component (-1 for up, 1 for down).
+     */
+    reorderComponent(direction: number): Promise<void>;
+    /**
+     * Checks if the currently selected component can be moved up.
+     * @returns {boolean} True if the component can be moved up, false otherwise.
+     */
+    canMoveUp(): boolean;
+    /**
+     * Checks if the currently selected component can be moved down.
+     * @returns {boolean} True if the component can be moved down, false otherwise.
+     */
+    canMoveDown(): boolean;
+    /**
+     * Ensures that a text area element has content, adding a visual indicator if it's empty.
+     */
+    ensureTextAreaHasContent: () => void;
+    /**
+     * Handles text input for an element, updating its content.
+     * @param {string} textContentVueModel - The new text content from the Vue model.
+     * @returns {Promise<void>}
+     */
+    handleTextInput: (textContentVueModel: string) => Promise<void>;
+    /**
+     * Checks if the selected element or its first child is an iframe.
+     * @returns {boolean} True if it is an iframe, false otherwise.
+     */
+    ElOrFirstChildIsIframe(): boolean;
+    /**
+     * Checks if the selected element is a valid text container (i.e., does not contain images or divs).
+     * @returns {boolean | undefined} True if it's a valid text element, otherwise undefined.
+     */
+    isSelectedElementValidText(): false | undefined;
+    /**
+     * Generates a preview of the current page design.
+     */
+    previewCurrentDesign(): void;
+    /**
+     * Sanitizes a string to be used as a key in local storage.
+     * @param {string} input - The string to sanitize.
+     * @returns {string} The sanitized string.
+     */
+    sanitizeForLocalStorage(input: string): string;
+    /**
+     * Clones an element and removes selection-related attributes from the clone.
+     * @param {HTMLElement} element - The element to clone.
+     * @returns {HTMLElement} The sanitized clone.
+     * @private
+     */
+    private cloneAndRemoveSelectionAttributes;
+    /**
+     * Syncs the current DOM state of components to the in-memory store.
+     * @private
+     */
+    syncDomToStoreOnly(): void;
+    generateHtmlFromComponents(): Promise<string>;
+    /**
+     * Saves the current DOM state of components to local storage.
+     * @private
+     */
+    private saveDomComponentsToLocalStorage;
+    /**
+     * Removes the current page's components from local storage.
+     * @private
+     */
+    private removeCurrentComponentsFromLocalStorage;
+    /**
+     * Handles the form submission process, clearing local storage and the DOM.
+     * @returns {Promise<void>}
+     */
+    handleFormSubmission(): Promise<void>;
+    /**
+     * Parses a CSS style string into a key-value object.
+     * @param {string} style - The style string to parse.
+     * @returns {Record<string, string>} The parsed style object.
+     * @private
+     */
+    private parseStyleString;
+    /**
+     * Deletes old page builder data from local storage (older than 2 weeks).
+     */
+    deleteOldPageBuilderLocalStorage(): void;
+    /**
+     * Sets a flag to indicate that the user has started editing.
+     */
+    startEditing(): void;
+    /**
+     * Re-attaches click/hover listeners to any newly added DOM elements.
+     * Call this after programmatically inserting elements into the builder canvas.
+     */
+    refreshListeners(): Promise<void>;
+    /**
+     * Resumes editing from a draft saved in local storage.
+     * @returns {Promise<void>}
+     */
+    resumeEditingFromDraft(): Promise<void>;
+    /**
+     * Restores the original content that was loaded when the builder started.
+     * @returns {Promise<void>}
+     */
+    restoreOriginalContent(): Promise<void>;
+    returnLatestComponents(): Promise<ComponentObject[]>;
+    /**
+     * Gets the local storage key for the current resource.
+     * @returns {string | null} The local storage key.
+     */
+    getStorageItemNameForResource(): string | null;
+    /**
+     * Retrieves the saved page HTML from local storage.
+     * @returns {string | false} The HTML string or false if not found.
+     */
+    getSavedPageHtml(): string | false;
+    /**
+     * Applies a selected image to the current element.
+     * @param {ImageObject} image - The image object to apply.
+     * @returns {Promise<void>}
+     */
+    applySelectedImage(image: ImageObject): Promise<void>;
+    /**
+     * Sets the base primary image from the currently selected element if it's an image.
+     * @private
+     */
+    private setBasePrimaryImageFromSelectedElement;
+    /**
+     * Adds or removes a hyperlink from the selected element.
+     * @param {boolean} hyperlinkEnable - Whether to enable or disable the hyperlink.
+     * @param {string | null} urlInput - The URL for the hyperlink.
+     * @param {boolean} openHyperlinkInNewTab - Whether the link should open in a new tab.
+     * @private
+     */
+    private addHyperlinkToElement;
+    /**
+     * Checks if the selected element contains a hyperlink and updates the state accordingly.
+     * @private
+     */
+    private checkForHyperlink;
+    /**
+     * Handles all hyperlink-related actions for the selected element.
+     * @param {boolean} [hyperlinkEnable] - Whether to enable or disable the hyperlink.
+     * @param {string | null} [urlInput] - The URL for the hyperlink.
+     * @param {boolean} [openHyperlinkInNewTab] - Whether the link should open in a new tab.
+     */
+    handleHyperlink(hyperlinkEnable?: boolean, urlInput?: string | null, openHyperlinkInNewTab?: boolean): void;
+    addTheme(components: string): Promise<void>;
+    analyzeSEO(): Promise<SEOSummary>;
+    /**
+     * Adds a new component to the page builder.
+     * @param {ComponentObject} componentObject - The component to add.
+     * @returns {Promise<void>}
+     */
+    addComponent(componentObject: ComponentObject): Promise<void>;
+    /**
+     * Adds a prefix to Tailwind CSS classes in a string.
+     * @param {string} classList - The string of classes.
+     * @param {string} [prefix='pbx-'] - The prefix to add.
+     * @returns {string} The prefixed class string.
+     * @private
+     */
+    private addTailwindPrefixToClasses;
+    /**
+     * Converts a style object to a CSS string.
+     * @param {string | Record<string, string> | null | undefined} styleObj - The style object.
+     * @returns {string} The CSS style string.
+     * @private
+     */
+    private convertStyleObjectToString;
+    /**
+     * Parses a string of HTML and extracts builder components and global page settings.
+     * - This method expects an **HTML string** containing one or more `<section>...</section>` elements (such as the output from `getSavedPageHtml()` or a previously saved builder HTML string).
+     * - **Do NOT pass a JSON string** (such as the result of `JSON.stringify(componentsArray)`) to this method. Passing a JSON string to `DOMParser.parseFromString(..., 'text/html')` will not produce valid DOM nodes. Instead, it will treat the JSON as plain text, resulting in a `<html><head></head><body>{...json...}</body></html>` structure, not real HTML elements.
+     * - If you pass a JSON string, you will see lots of `\n` and strange HTML, because the parser is just wrapping your JSON in a `<body>` tag as text.
+     *
+     * Why only HTML?
+     * - It enforces a single source of truth for builder state (HTML).
+     * - It prevents misuse (e.g., passing JSON to a DOM parser, which is always a bug).
+     * - It makes your documentation and support much simpler.
+     *
+     * @param htmlString - The HTML string to parse (must contain `<section>...</section>` elements, not JSON).
+     * @returns An object with `components` (array of builder components) and `pageSettings` (global styles for the page).
+     */
+    parsePageBuilderHTML(htmlString: string): {
+        components: ComponentObject[];
+        pageSettings: PageSettings;
+    };
+    /**
+     * Applies modified components by mounting them to the DOM and attaching listeners.
+     * @param htmlString - The HTML string to apply
+     * @returns {Promise<string | null>} - Returns error message if failed, otherwise null
+     */
+    applyModifiedHTML(htmlString: string): Promise<string | null>;
+    private validateMountingHTML;
+    /**
+     * Applies modified components by mounting them to the DOM and attaching listeners.
+     * @param htmlString - The HTML string to apply
+     * @returns {Promise<string | null>} - Returns error message if failed, otherwise null
+     */
+    applyModifiedComponents(htmlString: string): Promise<string | null>;
+    /**
+     * Mounts builder components to the DOM from an HTML string.
+     *
+     * Input format detection:
+     *   - If the input starts with `[` or `{`: treated as JSON (array or object).
+     *   - If the input starts with `<`: treated as HTML.
+     *
+     * This function should be used when:
+     *   - Restoring the builder from a published HTML snapshot.
+     *   - Importing a static HTML export.
+     *   - Loading the builder from previously published or saved HTML (e.g., from `getSavedPageHtml()`).
+     *
+     * Typical use cases include restoring a published state, importing templates, or previewing published content.
+     */
+    private mountComponentsToDOM;
+    private updateLocalStorageItemName;
+    /**
+     * Initializes the styles for the currently selected element.
+     */
+    initializeElementStyles(): Promise<void>;
+}