# Vue2 Premium BBL Editor - Complete Package Documentation

This document provides comprehensive documentation for all components, features, and APIs included in the Vue2 Premium BBL Editor package.

## Table of Contents

1. [Package Overview](#package-overview)
2. [Installation & Setup](#installation--setup)
3. [Main Components](#main-components)
4. [Toolbar Components](#toolbar-components)
5. [Menu Components](#menu-components)
6. [Modal Components](#modal-components)
7. [Upload System](#upload-system)
8. [Development Tools](#development-tools)
9. [Extensions](#extensions)
10. [Composables](#composables)
11. [TypeScript Support](#typescript-support)
12. [Styling & Theming](#styling--theming)
13. [Configuration Reference](#configuration-reference)
14. [Event Reference](#event-reference)
15. [Method Reference](#method-reference)
16. [Best Practices](#best-practices)
17. [Troubleshooting](#troubleshooting)

## Package Overview

The Vue2 Premium BBL Editor is a comprehensive rich text editing solution for Vue 2.6+ applications. It provides:

- **Full-featured WYSIWYG editor** with extensive formatting options
- **Advanced media handling** with resizable images and videos
- **Comprehensive upload system** with multiple adapter support
- **Smart table editing** with interactive controls
- **Multiple themes** and extensive customization options
- **TypeScript support** with complete type definitions
- **Development tools** for debugging and diagnostics
- **External project integration** capabilities

### Key Features

- ✅ Vue 2.6+ compatible with Composition API support
- ✅ Production-ready with comprehensive error handling
- ✅ Modular architecture with individual component exports
- ✅ Advanced upload management with retry logic and progress tracking
- ✅ Accessibility compliant (WCAG guidelines)
- ✅ Mobile responsive design
- ✅ Auto-save functionality
- ✅ Source code editing mode
- ✅ Extensive customization options

## Installation & Setup

### Basic Installation

```bash
npm install vue2-premium-bbl-editor
```

### Required Dependencies

```bash
npm install @vue/composition-api @tiptap/core @tiptap/vue-2 @tiptap/starter-kit @tiptap/extension-text-style @tiptap/extension-color @tiptap/extension-highlight @tiptap/extension-underline @tiptap/extension-text-align @tiptap/extension-link @tiptap/extension-font-family @tiptap/extension-code @tiptap/extension-code-block @tiptap/extension-table @tiptap/extension-table-row @tiptap/extension-table-cell @tiptap/extension-table-header @tiptap/extension-task-list @tiptap/extension-task-item @tiptap/extension-placeholder
```

### Quick Setup

```javascript
// main.js
import Vue from 'vue'
import PremiumBblEditor from 'vue2-premium-bbl-editor'

// Register globally
Vue.use(PremiumBblEditor)

// Or register with options
Vue.use(PremiumBblEditor, {
  registerAllComponents: true
})
```

## Main Components

### PremiumBblEditor

The primary editor component using Composition API.

**Import:**
```javascript
import { PremiumBblEditor } from 'vue2-premium-bbl-editor'
```

**Basic Usage:**
```vue
<template>
  <PremiumBblEditor
    v-model="content"
    placeholder="Start writing..."
    @ready="handleReady"
  />
</template>
```

### PremiumBblEditorOptionsAPI

The same editor component using pure Vue 2 Options API.

**Import:**
```javascript
import { PremiumBblEditorOptionsAPI } from 'vue2-premium-bbl-editor'
```

**Basic Usage:**
```vue
<template>
  <PremiumBblEditorOptionsAPI
    v-model="content"
    placeholder="Start writing..."
    @ready="handleReady"
  />
</template>
```

**Complete Options API Example:**
```vue
<template>
  <PremiumBblEditorOptionsAPI
    v-model="content"
    :placeholder="placeholder"
    :theme="theme"
    :toolbar-config="toolbarConfig"
    :extension-config="extensionConfig"
    :upload-handler="uploadHandler"
    :auto-save="autoSave"
    :auto-save-interval="autoSaveInterval"
    :max-height="maxHeight"
    :min-height="minHeight"
    :font-families="fontFamilies"
    :font-sizes="fontSizes"
    :show-toolbar="showToolbar"
    :show-bubble-menu="showBubbleMenu"
    :editor-class="editorClass"
    :toolbar-class="toolbarClass"
    :content-class="contentClass"
    @input="handleInput"
    @ready="handleReady"
    @focus="handleFocus"
    @blur="handleBlur"
    @auto-save="handleAutoSave"
    @error="handleError"
  />
</template>

<script>
import { PremiumBblEditorOptionsAPI } from 'vue2-premium-bbl-editor'

export default {
  components: {
    PremiumBblEditorOptionsAPI
  },
  
  data() {
    return {
      content: '<p>Options API Editor</p>',
      placeholder: 'Start writing with Options API...',
      theme: 'default',
      autoSave: true,
      autoSaveInterval: 30000,
      maxHeight: 500,
      minHeight: 200,
      showToolbar: true,
      showBubbleMenu: true,
      
      toolbarConfig: {
        bold: true,
        italic: true,
        underline: true,
        textColor: true,
        highlight: true,
        fontFamily: true,
        fontSize: true,
        headings: true,
        lists: true,
        link: true,
        image: true,
        video: true,
        table: true
      },
      
      extensionConfig: {
        image: {
          allowResize: true,
          allowAlignment: true,
          maxWidth: '100%'
        },
        table: {
          resizable: true,
          cellSelection: true
        }
      },
      
      fontFamilies: ['Inter', 'Arial', 'Georgia'],
      fontSizes: ['14px', '16px', '18px', '20px'],
      
      editorClass: 'my-editor',
      toolbarClass: 'my-toolbar',
      contentClass: 'my-content'
    }
  },
  
  methods: {
    handleInput(content) {
      console.log('Content changed:', content)
    },
    
    handleReady(editor) {
      console.log('Options API Editor ready:', editor)
      this.editorInstance = editor
    },
    
    handleFocus() {
      console.log('Editor focused')
    },
    
    handleBlur() {
      console.log('Editor blurred')
    },
    
    handleAutoSave(content) {
      console.log('Auto-saving...')
      this.saveToServer(content)
    },
    
    handleError(error) {
      console.error('Editor error:', error)
    },
    
    async uploadHandler(file) {
      const formData = new FormData()
      formData.append('file', file)
      
      const response = await fetch('/api/upload', {
        method: 'POST',
        body: formData
      })
      
      const data = await response.json()
      return { src: data.url, alt: file.name }
    },
    
    async saveToServer(content) {
      try {
        await fetch('/api/save', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ content })
        })
      } catch (error) {
        console.error('Save failed:', error)
      }
    }
  }
}
</script>
```

**Props:**
- `value` (String): Editor content (v-model)
- `placeholder` (String): Placeholder text
- `editable` (Boolean): Whether content can be edited
- `theme` (String): Theme name ('default', 'minimal', 'dark')
- `toolbarConfig` (Object): Toolbar button configuration
- `extensionConfig` (Object): Extension behavior configuration
- `uploadHandler` (Function): Custom upload handler
- `autoSave` (Boolean): Enable auto-save
- `autoSaveInterval` (Number): Auto-save interval in milliseconds
- `maxHeight` (String|Number): Maximum editor height
- `minHeight` (String|Number): Minimum editor height
- `showToolbar` (Boolean): Show/hide toolbar
- `showBubbleMenu` (Boolean): Show/hide bubble menu

**Local File Base64 Management:**
- `useBase64Upload` (Boolean): Force base64 conversion even when upload URLs are provided
- `base64Quality` (Number): Image compression quality (0.1 - 1.0)
- `base64MaxWidth` (Number): Maximum width for compressed images (px)
- `base64MaxHeight` (Number): Maximum height for compressed images (px)
- `enableImageCompression` (Boolean): Enable automatic image compression
- `preserveOriginalFileName` (Boolean): Preserve original file names in alt text
- `base64Prefix` (String): Custom prefix for base64 data URLs
- And many more...

**Events:**
- `@input`: Content changed (v-model)
- `@ready`: Editor ready for use
- `@focus`: Editor gained focus
- `@blur`: Editor lost focus
- `@auto-save`: Auto-save triggered
- `@image-compressed`: Image compression completed with statistics
- `@error`: Error occurred

**Methods:**
- `focus()`: Focus the editor
- `blur()`: Blur the editor
- `getContent(format)`: Get editor content
- `setContent(content)`: Set editor content
- `executeCommand(command, options)`: Execute editor command

### PremiumBblEditorOptionsAPI

The same editor component using Vue 2 Options API.

**Import:**
```javascript
import { PremiumBblEditorOptionsAPI } from 'vue2-premium-bbl-editor'
```

**Usage:**
```vue
<template>
  <PremiumBblEditorOptionsAPI
    v-model="content"
    :toolbar-config="toolbarConfig"
    @ready="handleReady"
  />
</template>
```

Same props, events, and methods as PremiumBblEditor.

## Toolbar Components

### ToolbarMain

Complete toolbar with all formatting options.

**Import:**
```javascript
import { ToolbarMain } from 'vue2-premium-bbl-editor'
```

**Usage:**
```vue
<template>
  <ToolbarMain
    :editor="editor"
    :config="toolbarConfig"
    :font-families="fontFamilies"
    :font-sizes="fontSizes"
    @execute-command="executeCommand"
  />
</template>
```

**Props:**
- `editor` (Object): TipTap editor instance
- `config` (Object): Toolbar configuration
- `fontFamilies` (Array): Available font families
- `fontSizes` (Array): Available font sizes
- `lineHeights` (Array): Available line heights
- `allowedHeadings` (Array): Allowed heading levels
- `sourceCodeMode` (Boolean): Source code mode state

**Events:**
- `@execute-command`: Execute editor command
- `@insert-link`: Insert link request
- `@insert-image`: Insert image request
- `@insert-video`: Insert video request
- `@clear-formatting`: Clear formatting request
- `@toggle-source-code`: Toggle source code mode

### ToolbarGroup

Container for grouping related toolbar buttons.

**Import:**
```javascript
import { ToolbarGroup } from 'vue2-premium-bbl-editor'
```

**Usage:**
```vue
<template>
  <ToolbarGroup label="Text Formatting">
    <ToolbarButton ... />
    <ToolbarButton ... />
  </ToolbarGroup>
</template>
```

**Props:**
- `label` (String): Group label for accessibility

### ToolbarButton

Individual toolbar button component.

**Import:**
```javascript
import { ToolbarButton } from 'vue2-premium-bbl-editor'
```

**Usage:**
```vue
<template>
  <ToolbarButton
    :editor="editor"
    command="toggleBold"
    icon="B"
    tooltip="Bold"
    :is-active="editor && editor.isActive('bold')"
    @click="handleClick"
  />
</template>
```

**Props:**
- `editor` (Object): TipTap editor instance
- `command` (String): Command to execute
- `icon` (String): Button icon text/HTML
- `tooltip` (String): Tooltip text
- `isActive` (Boolean): Whether button is active
- `isDropdown` (Boolean): Whether button has dropdown
- `disabled` (Boolean): Whether button is disabled

**Events:**
- `@click`: Button clicked

**Slots:**
- `#icon`: Custom icon content
- `#dropdown`: Dropdown content

## Menu Components

### EditorBubbleMenu

Text selection bubble menu.

**Import:**
```javascript
import { EditorBubbleMenu } from 'vue2-premium-bbl-editor'
```

**Usage:**
```vue
<template>
  <EditorBubbleMenu
    :editor="editor"
    :config="bubbleConfig"
    @execute-command="executeCommand"
  />
</template>
```

**Props:**
- `editor` (Object): TipTap editor instance
- `config` (Object): Bubble menu configuration
- `showLinkOptions` (Boolean): Show link options
- `showTextFormatting` (Boolean): Show text formatting
- `showTextStyling` (Boolean): Show text styling

**Events:**
- `@execute-command`: Execute command
- `@open-link-modal`: Open link modal

### TableBubbleMenu

Table-specific bubble menu.

**Import:**
```javascript
import { TableBubbleMenu } from 'vue2-premium-bbl-editor'
```

**Usage:**
```vue
<template>
  <TableBubbleMenu
    :editor="editor"
    @add-row-before="addRowBefore"
    @delete-table="deleteTable"
  />
</template>
```

**Props:**
- `editor` (Object): TipTap editor instance
- `showRowControls` (Boolean): Show row controls
- `showColumnControls` (Boolean): Show column controls
- `showCellControls` (Boolean): Show cell controls
- `showTableControls` (Boolean): Show table controls

**Events:**
- `@add-row-before`: Add row before current
- `@add-row-after`: Add row after current
- `@delete-row`: Delete current row
- `@add-column-before`: Add column before current
- `@add-column-after`: Add column after current
- `@delete-column`: Delete current column
- `@merge-cells`: Merge selected cells
- `@split-cell`: Split current cell
- `@delete-table`: Delete entire table

### ImageBubbleMenu

Image-specific bubble menu.

**Import:**
```javascript
import { ImageBubbleMenu } from 'vue2-premium-bbl-editor'
```

**Usage:**
```vue
<template>
  <ImageBubbleMenu
    :editor="editor"
    @align-left="alignImageLeft"
    @delete-image="deleteImage"
  />
</template>
```

**Props:**
- `editor` (Object): TipTap editor instance
- `showAlignmentControls` (Boolean): Show alignment controls
- `showResizeControls` (Boolean): Show resize controls
- `showDeleteControl` (Boolean): Show delete control
- `showAltTextControl` (Boolean): Show alt text control

**Events:**
- `@align-left`: Align image left
- `@align-center`: Align image center
- `@align-right`: Align image right
- `@resize-image`: Resize image
- `@delete-image`: Delete image
- `@edit-alt-text`: Edit alt text

### VideoBubbleMenu

Video-specific bubble menu.

**Import:**
```javascript
import { VideoBubbleMenu } from 'vue2-premium-bbl-editor'
```

**Usage:**
```vue
<template>
  <VideoBubbleMenu
    :editor="editor"
    @toggle-autoplay="toggleAutoplay"
    @delete-video="deleteVideo"
  />
</template>
```

**Props:**
- `editor` (Object): TipTap editor instance
- `showAlignmentControls` (Boolean): Show alignment controls
- `showResizeControls` (Boolean): Show resize controls
- `showPlaybackControls` (Boolean): Show playback controls
- `showDeleteControl` (Boolean): Show delete control

**Events:**
- `@align-left`: Align video left
- `@align-center`: Align video center
- `@align-right`: Align video right
- `@resize-video`: Resize video
- `@toggle-autoplay`: Toggle autoplay
- `@toggle-controls`: Toggle controls
- `@delete-video`: Delete video

## Modal Components

### ImageModal

Modal for uploading and configuring images.

**Import:**
```javascript
import { ImageModal } from 'vue2-premium-bbl-editor'
```

**Usage:**
```vue
<template>
  <ImageModal
    :visible="showModal"
    :upload-handler="uploadHandler"
    :max-file-size="maxFileSize"
    :allowed-types="allowedTypes"
    @close="showModal = false"
    @insert="insertImage"
  />
</template>
```

**Props:**
- `visible` (Boolean): Modal visibility
- `uploadHandler` (Function): Upload handler function
- `maxFileSize` (Number): Maximum file size in bytes
- `allowedTypes` (Array): Allowed MIME types
- `showUrlInput` (Boolean): Show URL input field
- `showAltTextInput` (Boolean): Show alt text input
- `showAlignmentOptions` (Boolean): Show alignment options
- `showSizeOptions` (Boolean): Show size options

**Events:**
- `@close`: Close modal
- `@insert`: Insert image
- `@upload-progress`: Upload progress update
- `@upload-error`: Upload error

### VideoModal

Modal for uploading and configuring videos.

**Import:**
```javascript
import { VideoModal } from 'vue2-premium-bbl-editor'
```

**Usage:**
```vue
<template>
  <VideoModal
    :visible="showModal"
    :upload-handler="uploadHandler"
    @close="showModal = false"
    @insert="insertVideo"
  />
</template>
```

**Props:**
- `visible` (Boolean): Modal visibility
- `uploadHandler` (Function): Upload handler function
- `maxFileSize` (Number): Maximum file size in bytes
- `allowedTypes` (Array): Allowed MIME types
- `showUrlInput` (Boolean): Show URL input field
- `showEmbedInput` (Boolean): Show embed code input
- `showPlaybackOptions` (Boolean): Show playback options
- `showSizeOptions` (Boolean): Show size options

**Events:**
- `@close`: Close modal
- `@insert`: Insert video
- `@upload-progress`: Upload progress update
- `@upload-error`: Upload error

### LinkModal

Modal for creating and editing links.

**Import:**
```javascript
import { LinkModal } from 'vue2-premium-bbl-editor'
```

**Usage:**
```vue
<template>
  <LinkModal
    :visible="showModal"
    :initial-text="linkText"
    :initial-url="linkUrl"
    @close="showModal = false"
    @insert="insertLink"
  />
</template>
```

**Props:**
- `visible` (Boolean): Modal visibility
- `initialText` (String): Initial link text
- `initialUrl` (String): Initial link URL
- `initialTarget` (String): Initial link target
- `showTextInput` (Boolean): Show text input field
- `showTargetOptions` (Boolean): Show target options
- `showTitleInput` (Boolean): Show title input field
- `validateUrl` (Boolean): Enable URL validation

**Events:**
- `@close`: Close modal
- `@insert`: Insert link
- `@update`: Update existing link
- `@remove`: Remove link

## Upload System

The package includes a comprehensive upload management system with multiple adapters and advanced features.

### UploadManager

Main upload management class.

**Import:**
```javascript
import { UploadManager } from 'vue2-premium-bbl-editor'
```

#### Composition API Usage
```javascript
const config = createUploadConfig('localStorage')
const uploadManager = new UploadManager(config)
```

#### Options API Usage
```javascript
// In data()
data() {
  return {
    uploadManager: null
  }
},

// In created()
async created() {
  const config = createUploadConfig('localStorage')
  this.uploadManager = new UploadManager(config)
}
```

**Methods:**
- `registerAdapter(adapter)`: Register upload adapter
- `setDefaultAdapter(name)`: Set default adapter
- `upload(file, options)`: Upload file
- `uploadWithAdapter(name, file, options)`: Upload with specific adapter
- `cancelUpload(uploadId)`: Cancel upload
- `getStats()`: Get upload statistics
- `destroy()`: Cleanup resources
- `on(event, callback)`: Add event listener
- `off(event, callback)`: Remove event listener

**Events:**
- `uploadStarted`: Upload started
- `progress`: Upload progress update
- `uploadCompleted`: Upload completed successfully
- `uploadFailed`: Upload failed
- `retryAttemptStarted`: Retry attempt started
- `defaultAdapterChanged`: Default adapter changed
- `validationFailed`: File validation failed

### LocalStorageAdapter

Local storage upload adapter for development.

**Import:**
```javascript
import { LocalStorageAdapter } from 'vue2-premium-bbl-editor'
```

#### Composition API Usage
```javascript
const adapter = new LocalStorageAdapter({
  generateObjectUrl: true,
  persistToIndexedDB: false
})
uploadManager.registerAdapter(adapter)
```

#### Options API Usage
```javascript
// In methods
setupAdapters() {
  const adapter = new LocalStorageAdapter({
    generateObjectUrl: true,
    persistToIndexedDB: false
  })
  this.uploadManager.registerAdapter(adapter)
}
```

### Upload Configuration

**Import:**
```javascript
import { createUploadConfig } from 'vue2-premium-bbl-editor'
```

#### Composition API Usage
```javascript
const config = createUploadConfig('localStorage', {
  validation: {
    maxSize: 10 * 1024 * 1024, // 10MB
    allowedTypes: ['image/jpeg', 'image/png']
  },
  retry: {
    maxAttempts: 3,
    baseDelay: 1000
  }
})
```

#### Options API Usage
```javascript
// In methods
createUploadConfiguration() {
  return createUploadConfig('localStorage', {
    validation: {
      maxSize: this.maxFileSize,
      allowedTypes: this.allowedFileTypes
    },
    retry: {
      maxAttempts: this.maxRetryAttempts,
      baseDelay: this.retryBaseDelay
    }
  })
}
```

**Configuration Options:**
- `defaultAdapter` (String): Default adapter name
- `adapters` (Object): Adapter configurations
- `validation` (Object): File validation settings
- `retry` (Object): Retry configuration
- `progress` (Object): Progress tracking settings
- `debug` (Boolean): Enable debug logging

### TipTap Integration

**Import:**
```javascript
import { integrateTipTapUpload } from 'vue2-premium-bbl-editor'
```

#### Composition API Usage
```javascript
integrateTipTapUpload(editor, uploadManager, {
  onStart: () => console.log('Upload started'),
  onEnd: () => console.log('Upload finished')
})
```

#### Options API Usage
```javascript
// In methods
onEditorReady(editor) {
  integrateTipTapUpload(editor, this.uploadManager, {
    onStart: () => {
      this.uploadInProgress = true
      console.log('Upload started')
    },
    onEnd: () => {
      this.uploadInProgress = false
      console.log('Upload finished')
    }
  })
}
```

## Development Tools

### DiagnosticTool

Built-in diagnostic and troubleshooting tool.

**Import:**
```javascript
import { DiagnosticTool } from 'vue2-premium-bbl-editor'
```

**Usage:**
```vue
<template>
  <DiagnosticTool
    :editor="editor"
    :show-dependency-check="true"
    :show-browser-info="true"
    @diagnostic-complete="handleDiagnostic"
  />
</template>
```

**Props:**
- `editor` (Object): Editor instance to diagnose
- `showDependencyCheck` (Boolean): Show dependency check
- `showBrowserInfo` (Boolean): Show browser information
- `showEditorState` (Boolean): Show editor state
- `showPerformanceMetrics` (Boolean): Show performance metrics

**Events:**
- `@diagnostic-complete`: Diagnostic completed

### DebugHelper

Development debugging helper component.

**Import:**
```javascript
import { DebugHelper } from 'vue2-premium-bbl-editor'
```

**Usage:**
```vue
<template>
  <DebugHelper
    :editor="editor"
    :show-editor-state="true"
    :show-event-log="true"
    @state-change="handleStateChange"
  />
</template>
```

**Props:**
- `editor` (Object): Editor instance to debug
- `showEditorState` (Boolean): Show editor state
- `showContentAnalysis` (Boolean): Show content analysis
- `showEventLog` (Boolean): Show event log
- `showPerformanceMonitor` (Boolean): Show performance monitor
- `autoRefresh` (Boolean): Auto-refresh data
- `refreshInterval` (Number): Refresh interval in milliseconds

**Events:**
- `@state-change`: Editor state changed
- `@performance-update`: Performance metrics updated

## Extensions

The package includes custom TipTap extensions for enhanced functionality.

### ResizableImage

Enhanced image extension with resize controls.

**Import:**
```javascript
import { ResizableImage } from 'vue2-premium-bbl-editor'
```

**Configuration:**
```javascript
ResizableImage.configure({
  allowResize: true,
  allowAlignment: true,
  allowDelete: true,
  maxWidth: '100%',
  quality: 0.8
})
```

### ResizableVideo

Enhanced video extension with resize controls.

**Import:**
```javascript
import { ResizableVideo } from 'vue2-premium-bbl-editor'
```

**Configuration:**
```javascript
ResizableVideo.configure({
  allowResize: true,
  allowAlignment: true,
  allowDelete: true,
  maxWidth: '100%',
  autoplay: false
})
```

### CustomTableCell

Enhanced table cell with interactive controls.

**Import:**
```javascript
import { CustomTableCell } from 'vue2-premium-bbl-editor'
```

### CustomTableHeader

Enhanced table header with interactive controls.

**Import:**
```javascript
import { CustomTableHeader } from 'vue2-premium-bbl-editor'
```

## Composables

### useEditor

Core editor composable for custom implementations.

**Import:**
```javascript
import { useEditor } from 'vue2-premium-bbl-editor'
```

**Usage:**
```javascript
const {
  editor,
  isEditorReady,
  currentContent,
  editorError,
  executeCommand,
  isActive,
  getContent,
  setContent,
  focus,
  blur
} = useEditor(props, emit)
```

**Parameters:**
- `props` (Object): Component props
- `emit` (Function): Component emit function

**Returns:**
- `editor` (Ref): TipTap editor instance
- `isEditorReady` (Ref): Editor ready state
- `currentContent` (Computed): Current editor content
- `editorError` (Ref): Editor error state
- `missingDependencies` (Ref): Missing dependencies
- `executeCommand` (Function): Execute editor command
- `isActive` (Function): Check if feature is active
- `getContent` (Function): Get editor content
- `setContent` (Function): Set editor content
- `focus` (Function): Focus editor
- `blur` (Function): Blur editor

## TypeScript Support

The package includes comprehensive TypeScript definitions.

### Main Interfaces

```typescript
import {
  PremiumBblEditorProps,
  PremiumBblEditorEvents,
  PremiumBblEditorMethods,
  ToolbarConfig,
  ExtensionConfig,
  UploadHandler,
  UploadConfig,
  UploadResult
} from 'vue2-premium-bbl-editor'
```

### Component Types

```typescript
import { PremiumBblEditor } from 'vue2-premium-bbl-editor'

// Component instance type
type EditorInstance = InstanceType<typeof PremiumBblEditor>
```

### Upload System Types

```typescript
import { UploadManager, LocalStorageAdapter } from 'vue2-premium-bbl-editor'

const uploadManager: UploadManager = new UploadManager(config)
const adapter: LocalStorageAdapter = new LocalStorageAdapter()
```

## Styling & Theming

### Built-in Themes

The package includes three built-in themes:

1. **Default Theme**: Clean, professional appearance
2. **Minimal Theme**: Simplified interface with reduced visual elements
3. **Dark Theme**: Dark color scheme for low-light environments

**Usage:**
```vue
<template>
  <PremiumBblEditor
    v-model="content"
    theme="dark"
  />
</template>
```

### Custom Themes

Create custom themes using CSS custom properties:

```css
.premium-editor-container.theme-custom {
  --editor-bg: #f8fafc;
  --editor-text: #1a202c;
  --toolbar-bg: #ffffff;
  --toolbar-border: #e2e8f0;
  --button-hover: #f7fafc;
  --button-active: #3182ce;
  --bubble-menu-bg: #ffffff;
  --bubble-menu-border: #e2e8f0;
  --modal-bg: #ffffff;
  --modal-overlay: rgba(0, 0, 0, 0.5);
}
```

### Custom CSS Classes

Apply custom CSS classes to different parts of the editor:

```vue
<template>
  <PremiumBblEditor
    v-model="content"
    editor-class="my-editor"
    toolbar-class="my-toolbar"
    content-class="my-content"
  />
</template>

<style>
.my-editor {
  border-radius: 12px;
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
}

.my-toolbar {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}

.my-content {
  font-family: 'Georgia', serif;
  line-height: 1.8;
}
</style>
```

## Configuration Reference

### Toolbar Configuration

Complete toolbar configuration options:

```javascript
const toolbarConfig = {
  // Text formatting
  bold: true,              // Bold text
  italic: true,            // Italic text
  underline: true,         // Underlined text
  strike: true,            // Strikethrough text
  code: true,              // Inline code
  
  // Text styling
  textColor: true,         // Text color picker
  highlight: true,         // Text highlight
  fontFamily: true,        // Font family dropdown
  fontSize: true,          // Font size dropdown
  
  // Alignment and spacing
  textAlign: true,         // Text alignment options
  lineHeight: true,        // Line height options
  
  // Structure
  headings: true,          // Heading levels
  lists: true,             // Bullet and numbered lists
  blockquote: true,        // Blockquotes
  codeBlock: true,         // Code blocks
  horizontalRule: true,    // Horizontal rules
  
  // Media
  link: true,              // Links
  image: true,             // Images
  video: true,             // Videos
  table: true,             // Tables
  
  // Utilities
  clearFormatting: true,   // Clear formatting
  sourceCode: true,        // Source code view
  undo: true,              // Undo
  redo: true               // Redo
}
```

### Extension Configuration

Complete extension configuration options:

```javascript
const extensionConfig = {
  image: {
    allowResize: true,       // Allow image resizing
    allowAlignment: true,    // Allow image alignment
    allowDelete: true,       // Allow image deletion
    maxWidth: '100%',        // Maximum image width
    quality: 0.8            // Image quality (0-1)
  },
  
  video: {
    allowResize: true,       // Allow video resizing
    allowAlignment: true,    // Allow video alignment
    allowDelete: true,       // Allow video deletion
    maxWidth: '100%',        // Maximum video width
    autoplay: false         // Auto-play videos
  },
  
  table: {
    resizable: true,         // Allow table resizing
    allowRowControls: true,  // Show row controls
    allowColumnControls: true, // Show column controls
    cellSelection: true      // Allow cell selection
  },
  
  link: {
    openOnClick: false,      // Open links on click
    autolink: true,          // Auto-detect links
    linkOnPaste: true       // Create links on paste
  },
  
  textAlign: {
    types: ['heading', 'paragraph'] // Elements that support alignment
  }
}
```

## Event Reference

### Editor Events

| Event | Payload | Description |
|-------|---------|-------------|
| `input` | `content: string` | Content changed (v-model) |
| `update` | `content: string` | Content updated |
| `ready` | `editor: Editor` | Editor ready for use |
| `created` | `editor: Editor` | Editor instance created |
| `focus` | - | Editor gained focus |
| `blur` | - | Editor lost focus |
| `destroyed` | - | Editor destroyed |
| `auto-save` | `content: string` | Auto-save triggered |
| `content-limit-exceeded` | `{current: number, max: number}` | Content limit exceeded |
| `error` | `{type: string, message: string, ...}` | Error occurred |

### Upload Events

| Event | Payload | Description |
|-------|---------|-------------|
| `uploadStarted` | `{uploadId: string, fileName: string, ...}` | Upload started |
| `progress` | `{percentage: number, loaded: number, total: number, ...}` | Upload progress |
| `uploadCompleted` | `{result: UploadResult, uploadId: string, ...}` | Upload completed |
| `uploadFailed` | `{error: Error, uploadId: string, ...}` | Upload failed |
| `retryAttemptStarted` | `{attempt: number, maxAttempts: number, ...}` | Retry attempt started |
| `validationFailed` | `{error: Error, file: File}` | File validation failed |

## Method Reference

### Editor Methods

| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| `focus()` | - | `void` | Focus the editor |
| `blur()` | - | `void` | Blur the editor |
| `getContent(format?)` | `format?: 'html' \| 'json'` | `string \| object` | Get editor content |
| `setContent(content, emitUpdate?)` | `content: string, emitUpdate?: boolean` | `void` | Set editor content |
| `executeCommand(command, options?)` | `command: string, options?: any` | `void` | Execute editor command |

### Upload Manager Methods

| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| `registerAdapter(adapter)` | `adapter: UploadAdapter` | `void` | Register upload adapter |
| `setDefaultAdapter(name)` | `name: string` | `void` | Set default adapter |
| `upload(file, options?)` | `file: File, options?: any` | `Promise<UploadResult>` | Upload file |
| `uploadWithAdapter(name, file, options?)` | `name: string, file: File, options?: any` | `Promise<UploadResult>` | Upload with specific adapter |
| `cancelUpload(uploadId)` | `uploadId: string` | `Promise<void>` | Cancel upload |
| `getStats()` | - | `object` | Get upload statistics |
| `destroy()` | - | `void` | Cleanup resources |

## Best Practices

### Performance Optimization

1. **Lazy Load Components**: Import components only when needed
2. **Optimize Images**: Use appropriate image sizes and formats
3. **Debounce Auto-save**: Use reasonable auto-save intervals
4. **Limit Content Length**: Set appropriate content limits
5. **Use Production Builds**: Always use minified builds in production

### Accessibility

1. **Keyboard Navigation**: Ensure all features are keyboard accessible
2. **Screen Reader Support**: Use proper ARIA labels and descriptions
3. **Color Contrast**: Maintain sufficient color contrast ratios
4. **Focus Management**: Provide clear focus indicators
5. **Alternative Text**: Always provide alt text for images

### Security

1. **Sanitize Content**: Always sanitize HTML content on the server
2. **Validate Uploads**: Implement proper file validation
3. **HTTPS Only**: Use HTTPS for all upload endpoints
4. **Authentication**: Secure upload endpoints with proper authentication
5. **Content Security Policy**: Implement appropriate CSP headers

### Error Handling

1. **Graceful Degradation**: Handle missing dependencies gracefully
2. **User-Friendly Messages**: Show clear error messages to users
3. **Retry Logic**: Implement retry logic for failed operations
4. **Logging**: Log errors for debugging purposes
5. **Fallback Options**: Provide fallback options when features fail

## Troubleshooting

### Common Issues

#### Editor Not Loading

**Symptoms**: Editor shows loading state indefinitely or displays error message.

**Solutions**:
1. Check if all required dependencies are installed
2. Verify Vue Composition API is properly configured
3. Check browser console for error messages
4. Use DiagnosticTool component to identify issues

#### Upload Not Working

**Symptoms**: File uploads fail or don't start.

**Solutions**:
1. Verify upload handler is properly configured
2. Check file size and type restrictions
3. Ensure upload endpoint is accessible
4. Check network connectivity and CORS settings

#### Styling Issues

**Symptoms**: Editor appearance is broken or inconsistent.

**Solutions**:
1. Ensure CSS files are properly imported
2. Check for CSS conflicts with existing styles
3. Verify theme configuration is correct
4. Use browser developer tools to inspect styles

#### Performance Issues

**Symptoms**: Editor is slow or unresponsive.

**Solutions**:
1. Reduce auto-save frequency
2. Limit content length
3. Optimize images and media
4. Check for memory leaks
5. Use production builds

### Debug Mode

Enable debug mode for detailed logging:

```vue
<template>
  <PremiumBblEditor
    v-model="content"
    :debug="true"
  />
</template>
```

### Diagnostic Tools

Use built-in diagnostic tools:

```vue
<template>
  <div>
    <PremiumBblEditor v-model="content" />
    <DiagnosticTool v-if="isDevelopment" />
    <DebugHelper v-if="isDevelopment" />
  </div>
</template>
```

### Getting Help

1. **Check Documentation**: Review this documentation and examples
2. **Search Issues**: Search existing GitHub issues
3. **Create Issue**: Create a new issue with detailed information
4. **Community Support**: Ask questions in community forums
5. **Professional Support**: Contact for professional support options

---

This documentation covers all aspects of the Vue2 Premium BBL Editor package. For additional examples and advanced usage patterns, see the [Component Usage Guide](COMPONENT_USAGE_GUIDE.md) and [External Integration Guide](EXTERNAL_INTEGRATION_GUIDE.md).