vue2-bbl-editor 1.3.0

package/CONTENT_WRAPPER_GUIDE.md

@@ -0,0 +1,385 @@
+# Content Wrapper Guide
+
+This guide explains how to use the `bbl-html-section` wrapper functionality in both Options API and Composition API components.
+
+## Overview
+
+The vue2-premium-bbl-editor automatically wraps HTML output with the `bbl-html-section` class to ensure proper styling when using the CDN CSS. This makes it easy to render editor content in external projects with consistent styling.
+
+## Automatic Wrapping
+
+By default, HTML output is automatically wrapped with the `bbl-html-section` class:
+
+```javascript
+// Default behavior - content is wrapped
+const content = editor.getContent()
+// Returns: <div class="bbl-html-section"><p>Your content here</p></div>
+```
+
+## Options API Usage
+
+### Basic Usage
+
+```vue
+<template>
+  <div>
+    <PremiumBblEditorOptionsAPI 
+      v-model="content"
+      ref="editor"
+    />
+    
+    <div class="output-section">
+      <h3>Wrapped Output (Default)</h3>
+      <div v-html="wrappedContent"></div>
+      
+      <h3>Unwrapped Output</h3>
+      <div class="bbl-html-section" v-html="unwrappedContent"></div>
+    </div>
+  </div>
+</template>
+
+<script>
+import { PremiumBblEditorOptionsAPI } from 'vue2-premium-bbl-editor'
+
+export default {
+  components: {
+    PremiumBblEditorOptionsAPI
+  },
+  data() {
+    return {
+      content: '<p>Hello World!</p>'
+    }
+  },
+  computed: {
+    wrappedContent() {
+      // Automatically wrapped with bbl-html-section
+      return this.$refs.editor?.getContent() || ''
+    },
+    unwrappedContent() {
+      // Get content without wrapper
+      return this.$refs.editor?.getContent('html', false) || ''
+    }
+  }
+}
+</script>
+```
+
+### Disabling Auto-Wrap
+
+```vue
+<template>
+  <PremiumBblEditorOptionsAPI 
+    v-model="content"
+    :wrap-with-content-class="false"
+    ref="editor"
+  />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      content: '<p>Content without auto-wrap</p>'
+    }
+  },
+  methods: {
+    getContent() {
+      // Returns unwrapped content when wrap-with-content-class is false
+      return this.$refs.editor.getContent()
+    }
+  }
+}
+</script>
+```
+
+## Composition API Usage
+
+### Basic Usage
+
+```vue
+<template>
+  <div>
+    <PremiumBblEditor 
+      v-model="content"
+      ref="editor"
+    />
+    
+    <div class="output-section">
+      <h3>Wrapped Output (Default)</h3>
+      <div v-html="wrappedContent"></div>
+      
+      <h3>Unwrapped Output</h3>
+      <div class="bbl-html-section" v-html="unwrappedContent"></div>
+    </div>
+  </div>
+</template>
+
+<script>
+import { ref, computed } from '@vue/composition-api'
+import { PremiumBblEditor } from 'vue2-premium-bbl-editor'
+
+export default {
+  components: {
+    PremiumBblEditor
+  },
+  setup() {
+    const content = ref('<p>Hello World!</p>')
+    const editor = ref(null)
+    
+    const wrappedContent = computed(() => {
+      // Automatically wrapped with bbl-html-section
+      return editor.value?.getContent() || ''
+    })
+    
+    const unwrappedContent = computed(() => {
+      // Get content without wrapper
+      return editor.value?.getContent('html', false) || ''
+    })
+    
+    return {
+      content,
+      editor,
+      wrappedContent,
+      unwrappedContent
+    }
+  }
+}
+</script>
+```
+
+### Disabling Auto-Wrap
+
+```vue
+<template>
+  <PremiumBblEditor 
+    v-model="content"
+    :wrap-with-content-class="false"
+    ref="editor"
+  />
+</template>
+
+<script>
+import { ref } from '@vue/composition-api'
+import { PremiumBblEditor } from 'vue2-premium-bbl-editor'
+
+export default {
+  components: {
+    PremiumBblEditor
+  },
+  setup() {
+    const content = ref('<p>Content without auto-wrap</p>')
+    const editor = ref(null)
+    
+    const getContent = () => {
+      // Returns unwrapped content when wrap-with-content-class is false
+      return editor.value?.getContent()
+    }
+    
+    return {
+      content,
+      editor,
+      getContent
+    }
+  }
+}
+</script>
+```
+
+## Method Signatures
+
+### getContent Method
+
+Both components support the enhanced `getContent` method:
+
+```javascript
+// Get wrapped HTML (default)
+const wrappedHtml = editor.getContent()
+const wrappedHtml2 = editor.getContent('html')
+const wrappedHtml3 = editor.getContent('html', true)
+
+// Get unwrapped HTML
+const unwrappedHtml = editor.getContent('html', false)
+
+// Get JSON (wrapping doesn't apply to JSON)
+const jsonContent = editor.getContent('json')
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `wrapWithContentClass` | Boolean | `true` | Whether to automatically wrap HTML output with `bbl-html-section` class |
+
+## External Project Integration
+
+### React Example
+
+```jsx
+import React, { useState } from 'react';
+
+function BlogPost({ editorContent }) {
+  // Content is already wrapped with bbl-html-section from Vue editor
+  return (
+    <article>
+      <div dangerouslySetInnerHTML={{ __html: editorContent }} />
+    </article>
+  );
+}
+
+// Or if you have unwrapped content
+function BlogPostUnwrapped({ editorContent }) {
+  return (
+    <article>
+      <div 
+        className="bbl-html-section"
+        dangerouslySetInnerHTML={{ __html: editorContent }} 
+      />
+    </article>
+  );
+}
+```
+
+### Vue 3 Example
+
+```vue
+<template>
+  <article>
+    <!-- Content already wrapped -->
+    <div v-html="editorContent"></div>
+    
+    <!-- Or manually wrap unwrapped content -->
+    <div class="bbl-html-section" v-html="unwrappedContent"></div>
+  </article>
+</template>
+
+<script setup>
+defineProps({
+  editorContent: String,
+  unwrappedContent: String
+});
+</script>
+```
+
+### Angular Example
+
+```typescript
+@Component({
+  selector: 'app-blog-post',
+  template: `
+    <!-- Content already wrapped -->
+    <article [innerHTML]="editorContent"></article>
+    
+    <!-- Or manually wrap unwrapped content -->
+    <article>
+      <div class="bbl-html-section" [innerHTML]="unwrappedContent"></div>
+    </article>
+  `
+})
+export class BlogPostComponent {
+  @Input() editorContent: string = '';
+  @Input() unwrappedContent: string = '';
+}
+```
+
+## Best Practices
+
+### 1. Use Auto-Wrap for External Projects
+
+When content will be rendered in external projects, keep auto-wrap enabled:
+
+```javascript
+// Good - content ready for external use
+const content = editor.getContent() // Wrapped with bbl-html-section
+```
+
+### 2. Disable Auto-Wrap for Internal Processing
+
+When processing content internally or storing in database:
+
+```javascript
+// Good - clean content for storage
+const content = editor.getContent('html', false) // No wrapper
+```
+
+### 3. Consistent CDN Usage
+
+Always include the CDN CSS when rendering wrapped content:
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vue2-premium-bbl-editor/dist/editor-content.css" />
+```
+
+### 4. Manual Wrapping
+
+If you have unwrapped content, manually add the wrapper:
+
+```html
+<div class="bbl-html-section">
+  <!-- Your unwrapped content here -->
+</div>
+```
+
+## Migration Guide
+
+### From v1.2.x to v1.3.x
+
+The wrapper functionality is backward compatible. Existing code will continue to work, but HTML output will now be wrapped by default.
+
+**If you don't want wrapping:**
+
+```vue
+<!-- Add this prop to disable wrapping -->
+<PremiumBblEditor :wrap-with-content-class="false" />
+```
+
+**If you want to control wrapping programmatically:**
+
+```javascript
+// Old way (still works)
+const content = editor.getContent()
+
+// New way with explicit control
+const wrappedContent = editor.getContent('html', true)
+const unwrappedContent = editor.getContent('html', false)
+```
+
+## Troubleshooting
+
+### Content Not Styled Properly
+
+1. Ensure CDN CSS is loaded
+2. Check that content has `bbl-html-section` wrapper
+3. Verify no CSS conflicts
+
+### Double Wrapping
+
+If you see nested `bbl-html-section` divs:
+
+```javascript
+// Wrong - will create double wrapper
+const content = `<div class="bbl-html-section">${editor.getContent()}</div>`
+
+// Right - let editor handle wrapping
+const content = editor.getContent()
+
+// Or get unwrapped and wrap manually
+const content = `<div class="bbl-html-section">${editor.getContent('html', false)}</div>`
+```
+
+### TypeScript Support
+
+The wrapper functionality is fully typed:
+
+```typescript
+interface EditorMethods {
+  getContent(format?: 'html' | 'json', wrapContent?: boolean): string | object
+}
+```
+
+## Examples Repository
+
+For complete working examples, see:
+- [React Integration Example](examples/react-integration.md)
+- [Vue 3 Integration Example](examples/vue3-integration.md)
+- [Angular Integration Example](examples/angular-integration.md)
+- [Vanilla HTML Example](dist/cdn-demo.html)

package/EXTERNAL_HTML_RENDERING.md

@@ -0,0 +1,266 @@
+# External HTML Rendering Guide
+
+This guide shows how to use the vue2-premium-bbl-editor styles for rendering HTML content in external projects (React, Vue, Angular, vanilla HTML, etc.).
+
+## CDN Usage
+
+### Basic Setup
+
+Add the CDN link to your HTML head or import it in your project:
+
+```html
+<!-- Global CDN styles for HTML output rendering -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vue2-premium-bbl-editor/dist/editor-content.css" />
+```
+
+### Version-Agnostic URL
+
+The CDN URL automatically uses the latest version. If you need a specific version, you can pin it:
+
+```html
+<!-- Pinned to specific version (optional) -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vue2-premium-bbl-editor@1.3.0/dist/editor-content.css" />
+```
+
+## Usage in Different Frameworks
+
+### React
+
+```jsx
+import React from 'react';
+
+function EditorContent({ htmlContent }) {
+  return (
+    <div 
+      className="bbl-html-section"
+      dangerouslySetInnerHTML={{ __html: htmlContent }}
+    />
+  );
+}
+
+export default EditorContent;
+```
+
+### Vue 3
+
+```vue
+<template>
+  <div class="bbl-html-section" v-html="htmlContent"></div>
+</template>
+
+<script setup>
+defineProps({
+  htmlContent: {
+    type: String,
+    required: true
+  }
+});
+</script>
+```
+
+### Vue 2
+
+```vue
+<template>
+  <div class="bbl-html-section" v-html="htmlContent"></div>
+</template>
+
+<script>
+export default {
+  props: {
+    htmlContent: {
+      type: String,
+      required: true
+    }
+  }
+};
+</script>
+```
+
+### Angular
+
+```typescript
+// component.ts
+import { Component, Input } from '@angular/core';
+
+@Component({
+  selector: 'app-editor-content',
+  template: `<div class="bbl-html-section" [innerHTML]="htmlContent"></div>`
+})
+export class EditorContentComponent {
+  @Input() htmlContent: string = '';
+}
+```
+
+### Vanilla HTML/JavaScript
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vue2-premium-bbl-editor/dist/editor-content.css" />
+</head>
+<body>
+  <div id="content" class="bbl-html-section">
+    <!-- Your editor HTML content goes here -->
+  </div>
+
+  <script>
+    // Example: Load content dynamically
+    document.getElementById('content').innerHTML = yourEditorHtmlContent;
+  </script>
+</body>
+</html>
+```
+
+## CSS Classes Reference
+
+The CDN provides styles for the following content types:
+
+### Container Class
+- `.bbl-html-section` - Main container class for all editor content
+
+### Typography
+- `h1, h2, h3, h4, h5, h6` - Headings with proper spacing and sizing
+- `p` - Paragraphs with consistent margins
+- `strong` - Bold text
+- `em` - Italic text
+- `u` - Underlined text
+- `s` - Strikethrough text
+
+### Lists
+- `ul, ol` - Ordered and unordered lists
+- `li` - List items
+- `ul[data-type="taskList"]` - Task lists with checkboxes
+
+### Tables
+- `table` - Tables with borders and proper spacing
+- `th, td` - Table headers and cells
+- Responsive table styling for mobile devices
+
+### Media
+- `img` - Images with responsive sizing
+- `video` - Videos with responsive sizing
+- `.editor-image` - Specific editor image class
+
+### Code
+- `code` - Inline code with syntax highlighting
+- `pre` - Code blocks with dark theme
+- `pre code` - Code within pre blocks
+
+### Other Elements
+- `blockquote` - Styled blockquotes with left border
+- `hr` - Horizontal rules
+- `a, .editor-link` - Links with hover effects
+
+### Text Alignment
+- `.text-left` - Left-aligned text
+- `.text-center` - Center-aligned text
+- `.text-right` - Right-aligned text
+- `.text-justify` - Justified text
+
+## Example Implementation
+
+Here's a complete example for a React blog component:
+
+```jsx
+import React from 'react';
+
+function BlogPost({ title, content, author, date }) {
+  return (
+    <article>
+      <header>
+        <h1>{title}</h1>
+        <p>By {author} on {date}</p>
+      </header>
+      
+      {/* Editor content with proper styling */}
+      <div 
+        className="bbl-html-section"
+        dangerouslySetInnerHTML={{ __html: content }}
+      />
+    </article>
+  );
+}
+
+export default BlogPost;
+```
+
+## Security Considerations
+
+When rendering HTML content from the editor:
+
+1. **Sanitize HTML**: Always sanitize HTML content before rendering to prevent XSS attacks
+2. **Content Security Policy**: Implement proper CSP headers
+3. **Trusted Sources**: Only render content from trusted sources
+
+Example with DOMPurify (React):
+
+```jsx
+import DOMPurify from 'dompurify';
+
+function SafeEditorContent({ htmlContent }) {
+  const sanitizedContent = DOMPurify.sanitize(htmlContent);
+  
+  return (
+    <div 
+      className="bbl-html-section"
+      dangerouslySetInnerHTML={{ __html: sanitizedContent }}
+    />
+  );
+}
+```
+
+## Customization
+
+You can override the default styles by adding your own CSS after the CDN link:
+
+```css
+/* Custom overrides */
+.bbl-html-section {
+  font-family: 'Your Custom Font', sans-serif;
+}
+
+.bbl-html-section h1 {
+  color: #your-brand-color;
+}
+
+.bbl-html-section table {
+  border-color: #your-border-color;
+}
+```
+
+## Browser Support
+
+The CSS is compatible with:
+- Chrome 60+
+- Firefox 55+
+- Safari 12+
+- Edge 79+
+- Mobile browsers (iOS Safari, Chrome Mobile)
+
+## Performance Tips
+
+1. **CDN Caching**: The jsdelivr CDN provides excellent caching and global distribution
+2. **Preload**: Consider preloading the CSS for better performance:
+   ```html
+   <link rel="preload" href="https://cdn.jsdelivr.net/npm/vue2-premium-bbl-editor/dist/editor-content.css" as="style" onload="this.onload=null;this.rel='stylesheet'">
+   ```
+3. **Critical CSS**: For above-the-fold content, consider inlining critical styles
+
+## Troubleshooting
+
+### Styles Not Applied
+- Ensure the CDN link is in the `<head>` section
+- Check that the `.bbl-html-section` class is applied to the container
+- Verify there are no CSS conflicts with existing styles
+
+### Content Not Displaying Correctly
+- Check that the HTML structure matches the expected format
+- Ensure proper sanitization isn't removing necessary classes
+- Verify responsive viewport meta tag is present
+
+### Version Issues
+- Use the version-agnostic URL for automatic updates
+- Pin to a specific version if you need stability
+- Check the [changelog](CHANGELOG.md) for breaking changes between versions