eddyter 1.3.70 → 1.3.72

package/README.md

@@ -1,6 +1,6 @@
 # Eddyter
 
-A configurable rich text editor component with AI-powered features and API key authentication.
+A powerful, configurable rich text editor built on [Lexical](https://lexical.dev/) with AI capabilities, dark mode support, and API key authentication.
 
 ## Installation
 
@@ -8,44 +8,48 @@ A configurable rich text editor component with AI-powered features and API key a
 npm install eddyter
 # or
 yarn add eddyter
+# or
+pnpm add eddyter
 ```
 
-## Features
+### Compatibility
 
-- Rich text editor with extensive formatting options
-- API key authentication
-- Configurable UI components (toolbar, floating menu)
-- HTML view option
-- Support for tables, images, links, and more
-- AI chat integration (for premium plans)
-- Environment-based API configuration
+| Requirement | Version |
+|-------------|---------|
+| React | 18.2+ or 19.x |
+| React DOM | 18.2+ or 19.x |
+| Node.js | 16+ |
 
-## Usage
+## Quick Start
 
-### Important: Importing Styles
-To ensure proper styling of the editor components including tables, you must import the package's CSS:
+### 1. Import styles
 
-```jsx
-// Import the styles in your application
+```tsx
 import 'eddyter/style.css';
 ```
 
-### Basic Setup
+> **Important:** The stylesheet is required for tables, toolbars, and all editor components to render correctly.
+
+### 2. Get your API key
 
-```jsx
+1. Create an account at [eddyter.com](https://www.eddyter.com/)
+2. Navigate to [License Keys](https://www.eddyter.com/user/license-key) in your dashboard
+3. Copy your API key
+
+### 3. Add the editor
+
+```tsx
 import React from 'react';
 import {
   ConfigurableEditorWithAuth,
   EditorProvider,
   defaultEditorConfig
 } from 'eddyter';
-// Import required styles
 import 'eddyter/style.css';
 
 function App() {
-  const apiKey = 'your-api-key'; // Replace with your actual API key
+  const apiKey = process.env.NEXT_PUBLIC_EDITOR_API_KEY!;
 
-  // Current logged-in user for comments
   const currentUser = {
     id: 'user-123',
     name: 'John Doe',
@@ -53,11 +57,6 @@ function App() {
     avatar: 'https://example.com/avatar.jpg' // optional
   };
 
-  const handleContentChange = (html) => {
-    console.log('Editor HTML content:', html);
-    // Handle the HTML content (save to state, send to server, etc.)
-  };
-
   return (
     <EditorProvider
       defaultFontFamilies={defaultEditorConfig.defaultFontFamilies}
@@ -65,156 +64,235 @@ function App() {
     >
       <ConfigurableEditorWithAuth
         apiKey={apiKey}
-        onChange={handleContentChange}
-        initialContent="<p>Welcome to the editor!</p>"
-        mentionUserList={["Alice", "Bob", "Charlie"]}
-        onAuthSuccess={() => console.log('Authentication successful')}
-        onAuthError={(error) => console.error('Authentication error:', error)}
+        onChange={(html) => console.log('Content:', html)}
+        initialContent="<p>Start writing...</p>"
+        mentionUserList={['Alice', 'Bob', 'Charlie']}
+        onAuthSuccess={() => console.log('Editor ready!')}
+        onAuthError={(error) => console.error('Auth failed:', error)}
       />
     </EditorProvider>
   );
 }
 ```
 
+## Features
+
+### Text & Formatting
+- Bold, italic, underline, strikethrough, subscript, superscript
+- Text color and background highlight with color picker
+- 20+ font families with adjustable font sizes
+- Text alignment (left, center, right, justify)
+- Line height and letter spacing controls
+
+### Lists & Structure
+- Bullet lists, numbered lists (decimal, alpha, roman)
+- Interactive checklists with strikethrough
+- Headings (H1-H6), blockquotes
+- Horizontal rules
+
+### Tables
+- Insert/delete rows and columns, merge cells
+- Drag-to-resize columns and rows
+- Header row styling
+- Row striping with custom colors
+- Right-click context menu for table actions
+
+### Media
+- Image upload with drag-drop and 8-point resize handles
+- Video embed with drag-drop and paste support
+- File attachments (downloadable files)
+- Link insertion with floating editor
+- Automatic link preview on hover
+- Rich embeds for external content (YouTube, etc.)
+
+### AI Features (Premium)
+- AI Chat assistant for content help
+- Smart autocomplete (AI-powered text suggestions)
+- Real-time grammar check and corrections
+- Text enhancement (improve, shorten, expand)
+- Tone adjustment (formal, casual, professional)
+- AI image generation from text prompts
+
+### Advanced
+- Slash commands (`/` for quick formatting)
+- @Mentions with customizable user list
+- Inline comments with bubble UI and sidebar
+- Note panels (info, warning, error, success)
+- Code blocks with syntax highlighting
+- Interactive charts
+- Digital signature capture
+- Voice input / transcription
+- Export to PDF
+- HTML view toggle
+- Drag-and-drop block reordering
+- Markdown shortcuts
+
+### Dark Mode
+
+The editor automatically detects your app's theme:
+- Checks for `dark` class on `<html>` or `<body>`
+- Falls back to `prefers-color-scheme: dark` system preference
+- Or set explicitly via the `darkMode` prop on `EditorProvider`
+
+### Preview Mode
+
+Display saved editor content in read-only mode with interactive features:
+
+```tsx
+<ConfigurableEditorWithAuth
+  apiKey={apiKey}
+  mode="preview"
+  initialContent={savedHtml}
+  onPreviewClick={() => setMode('edit')}
+  previewClassName="my-preview-styles"
+/>
+```
+
 ## API Reference
 
-### EditorProvider
+### `<EditorProvider>`
 
-Provides authentication and configuration context for the editor.
+Provides authentication and configuration context. Must wrap the editor component.
 
-#### Props
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `children` | `ReactNode` | Yes | Editor component to render |
+| `defaultFontFamilies` | `string[]` | No | Font family names for the font selector |
+| `currentUser` | `CurrentUser` | No | Current user for comments feature |
+| `enableLinkPreview` | `boolean` | No | Enable link preview on hover (default: `true`) |
+| `apiKey` | `string` | No | API key for link preview in read-only mode |
 
-- `children`: React nodes to render
-- `defaultFontFamilies`: Array of font names (optional)
-- `currentUser`: Current logged-in user for comments (optional) - Object with `id`, `name`, `email`, and optional `avatar`
-- `enableLinkPreview`: Enable automatic link preview on hover (optional, default: `true`)
-- `apiKey`: API key for authentication (optional) - Required only if you need link preview to work immediately without opening the editor first
+#### CurrentUser Type
 
-### ConfigurableEditorWithAuth
+```ts
+interface CurrentUser {
+  id: string;
+  name: string;
+  email: string;
+  avatar?: string;
+}
+```
 
-The main editor component with authentication.
+### `<ConfigurableEditorWithAuth>`
 
-#### Props
+The main editor component with authentication.
 
-- `apiKey`: Your API key for authentication (required)
-- `initialContent`: Initial HTML content for the editor (optional) - string
-- `onChange`: Callback function when editor content changes (optional) - receives HTML string
-- `defaultFontFamilies`: Array of font names for the font selector (optional)
-- `mentionUserList`: Array of usernames for mention functionality (optional) - Array of strings like `["Alice", "Bob", "Charlie"]`
-- `onAuthSuccess`: Callback function when authentication is successful (optional)
-- `onAuthError`: Callback function when authentication fails (optional)
-- `customVerifyKey`: Custom function to verify API key (optional)
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `apiKey` | `string` | Yes | Your API key for authentication |
+| `initialContent` | `string` | No | Initial HTML content |
+| `onChange` | `(html: string) => void` | No | Content change callback |
+| `defaultFontFamilies` | `string[]` | No | Font names for the font selector |
+| `mentionUserList` | `string[]` | No | Usernames for @mention feature |
+| `onAuthSuccess` | `() => void` | No | Called when authentication succeeds |
+| `onAuthError` | `(error: string) => void` | No | Called when authentication fails |
+| `customVerifyKey` | `(key: string) => Promise<ApiResponse>` | No | Custom key verification function |
+| `mode` | `"edit" \| "preview"` | No | Editor mode (default: `"edit"`) |
+| `previewClassName` | `string` | No | CSS class for preview container |
+| `previewStyle` | `React.CSSProperties` | No | Inline styles for preview container |
+| `onPreviewClick` | `() => void` | No | Click handler for preview mode |
+| `enableReactNativeBridge` | `boolean` | No | Enable React Native WebView bridge |
+| `onEditorReady` | `() => void` | No | Called when editor is fully loaded |
+| `onFocus` | `() => void` | No | Called on editor focus |
+| `onBlur` | `() => void` | No | Called on editor blur |
+| `onHeightChange` | `(height: number) => void` | No | Called when editor height changes |
 
 ## Examples
 
-### Basic Editor with Authentication
+### Basic Editor
 
-```jsx
-import React from 'react';
+```tsx
 import { ConfigurableEditorWithAuth, EditorProvider } from 'eddyter';
 import 'eddyter/style.css';
 
-function App() {
+export default function BasicEditor() {
   return (
     <EditorProvider>
       <ConfigurableEditorWithAuth
         apiKey="your-api-key"
-        onAuthSuccess={() => console.log('Authenticated')}
-        onAuthError={(error) => console.error(error)}
+        onAuthSuccess={() => console.log('Ready!')}
       />
     </EditorProvider>
   );
 }
 ```
 
-### Editor with Content Handling
+### Editor with State Management
 
-```jsx
-import React, { useState } from 'react';
+```tsx
+import { useState } from 'react';
 import { ConfigurableEditorWithAuth, EditorProvider } from 'eddyter';
 import 'eddyter/style.css';
 
-function App() {
-  const [editorContent, setEditorContent] = useState('');
-
-  // Current user (typically from your auth system)
-  const currentUser = {
-    id: 'user-456',
-    name: 'Jane Smith',
-    email: 'jane@example.com'
-  };
-
-  const handleContentChange = (html) => {
-    setEditorContent(html);
-    console.log('Current content:', html);
-    // You can also save to localStorage, send to API, etc.
-  };
+export default function EditorWithState() {
+  const [content, setContent] = useState('<p>Start writing...</p>');
 
-  const handleSave = () => {
-    // Save the HTML content to your backend or localStorage
-    localStorage.setItem('saved-content', editorContent);
-    console.log('Content saved!');
-  };
-
-  const loadSavedContent = () => {
-    const saved = '<p>Start writing your content here...</p>';
-    return saved;
+  const handleSave = async () => {
+    await fetch('/api/save', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ content })
+    });
   };
 
   return (
     <div>
-      <EditorProvider currentUser={currentUser}>
+      <EditorProvider>
         <ConfigurableEditorWithAuth
           apiKey="your-api-key"
-          initialContent={loadSavedContent()}
-          onChange={handleContentChange}
-          defaultFontFamilies={['Arial', 'Helvetica', 'Times New Roman']}
-          mentionUserList={['Alice', 'Bob', 'Charlie']}
-          onAuthSuccess={() => console.log('Ready to edit!')}
-          onAuthError={(error) => console.error('Auth failed:', error)}
+          initialContent={content}
+          onChange={setContent}
         />
       </EditorProvider>
+      <button onClick={handleSave}>Save</button>
+    </div>
+  );
+}
+```
 
-      <button onClick={handleSave} style={{ marginTop: '10px', padding: '10px' }}>
-        Save Content
-      </button>
+### Editor with Comments & Mentions
 
-      <div style={{ marginTop: '20px', padding: '10px', background: '#f5f5f5' }}>
-        <h3>Current HTML Content:</h3>
-        <pre>{editorContent}</pre>
-      </div>
-    </div>
+```tsx
+import { ConfigurableEditorWithAuth, EditorProvider } from 'eddyter';
+import 'eddyter/style.css';
+
+export default function EditorWithComments({ user }) {
+  const currentUser = {
+    id: user.id,
+    name: user.name,
+    email: user.email,
+    avatar: user.avatarUrl
+  };
+
+  return (
+    <EditorProvider currentUser={currentUser}>
+      <ConfigurableEditorWithAuth
+        apiKey="your-api-key"
+        mentionUserList={['Alice', 'Bob', 'Charlie']}
+      />
+    </EditorProvider>
   );
 }
 ```
 
 ### Custom API Key Verification
 
-```jsx
-import React from 'react';
+```tsx
 import { ConfigurableEditorWithAuth, EditorProvider } from 'eddyter';
 import 'eddyter/style.css';
 
-function App() {
-  const customVerifyKey = async (apiKey) => {
+export default function EditorWithCustomAuth() {
+  const customVerifyKey = async (apiKey: string) => {
     try {
       const response = await fetch('/api/verify-key', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({ apiKey })
       });
-
       const data = await response.json();
-
-      return {
-        success: data.valid,
-        message: data.message || 'API key verified'
-      };
-    } catch (error) {
-      return {
-        success: false,
-        message: 'Failed to verify API key'
-      };
+      return { success: data.valid, message: data.message || 'Verified' };
+    } catch {
+      return { success: false, message: 'Verification failed' };
     }
   };
 
@@ -223,71 +301,43 @@ function App() {
       <ConfigurableEditorWithAuth
         apiKey="your-api-key"
         customVerifyKey={customVerifyKey}
-        onChange={(html) => console.log('Content changed:', html)}
       />
     </EditorProvider>
   );
 }
 ```
 
-## Link Preview Feature
-
-Eddyter includes automatic link preview on hover. When users hover over links in content wrapped by `EditorProvider`, a preview popup shows the link's title, description, and image.
-
-### How It Works
-
-- **Inside the editor**: Link preview works automatically after authentication
-- **Outside the editor** (preview mode, saved content): Link preview works if the user has opened the editor at least once in the session (authentication stores the API key)
-
-### Preview-Only Scenarios
-
-If your application displays saved content without ever opening the editor (e.g., a read-only view), you need to pass `apiKey` to `EditorProvider`:
-
-```jsx
-import React from 'react';
-import { EditorProvider } from 'eddyter';
-import 'eddyter/style.css';
+## Link Preview
 
-function ContentPreviewPage({ savedHtml }) {
-  return (
-    <EditorProvider apiKey="your-api-key">
-      <div dangerouslySetInnerHTML={{ __html: savedHtml }} />
-    </EditorProvider>
-  );
-}
-```
+The editor includes automatic link preview on hover.
 
-### Disabling Link Preview
+- **Inside the editor**: Works automatically after authentication
+- **Read-only content**: Pass `apiKey` to `EditorProvider`
+- **Disable**: Set `enableLinkPreview={false}` on `EditorProvider`
 
-To disable link preview entirely:
+```tsx
+// Read-only content with link preview
+<EditorProvider apiKey="your-api-key">
+  <div dangerouslySetInnerHTML={{ __html: savedHtml }} />
+</EditorProvider>
 
-```jsx
+// Disable link preview
 <EditorProvider enableLinkPreview={false}>
-  {/* Your content */}
+  {/* content */}
 </EditorProvider>
 ```
 
----
-
 ## React Native Integration
 
-You can use Eddyter in React Native applications via WebView by loading a deployed version of the editor.
-
-### Prerequisites
+Use Eddyter in React Native via WebView by loading a deployed version of the editor.
 
 ```bash
 npm install react-native-webview
-# or
-yarn add react-native-webview
 ```
 
-### RichTextEditor Component
-
-Create a reusable `RichTextEditor` component that wraps the WebView:
-
 ```tsx
 import React, { useRef, useState, useCallback } from 'react';
-import { View, ActivityIndicator, Text, StyleSheet } from 'react-native';
+import { View, ActivityIndicator, KeyboardAvoidingView, Platform } from 'react-native';
 import { WebView, WebViewMessageEvent } from 'react-native-webview';
 
 interface RichTextEditorProps {
@@ -302,11 +352,6 @@ interface RichTextEditorProps {
   onAuthError?: (error: string) => void;
 }
 
-interface WebViewMessage {
-  type: string;
-  payload?: Record<string, unknown>;
-}
-
 export const RichTextEditor: React.FC<RichTextEditorProps> = ({
   editorBaseUrl,
   apiKey,
@@ -320,7 +365,6 @@ export const RichTextEditor: React.FC<RichTextEditorProps> = ({
 }) => {
   const webViewRef = useRef<WebView>(null);
   const [isLoading, setIsLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
 
   const buildEditorUrl = () => {
     const baseUrl = editorBaseUrl.replace(/\/$/, '');
@@ -332,33 +376,25 @@ export const RichTextEditor: React.FC<RichTextEditorProps> = ({
 
   const handleMessage = useCallback((event: WebViewMessageEvent) => {
     try {
-      const message: WebViewMessage = JSON.parse(event.nativeEvent.data);
-
+      const message = JSON.parse(event.nativeEvent.data);
       switch (message.type) {
         case 'EDITOR_READY':
           setIsLoading(false);
           onReady?.();
-          // Send initial content after editor is ready
           if (initialContent && webViewRef.current) {
             webViewRef.current.postMessage(
-              JSON.stringify({
-                type: 'SET_CONTENT',
-                payload: { content: initialContent },
-              })
+              JSON.stringify({ type: 'SET_CONTENT', payload: { content: initialContent } })
             );
           }
           break;
-
         case 'CONTENT_CHANGE':
-          onChange?.(message.payload?.content as string || '');
+          onChange?.(message.payload?.content || '');
           break;
-
         case 'AUTH_SUCCESS':
           onAuthSuccess?.();
           break;
-
         case 'AUTH_ERROR':
-          onAuthError?.(message.payload?.error as string);
+          onAuthError?.(message.payload?.error);
           break;
       }
     } catch (e) {
@@ -366,121 +402,70 @@ export const RichTextEditor: React.FC<RichTextEditorProps> = ({
     }
   }, [onChange, onReady, onAuthSuccess, onAuthError, initialContent]);
 
-  const handleError = useCallback((syntheticEvent: any) => {
-    const { nativeEvent } = syntheticEvent;
-    setError(nativeEvent.description || 'Failed to load editor');
-    setIsLoading(false);
-  }, []);
-
-  if (error) {
-    return (
-      <View style={styles.errorContainer}>
-        <Text style={styles.errorText}>Failed to load editor</Text>
-        <Text style={styles.errorDetail}>{error}</Text>
-      </View>
-    );
-  }
-
   return (
-    <View style={[styles.container, style]}>
+    <View style={[{ flex: 1 }, style]}>
       <WebView
         ref={webViewRef}
         source={{ uri: buildEditorUrl() }}
-        style={styles.webview}
+        style={{ flex: 1 }}
         onMessage={handleMessage}
-        onError={handleError}
         javaScriptEnabled={true}
         domStorageEnabled={true}
-        startInLoadingState={false}
-        scalesPageToFit={true}
-        allowsInlineMediaPlayback={true}
         keyboardDisplayRequiresUserAction={false}
       />
       {isLoading && (
-        <View style={styles.loadingOverlay}>
-          <ActivityIndicator size="large" color="#007AFF" />
+        <View style={{ position: 'absolute', top: 0, left: 0, right: 0, bottom: 0, justifyContent: 'center', alignItems: 'center' }}>
+          <ActivityIndicator size="large" />
         </View>
       )}
     </View>
   );
 };
-
-const styles = StyleSheet.create({
-  container: { flex: 1 },
-  webview: { flex: 1, backgroundColor: 'transparent' },
-  loadingOverlay: {
-    ...StyleSheet.absoluteFillObject,
-    justifyContent: 'center',
-    alignItems: 'center',
-    backgroundColor: 'rgba(255, 255, 255, 0.9)',
-  },
-  errorContainer: { flex: 1, justifyContent: 'center', alignItems: 'center', padding: 20 },
-  errorText: { fontSize: 18, fontWeight: 'bold', color: '#FF3B30' },
-  errorDetail: { fontSize: 14, color: '#666', marginTop: 8, textAlign: 'center' },
-});
-```
-
-### Usage Example
-
-```tsx
-import React, { useState } from 'react';
-import { View, KeyboardAvoidingView, Platform } from 'react-native';
-import { RichTextEditor } from './components/RichTextEditor';
-
-const EDITOR_CONFIG = {
-  editorBaseUrl: 'https://your-deployed-editor-url.com',
-  apiKey: 'your-api-key',
-};
-
-function NoteEditorScreen() {
-  const [content, setContent] = useState('');
-
-  return (
-    <KeyboardAvoidingView
-      style={{ flex: 1 }}
-      behavior={Platform.OS === 'ios' ? 'padding' : 'height'}
-    >
-      <RichTextEditor
-        editorBaseUrl={EDITOR_CONFIG.editorBaseUrl}
-        apiKey={EDITOR_CONFIG.apiKey}
-        theme="light"
-        initialContent="<p>Start writing...</p>"
-        onChange={setContent}
-        onReady={() => console.log('Editor ready')}
-        onAuthSuccess={() => console.log('Authenticated')}
-        onAuthError={(error) => console.error('Auth failed:', error)}
-      />
-    </KeyboardAvoidingView>
-  );
-}
 ```
 
 ### Message Protocol
 
-The editor and React Native communicate via `postMessage`. Here are the supported message types:
-
 | Message Type | Direction | Description |
-|--------------|-----------|-------------|
+|---|---|---|
 | `EDITOR_READY` | Editor → RN | Editor has finished loading |
-| `CONTENT_CHANGE` | Editor → RN | Content was modified (payload: `{ content: string }`) |
-| `AUTH_SUCCESS` | Editor → RN | API key authentication succeeded |
-| `AUTH_ERROR` | Editor → RN | Authentication failed (payload: `{ error: string }`) |
-| `SET_CONTENT` | RN → Editor | Set editor content (payload: `{ content: string }`) |
+| `CONTENT_CHANGE` | Editor → RN | Content was modified (`{ content: string }`) |
+| `AUTH_SUCCESS` | Editor → RN | Authentication succeeded |
+| `AUTH_ERROR` | Editor → RN | Authentication failed (`{ error: string }`) |
+| `SET_CONTENT` | RN → Editor | Set editor content (`{ content: string }`) |
 
-### Sending Content to Editor
+## Exports
 
-After receiving the `EDITOR_READY` message, you can programmatically set content:
+```ts
+// Components
+import {
+  ConfigurableEditorWithAuth,  // Main editor with auth
+  ConfigurableEditor,           // Editor without auth wrapper
+  EditorProvider,               // Context provider
+  LinkPreviewHover,             // Standalone link preview component
+} from 'eddyter';
 
-```tsx
-webViewRef.current?.postMessage(
-  JSON.stringify({
-    type: 'SET_CONTENT',
-    payload: { content: '<p>New content here</p>' },
-  })
-);
-```
+// Hooks & utilities
+import {
+  useEditor,                    // Access editor context
+  useHtmlView,                  // Access HTML view state
+  verifyApiKey,                 // Verify API key programmatically
+  useReactNativeBridge,         // React Native bridge hook
+  isReactNativeWebView,         // Check if running in RN WebView
+} from 'eddyter';
 
----
+// Config
+import { defaultEditorConfig } from 'eddyter';
+
+// Types
+import type {
+  CurrentUser,
+  EditorConfigTypes,
+  LinkPreviewHoverProps,
+  ReactNativeBridgeConfig,
+  ReactNativeMessage,
+  ReactNativeMessageType,
+} from 'eddyter';
+```
 
 ## License
 
@@ -490,4 +475,4 @@ Eddyter is **proprietary software**.
 - **Commercial use requires a paid license**
 - SaaS, redistribution, and competing products are prohibited without permission
 
-For commercial licensing, contact: licensing@yourcompany.com
+For commercial licensing, visit [eddyter.com](https://www.eddyter.com/)