@crashbytes/contentful-richtext-editor 1.0.11 → 2.0.5

package/README.md

@@ -1,179 +1,391 @@
-# Release v2.0.0 - Major Feature Update 🎉
+# Contentful Rich Text Editor
 
-## 🚀 What's New
+A modern, Tiptap-based rich text editor that's fully compatible with Contentful's rich text format. Provides the same editing experience as Contentful's native editor while maintaining perfect compatibility with Contentful's document structure.
 
-This major release introduces **automatic configuration** from Contentful field settings, significantly enhancing the developer experience and ensuring your editor UI always matches your Contentful configuration.
+## ✨ Features
 
-### ✨ Major New Features
+- ✅ **Full Contentful Compatibility** - Seamless conversion between Contentful and Tiptap formats
+- ✅ **Automatic Configuration** - Reads Contentful field settings to auto-configure the editor *(NEW in v2.0)*
+- ✅ **Modern UI** - Clean, intuitive interface matching Contentful's design  
+- ✅ **TypeScript Support** - Complete type safety with Contentful's rich text types
+- ✅ **Extensible** - Built on Tiptap v2 for easy customization
+- ✅ **Lightweight** - Tree-shakeable, only import what you need
+- ✅ **Responsive** - Works on desktop and mobile devices
+- ✅ **Keyboard Shortcuts** - Built-in shortcuts for common actions *(NEW in v2.0)*
 
-- **🔄 Automatic Contentful Configuration**: The editor now reads your Contentful field validation settings and automatically enables/disables toolbar features
-- **📝 Inline Entry Support**: Added support for inline embedded entries (as configured in Contentful)
-- **⌨️ Keyboard Shortcuts**: Built-in shortcuts for common actions (`Cmd/Ctrl + Shift + E` for entries, `Cmd/Ctrl + Shift + A` for assets, etc.)
-- **🔍 Enhanced TypeScript Support**: Comprehensive type definitions and better developer experience
-- **📊 Content Analysis Utilities**: New utilities for word counting, plain text extraction, and content validation
+### Supported Features
 
-### 🔧 Enhanced Features
+- **Text Formatting**: Bold, italic, underline
+- **Headings**: H1 through H6  
+- **Lists**: Ordered and unordered lists
+- **Links**: Hyperlinks with URL validation
+- **Tables**: Full table support with headers
+- **Quotes**: Blockquotes
+- **Embedded Content**: Callbacks for Contentful entries and assets
+- **Inline Entries**: Support for inline embedded entries *(NEW in v2.0)*
+- **Undo/Redo**: Full history support
 
-- **Smart Toolbar**: Toolbar buttons now appear/disappear based on your Contentful field configuration
-- **Better Error Handling**: Improved error messages and validation
-- **Performance Optimizations**: Faster rendering and better memory usage
-- **Accessibility Improvements**: Enhanced ARIA support and keyboard navigation
+## 📦 Installation
 
-### 🎨 Developer Experience
+```bash
+npm install @crashbytes/contentful-richtext-editor
+```
 
-- **Configuration Parser**: New utility to parse Contentful field settings
-- **Mock Configuration**: Easy testing with `createMockFieldConfig()`
-- **Backward Compatibility**: Existing manual configuration still works
-- **Comprehensive Documentation**: Updated with examples and API reference
+## 🚀 Quick Start
 
-## 🛠️ Installation
+### Basic Usage
 
-```bash
-npm install @crashbytes/contentful-richtext-editor@2.0.0
+```tsx
+import React, { useState } from 'react';
+import { ContentfulRichTextEditor } from '@crashbytes/contentful-richtext-editor';
+import '@crashbytes/contentful-richtext-editor/dist/index.css';
+import { Document } from '@contentful/rich-text-types';
+
+function App() {
+  const [content, setContent] = useState<Document>();
+
+  const handleChange = (document: Document) => {
+    setContent(document);
+    console.log('Contentful document:', document);
+  };
+
+  return (
+    <div>
+      <h1>My Rich Text Editor</h1>
+      <ContentfulRichTextEditor
+        placeholder="Start writing your content..."
+        onChange={handleChange}
+        initialValue={content}
+      />
+    </div>
+  );
+}
+
+export default App;
+```
+
+### Automatic Configuration (NEW in v2.0)
+
+The editor can automatically configure itself based on your Contentful field settings:
+
+```tsx
+import { 
+  ContentfulRichTextEditor,
+  fetchContentfulFieldConfig 
+} from '@crashbytes/contentful-richtext-editor';
+import '@crashbytes/contentful-richtext-editor/dist/index.css';
+
+function AutoConfiguredEditor() {
+  const [fieldConfig, setFieldConfig] = useState();
+
+  useEffect(() => {
+    // Fetch configuration from Contentful Management API
+    fetchContentfulFieldConfig(
+      'your-space-id',
+      'your-content-type-id', 
+      'your-field-id',
+      'your-management-token'
+    ).then(setFieldConfig);
+  }, []);
+
+  return (
+    <ContentfulRichTextEditor
+      fieldConfiguration={fieldConfig}
+      placeholder="Auto-configured based on Contentful settings!"
+      onChange={handleChange}
+    />
+  );
+}
+```
+
+### Advanced Usage with Embeds
+
+```tsx
+import { ContentfulRichTextEditor } from '@crashbytes/contentful-richtext-editor';
+import '@crashbytes/contentful-richtext-editor/dist/index.css';
+
+function ContentfulEditor() {
+  const handleEmbedEntry = async () => {
+    // Your logic to select a Contentful entry
+    const entry = await openEntrySelector();
+    return entry;
+  };
+
+  const handleEmbedAsset = async () => {
+    // Your logic to select a Contentful asset  
+    const asset = await openAssetSelector();
+    return asset;
+  };
+
+  const handleEmbedInlineEntry = async () => {
+    // NEW v2.0 - Your logic to select an inline entry
+    const entry = await openInlineEntrySelector();
+    return entry;
+  };
+
+  return (
+    <ContentfulRichTextEditor
+      placeholder="Write your travel tip..."
+      onChange={(doc) => saveToContentful(doc)}
+      onEmbedEntry={handleEmbedEntry}
+      onEmbedAsset={handleEmbedAsset}
+      onEmbedInlineEntry={handleEmbedInlineEntry}
+      theme="contentful"
+    />
+  );
+}
 ```
 
-## 🔄 Migration from v1.x
+### Minimal Configuration
 
-### Automatic Configuration (Recommended)
 ```tsx
-// Before (v1.x)
 <ContentfulRichTextEditor
-  availableHeadings={[1, 2, 3]}
-  availableMarks={['bold', 'italic']}
-  disabledFeatures={['table']}
+  placeholder="Simple editor..."
+  disabledFeatures={['table', 'embed', 'quote']}
+  theme="minimal"
+  readonly={false}
+  showBorder={false}
+  onChange={handleChange}
 />
+```
+
+### With Initial Content
+
+```tsx
+import { createEmptyDocument } from '@crashbytes/contentful-richtext-editor';
+
+const initialContent = {
+  nodeType: 'document',
+  data: {},
+  content: [
+    {
+      nodeType: 'paragraph', 
+      data: {},
+      content: [
+        {
+          nodeType: 'text',
+          value: 'Hello world!',
+          marks: [{ type: 'bold' }],
+          data: {}
+        }
+      ]
+    }
+  ]
+};
 
-// After (v2.x) - Automatically configured!
 <ContentfulRichTextEditor
-  fieldConfiguration={contentfulFieldConfig}
-  onEmbedInlineEntry={handleInlineEntry} // New!
+  initialValue={initialContent}
+  onChange={handleChange}
 />
 ```
 
-### New Props Available
+## 📋 API Reference
+
+### ContentfulRichTextEditor Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `availableHeadings` | `Array<1\|2\|3\|4\|5\|6>` | `[1,2,3,4,5,6]` | Available heading levels (fallback when no fieldConfiguration) |
+| `availableMarks` | `Array<'bold'\|'italic'\|'underline'>` | `['bold','italic','underline']` | Available text formatting marks (fallback when no fieldConfiguration) |
+| `className` | `string` | `''` | Additional CSS classes |
+| `disabledFeatures` | `Array<string>` | `[]` | Features to disable |
+| `fieldConfiguration` | `ContentfulFieldConfiguration` | `undefined` | **NEW v2.0** - Contentful field validation config (takes precedence over manual settings) |
+| `initialValue` | `Document` | `undefined` | Initial Contentful rich text document |
+| `onChange` | `(document: Document) => void` | `undefined` | Callback when content changes |
+| `onEmbedAsset` | `() => Promise<any> \| void` | `undefined` | Callback for embedding Contentful assets |
+| `onEmbedEntry` | `() => Promise<any> \| void` | `undefined` | Callback for embedding Contentful entries |
+| `onEmbedInlineEntry` | `() => Promise<any> \| void` | `undefined` | **NEW v2.0** - Callback for embedding inline entries |
+| `placeholder` | `string` | `'Start writing...'` | Placeholder text |
+| `readonly` | `boolean` | `false` | Whether editor is read-only |
+| `showBorder` | `boolean` | `true` | Whether to show border around the editor |
+| `theme` | `'default' \| 'minimal' \| 'contentful'` | `'contentful'` | Visual theme |
+
+### Disabled Features
+
+You can disable specific features by passing them in the `disabledFeatures` array:
+
+- `'bold'` - Bold text formatting
+- `'italic'` - Italic text formatting  
+- `'underline'` - Underline text formatting
+- `'link'` - Hyperlinks
+- `'lists'` - Ordered and unordered lists
+- `'headings'` - All heading levels
+- `'quote'` - Blockquotes
+- `'table'` - Tables
+- `'embed'` - Embedded content
+
+### Configuration Types (NEW v2.0)
+
 ```tsx
-interface ContentfulRichTextEditorProps {
-  // New in v2.0
-  fieldConfiguration?: ContentfulFieldConfiguration;
-  onEmbedInlineEntry?: () => Promise<any> | void;
-  
-  // Existing props still work (backward compatible)
-  availableHeadings?: Array<1 | 2 | 3 | 4 | 5 | 6>;
-  availableMarks?: Array<'bold' | 'italic' | 'underline'>;
-  disabledFeatures?: Array<string>;
+interface ContentfulFieldConfiguration {
+  validations?: Array<{
+    enabledMarks?: string[];        // ['bold', 'italic', 'underline', 'code']
+    enabledNodeTypes?: string[];    // ['paragraph', 'heading-1', 'unordered-list', ...]
+  }>;
+  settings?: {
+    helpText?: string;
+  };
 }
 ```
 
-### Fetching Configuration from Contentful
+## 🛠️ Utility Functions
+
 ```tsx
-import { fetchContentfulFieldConfig } from '@crashbytes/contentful-richtext-editor';
+import {
+  contentfulToTiptap,
+  tiptapToContentful,
+  validateContentfulDocument,
+  createEmptyDocument,
+  extractPlainText,        // NEW v2.0
+  countWords,             // NEW v2.0
+  findEmbeddedContent,    // NEW v2.0
+  sanitizeContentfulDocument // NEW v2.0
+} from '@crashbytes/contentful-richtext-editor';
+
+// Convert between formats
+const tiptapJson = contentfulToTiptap(contentfulDocument);
+const contentfulDoc = tiptapToContentful(tiptapJson);
+
+// Validation
+const isValid = validateContentfulDocument(someDocument);
 
-const fieldConfig = await fetchContentfulFieldConfig(
-  'space-id',
-  'content-type-id',
-  'field-id',
-  'management-token'
+// Create empty document
+const emptyDoc = createEmptyDocument();
+
+// NEW v2.0 - Content analysis
+const plainText = extractPlainText(contentfulDocument);
+const wordCount = countWords(contentfulDocument);
+const embedded = findEmbeddedContent(contentfulDocument);
+
+// NEW v2.0 - Sanitize content
+const sanitized = sanitizeContentfulDocument(
+  document,
+  ['paragraph', 'heading-1', 'unordered-list'], // allowed nodes
+  ['bold', 'italic'] // allowed marks
 );
 ```
 
-## 📋 New Utilities
+## ⌨️ Keyboard Shortcuts (NEW v2.0)
 
-### Content Analysis
-```tsx
-import { 
-  extractPlainText, 
-  countWords, 
-  findEmbeddedContent,
-  sanitizeContentfulDocument 
-} from '@crashbytes/contentful-richtext-editor';
+- `Cmd/Ctrl + B` - Bold
+- `Cmd/Ctrl + I` - Italic
+- `Cmd/Ctrl + U` - Underline
+- `Cmd/Ctrl + K` - Add/edit link
+- `Cmd/Ctrl + Shift + E` - Embed entry
+- `Cmd/Ctrl + Shift + A` - Embed asset
+- `Cmd/Ctrl + Shift + I` - Embed inline entry
+- `Cmd/Ctrl + Z` - Undo
+- `Cmd/Ctrl + Y` / `Cmd/Ctrl + Shift + Z` - Redo
 
-const plainText = extractPlainText(document);
-const wordCount = countWords(document);
-const embedded = findEmbeddedContent(document);
-```
+## 🎨 Styling
+
+The editor comes with default styles that match Contentful's design. Import the CSS:
 
-### Configuration Management
 ```tsx
-import { 
-  parseContentfulFieldConfig,
-  createMockFieldConfig 
-} from '@crashbytes/contentful-richtext-editor';
+import '@crashbytes/contentful-richtext-editor/dist/index.css';
+```
+
+You can override the default styles by targeting the CSS classes:
+
+```css
+.contentful-editor {
+  border: 2px solid #your-color;
+}
 
-// Parse Contentful config
-const parsed = parseContentfulFieldConfig(fieldConfig);
+.contentful-toolbar {
+  background: #your-background;
+}
+
+.contentful-editor-content {
+  font-family: 'Your Font', sans-serif;
+}
 
-// Create mock for testing
-const mockConfig = createMockFieldConfig({
-  enabledMarks: ['bold', 'italic'],
-  enabledNodeTypes: ['paragraph', 'heading-1', 'unordered-list']
-});
+/* NEW v2.0 - Inline entries */
+.contentful-inline-embedded-entry {
+  background: #e8f4fd;
+  padding: 2px 4px;
+  border-radius: 3px;
+  font-weight: 600;
+}
 ```
 
-## ⌨️ New Keyboard Shortcuts
+### Themes
 
-- `Cmd/Ctrl + Shift + E` - Embed entry
-- `Cmd/Ctrl + Shift + A` - Embed asset  
-- `Cmd/Ctrl + Shift + I` - Embed inline entry
-- `Cmd/Ctrl + K` - Add/edit link
-- Standard formatting shortcuts (Bold, Italic, Underline)
+**`contentful`** (default)  
+Matches Contentful's native editor appearance.
 
-## 🐛 Bug Fixes
+**`minimal`**  
+Clean, minimal design with reduced visual elements.
 
-- Fixed TypeScript compilation warnings
-- Improved link handling in complex nested structures
-- Fixed table rendering issues
-- Better handling of embedded content transformation
-- Resolved build process issues
+**`default`**  
+Standard rich text editor appearance with serif fonts.
 
-## 🔧 Technical Improvements
+## ⚛️ Next.js Integration
 
-- **Build System**: Improved Rollup configuration
-- **Type Safety**: Better TypeScript definitions throughout
-- **Performance**: Optimized re-renders and memory usage
-- **Code Quality**: Enhanced error boundaries and validation
+```tsx
+// pages/editor.tsx or app/editor/page.tsx
+import dynamic from 'next/dynamic';
 
-## 📚 Documentation
+const ContentfulEditor = dynamic(
+  () => import('@crashbytes/contentful-richtext-editor').then(mod => mod.ContentfulRichTextEditor),
+  { ssr: false }
+);
 
-- **Complete API Reference**: Full documentation of all props and methods
-- **Usage Examples**: 5 different implementation examples
-- **Migration Guide**: Step-by-step upgrade instructions
-- **TypeScript Support**: Full type definitions and examples
+export default function EditorPage() {
+  return (
+    <div>
+      <ContentfulEditor
+        placeholder="Write something amazing..."
+        onChange={(doc) => console.log(doc)}
+      />
+    </div>
+  );
+}
+```
 
-## 🎯 What's Next
+## 🔷 TypeScript Support
 
-We're already working on v2.1 with:
-- Real-time collaboration support
-- Advanced table editing features
-- Plugin system for custom extensions
-- More keyboard shortcuts and accessibility improvements
+This package is written in TypeScript and includes full type definitions. All Contentful rich text types are re-exported for convenience:
 
-## 🤝 Contributing
+```tsx
+import type {
+  Document,
+  Block,
+  Inline,
+  Text,
+  ContentfulRichTextEditorProps,
+  ContentfulFieldConfiguration,    // NEW v2.0
+  ParsedEditorConfig              // NEW v2.0
+} from '@crashbytes/contentful-richtext-editor';
+```
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+## 🌐 Browser Support
 
-## 📖 Full Documentation
+- Chrome 80+
+- Firefox 78+
+- Safari 13+
+- Edge 80+
 
-- [README](README.md) - Complete setup and usage guide
-- [API Reference](docs/API.md) - Detailed prop and method documentation
-- [Examples](examples/) - Implementation examples
-- [Changelog](CHANGELOG.md) - Complete version history
+## 🤝 Contributing
 
-## 🔗 Links
+Contributions are welcome! Please feel free to submit a Pull Request.
 
-- **GitHub**: https://github.com/your-org/contentful-richtext-editor
-- **npm**: https://www.npmjs.com/package/@crashbytes/contentful-richtext-editor
-- **Issues**: https://github.com/your-org/contentful-richtext-editor/issues
-- **Discussions**: https://github.com/your-org/contentful-richtext-editor/discussions
+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
 
-## 💝 Acknowledgments
+## 📄 License
 
-Special thanks to:
-- The Contentful team for their excellent Rich Text API
-- The TipTap team for the amazing editor framework
-- All early adopters and contributors who provided feedback
+MIT © [CrashBytes](https://github.com/CrashBytes)
 
----
+## 🔗 Related Packages
+
+- [@contentful/rich-text-react-renderer](https://www.npmjs.com/package/@contentful/rich-text-react-renderer) - For rendering Contentful rich text
+- [@contentful/rich-text-types](https://www.npmjs.com/package/@contentful/rich-text-types) - Contentful rich text type definitions  
+- [@tiptap/react](https://www.npmjs.com/package/@tiptap/react) - The underlying editor framework
 
-**Full Changelog**: https://github.com/your-org/contentful-richtext-editor/compare/v1.0.10...v2.0.0
+---
 
-**Happy editing! 🎉**
+Made with ❤️ for the Contentful community

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crashbytes/contentful-richtext-editor",
-  "version": "1.0.11",
+  "version": "2.0.5",
   "description": "A Tiptap-based rich text editor compatible with Contentful's rich text format",
   "type": "module",
   "main": "dist/index.js",
@@ -9,6 +9,9 @@
   "files": [
     "dist"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "keywords": [
     "contentful",
     "tiptap",