@lax-wp/editor 0.0.1

package/README.md

@@ -0,0 +1,724 @@
+# Lax WP Editor
+
+A modern, feature-rich WordPress-style editor built with React and TipTap. This editor provides a clean, intuitive interface for rich text editing with customizable toolbars and extensive formatting options.
+
+## Table of Contents
+
+- [Recent Updates](#recent-updates)
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+  - [Basic Configuration](#basic-configuration)
+  - [AI Autocompletion](#ai-autocompletion)
+  - [Export Functionality](#export-functionality)
+  - [Variable Text Feature](#variable-text-feature)
+  - [Configuration Options Reference](#configuration-options-reference)
+- [Components](#components)
+- [Hooks](#hooks)
+- [API Reference](#api-reference)
+- [Examples](#examples)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Recent Updates
+
+### v2.0.0 - Latest Release
+
+#### ✨ Export Functionality
+- Added comprehensive export system with support for multiple formats
+- Export your content as Text (.txt), JSON (.json), Markdown (.md), or HTML (.html)
+- New **Export** tab in the toolbar for quick access to all export options
+- `useExport` hook for programmatic export functionality
+
+#### 📝 Variable Text Feature
+- Dynamic variable text support for mail merge and templates
+- Insert variables programmatically from your application
+- `onEditorReady` callback provides `insertVariable` method
+- Variables display actual values or `{{variableName}}` placeholders
+- Supports manual typing with `{{variableName}}` syntax
+
+#### 🎨 Toolbar Enhancements
+- Improved toolbar dropdown with visual icons for each mode
+- Better visual distinction between Professional, Classic, and Hide Toolbar modes
+- Enhanced toolbar tab interface with 5 tabs: Home, Insert, Table, Page, and Export
+- Smoother transitions between toolbar types
+
+#### 🖼️ Custom Image Support
+- Resizable images with drag handles
+- Image alignment (left, center, right)
+- Bubble menu for image options
+- Inline and block image support
+
+## Features
+
+- 🎨 **Modern UI**: Clean, responsive design with customizable themes
+- 📝 **Rich Text Editing**: Full-featured WYSIWYG editor with TipTap
+- 🛠️ **Flexible Toolbars**: Professional and Classic toolbar modes with tabbed interface
+- 📄 **Page Management**: Multiple page sizes and orientations
+- 📤 **Export Options**: Export your content as Text, HTML, Markdown, or JSON
+- 📝 **Variable Text**: Dynamic variables for mail merge and template systems
+- 🖼️ **Image Support**: Resizable images with alignment and custom styling
+- 🎯 **Customizable**: Easy to integrate and customize
+- 📱 **Responsive**: Works seamlessly on desktop and mobile
+- 🔧 **TypeScript**: Full TypeScript support with type definitions
+
+## Installation
+
+```bash
+npm install lax-wp-editor
+# or
+yarn add lax-wp-editor
+# or
+pnpm add lax-wp-editor
+```
+
+## Quick Start
+
+```tsx
+import React from 'react';
+import { Editor } from 'lax-wp-editor'; // CSS is automatically included!
+
+function App() {
+  return (
+    <div style={{ height: '100vh', width: '100%' }}>
+      <Editor />
+    </div>
+  );
+}
+
+export default App;
+```
+
+> **✨ New in v1.2.0:** CSS is now automatically imported! You no longer need to manually import the styles.
+> 
+> **For older versions (v1.1.x), you need to manually import styles:**
+> ```tsx
+> import 'lax-wp-editor/styles';
+> // or
+> import 'lax-wp-editor/dist/lax-wp-editor.css';
+> ```
+
+## Configuration
+
+The editor accepts a `config` prop with the following options:
+
+### Basic Configuration
+
+```tsx
+import { Editor, type EditorConfig } from 'lax-wp-editor';
+
+function App() {
+  const config: EditorConfig = {
+    // Initial content (HTML string)
+    content: '<p>Your initial content here</p>',
+    
+    // Toolbar type: 'professional' or 'classic'
+    defaultToolbar: 'professional',
+    
+    // Enable/disable features
+    showBubbleMenu: true,           // Show bubble menu on text selection
+    showFloatingMenu: false,        // Show floating menu on empty lines
+    showPageSizeSelector: true,     // Show page size selector
+    enablePagination: true,         // Enable pagination
+    
+    // Content change callback with debounce
+    debounceTimeForContentChange: 300,  // Debounce time in milliseconds (default: 300ms)
+    onContentChange: (editor) => {
+      const html = editor.getHTML();
+      console.log('Content changed:', html);
+    },
+  };
+
+  return (
+    <div style={{ height: '100vh', width: '100%' }}>
+      <Editor config={config} />
+    </div>
+  );
+}
+```
+
+### AI Autocompletion
+
+You can enable AI autocompletion by providing your own completion function:
+
+```tsx
+import { Editor, type EditorConfig } from 'lax-wp-editor';
+
+function App() {
+  const config: EditorConfig = {
+    aiAutocompletion: {
+      enabled: true,
+      minWordsToTriggerAutoCompletion: 5, // Trigger after 5 words (default: 3)
+      debounceTime: 300, // Wait 300ms before calling API (default: 100ms)
+      
+      // Required: Provide your custom fetch function
+      fetchCompletion: async (text: string) => {
+        const response = await fetch('https://your-api.com/completions', {
+          method: 'POST',
+          headers: { 
+            'Content-Type': 'application/json',
+            'Authorization': 'Bearer YOUR_API_KEY',
+          },
+          body: JSON.stringify({ prompt: text }),
+        });
+        const data = await response.json();
+        return data.completion; // Return the completion text
+      },
+    },
+  };
+
+  return (
+    <div style={{ height: '100vh', width: '100%' }}>
+      <Editor config={config} />
+    </div>
+  );
+}
+```
+
+> **⚠️ Important:** AI autocompletion requires you to provide a `fetchCompletion` function. The editor does not include a default AI service.
+
+**Keyboard Shortcuts for AI Autocompletion:**
+- `Tab` - Accept suggestion
+- `Escape` - Dismiss suggestion
+- `Ctrl+Shift+Space` (Windows/Linux) or `Cmd+Shift+Space` (Mac) - Toggle autocompletion on/off
+
+### Export Functionality
+
+The editor includes a comprehensive export system that allows users to download their content in multiple formats:
+
+```tsx
+import { Editor, useExport } from 'lax-wp-editor';
+
+function MyEditorComponent({ editor }) {
+  const { 
+    downloadTextFile, 
+    downloadJsonFile, 
+    downloadMarkdownFile, 
+    downloadHtmlFile 
+  } = useExport(editor);
+
+  return (
+    <div>
+      <button onClick={downloadTextFile}>Export as Text</button>
+      <button onClick={downloadJsonFile}>Export as JSON</button>
+      <button onClick={downloadMarkdownFile}>Export as Markdown</button>
+      <button onClick={downloadHtmlFile}>Export as HTML</button>
+    </div>
+  );
+}
+```
+
+**Available Export Formats:**
+
+| Format | Description | Method |
+|--------|-------------|--------|
+| **Text** | Plain text (.txt) | `downloadTextFile()` |
+| **JSON** | TipTap JSON format (.json) | `downloadJsonFile()` |
+| **Markdown** | Markdown format (.md) | `downloadMarkdownFile()` |
+| **HTML** | HTML format (.html) | `downloadHtmlFile()` |
+
+> **💡 Tip:** The Export tab is built into the toolbar and provides quick access to all export formats. You can also use the `useExport` hook to create custom export buttons.
+
+### Variable Text Feature
+
+The editor supports dynamic variable text that can be inserted programmatically from your application. Variables are displayed as placeholders that get replaced with actual values.
+
+**Enable Variable Text:**
+
+```tsx
+import { useState } from 'react';
+import { Editor } from 'lax-wp-editor';
+
+function App() {
+  const [insertVariable, setInsertVariable] = useState<((key: string, value?: string) => void) | null>(null);
+
+  const handleInsertName = () => {
+    insertVariable?.('userName');
+  };
+
+  const handleInsertEmailWithValue = () => {
+    insertVariable?.('email', 'newemail@example.com');
+  };
+
+  return (
+    <div>
+      <button onClick={handleInsertName}>Insert User Name</button>
+      <button onClick={handleInsertEmailWithValue}>Insert Email</button>
+      
+      <Editor 
+        config={{
+          enableVariableText: true,
+          variableValues: {
+            userName: 'John Doe',
+            email: 'john@example.com',
+            company: 'Acme Inc',
+          },
+          onEditorReady: ({ insertVariable: insert }) => {
+            // Store the insertVariable method when editor is ready
+            setInsertVariable(() => insert);
+          },
+        }}
+      />
+    </div>
+  );
+}
+```
+
+**Variable Text Configuration:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `enableVariableText` | `boolean` | Enable/disable variable text feature |
+| `variableValues` | `Record<string, string>` | Key-value pairs for variable replacements |
+| `onEditorReady` | `(methods) => void` | Callback that provides editor methods including `insertVariable` |
+
+**Insert Variable Method:**
+
+```tsx
+insertVariable(key: string, value?: string)
+```
+
+- **`key`**: The variable name/key
+- **`value`**: (Optional) Update the variable value before inserting
+
+**How Variables Work:**
+
+1. Variables are inserted as special nodes in the editor
+2. They display the value from `variableValues` config
+3. If no value exists, they display as `{{variableName}}`
+4. Variables can be typed manually using `{{variableName}}` syntax (if enabled)
+5. Users can insert variables programmatically from outside the editor
+
+**Example Use Cases:**
+
+- Mail merge functionality
+- Template systems
+- Dynamic content generation
+- Personalized documents
+
+### Configuration Options Reference
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `content` | `string` | `""` | Initial HTML content for the editor |
+| `defaultToolbar` | `'professional' \| 'classic'` | `'professional'` | Toolbar style |
+| `showBubbleMenu` | `boolean` | `true` | Show bubble menu on text selection |
+| `showFloatingMenu` | `boolean` | `false` | Show floating menu on empty lines |
+| `showPageSizeSelector` | `boolean` | `true` | Show page size selector |
+| `enablePagination` | `boolean` | `true` | Enable pagination |
+| `debounceTimeForContentChange` | `number` | `300` | Debounce time (ms) for `onContentChange` callback |
+| `onContentChange` | `(editor: Editor) => void` | `undefined` | Callback when content changes (debounced) |
+| `enableVariableText` | `boolean` | `false` | Enable variable text feature |
+| `variableValues` | `Record<string, string>` | `{}` | Variable name to value mappings |
+| `onEditorReady` | `(methods) => void` | `undefined` | Callback with editor methods when ready |
+| `onShare` | `() => void` | `undefined` | Callback when share button is clicked |
+| `aiAutocompletion` | `AIAutocompletionConfig` | See below | AI autocompletion configuration |
+
+**AIAutocompletionConfig:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | `boolean` | `false` | Enable/disable AI autocompletion |
+| `minWordsToTriggerAutoCompletion` | `number` | `3` | Minimum words to trigger autocompletion |
+| `debounceTime` | `number` | `100` | Debounce time (ms) before calling API |
+| `fetchCompletion` | `(text: string) => Promise<string>` | `undefined` | **Required** - Custom fetch function for AI completions |
+
+### Important: Fixing ProseMirror Duplication Error
+
+If you encounter the `localsInner` error, it's caused by multiple versions of ProseMirror packages in **your application's** dependency tree.
+
+**Official Tiptap Solution:**
+
+This package already uses `@tiptap/pm` for all ProseMirror functionality (as recommended by Tiptap). However, you need to ensure your application also deduplicates ProseMirror versions.
+
+**1. In your application directory, check for duplicate ProseMirror versions:**
+```bash
+npm ls prosemirror-view
+# or
+yarn list prosemirror-view
+```
+
+**2. If you see multiple versions, add this to YOUR APPLICATION's `package.json`:**
+
+**For Yarn users:**
+```json
+{
+  "resolutions": {
+    "prosemirror-view": "^1.41.0",
+    "prosemirror-state": "^1.4.3",
+    "prosemirror-model": "^1.25.0",
+    "prosemirror-transform": "^1.10.0"
+  }
+}
+```
+
+**For npm users (v8.3.0+):**
+```json
+{
+  "overrides": {
+    "prosemirror-view": "^1.41.0",
+    "prosemirror-state": "^1.4.3",
+    "prosemirror-model": "^1.25.0",
+    "prosemirror-transform": "^1.10.0"
+  }
+}
+```
+
+**For pnpm users:**
+```json
+{
+  "pnpm": {
+    "overrides": {
+      "prosemirror-view": "^1.41.0",
+      "prosemirror-state": "^1.4.3",
+      "prosemirror-model": "^1.25.0",
+      "prosemirror-transform": "^1.10.0"
+    }
+  }
+}
+```
+
+**3. Clean install in YOUR APPLICATION:**
+```bash
+# In your application directory (not lax-wp-editor)
+rm -rf node_modules package-lock.json  # or yarn.lock / pnpm-lock.yaml
+npm install  # or yarn / pnpm install
+```
+
+**4. Verify all packages are deduped:**
+```bash
+npm ls prosemirror-view
+# All instances should show "deduped" and point to the same version
+```
+
+> **Note:** This package uses `@tiptap/pm` internally (not direct ProseMirror imports) to prevent version conflicts. The deduplication step is only needed if other packages in your project import ProseMirror directly.
+
+## Basic Usage
+
+### Simple Editor
+
+```tsx
+import { Editor, ToolbarProvider } from 'lax-wp-editor';
+import 'lax-wp-editor/styles';
+
+function MyEditor() {
+  return (
+    <ToolbarProvider>
+      <Editor />
+    </ToolbarProvider>
+  );
+}
+```
+
+### Custom Configuration
+
+```tsx
+import { Editor, ToolbarProvider, defaultEditorConfig } from 'lax-wp-editor';
+import 'lax-wp-editor/styles';
+
+function MyEditor() {
+  const config = {
+    ...defaultEditorConfig,
+    // Add your custom configuration
+  };
+
+  return (
+    <ToolbarProvider>
+      <Editor config={config} />
+    </ToolbarProvider>
+  );
+}
+```
+
+### Different Toolbar Types
+
+The editor supports three toolbar modes:
+
+1. **Professional** - Multi-row toolbar with all options visible
+2. **Classic** - Single-row compact toolbar with grouped controls
+3. **Hide Toolbar** - No toolbar (presentation mode)
+
+```tsx
+import { Editor, ToolbarProvider, TOOLBAR_TYPES_ENUM } from 'lax-wp-editor';
+import 'lax-wp-editor/styles';
+
+function MyEditor() {
+  return (
+    <ToolbarProvider initialToolbar={TOOLBAR_TYPES_ENUM.CLASSIC}>
+      <Editor />
+    </ToolbarProvider>
+  );
+}
+```
+
+Users can switch between toolbar modes using the built-in toolbar dropdown menu, which includes icons for each mode:
+- 📊 **Classic** - Compact view
+- 🎛️ **Professional** - Full view
+- 👁️ **Hide Toolbar** - Hidden view
+
+## Components
+
+### Main Components
+
+- **`Editor`**: The main editor component
+- **`ToolbarProvider`**: Context provider for toolbar state
+- **`Toolbar`**: Main toolbar component with tabbed interface
+- **`ProfessionalToolbar`**: Professional-style toolbar (multi-row layout)
+- **`ClassicToolbar`**: Classic-style toolbar (single-row layout)
+- **`ToolbarDropdown`**: Dropdown to switch between toolbar modes
+
+### Toolbar Tabs
+
+The editor includes a tabbed toolbar interface with the following tabs:
+
+- **`Home`**: Basic formatting options (bold, italic, underline, alignment, etc.)
+- **`Insert`**: Insert elements (tables, images, dividers, etc.)
+- **`Table`**: Table-specific operations (add/remove rows/columns, merge cells, etc.)
+- **`Page`**: Page settings (size, orientation, margins, background)
+- **`Export`**: Export content in multiple formats (Text, JSON, Markdown, HTML)
+
+### Individual Toolbar Components
+
+- **`HeadingOptions`**: Heading selection dropdown
+- **`HomeOptions`**: Basic formatting options
+- **`FontStyleOptions`**: Font styling options
+- **`ParagraphStyleOption`**: Paragraph styling
+- **`ExportOptions`**: Export functionality for multiple file formats
+- **`TableOptions`**: Table manipulation controls
+- **`InsertOptions`**: Insert various elements into the document
+
+### Utility Components
+
+- **`SvgIcon`**: SVG icon component
+- **`PageSizeSelector`**: Page size and orientation selector
+- **`Button`**: Base button component
+- **`ColorPicker`**: Color picker for text and background colors
+
+## Hooks
+
+- **`useTiptapEditorState`**: Access editor state
+- **`useHeadingStyleMethods`**: Heading manipulation methods
+- **`useFontStyleMethods`**: Font styling methods
+- **`useHomeOptionMethods`**: Basic formatting methods
+- **`useParagraphStyleMethods`**: Paragraph styling methods
+- **`usePageMethods`**: Page size and layout management
+- **`useExport`**: Export content in multiple formats (Text, JSON, Markdown, HTML)
+- **`useTableMethods`**: Table manipulation methods
+- **`useLinks`**: Link management methods
+- **`usePresentationMode`**: Presentation mode controls
+- **`useZoom`**: Zoom controls for the editor
+
+## Configuration
+
+### Editor Configuration
+
+```tsx
+import { EditorConfig } from 'lax-wp-editor';
+
+const config: EditorConfig = {
+  // Your configuration options
+};
+```
+
+### Toolbar Types
+
+```tsx
+import { TOOLBAR_TYPES_ENUM } from 'lax-wp-editor';
+
+// Available toolbar types:
+TOOLBAR_TYPES_ENUM.PROFESSIONAL  // Professional toolbar (multi-row, all options visible)
+TOOLBAR_TYPES_ENUM.CLASSIC       // Classic toolbar (single-row, compact)
+TOOLBAR_TYPES_ENUM.HIDE_TOOLBAR  // Hide toolbar completely
+```
+
+The toolbar includes 5 tabs:
+- **Home**: Text formatting, alignment, lists, etc.
+- **Insert**: Tables, images, dividers, and other insertable elements
+- **Table**: Table-specific operations (add/remove rows/columns, merge cells)
+- **Page**: Page layout settings (size, orientation, margins, background)
+- **Export**: Download content in various formats (Text, JSON, Markdown, HTML)
+
+## Styling
+
+The package includes default styles that you can import:
+
+```tsx
+import 'lax-wp-editor/styles';
+```
+
+You can also customize the styles by overriding CSS variables or using your own CSS.
+
+## TypeScript Support
+
+The package includes full TypeScript definitions:
+
+```tsx
+import { Editor, EditorConfig, PageSize } from 'lax-wp-editor';
+```
+
+## API Reference
+
+### Editor Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `config` | `EditorConfig` | `defaultEditorConfig` | Editor configuration |
+| `onUpdate` | `(content: string) => void` | - | Callback when content changes |
+| `initialContent` | `string` | - | Initial editor content |
+
+### ToolbarProvider Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `initialToolbar` | `ToolbarType` | `PROFESSIONAL` | Initial toolbar type |
+| `children` | `ReactNode` | - | Child components |
+
+### ToolbarDropdown Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `onToolbarChange` | `(toolbarType: string) => void` | - | Callback when toolbar type changes |
+
+### useExport Hook
+
+Returns an object with the following methods:
+
+| Method | Description |
+|--------|-------------|
+| `downloadTextFile()` | Downloads content as plain text (.txt) |
+| `downloadJsonFile()` | Downloads content as TipTap JSON format (.json) |
+| `downloadMarkdownFile()` | Downloads content as Markdown (.md) |
+| `downloadHtmlFile()` | Downloads content as HTML (.html) |
+
+## Examples
+
+### Custom Toolbar
+
+```tsx
+import { Editor, Toolbar, HeadingOptions, HomeOptions } from 'lax-wp-editor';
+
+function CustomEditor() {
+  return (
+    <div>
+      <Toolbar>
+        <HeadingOptions />
+        <HomeOptions />
+      </Toolbar>
+      <Editor />
+    </div>
+  );
+}
+```
+
+### Page Size Management
+
+```tsx
+import { Editor, PageSizeSelector, usePageMethods } from 'lax-wp-editor';
+
+function EditorWithPageSize() {
+  const { pageSize, setPageSize } = usePageMethods();
+  
+  return (
+    <div>
+      <PageSizeSelector />
+      <Editor />
+    </div>
+  );
+}
+```
+
+### Export Functionality
+
+```tsx
+import { Editor, useExport } from 'lax-wp-editor';
+
+function EditorWithExport() {
+  const editorRef = useRef(null);
+  const { 
+    downloadTextFile, 
+    downloadJsonFile, 
+    downloadMarkdownFile, 
+    downloadHtmlFile 
+  } = useExport(editorRef.current);
+  
+  return (
+    <div>
+      <div className="export-buttons">
+        <button onClick={downloadTextFile}>Download as Text</button>
+        <button onClick={downloadJsonFile}>Download as JSON</button>
+        <button onClick={downloadMarkdownFile}>Download as Markdown</button>
+        <button onClick={downloadHtmlFile}>Download as HTML</button>
+      </div>
+      <Editor ref={editorRef} />
+    </div>
+  );
+}
+```
+
+### Switching Toolbar Modes
+
+```tsx
+import { Editor, ToolbarProvider, ToolbarDropdown } from 'lax-wp-editor';
+
+function EditorWithToolbarSwitch() {
+  return (
+    <ToolbarProvider>
+      <ToolbarDropdown onToolbarChange={(type) => console.log('Toolbar changed to:', type)} />
+      <Editor />
+    </ToolbarProvider>
+  );
+}
+```
+
+## Development
+
+### Building the Package
+
+```bash
+npm run build
+```
+
+### Linting
+
+```bash
+npm run lint
+```
+
+## Keywords
+
+`wysiwyg`, `editor`, `react`, `tiptap`, `wordpress`, `rich-text`, `text-editor`, `markdown`, `html-editor`, `document-editor`, `export`, `typescript`
+
+## Contributing
+
+Contributions are welcome! Here's how you can help:
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+Please make sure to:
+- Follow the existing code style
+- Add tests for new features
+- Update documentation as needed
+- Test your changes thoroughly
+
+## License
+
+MIT © Rifat Hasan Shaun
+
+## Author
+
+**Rifat Hasan Shaun**
+- Email: mdrifathasanshaun@gmail.com
+- GitHub: [@rifat-shaun](https://github.com/rifat-shaun)
+
+## Support
+
+If you have any questions or need help, please:
+- Open an issue on [GitHub](https://github.com/rifat-shaun/wp-editor/issues)
+- Check the [documentation](https://github.com/rifat-shaun/wp-editor#readme)
+- Review the examples in this README