@myissue/vue-website-page-builder 3.3.1 → 3.3.12

package/README.md

@@ -89,7 +89,7 @@ Powerful Page Builder for any growing merchants, brands, & agencies. Empower use
 
 ## Documentation
 
-### Requirements
+## Requirements
 
 Please note that these instructions assume you have Node.js installed.
 
@@ -97,7 +97,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:
 
@@ -115,15 +115,15 @@ yarn install
 bun install
 ```
 
-### Quick Start
+## Quick Start
 
-Grammar: Should be "Get up and running quickly by initializing the builder in your Vue project. The following code example demonstrates the minimal setup required to start building pages.
+### Initializing the Page Builder
 
-- You must explicitly call initPageBuilder() once in your app entry (e.g. main.ts) before using any Page Builder features.
+To get started with the Page Builder, follow these steps:
 
-- Then, use `getPageBuilder()` anywhere to access the shared builder instance.
-
-- Import the CSS file once, ideally in your `main.js`/`main.ts` or root component for proper styling and automatic icon loading.
+- **Call `initPageBuilder()` once** in your application entry point (e.g., `main.ts` or `main.js`). This sets up the shared builder instance for your entire app.
+- **Access the shared builder instance** anywhere in your application using the `getPageBuilder()` composable.
+- **Import the CSS file once** in your `main.js`, `main.ts`, or root component to ensure proper styling and automatic icon loading.
 
 ```typescript
 import { createApp } from 'vue'
@@ -131,26 +131,37 @@ import App from './App.vue'
 import { initPageBuilder } from '@myissue/vue-website-page-builder'
 import '@myissue/vue-website-page-builder/style.css'
 
-// Initialize shared builder instance
-// MUST be called once
+// Initialize the shared Page Builder instance
+// This must be called once in your app entry point
 initPageBuilder()
 
 const app = createApp(App)
 app.mount('#app')
 ```
 
-#### Accessing the Shared Page Builder Service
+> **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.
+
+### Accessing the Shared Page Builder Service
+
+After initializing the Page Builder service in your application (by calling `initPageBuilder()` once in your app entry point), you may access the shared instance from anywhere in your application using the `getPageBuilder()` composable.
+
+> **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.
 
-Once you have initialized the Page Builder service in your application (by calling `initPageBuilder()` once in your app entry), you can access the shared instance anywhere by using the `getPageBuilder()` composable. This ensures you are always working with the same underlying builder service and state, keeping your application consistent and synchronized.
+#### Why Use the Shared Instance?
 
-**Why Access the Shared Instance?**
-The Page Builder is implemented as a singleton service. This means there is only one instance that manages all page-building logic and state across your app. Using this shared instance avoids creating multiple, isolated copies of the builder, which can lead to data inconsistencies, synchronization issues, and unpredictable behavior.
+By always accessing the shared instance, you avoid creating multiple, isolated copies of the builder. This prevents data inconsistencies, synchronization issues, and unpredictable behavior. All components and modules interact with the same centralized service, ensuring that updates and state changes are reflected everywhere in your application.
 
-**There’s only one source of truth:**  
-By accessing the shared instance, your components and modules interact with the same centralized service, allowing smooth and reliable updates and coordination. This guarantees that all builder actions and state changes are reflected everywhere in your app.
+#### Usage
 
-**How to Use the Shared Instance**
-Whenever you need to interact with the Page Builder service, import and call the `getPageBuilder()` function. This will return the existing instance you initialized earlier — no need to create a new one.
+Ensure the following configuration options are set:
+
+- **`formType` (required):**  
+  Indicates whether you are creating or updating a resource. This is used to retrieve the correct content from local storage.
+
+- **`formName` (required):**  
+  Specifies the resource type (for example, `article`, `jobPost`, `store`, etc.). This is essential for platforms supporting multiple resource types, as it enables the builder to manage layouts and local storage for each resource uniquely.
 
 ```vue
 <script setup>
@@ -164,9 +175,10 @@ const configPageBuilder = {
   },
 }
 
-// Retrieve Page Builder service instance
 const pageBuilderService = getPageBuilder()
-await pageBuilderService.startBuilder(configPageBuilder)
+const result = await pageBuilderService.startBuilder(configPageBuilder)
+
+console.log('You may inspect this result for message, status, or error:', result)
 </script>
 
 <template>
@@ -174,76 +186,42 @@ await pageBuilderService.startBuilder(configPageBuilder)
 </template>
 ```
 
-### Important: CSS Import Required
-
-The Page Builder requires its CSS file to be imported for proper styling and automatic icon loading.
-
-**You only need to import the CSS file once, ideally in your `main.js`/`main.ts` or root component.**  
-If you have already imported it in your app entry, you do not need to import it again in individual components.
-
-```vue
-<script setup>
-import '@myissue/vue-website-page-builder/style.css'
-</script>
-```
-
-This import automatically includes:
-
-- ✅ Page Builder styles
-- ✅ Responsive design utilities
-
-### Important: CSS Prefix (`pbx-`) for All Builder Styles
-
-The Page Builder automatically adds a `pbx-` prefix to **all CSS classes** it generates or processes, including Tailwind utility classes and any custom classes you add through the builder interface. This namespacing ensures that the builder’s styles will **not conflict** with your application's existing CSS or Tailwind classes.
+## Important: CSS Prefixing (`pbx-`)
 
-**What does this mean for you?**
+All CSS classes generated or processed by the Page Builder—including Tailwind utilities and your custom classes—are automatically prefixed with `pbx-`. This ensures the builder’s styles never conflict with your app’s existing CSS or Tailwind setup.
 
-- If you create your own custom components to use with the Page Builder (instead of the default ones), **remember that the builder will automatically add the `pbx-` prefix to every CSS class** in your component’s markup. This applies to both Tailwind utility classes and any custom classes you define.
-- For example, if you use a custom class called `myCustomCSSClass` in your component, it will be rendered as `pbx-myCustomCSSClass` in the final HTML output.
-- All Tailwind classes are also prefixed, e.g. `bg-red-100` becomes `pbx-bg-red-100`, `md:grid-cols-2` becomes `md:pbx-grid-cols-2`, etc.
+**How does this affect you?**
 
-**Why is this important?**
-
-- The prefixing is done automatically by the builder to avoid style conflicts between the builder’s output and your own app’s CSS or Tailwind setup.
+- Any class you use in builder components will be output as `pbx-ClassName`.
+- Tailwind classes are also prefixed, e.g. `bg-red-100` becomes `pbx-bg-red-100`, `md:grid-cols-2` becomes `md:pbx-grid-cols-2`.
 
 **Example:**
 
 ```html
-<!-- Builder output -->
 <div class="pbx-myCustomCSSClass pbx-bg-blue-100 md:pbx-grid-cols-2"></div>
 ```
 
 ```css
-/* To style this element, use the pbx- prefix */
 .pbx-myCustomCSSClass {
   margin-bottom: 2rem;
 }
 ```
 
-**When** you import the builder’s CSS file:
-
-```vue
-<script setup>
-import '@myissue/vue-website-page-builder/style.css'
-</script>
-```
+> **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
 
-**What does this mean for you?**
+## Rendering HTML Output in Other Frameworks (React, Nuxt, etc.)
 
-- ✅ **All Tailwind and custom CSS classes in this file prefixed with `pbx-` to prevent style conflicts.**.
-- ✅ **There is no risk of style conflicts between the builder and your app, since all builder-related styles are namespaced.**.
+You can use the Page Builder to generate HTML and render it in any frontend framework, such as React, Nuxt, or even server-side apps.
 
-### Rendering Only the HTML Output from the Page Builder in Other Frameworks (React, Nuxt, etc.)
+To ensure your content is styled correctly, simply install the Page Builder package in your target project and import its CSS file. All builder and Tailwind-prefixed styles will be applied automatically.
 
-If you use the Page Builder to generate HTML pages and want to render them in another application (such as React, Nuxt, or any server-side app), simply install the Page Builder package in your target project and import its CSS file. This ensures that all prefix Tailwind and builder-specific styles are applied to the rendered HTML.
-
-```vue
-<script setup>
+```js
+// Import the builder's CSS file once in your project
 import '@myissue/vue-website-page-builder/style.css'
-</script>
 ```
 
-This will apply all the necessary styles to any HTML output from the builder, even if you render it with `dangerouslySetInnerHTML`, `v-html`, or similar methods.
+This will apply all necessary styles to any HTML output from the builder, even if you render it with `dangerouslySetInnerHTML`, `v-html`, or similar methods.
 
 **Example (React):**
 
@@ -265,20 +243,29 @@ import '@myissue/vue-website-page-builder/style.css'
 
 Then use `v-html` to render the HTML.
 
-> **Note:** You do not need to import any Vue components if you only want to render the HTML. Just import the CSS file.
+> **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
 
-### Provide Config to PageBuilder
+The example below demonstrates the setup to start building pages, with additional options available for customization and branding.
 
-Get up and running quickly by importing the PageBuilder component, setting up your configuration, and initializing the builder in your Vue project. The following example demonstrates the minimal setup required to start building pages with your own config and logo.
+Your `configPageBuilder` object can include:
 
-- Provide a `configPageBuilder` object to customize the builder, such as:
-  - `formType` (required): Used to retrieve the correct content from local storage. Specify whether you are creating or updating a resource by setting this to `create` or `update` in the `updateOrCreate` config.
-  - `formName` (required): Specify the resource type (e.g., `"article"`, `"jobPost"`, `"store"`, etc.) in the `updateOrCreate` config. This is especially useful if your platform supports multiple resource types. By providing a unique name, the Page Builder can correctly manage layouts and local storage for each resource type, allowing users to continue where they left off for different resources.
-  - `resourceData` (optional): Prefill the builder with initial resource data (e.g., `"title"`, `"id"`).
-  - `userForPageBuilder` (optional): Pass an object with user information (e.g., `name` and `image`) in your config to display the logged-in user's details within the builder interface.
-  - `pageBuilderLogo` (optional): Display your company logo in the builder toolbar.
-  - `userSettings` (optional): Set user preferences such as theme, language, or autoSave.
-  - `brandColor` (optional): Set your brand’s primary color for key UI elements in the builder (inside the `settings` config).
+- **`formType` (required):**  
+  Used to retrieve the correct content from local storage. Specify whether you are creating or updating a resource.
+- **`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):**  
+  Prefill the builder with initial resource data (e.g., `title`, `id`).
+- **`userForPageBuilder` (optional):**  
+  Pass user information (such as `name` and `image`) to display the logged-in user’s details in the builder.
+- **`pageBuilderLogo` (optional):**  
+  Display your company logo in the builder toolbar.
+- **`userSettings` (optional):**  
+  Set user preferences such as theme, language, or auto-save.
+- **`brandColor` (optional):**  
+  Set your brand’s primary color for key UI elements (inside the `settings` config).
 
 ```vue
 <script setup>
@@ -310,7 +297,9 @@ const configPageBuilder = {
 
 // Retrieve Page Builder service instance
 const pageBuilderService = getPageBuilder()
-await pageBuilderService.startBuilder(configPageBuilder)
+const result = await pageBuilderService.startBuilder(configPageBuilder)
+
+console.log('You may inspect this result for message, status, or error:', result)
 </script>
 
 <template>
@@ -318,23 +307,20 @@ await pageBuilderService.startBuilder(configPageBuilder)
 </template>
 ```
 
-### Local Storage & Auto-Save
-
-The Page Builder automatically manages all changes using the browser's local storage. Every change you make—such as adding, editing, or deleting components—is saved in local storage. This ensures your progress is not lost, even if you accidentally close the browser or navigate away.
+## Local Storage & Auto-Save
 
-- **Auto-Save:** The builder periodically auto-saves your changes to local storage, so you don't have to worry about losing your work.
-- **Manual Save:** When the user clicks the Save button, the current state is also saved to local storage.
+The Page Builder automatically saves all changes to the browser’s local storage. Every time you add, edit, or delete a component, your progress is preserved—even if you close the browser or navigate away.
 
-#### Example: Retrieving the Most Up-to-Date HTML Content for Form Submission
+- **Auto-Save:** Changes are periodically saved as you work.
+- **Manual Save:** Clicking the Save button also stores the current state.
 
-The Page Builder uses auto-save, so the data you retrieve from local storage always reflects the latest state of the builder—what the user currently sees in the editor. This means you are getting the most up-to-date content, saved live as the user edits.
+## Retrieving the Latest HTML Content for Form Submission
 
-To use the builder’s saved data in your form submission, you may want both the combined HTML content and the titles of each component. The `PageBuilderClass` provides a method to access the latest saved state from local storage. The example below demonstrates how to retrieve and parse this data, combining all component HTML into a single string and collecting all titles into an array. This is useful if you want to display or store both the rendered content and the structure or headings of your page.
+The builder’s auto-save ensures that the data in local storage always reflects the latest state of your page. You can retrieve this data at any time for form submission, publishing, or preview.
 
-**Important:**  
-To retrieve the correct content from local storage, you must pass the same `resourceData` (such as `formType` and `formName`) to the Page Builder that was used when the content was originally saved. If the resource data does not match, the Page Builder will look for a different local storage key and may not find the expected content.
+To get the most up-to-date content, use the same `resourceData` (such as `formType` and `formName`) that was used when saving. If these values do not match, the builder may not find the expected content.
 
-Example:
+**Example:**
 
 ```js
 const configPageBuilder = {
@@ -345,7 +331,7 @@ const configPageBuilder = {
 }
 ```
 
-Call this logic when you want to submit or save the builder’s output, for example, when the user clicks a “Save” or “Publish” button. The code safely parses the local storage data, handles errors, and assigns the results to your form fields.
+Call this logic when you need to submit or save the builder’s output—for example, when the user clicks “Save” or “Publish.” The code below safely retrieves and parses the latest data from local storage, handling errors and assigning the results to your form fields.
 
 ```vue
 <script setup>
@@ -380,7 +366,7 @@ try {
 </script>
 ```
 
-#### Resetting the Builder After Successful Resource Creation or Update
+### 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.
 
@@ -388,25 +374,29 @@ You can reset the builder state and clear the draft with:
 
 ```js
 // Delete the HTML from the Live DOM
-pageBuilderService.deleteAllComponents()
+pageBuilderService.deleteAllComponentsFromDOM()
 // Clear Local Storage for the created or updated resource
-await pageBuilderService.removeItemComponentsLocalStorage()
+await pageBuilderService.removeCurrentComponentsFromLocalStorage()
 ```
 
 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.
 
-### Loading Published Content from the Backend 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.
 
-You can easily load existing content—created with this Page Builder—from any backend source.
+The `startBuilder` method accepts two arguments:
 
-- **Set `formType` (required):** This tells the builder to look for the correct content in local storage. Set `formType` to `update`.
-- **Set `formName` (required):** Specify the resource type (for example, `"article"`, `"jobPost"`, `"store"`, etc.) in the `updateOrCreate` config.
-- Even when loading an existing resource, these values are important if your platform supports multiple resource types. By providing a unique name, the Page Builder can properly manage layouts and local storage for the resource, allowing users to pick up right where they left off.
+1. **Configuration** (required):  
+   The builder configuration object.
+2. **Components Data** (optional):  
+   An object containing existing components. This is especially useful when loading previously published or saved content into the builder.
+
+If you provide the second argument, it must be an object with a `components` property, which is an array of objects. Each object must include a `html_code` string and may optionally include a `title` string.
 
 ```vue
 <script setup>
 import { getPageBuilder } from '@myissue/vue-website-page-builder'
-import html from './html.json'
 
 const configPageBuilder = {
   updateOrCreate: {
@@ -415,12 +405,21 @@ const configPageBuilder = {
   },
 }
 
-// Retrieve Page Builder service instance
+// Retrieve the Page Builder service instance
 const pageBuilderService = getPageBuilder()
-await pageBuilderService.startBuilder(configPageBuilder)
 
-// Load content from your backend or a JSON file into the Page Buildder
-await pageBuilderService.mountComponentsToDOM(JSON.stringify(html))
+// Load existing components into the builder (title is optional)
+const myArticle = {
+  components: [
+    { html_code: '<section>...</section>', title: 'Header H2' },
+    { html_code: '<section>...</section>', title: 'Text' },
+    { html_code: '<section>...</section>', title: 'Image' },
+  ],
+}
+
+const result = await pageBuilderService.startBuilder(configPageBuilder, myArticle)
+
+console.log('You may inspect this result for message, status, or error:', result)
 </script>
 
 <template>
@@ -428,34 +427,34 @@ await pageBuilderService.mountComponentsToDOM(JSON.stringify(html))
 </template>
 ```
 
-**Note:**  
-Your `html.json` file should contain an array of component objects, each with a `html_code` and `title` (optional) property, as shown below:
-
-```json
-{
-  "components": [
-    {
-      "html_code": "<section><div class=\"relative py-4\"><div class=\"mx-auto max-w-7xl lg:px-4 px-2\"><div class=\"pbx-break-words pbx-text-5xl\"><h2><strong>Demo Content</strong></h2></div></div></div></section>",
-      "title": "Header H2"
-    },
-    {
-      "html_code": "<section>...</section>",
-      "title": "Text"
-    }
-    // ...more components
-  ]
-}
-```
-
-This approach ensures your users can seamlessly load and edit previously published content, providing a smooth and reliable editing experience.
-
-### Automatic Draft Recovery
-
-The Page Builder automatically checks for any unsaved drafts in local storage for the current resource.  
-If a draft is found, users will be prompted to either continue where they left off or use the version currently loaded from your backend.
-
-- **`formType` (required):** Used to retrieve the correct content from local storage. Set this to either `create` or `update` in the `updateOrCreate` config, depending on your use case.
-- **`formName` (required):** Specify the resource type (e.g., `"article"`, `"jobPost"`, `"store"`, etc.) in the `updateOrCreate` config. This is especially useful if your platform supports multiple resource types. By providing a unique name, the Page Builder can correctly manage layouts and local storage for each resource type, allowing users to continue where they left off for different resources.
+> **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.
+>
+> **Example:**
+>
+> ```json
+> {
+>   "components": [
+>     {
+>       "html_code": "<section><div>My content</div></section>",
+>       "title": "Header"
+>     }
+>   ]
+> }
+> ```
+
+This approach ensures your users can seamlessly load and edit previously published content, providing a smooth and reliable editing.
+
+## Automatic Draft Recovery
+
+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):**  
+  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
 
 ```vue
 <script setup>
@@ -468,9 +467,9 @@ const configPageBuilder = {
   },
 }
 
-// Retrieve Page Builder service instance
-const pageBuilderService = getPageBuilder()
-await pageBuilderService.startBuilder(configPageBuilder)
+const result = await pageBuilderService.startBuilder(configPageBuilder)
+
+console.log('You may inspect this result for message, status, or error:', result)
 </script>
 
 <template>