@myissue/vue-website-page-builder 3.3.64 → 3.3.65

package/README.md

@@ -11,10 +11,10 @@
   - [Installation](#installation)
   - [About](#about)
   - [Features](#features)
-  - [Technical details](#technical-details)
+  - [Technical Details](#technical-details)
   - [Documentation](#documentation)
   - [Requirements](#requirements)
-  - [Getting started \& installation](#getting-started--installation)
+  - [Getting Started \& Installation](#getting-started--installation)
   - [Quick Start](#quick-start)
     - [Initializing the Page Builder](#initializing-the-page-builder)
     - [Why Use the Shared Instance?](#why-use-the-shared-instance)
@@ -25,11 +25,13 @@
   - [Local Storage \& Auto-Save](#local-storage--auto-save)
   - [Retrieving the Latest HTML Content for Form Submission](#retrieving-the-latest-html-content-for-form-submission)
     - [Resetting the Builder After Successful Resource Creation or Update](#resetting-the-builder-after-successful-resource-creation-or-update)
-  - [Loading existing Content or Components into the Page Builder](#loading-existing-content-or-components-into-the-page-builder)
+  - [Loading Existing Content or Components into the Page Builder](#loading-existing-content-or-components-into-the-page-builder)
+    - [Restoring Full Page Content (Global Styles \& Components)](#restoring-full-page-content-global-styles--components)
   - [Automatic Draft Recovery](#automatic-draft-recovery)
   - [Embedding Page Builder in a Modal or Dialog](#embedding-page-builder-in-a-modal-or-dialog)
+  - [Publish Button](#publish-button)
   - [Styling the Main Page Builder Container](#styling-the-main-page-builder-container)
-  - [Download HTML file](#download-html-file)
+  - [Download HTML File](#download-html-file)
   - [Custom Components](#custom-components)
     - [Custom Media Library Component](#custom-media-library-component)
     - [Integrate Unsplash Library](#integrate-unsplash-library)
@@ -40,35 +42,35 @@
     - [How the Page Builder Works](#how-the-page-builder-works)
   - [Contributing](#contributing)
   - [Security Vulnerabilities](#security-vulnerabilities)
-  - [Get in touch for customization or any questions](#get-in-touch-for-customization-or-any-questions)
+  - [Get in Touch for Customization or Any Questions](#get-in-touch-for-customization-or-any-questions)
   - [Feedback](#feedback)
   - [Support the Project](#support-the-project)
   - [License](#license)
 
 ## Demo
 
-A Vue 3 page builder component with drag & drop functionality for creating dynamic web pages.
+A Vue 3 page builder component with drag-and-drop functionality for creating dynamic web pages.
 
 Create and enhance digital experiences with Vue on any backend.
 
 Experience the power and simplicity of the Vue Website Page Builder in action.
-Try the live demo to explore real-time visual updates, and smooth content management
+Try the live demo to explore real-time visual updates and smooth content management.
 
-[Play around with the Page Builder](https://www.builder-demo.myissue.dk)
+[Play around with the Page Builder](https://mybuilder.dev)
 
 ## Overview
 
-If you're a Vue 3 developer, this builder feels right at home. It installs quickly via npm and supports full customization through props and configuration objects. You can even set specific user settings like image, name, theme, language, company logo and autosave preferences, making it a personalized experience for every user.
+If you're a Vue 3 developer, this builder feels right at home. It installs quickly via npm and supports full customization through props and configuration objects. You can even set specific user settings like image, name, theme, language, company logo, and autosave preferences, making it a personalized experience for every user.
 
-Lightweight & Minimalist Page Builder with an elegant and intuitive design, focused on simplicity and speed.
+A lightweight and minimalist Page Builder with an elegant and intuitive design, focused on simplicity and speed.
 
-Build responsive pages like listings, jobs or blog posts and manage content easily.
+Build responsive pages like listings, jobs, or blog posts and manage content easily.
 
 <img style="max-width: 100%;" src="./public/home/editor.jpg" alt="Vue Website Page Builder - the editor" />
 
 ## Get Started in Minutes
 
-Easy setup and instant productivity.  
+Easy setup and instant productivity.
 Follow the [Quick Start](#quick-start) guide to begin building with just a few simple steps.
 
 ---
@@ -93,8 +95,8 @@ A Page Builder designed for growth. Build your website pages with ready-made com
 
 Includes:
 
-- **Page Builder**: Click & Drop Page Builder.
-- **Customizable Design**: Tailor the look to match your brand.
+- **Page Builder**: A Click & Drop Page Builder.
+- **Customizable Design**: Customize the look to match your brand.
 
 The Page Builder is packed with features:
 
@@ -102,24 +104,24 @@ The Page Builder is packed with features:
 - **Reordering**: Change the order of your content without hassle.
 - **True Visual Editing**: See your changes in real-time as you make them.
 - **Media Library**: Easily inject your own custom media library component.
-- **Local Storage & Auto-Save**: Never lose your work - changes are saved as you go.
-- **Unsplash**: Unsplash Integration.
+- **Local Storage & Auto-Save**: Never lose your work—changes are saved as you go.
+- **Unsplash**: Unsplash integration.
 - **Responsive Editing**: Ensure your site looks great on all devices.
 - **Text Editing**: Edit text content live and in real-time.
 - **Font Customization**: Choose the perfect fonts to match your style.
 - **Undo & Redo**: Experiment confidently with the ability to revert changes.
-- **Global Styles**: Global Styles for fonts, designs, & colors.
+- **Global Styles**: Global styles for fonts, designs, and colors.
 - **YouTube Videos**: Integrate video content smoothly.
 - **Download HTML**: Export the entire page as a standalone HTML file.
 - **Global Page Styling**: Instantly define, update, or clear global styles for the main page wrapper at initialization or dynamically at runtime. Gain full control over fonts, colors, backgrounds, and more for a dynamic user experience.
 - **Tailwind Support**: Fully compatible with Tailwind CSS (with automatic class prefixing to avoid conflicts).
-- **Styles Prefixed**: To ensure clean and predictable styling, the builder uses Scoped Style Isolation. No risk of style conflicts between the builder and your app.
+- **Scoped Styles**: To ensure clean and predictable styling, the builder uses scoped style isolation. There is no risk of style conflicts between the builder and your app.
 
-Powerful Page Builder for any growing merchants, brands, & agencies. Empower users to create the perfect content with the Page Builder.
+A powerful Page Builder for any growing merchants, brands, and agencies. Empower users to create the perfect content with the Page Builder.
 
 <img style="max-width: 100%;" src="./public/home/text_editor.jpg" alt="Vue Website Page Builder - the media library" />
 
-## Technical details
+## Technical Details
 
 - **Technologies**: This Page Builder is developed using TypeScript, Vue 3, the Composition API, Pinia, CSS, Tailwind CSS, and HTML.
 - **Features**: Click & Drop Page Builder.
@@ -137,7 +139,7 @@ Please note that these instructions assume you have Node.js installed.
 - Vue.js ≥ 3.0.0
 - Modern browser with ES6+ support
 
-## Getting started & installation
+## Getting Started & Installation
 
 Make sure to install the dependencies:
 
@@ -182,10 +184,10 @@ const app = createApp(App)
 app.mount('#app')
 ```
 
-> **Note:**  
+> **Note:**
 > You only need to import the CSS file once. If you have already imported it in your app entry, you do not need to import it again in individual components.
 
-> **Note**  
+> **Note**
 > The Page Builder is implemented as a singleton service. This ensures that all page-building logic and state are managed by a single, shared instance throughout your application.
 
 ### Why Use the Shared Instance?
@@ -196,10 +198,10 @@ By always accessing the shared instance, you avoid creating multiple, isolated c
 
 Ensure the following configuration options are set:
 
-- **`formType` (required):**  
+- **`formType` (required):**
   Indicates whether you are creating or updating a resource. This is used to retrieve the correct content from local storage.
 
-- **`formName` (required):**  
+- **`formName` (required):**
   Specifies the resource type (for example, `article`, `jobPost`, `store`, etc.).
 
 ```vue
@@ -232,10 +234,10 @@ This prevents global styles from leaking into the builder and vice versa, which
 
 **How does this affect you?**
 
-When a user adds a component into the page builder, all classes from that component are automatically prefixed with pbx- (e.g., pbx-button, pbx-container) to ensure style isolation and avoid conflicts.
+When a user adds a component into the page builder, all classes from that component are automatically prefixed with `pbx-` (e.g., `pbx-button`, `pbx-container`) to ensure style isolation and avoid conflicts.
 
-> **Note:**  
-> Simply import the builder’s CSS file once in your project. All builder styles are namespaced, so there is no risk of style conflicts
+> **Note:**
+> Simply import the builder’s CSS file once in your project. All builder styles are namespaced, so there is no risk of style conflicts.
 
 ## Rendering HTML Output in Other Frameworks (React, Nuxt, etc.)
 
@@ -270,7 +272,7 @@ import '@myissue/vue-website-page-builder/style.css'
 
 Then use `v-html` to render the HTML.
 
-> **Note:**  
+> **Note:**
 > You do not need to import any Vue components if you only want to render the HTML. Just import the CSS file.
 
 ## Providing Configuration to the Page Builder
@@ -279,19 +281,19 @@ The example below demonstrates the setup to start building pages, with additiona
 
 Your `configPageBuilder` object can include:
 
-- **`formType` (required):**  
+- **`formType` (required):**
   Used to retrieve the correct content from local storage. Specify whether you are creating or updating a resource.
-- **`formName` (required):**  
+- **`formName` (required):**
   The resource type (e.g., `article`, `jobPost`, `store`, etc.). This is especially useful for platforms supporting multiple resource types, allowing the builder to manage layouts and storage for each resource uniquely.
-- **`resourceData` (optional):**  
+- **`resourceData` (optional):**
   Prefill the builder with initial resource data (e.g., `title`, `id`).
-- **`userForPageBuilder` (optional):**  
+- **`userForPageBuilder` (optional):**
   Pass user information (such as `name` and `image`) to display the logged-in user’s details in the builder.
-- **`pageBuilderLogo` (optional):**  
+- **`pageBuilderLogo` (optional):**
   Display your company logo in the builder toolbar.
-- **`userSettings` (optional):**  
+- **`userSettings` (optional):**
   Set user preferences such as theme, language, or auto-save.
-- **`brandColor` (optional):**  
+- **`brandColor` (optional):**
   Set your brand’s primary color for key UI elements (inside the `settings` config).
 
 ```vue
@@ -375,101 +377,90 @@ const configPageBuilder = {
 const pageBuilderService = getPageBuilder()
 await pageBuilderService.startBuilder(configPageBuilder)
 
-let storedComponents = pageBuilderService.loadStoredComponentsFromStorage()
-let contentFromPageBuilder = ''
-
-try {
-  storedComponents = JSON.parse(storedComponents)
-  contentFromPageBuilder =
-    storedComponents && Array.isArray(storedComponents.components)
-      ? storedComponents.components.map((component) => component.html_code).join('')
-      : ''
-} catch (e) {
-  console.error('Unable to parse storedComponents from localStorage:', e)
-  contentFromPageBuilder = ''
-} finally {
-  yourForm.content = contentFromPageBuilder
-}
+const storedComponents = pageBuilderService.getSavedPageHtml()
+yourForm.content = storedComponents
 </script>
 ```
 
 ### Resetting the Builder After Successful Resource Creation or Update
 
-After you have successfully created or updated a resource (such as a post, article, or listing) using the Page Builder, it is important to clear the builder’s draft state and remove the corresponding local storage entry. This ensures that old drafts do not appear the next time the builder is opened for a new or existing resource.
+After successfully creating or updating a resource (such as a post, article, or listing) using the Page Builder, it is important to clear the DOM and the builder’s draft state, as well as remove the corresponding local storage entry. This ensures that old drafts do not appear the next time the builder is opened for a new or existing resource.
 
-You can reset the builder state and clear the draft with:
+You can reset the Page Builder’s live DOM, builder state, and clear the draft with:
 
 ```js
-// Delete the HTML from the Live DOM
-pageBuilderService.deleteAllComponentsFromDOM()
-// Clear Local Storage for the created or updated resource
-await pageBuilderService.removeCurrentComponentsFromLocalStorage()
+await pageBuilderService.handleFormSubmission()
 ```
 
-Always call these methods after a successful post or resource update to ensure users start with a fresh builder the next time they create or edit a resource.
+Always call this method after a successful post or resource update to ensure users start with a fresh builder the next time they create or edit a resource.
 
-## Loading existing Content or Components into the Page Builder
+## Loading Existing Content or Components into the Page Builder
 
-The Page Builder makes it simple to load previously published content from any backend source, such as your database or API.
+The Page Builder makes it simple to load previously published content—including both your page’s global styles and all components—from any backend source, such as your database or API.
 
-The `startBuilder` method accepts two arguments:
+### Restoring Full Page Content (Global Styles & Components)
 
-1. **Configuration** (required):  
-   The builder configuration object.
-2. **Components Data** (optional):  
-   An array of component objects. Each object must include a `html_code` string and may optionally include a title string. This is especially useful when loading previously published or saved content into the builder.
+If you have previously saved or published HTML content (for example, from your database), you can easily restore both the global page styles (classes, inline styles) and all builder components for seamless editing.
 
-**Important**
+**Recommended Workflow:**
 
-To load existing content into the Page Builder, ensure that the formType is set to update in your configuration.
-This tells the builder to expect and load your provided components array as the initial content.
+1. **Parse your saved HTML** using the builder’s helper method to extract both the components and the global page settings:
 
-```vue
-<script setup>
-import { getPageBuilder } from '@myissue/vue-website-page-builder'
+   ```js
+   // yourPageHTML: the full HTML string previously saved from the builder
+   const { components, pageSettings } = pageBuilderService.parsePageBuilderHTML(yourPageHTML)
+   ```
 
-const configPageBuilder = {
-  updateOrCreate: {
-    formType: 'update',
-    formName: 'article',
-  },
-}
+2. **Pass `pageSettings` directly** in your config object, and pass the `components` array as the second argument to `startBuilder`:
 
-// Retrieve the Page Builder service instance
-const pageBuilderService = getPageBuilder()
+   ```vue
+   <script setup>
+   import { getPageBuilder } from '@myissue/vue-website-page-builder'
 
-// Load existing components into the builder (title is optional)
-const myArticle = [
-  { html_code: '<section>...</section>', title: 'Header H2' },
-  { html_code: '<section>...</section>', title: 'Text' },
-  { html_code: '<section>...</section>', title: 'Image' },
-]
+   // Retrieve the Page Builder service instance
+   const pageBuilderService = getPageBuilder()
 
-const result = await pageBuilderService.startBuilder(configPageBuilder, myArticle)
+   // Parse your saved HTML to extract both components and global page settings
+   const { components, pageSettings } = pageBuilderService.parsePageBuilderHTML(yourPageHTML)
 
-console.info('You may inspect this result for message, status, or error:', result)
-</script>
+   // Prepare the config, passing pageSettings directly
+   const configPageBuilder = {
+     updateOrCreate: {
+       formType: 'update', // important: set to update
+       formName: 'article',
+     },
+     // pass directly, not nested
+     pageSettings: pageSettings,
+   }
 
-<template>
-  <PageBuilder />
-</template>
-```
+   // Start the builder with both config and components
+   const result = await pageBuilderService.startBuilder(configPageBuilder, components)
 
-> **Note:**  
-> Each component’s `html_code` must be wrapped in a `<section>...</section>` tag.  
-> This is how the Page Builder defines and separates individual components.
+   console.info('You may inspect this result for message, status, or error:', result)
+   </script>
+
+   <template>
+     <PageBuilder />
+   </template>
+   ```
 
-This approach ensures your users can seamlessly load and edit previously published content, providing a smooth and reliable editing.
+> **Note:**
+>
+> - Each component’s `html_code` must be wrapped in a `<section>...</section>` tag. This is how the Page Builder defines and separates individual components.
+> - Always pass `pageSettings` directly in the config object (not as `{ pageSettings: { pageSettings } }`).
+> - Set `formType: 'update'` to ensure the builder loads your provided content for editing.
+
+This approach ensures your users can seamlessly restore and edit previously published content—including all global styles and layout—providing a smooth and reliable editing experience for existing pages.
 
 ## Automatic Draft Recovery
 
-The Page Builder automatically checks for unsaved drafts in local storage for the current resource.  
+The Page Builder automatically checks for unsaved drafts in local storage for the current resource.
 If a draft is found, users are prompted to either continue where they left off or use the version loaded from your backend.
 
-- **`formType` (required):**  
+- **`formType` (required):**
   Determines which draft to load from local storage. Set this to either `create` or `update` in the `updateOrCreate` config, depending on your use case.
-- **`formName` (required):**  
-  Specifies the resource type (e.g., `article`, `jobPost`, `store`, etc.) in the `updateOrCreate` config. This is especially important if your platform supports multiple resource types. By providing a unique name, the Page Builder can correctly manage layouts and drafts for each resource, allowing users to pick up where they left
+- **`formName` (required):**
+  Specifies the resource type (e.g., `article`, `jobPost`, `store`, etc.) in the `updateOrCreate` config. This is especially important if your platform supports multiple resource types. By providing a unique name, the Page Builder can correctly manage layouts and drafts for each resource, allowing users to pick up where they left off.
 
 ```vue
 <script setup>
@@ -494,7 +485,7 @@ console.info('You may inspect this result for message, status, or error:', resul
 
 ## Embedding Page Builder in a Modal or Dialog
 
-You can easily use the Page Builder inside a modal or dialog.  
+You can easily use the Page Builder inside a modal or dialog.
 To allow users to close the modal from inside the builder, use the `showCloseButton` prop and listen for the `@handleClosePageBuilder` event:
 
 ```vue
@@ -515,20 +506,52 @@ function closePageBuilder() {
 </template>
 ```
 
-- `:showCloseButton="true"` — shows a close button in the Page Builder toolbar.
-- `@handleClosePageBuilder="closePageBuilder"` — emits when the close button is clicked, so you can close your modal.
+## Publish Button
+
+To allow users to use the Publish button from inside the builder, use the `showPublishButton` prop and listen for the `@handlePublishPageBuilder` event.
+
+> **Note:**  
+> When the Publish button is clicked, the Page Builder will automatically save the latest changes to local storage before emitting the `@handlePublishPageBuilder` event. This ensures you always receive the most up-to-date content.
+
+```vue
+<script setup>
+import { getPageBuilder, PageBuilder } from '@myissue/vue-website-page-builder'
+
+const pageBuilderService = getPageBuilder()
+
+const handlePublish = () => {
+  // Retrieve the latest HTML content (saved by the builder)
+  const latestHtml = pageBuilderService.getSavedPageHtml()
+  // Submit, publish, or process the content as needed
+  // e.g., send latestHtml to your API or update your form
+}
+</script>
+
+<template>
+  <PageBuilder :showPublishButton="true" @handlePublishPageBuilder="handlePublish" />
+</template>
+```
+
+- `:showPublishButton="true"` — shows a publish button in the Page Builder toolbar.
+- `@handlePublishPageBuilder="handlePublish"` — emits after the builder auto-saves, so you always get the latest content.
 
 > **Tip:**  
-> You can name your handler function anything you like.  
+> You can name your handler function anything you like. This pattern makes it easy to embed the builder in modals, dialogs, or overlays in any Vue app.
+
+- `:showPublishButton="true"` — shows a publish button in the Page Builder toolbar.
+- `@handlePublishPageBuilder="yourMethod"` — emits when the close button is clicked, so you can close your modal.
+
+> **Tip:**
+> You can name your handler function anything you like.
 > This pattern makes it easy to embed the builder in modals, dialogs, or overlays in any Vue app.
 
 ## Styling the Main Page Builder Container
 
-The Page Builder allows you to define and update global styles for the main wrapper (#pagebuilder) at any time. These settings control the overall appearance, including font family, text color, background color, and more. Whether you set them initially in your config or update them dynamically at runtime, your changes are instantly reflected across all sections.
+The Page Builder allows you to define and update global styles for the main wrapper (`#pagebuilder`) at any time. These settings control the overall appearance, including font family, text color, background color, and more. Whether you set them initially in your config or update them dynamically at runtime, your changes are instantly reflected across all sections.
 
 Use the `pageSettings` config to apply custom CSS classes and inline styles to the Page Builder’s main wrapper.
-The Page Builder renders all components wrapped inside a single parent container `<div id="pagebuilder">`.  
-You can pass global CSS ``classes` and `style` to this wrapper by adding a `pageSettings` object in your config:
+The Page Builder renders all components wrapped inside a single parent container, `<div id="pagebuilder">`.
+You can pass global CSS `classes` and `style` to this wrapper by adding a `pageSettings` object in your config:
 
 ```ts
 const configPageBuilder = {
@@ -544,9 +567,9 @@ const configPageBuilder = {
 } as const
 ```
 
-You have full control over the page’s appearance at any time — instantly override or clear global styles for the entire page, ensuring a seamless and dynamic user experience.
+You have full control over the page’s appearance at any time—instantly override or clear global styles for the entire page, ensuring a seamless and dynamic user experience.
 
-## Download HTML file
+## Download HTML File
 
 Export the entire page as a standalone HTML file. This includes all sections, content, and applied styles, making the file ready for use or integration elsewhere.
 
@@ -556,9 +579,7 @@ To ensure images render properly after export, you must specify a URL prefix in
 
 ```ts
 const configPageBuilder = {
-  pageSettings: {
-    imageUrlPrefix: 'https://your-domain.com/uploads/',
-  },
+  imageUrlPrefix: 'https://your-domain.com/uploads/',
   // other config options...
 } as const
 ```
@@ -582,7 +603,7 @@ Learn how to create and integrate your own components step by step.
 ### Integrate Unsplash Library
 
 Easily add Unsplash image search to your media library modal—just like in the demo!
-Code example — You can copy-paste the provided example to get started.
+A code example is provided so you can copy-paste to get started.
 
 See the full step-by-step guide and working demo code here:
 📚 **[Unsplash Integration Guide](./UNSPLASH_INTEGRATION.md)**
@@ -600,7 +621,7 @@ Learn how to create and integrate your own components step by step.
 
 If fonts or Material Icons are not displaying correctly, verify that:
 
-**CSS Import**: Ensure you're importing the CSS file:
+**CSS Import**: You are importing the CSS file:
 
 ```js
 import '@myissue/vue-website-page-builder/style.css'
@@ -614,34 +635,34 @@ The Page Builder is designed as a modular, state-driven editor for dynamic page
 
 The Page Builder is designed to be easy to use and flexible for any web project. Here’s how it works behind the scenes:
 
-- **Configuration First:**  
-  When you start the builder, you pass in your configuration (such as what type of page you’re building, user info, branding, and any existing content).  
+- **Configuration First:**
+  When you start the builder, you pass in your configuration (such as what type of page you’re building, user info, branding, and any existing content).
   The builder saves this configuration immediately—even if the editing interface (DOM) isn’t loaded yet. This means you can safely set up the builder in advance, and it will be ready as soon as the editor appears on the page.
 
-- **Loading Content:**  
+- **Loading Content:**
   If you have existing content (like a published page), the builder loads it so you can keep editing. If not, you start with a blank page.
 
-- **Editing Experience:**  
+- **Editing Experience:**
   As you add, move, or edit components (like text, images, or sections), the builder keeps everything in sync—both in the app’s memory and in your browser’s local storage. This means your work is always saved, even if you close the browser.
 
-**In short:**  
+**In short:**
 The Page Builder handles all the technical details of editing, saving, and loading pages, so your users can focus on creating great content—without worrying about losing their work or dealing with complicated setup.
 
 <img style="max-width: 100%;" src="./public/home/page_builder_architecture.png" alt="Vue Website Page Builder - the editor" />
 
 ## Contributing
 
-1. Fork the repository
-2. Create your feature branch
-3. Make your changes
-4. Build and test locally
-5. Submit a pull request
+1. Fork the repository.
+2. Create your feature branch.
+3. Make your changes.
+4. Build and test locally.
+5. Submit a pull request.
 
 ## Security Vulnerabilities
 
 If you discover a security vulnerability, please send us a message.
 
-## Get in touch for customization or any questions
+## Get in Touch for Customization or Any Questions
 
 If you have any questions or if you're looking for customization, feel free to connect with our developer.
 
@@ -650,7 +671,7 @@ If you have any questions or if you're looking for customization, feel free to c
 
 ## Feedback
 
-Suggestions, or any issues you encounter while using this app. Feel free to reach out.
+Suggestions or any issues you encounter while using this app. Feel free to reach out.
 
 ## Support the Project