@myissue/vue-website-page-builder 3.2.91 → 3.2.93

package/README.md

@@ -15,6 +15,13 @@ Integration is easy, and content is safely auto stored in the browser's local st
 
 Want to include your company logo in the editor toolbar or reflect your brand's color scheme throughout the builder interface? Done. With robust configuration options, branding the builder to match your product or client identity is quick and effortless.
 
+## 🚀 Start Within Minutes
+
+Easy setup and instant productivity.  
+**Get up and running in just a few steps—see [Quick Start](#quick-start) below!**
+
+---
+
 ## Installation
 
 The web builder for stunning pages. Enable users to design and publish modern pages at any scale.
@@ -70,6 +77,7 @@ The Page Builder is packed with features:
 - **Undo & Redo**: Experiment confidently with the ability to revert changes.
 - **Global Styles**: Global Styles for fonts, designs, & colors.
 - **YouTube Videos**: Integrate video content smoothly.
+- **Tailwind Support**: Fully compatible with Tailwind CSS (with automatic class prefixing to avoid conflicts).
 - **Styles Prefixed**: 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.
@@ -111,14 +119,59 @@ bun install
 
 ### Quick Start
 
-Get up and running quickly and initializing the builder in your Vue project. The following example demonstrates the minimal setup required to start building pages.
+Get up and running quickly and initializing the builder in your Vue project. The following below code example demonstrates the minimal setup required to start building pages.
+
+- You must explicitly call initPageBuilder() once in your app entry (e.g. main.ts) before using any Page Builder features.
+
+- Then, use `getPageBuilder()` anywhere to access the shared builder instance.
 
-- The Page Builder requires its CSS file to be imported for proper styling and automatic icon loading:
+- Import the CSS file once, ideally in your `main.js`/`main.ts` or root component for proper styling and automatic icon loading..
+
+```typescript
+import { createApp } from 'vue'
+import { createPinia } from 'pinia'
+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
+initPageBuilder()
+
+const app = createApp(App)
+app.use(createPinia())
+app.mount('#app')
+```
+
+#### Accessing the Shared Page Builder Service
+
+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 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.
+
+**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.
+
+**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.
 
 ```vue
 <script setup>
-import { PageBuilder } from '@myissue/vue-website-page-builder'
+import { PageBuilder, getPageBuilder } from '@myissue/vue-website-page-builder'
 import '@myissue/vue-website-page-builder/style.css'
+
+const configPageBuilder = {
+  updateOrCreate: {
+    formType: 'create',
+    formName: 'article',
+  },
+}
+
+// Retrieve Page Builder service instance
+const pageBuilderService = getPageBuilder()
+
+await pageBuilderService.startBuilder(configPageBuilder)
 </script>
 
 <template>
@@ -128,17 +181,20 @@ import '@myissue/vue-website-page-builder/style.css'
 
 ### Important: CSS Import Required
 
-The Page Builder requires its CSS file to be imported for proper styling and automatic icon loading:
+The Page Builder requires its CSS file to be imported for proper styling and automatic icon loading.
 
-```js
+**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
-- ✅ Google Fonts (Jost, Cormorant - no additional setup needed)
-- ✅ Google Material Icons (no additional setup needed)
 - ✅ Responsive design utilities
 
 ### Important: CSS Prefix (`pbx-`) for All Builder Styles
@@ -171,24 +227,25 @@ The Page Builder automatically adds a `pbx-` prefix to **all CSS classes** it ge
 
 **When** you import the builder’s CSS file:
 
-```js
+```vue
+<script setup>
 import '@myissue/vue-website-page-builder/style.css'
+</script>
 ```
 
-- ✅ **All styles included in this file are already prefixed with `pbx-`**.
-- ✅ **All Tailwind and custom classes generated by the builder are automatically prefixed with `pbx-`**.
-- ✅ **Any custom components you create for the builder will also have their classes prefixed automatically**.
-
 **What does this mean for you?**
 
-- There is no risk of style conflicts between the builder and your app, since all builder-related styles are namespaced.
+- ✅ **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.**.
 
 ### Rendering Only the HTML Output from the Page Builder in Other Frameworks (React, Nuxt, etc.)
 
 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 Tailwind and builder-specific styles are applied to the rendered HTML.
 
-```js
+```vue
+<script setup>
 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.
@@ -205,8 +262,10 @@ function MyPage({ html }) {
 
 **Example (Nuxt/Vue):**
 
-```js
+```vue
+<script setup>
 import '@myissue/vue-website-page-builder/style.css'
+</script>
 ```
 
 Then use `v-html` to render the HTML.
@@ -223,6 +282,7 @@ Get up and running quickly by importing the PageBuilder component, setting up yo
   - `resourceData` to prefill the builder with initial data
   - `userSettings` to set user preferences such as theme, language, or autoSave
   - `brandColor` set brand’s primary color, which will be used for key UI elements in the builder in the `settings` config
+  - 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.
   - `formName` (recommended): 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.
   - Pass a `userForPageBuilder` object in your config to display or use the logged-in user's information within the builder (e.g., name and user image).
 
@@ -237,6 +297,7 @@ import '@myissue/vue-website-page-builder/style.css'
 
 const configPageBuilder = {
   updateOrCreate: {
+    formType: 'create'
     // Set the resource type for better local storage and multi-resource support
     formName: 'article',
   },
@@ -246,6 +307,7 @@ const configPageBuilder = {
   userForPageBuilder: { name: 'John Doe', image: '/jane_doe.jpg' },
   resourceData: {
     title: 'Demo Article',
+    // ID is optional for better local storage and multi-resource support
     id: 1,
   },
   userSettings: {
@@ -260,10 +322,10 @@ const configPageBuilder = {
 
 // Use sharedPageBuilderStore for shared state between PageBuilderClass and PageBuilder component
 const pageBuilderStateStore = sharedPageBuilderStore
-const pageBuilderClass = new PageBuilderClass(pageBuilderStateStore)
+const pageBuilderService.= new PageBuilderClass(pageBuilderStateStore)
+
 
-// Initializing with essential configuration
-pageBuilderClass.applyPageBuilderConfig(configPageBuilder)
+await pageBuilderService.startBuilder(configPageBuilder)
 </script>
 
 <template>
@@ -275,12 +337,12 @@ pageBuilderClass.applyPageBuilderConfig(configPageBuilder)
 
 You can display your company logo in the Page Builder interface and set the currently logged-in user by passing both a logo URL and user information in your config object:
 
-- **Company Logo:** Set the logo URL in your config object and pass it to the PageBuilder using `pageBuilderClass.applyPageBuilderConfig(configPageBuilder)`. When provided, the logo will appear at the top of the Page Builder with proper spacing in the toolbar.
+- **Company Logo:** Set the logo URL in your config object and pass it to the PageBuilder using `pageBuilderService.startBuilder(configPageBuilder)`. When provided, the logo will appear at the top of the Page Builder with proper spacing in the toolbar.
 - **Logged-in User:** Pass a `userForPageBuilder` object in your config to display or use the logged-in user's information within the builder (e.g., name and user image).
 
 **Basic Usage:**
 
-- You can display your company logo in the page builder interface by setting the `src` in your config object and passing it to the PageBuilder using `pageBuilderClass.applyPageBuilderConfig(configPageBuilder)`. When provided, the logo will appear in the top of the page builder.
+- You can display your company logo in the page builder interface by setting the `src` in your config object and passing it to the PageBuilder using `pageBuilderService.startBuilder(configPageBuilder)`. When provided, the logo will appear in the top of the page builder.
 
 Basic Usage:
 
@@ -302,10 +364,9 @@ const configPageBuilder = {
 
 // Use sharedPageBuilderStore for shared state between PageBuilderClass and PageBuilder component
 const pageBuilderStateStore = sharedPageBuilderStore
-const pageBuilderClass = new PageBuilderClass(pageBuilderStateStore)
+const pageBuilderService.= new PageBuilderClass(pageBuilderStateStore)
 
-// Initializing with essential configuration
-pageBuilderClass.applyPageBuilderConfig(configPageBuilder)
+await pageBuilderService.startBuilder(configPageBuilder)
 </script>
 
 <template>
@@ -347,7 +408,7 @@ const configPageBuilder = {
 
 Example Getting HTML Content from Local Storage for Form Submission
 
-```js
+```vue
 <script setup>
 import {
     PageBuilder,
@@ -356,9 +417,8 @@ import {
 } from "@myissue/vue-website-page-builder";
 import "@myissue/vue-website-page-builder/style.css";
 
-// Make sure to initialize these before using
 const pageBuilderStateStore = sharedPageBuilderStore;
-const pageBuilderClass = new PageBuilderClass(pageBuilderStateStore);
+const pageBuilderService.= new PageBuilderClass(pageBuilderStateStore);
 
 
 const configPageBuilder = {
@@ -368,10 +428,10 @@ const configPageBuilder = {
   },
 };
 
-pageBuilderClass.applyPageBuilderConfig(configPageBuilder);
+await pageBuilderService.startBuilder(configPageBuilder);
 
 
-let storedComponents = pageBuilderClass.loadStoredComponentsFromStorage();
+let storedComponents = pageBuilderService.loadStoredComponentsFromStorage();
 let contentFromPageBuilder = "";
 
 try {
@@ -398,7 +458,7 @@ After you have successfully created a new resource (such as a post, article, or
 
 Always call these methods after a successful post or resource creation to ensure users start with a fresh builder the next time they create a new resource.
 
-```js
+```vue
 <script setup>
 import {
     PageBuilder,
@@ -407,9 +467,8 @@ import {
 } from "@myissue/vue-website-page-builder";
 import "@myissue/vue-website-page-builder/style.css";
 
-// Make sure to initialize these before using
 const pageBuilderStateStore = sharedPageBuilderStore;
-const pageBuilderClass = new PageBuilderClass(pageBuilderStateStore);
+const pageBuilderService.= new PageBuilderClass(pageBuilderStateStore);
 
 
 const configPageBuilder = {
@@ -419,11 +478,11 @@ const configPageBuilder = {
   },
 };
 
-pageBuilderClass.applyPageBuilderConfig(configPageBuilder);
+await pageBuilderService.startBuilder(configPageBuilder);
 
 const createResource = async function(){
-pageBuilderClass.deleteAllComponents();
-await pageBuilderClass.removeItemComponentsLocalStorage();
+pageBuilderService.deleteAllComponents();
+await pageBuilderService.removeItemComponentsLocalStorage();
 };
 <script>
 ```
@@ -432,7 +491,7 @@ await pageBuilderClass.removeItemComponentsLocalStorage();
 
 After you have successfully updated an existing resource (such as a post, article, or listing) using the Page Builder with formType: 'update', you should clear the builder’s state and remove the corresponding local storage entry. This prevents outdated drafts from being loaded the next time you edit the same resource.
 
-```js
+```vue
 <script setup>
 import {
     PageBuilder,
@@ -441,9 +500,8 @@ import {
 } from "@myissue/vue-website-page-builder";
 import "@myissue/vue-website-page-builder/style.css";
 
-// Make sure to initialize these before using
 const pageBuilderStateStore = sharedPageBuilderStore;
-const pageBuilderClass = new PageBuilderClass(pageBuilderStateStore);
+const pageBuilderService.= new PageBuilderClass(pageBuilderStateStore);
 
 
 const configPageBuilder = {
@@ -453,11 +511,11 @@ const configPageBuilder = {
   },
 };
 
-pageBuilderClass.applyPageBuilderConfig(configPageBuilder);
+await pageBuilderService.startBuilder(configPageBuilder);
 
 const updateResource = async function() {
-  pageBuilderClass.deleteAllComponents();
-  await pageBuilderClass.removeItemComponentsLocalStorage();
+  pageBuilderService.deleteAllComponents();
+  await pageBuilderService.removeItemComponentsLocalStorage();
 };
 
 <script>
@@ -472,7 +530,7 @@ Each save is stored in local storage using a unique key. The key is determined b
 
 You can further customize and uniquely identify the storage key by providing a `formName` in your `configPageBuilder`:
 
-```js
+```vue
 <script setup>
 import {
   PageBuilder,
@@ -481,7 +539,6 @@ import {
 } from '@myissue/vue-website-page-builder'
 import '@myissue/vue-website-page-builder/style.css'
 
-
 const configPageBuilder = {
   updateOrCreate: {
     // Set the resource type for better local storage and multi-resource support
@@ -490,17 +547,14 @@ const configPageBuilder = {
   // ...other config options
 }
 
-const pageBuilderClass = new PageBuilderClass(pageBuilderStateStore)
+const pageBuilderService.= new PageBuilderClass(pageBuilderStateStore)
 
-// Initializing with essential configuration
-pageBuilderClass.applyPageBuilderConfig(configPageBuilder)
+await pageBuilderService.startBuilder(configPageBuilder)
 
 // Populating page builder with existing resource content
-pageBuilderClass.mountComponentsToDOM(existingResourceFromBackend)
+pageBuilderService.mountComponentsToDOM(existingResourceFromBackend)
 </script>
 
-
-
 <template>
   <PageBuilder />
 </template>
@@ -519,7 +573,7 @@ If a user started creating a new resource but hasn't finished (e.g., they want t
 
 **Example: Set `formType` to "create" for continuing a new resource draft**
 
-```js
+```vue
 <script setup>
 import {
   PageBuilder,
@@ -537,10 +591,9 @@ const configPageBuilder = {
   },
 }
 
-const pageBuilderClass = new PageBuilderClass(pageBuilderStateStore)
+const pageBuilderService.= new PageBuilderClass(pageBuilderStateStore)
 
-// Initializing with essential configuration
-pageBuilderClass.applyPageBuilderConfig(configPageBuilder)
+await pageBuilderService.startBuilder(configPageBuilder)
 </script>
 
 <template>
@@ -557,11 +610,11 @@ To load existing content that was created with this PageBuilder from any backend
 - Use `sharedPageBuilderStore` to ensure the external `PageBuilderClass` and internal `PageBuilder` component share the same state.
 - Import `PageBuilderClass` which contains all methods to manipulate and control the page builder state. Use the `mountComponentsToDOM()` method to load existing content into the page builder.
 - The `PageBuilderClass` uses the shared store to maintain state consistency between external operations and the internal `PageBuilder` component, ensuring that when you load content externally it appears correctly in the PageBuilder interface.
-- Set `formType` to `"update"` in your config object and pass it to the PageBuilder using `pageBuilderClass.applyPageBuilderConfig(configPageBuilder)`. This tells the PageBuilder that you're editing an existing resource rather than creating a new one, which affects how the component handles data and interactions.
+- Set `formType` to `"update"` in your config object and pass it to the PageBuilder using `pageBuilderService.startBuilder(configPageBuilder)`. This tells the PageBuilder that you're editing an existing resource rather than creating a new one, which affects how the component handles data and interactions.
 
 **Example: Set `formType` to "update" for editing an existing resource**
 
-```js
+```vue
 <script setup>
 import {
   PageBuilder,
@@ -579,7 +632,7 @@ const configPageBuilder = {
   },
 }
 
-const pageBuilderClass = new PageBuilderClass(pageBuilderStateStore)
+const pageBuilderService.= new PageBuilderClass(pageBuilderStateStore)
 
 // Saved content in DB from already created content using the Page Builder
 const existingResourceFromBackend = [
@@ -597,9 +650,8 @@ const existingResourceFromBackend = [
   },
 ]
 
-
 // Populating page builder with existing resource content from backend
-pageBuilderClass.mountComponentsToDOM(existingResourceFromBackend)
+pageBuilderService.mountComponentsToDOM(existingResourceFromBackend)
 </script>
 
 <template>
@@ -633,14 +685,14 @@ Example `existingResourceFromBackend`:
 
 ### Automatic Draft Recovery for Updates
 
-When you set `formType: 'update'` in your config, the Page Builder will automatically check for any unsaved draft in local storage for that resource.  
+When you set `formType: 'update'` in your config, the Page Builder will automatically check for any unsaved draft in local storage for that resource.
 If a draft is found, the user will be prompted to either continue where they left off or use the version currently loaded from your backend.
 
 - `formName` (recommended): 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.
   - Pass a `userForPageBuilder` object in your config to display or use the logged-in user's information within the builder (e.g., name and user image).
   - No extra setup is required—just set `formType: 'update'` and the feature is enabled by default.
 
-```js
+```vue
 <script setup>
 import {
   PageBuilder,
@@ -658,10 +710,9 @@ const configPageBuilder = {
   },
 }
 
-const pageBuilderClass = new PageBuilderClass(pageBuilderStateStore)
+const pageBuilderService.= new PageBuilderClass(pageBuilderStateStore)
 
-// Initializing with essential configuration
-pageBuilderClass.applyPageBuilderConfig(configPageBuilder)
+pageBuilderService.startBuilder(configPageBuilder)
 </script>
 
 <template>
@@ -693,30 +744,13 @@ import YourCustomBuilderComponents from './ComponentsPageBuilder/YourCustomBuild
 
 ### Fonts or Icons Not Displaying
 
-If fonts (Jost, Cormorant) or Material Icons are not displaying correctly, verify that:
-
-1. **CSS Import**: Ensure you're importing the CSS file:
-
-   ```js
-   import '@myissue/vue-website-page-builder/style.css'
-   ```
+If fonts or Material Icons are not displaying correctly, verify that:
 
-2. **Network Access**: The package loads fonts and icons from Google Fonts CDN. Ensure your application can access:
+**CSS Import**: Ensure you're importing the CSS file:
 
-   ```
-   https://fonts.googleapis.com/css2?family=Jost:*
-   https://fonts.googleapis.com/css2?family=Cormorant:*
-   https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined
-
-   ```
-
-3. **Content Security Policy**: If using CSP, allow Google Fonts:
-   ```html
-   <meta
-     http-equiv="Content-Security-Policy"
-     content="font-src 'self' https://fonts.googleapis.com;"
-   />
-   ```
+```js
+import '@myissue/vue-website-page-builder/style.css'
+```
 
 ## Contributing
 
@@ -748,3 +782,7 @@ We would greatly appreciate it if you could star the GitHub repository. Starring
 ## License
 
 [MIT License](./LICENSE)
+
+```
+
+```