@revinity/helios-editor

v4.3.0

Published

a month ago

A comprehensive React rich text editor component with Word document import, image upload, resize functionality, and standalone CSS. Ready for NPM publishing.

0High
0Medium
0Low

revinity-consulting

react helios-editor rich-text-editor standalone-css wysiwyg contenteditable text-editor image-upload image-resize npm-package github-packages

HeliosEditor - A React Rich Text Editor Component

HeliosEditor is a comprehensive, parameterized React rich text editor component designed for easy integration and customization. It supports Word document import (.docx), image uploads (via drag-drop, paste, or file dialog), client-side image resizing, and comes with a clean, standalone CSS file. It is configured for publishing to NPM and GitHub Packages.

New in v3.5.0: Added collaboration features including comments and @mentions! The comments feature allows users to add notes to selected text, while the mention feature enables tagging users within the document.

In v3.4.0: Import Word documents (.docx) with full formatting preservation! Supports headings, lists, tables, images, and text formatting using mammoth.js for robust document conversion.

Installation

Install the package from GitHub Packages (Private):

Note: You need access to the private GitHub repository and package to install. Contact Revinity for access.

Prerequisites

Before installing, configure npm to use GitHub Packages:

Create a GitHub Personal Access Token with read:packages scope
- Go to: https://github.com/settings/tokens
- Generate a new token with read:packages scope
Create or edit .npmrc file in your project root:

@revinityconsulting:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

IMPORTANT: Add .npmrc to your .gitignore to avoid committing your token!

Install the package:

npm install @revinityconsulting/helios-editor

You will also need to install the peer dependencies:

npm install react react-dom

Importing the Component and CSS

// Import the component
import HeliosEditor from "@revinityconsulting/helios-editor";

// Import the CSS file
import "@revinityconsulting/helios-editor/dist/editor.css";

Alternative CSS Import Options

You can also import the CSS file in different ways:

In your HTML file:

<link
  rel="stylesheet"
  href="node_modules/@revinityconsulting/helios-editor/dist/editor.css"
/>

Using CSS/SASS imports:

@import "~@revinityconsulting/helios-editor/dist/editor.css";

For webpack configurations, you might need to use:

import "@revinityconsulting/helios-editor/dist/editor.css";

Standalone Implementation

For standalone implementation, you can wrap your editor with the provided CSS classes for better styling and responsive design:

// Import the component
import HeliosEditor from "@revinityconsulting/helios-editor";
import "@revinityconsulting/helios-editor/dist/editor.css";

function MyEditor() {
  const [content, setContent] = useState("");

  return (
    <div className="dz-editor-container dz-editor-reset">
      <HeliosEditor
        value={content}
        onChange={setContent}
        placeholder="Start typing..."
      />
    </div>
  );
}

The standalone CSS includes:

Proper button styling for formatting options (B, I, U, S)
Enhanced dropdown components with wide layouts and selected value display
Visual feedback for active dropdown selections
Responsive design for mobile devices
Properly aligned button groups and separators
Support for theme customization
Improved z-index management for dropdown menus

Publishing to GitHub Packages

To publish new versions of this package, follow these steps:

1. Authenticate with GitHub Packages

You need to authenticate npm with GitHub Packages.

Create a Personal Access Token (PAT): Go to your GitHub Developer Settings and generate a new classic PAT. Grant it the write:packages scope.
Log in: Use the following command to log in, replacing YOUR-USERNAME with your GitHub username and YOUR-PAT with the token you just created.
```
npm login --scope=@revinityconsulting --registry=https://npm.pkg.github.com
```

2. Update Version

Before publishing, update the version in package.json according to semantic versioning rules.

3. Build the Package

Run the build script to transpile the component and generate the distributable files in the dist/ directory.

npm run build

4. Publish

Finally, publish the package to the GitHub Packages registry.

npm publish

Features

Collaboration:
- Comments: Add, view, and manage comments on selected text with a dedicated comments panel
- @Mentions: Tag and mention users in the document with a searchable user picker
Word Document Import: Import .docx files directly into the editor with full formatting preservation
Image Upload: Supports pasting, drag-and-drop, and a toolbar button for image uploads.
Backend Agnostic: Uploads images via a fetch call to a configurable backend endpoint.
Image Resizing: Simple and intuitive client-side image resizing with handles.
Customizable Uploads: Pass API URLs and credentials via the uploadConfig prop.
Clean HTML: The editor is designed to keep the underlying HTML clean from temporary resizing elements.
Standalone CSS: A separate editor.css file for easy styling and customization.
Enhanced Dropdowns: Wide dropdown components that display selected values directly on the button for better user experience.
Visual Feedback: Active dropdown selections are highlighted and the current value is always visible.
Export Functionality: Export content to Word (.doc) format and download as PDF files

Props

`HeliosEditor`

| Prop | Type | Default | Description | | -------------- | -------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | value | string | '' | The HTML content of the editor. | | onChange | func | (html) => {} | A callback function that receives the updated HTML content whenever it changes. | | uploadConfig | object | { clientId: 'default', clientSecret: 'default' } | Configuration for uploads (endpoints, credentials, optional disableEncryption). See uploadConfig section below for more details. | | placeholder | string | 'Compose an epic...' | Placeholder text to display when the editor is empty. |

Quick Start

import React, { useState } from "react";
import HeliosEditor from "@revinityconsulting/helios-editor";
import "@revinityconsulting/helios-editor/dist/editor.css"; // Import the CSS

function MyApp() {
  const [content, setContent] = useState(
    "<p>Welcome to <strong>DZ Rich Text Editor</strong>!</p>"
  );

  return (
    <HeliosEditor
      value={content}
      onChange={setContent}
      placeholder="Start typing..."
    />
  );
}

Image Upload Configuration

To enable image upload functionality, configure the uploadConfig prop:

import React, { useState } from "react";
import HeliosEditor from "@revinityconsulting/helios-editor";

function EditorWithImageUpload() {
  const [content, setContent] = useState("");

  const uploadConfig = {
    uploadApiUrl: "https://your-api.com/upload",
    clientId: "your-client-id",
    clientSecret: "your-client-secret"
  };

  return (
    <HeliosEditor
      value={content}
      onChange={setContent}
      uploadConfig={uploadConfig}
      toolbarOptions={[
        "bold",
        "italic",
        "underline",
        "insertImage", // Enable image insert button
        "link",
        "blockquote",
      ]}
    />
  );
}

Upload API Requirements

Your upload API should:

Accept POST requests to the configured endpoint
Accept FormData with the following fields:
- image: The image file
- client_id: Authentication client ID (optional)
- client_secret: Authentication client secret (optional)

Return JSON response in this format:

{
  "data": {
    "authenticatedUrl": "https://your-cdn.com/path/to/uploaded-image.jpg"
  }
}

Example Backend Implementation (Express.js)

app.post("/upload", upload.single("image"), (req, res) => {
  const { client_id, client_secret } = req.body;

  // Validate credentials
  if (!validateCredentials(client_id, client_secret)) {
    return res.status(401).json({ error: "Invalid credentials" });
  }

  // Upload to your storage (GCS, AWS S3, etc.)
  const imageUrl = uploadToStorage(req.file);

  res.json({
    data: {
      authenticatedUrl: imageUrl,
    },
  });
});

Secure Credential Transport

By default the editor encrypts client_id and client_secret with AES-GCM (key derived from SHA-256("helios_editor_revinity")) and sends a single auth_token to the /validate, /upload, and /upload-document endpoints. Your backend should base64-decode the token, read the first 12 bytes as the IV, and decrypt the remaining bytes with the same derived key to recover the payload:

{
  "client_id": "your-client-id",
  "client_secret": "your-client-secret",
  "timestamp": 1699999999999
}

If you want to fall back to plain credentials (for local debugging or bespoke flows), pass disableEncryption: true in uploadConfig.

Security note: The built-in key lives in client-side code, so treat it as obfuscation rather than strong secret storage. For higher assurance, proxy requests through infrastructure you control and rotate credentials regularly.

Dropdown Features

Enhanced Dropdown Components

The editor includes four main dropdown components, each designed for optimal user experience:

Headings Dropdown:
- Shows current heading level (Normal, Heading 1, Heading 2, etc.)
- Wide layout for better readability
- Visual feedback for active selection
Font Family Dropdown:
- Displays current font selection (Arial, Times New Roman, etc.)
- Font preview in dropdown items
- Wide layout to accommodate font names
Line & Paragraph Spacing Dropdown:
- Shows current spacing setting (Single, 1.5, Double, etc.)
- Includes paragraph spacing options
- Clear visual representation of spacing values
Bullet List Style Dropdown:
- Displays current bullet style (● Disc, ○ Circle, ■ Square)
- Visual bullet previews
- Easy switching between list styles

Dropdown Benefits

Always Visible: Selected values are displayed directly on the dropdown button
Wide Layout: Increased width for better readability and longer text
Visual Feedback: Active selections are highlighted
Consistent Styling: Uniform appearance across all dropdown types
Responsive Design: Adapts to different screen sizes

Word Document Import

Import from Word (.docx)

The HeliosEditor supports importing Microsoft Word documents (.docx) with full formatting preservation using the powerful mammoth.js library.

Features:

✅ Preserves text formatting (bold, italic, underline)
✅ Converts Word headings to HTML headings (H1-H6)
✅ Maintains paragraph structure
✅ Imports lists (ordered and unordered)
✅ Converts embedded images to base64 data URLs
✅ Preserves tables with formatting
✅ Handles blockquotes and code blocks
✅ Full error handling and user feedback

How to Use:

Click the 📥 "Import from Word" button in the toolbar
Select a .docx file from your computer
The document will be converted and loaded into the editor
Images are automatically embedded as base64 data URLs

Example:

<HeliosEditor
  value={content}
  onChange={setContent}
  toolbarOptions={[
    'bold', 'italic', 'underline',
    'headings', 'insertImage',
    'importWord', // Enable Word import
    'exportWord', // Enable Word export
    'exportPDF'   // Enable PDF export
  ]}
/>

Supported Word Features:

Paragraph styles (Normal, Heading 1-6, Quote, Code)
Text formatting (bold, italic, underline, strikethrough)
Lists (bullets, numbers)
Tables
Images (converted to base64)
Links
Text alignment

Note: Only .docx files (Office 2007 and later) are supported. Legacy .doc files are not supported.

PDF Export

Export to PDF

The HeliosEditor supports exporting content as a downloadable PDF file using jsPDF and html2canvas libraries.

Features:

✅ Generates high-quality PDF files
✅ Automatic multi-page support for long documents
✅ Preserves all formatting and styles
✅ Handles images and tables
✅ A4 format with proper margins
✅ Automatic filename with timestamp
✅ Loading indicator during generation

How to Use:

Click the 📄 "Export to PDF" button in the toolbar
Wait for the PDF to be generated (loading indicator will show)
PDF file will automatically download to your downloads folder
Filename format: document-YYYY-MM-DD.pdf

Example:

<HeliosEditor
  value={content}
  onChange={setContent}
  toolbarOptions={[
    'bold', 'italic', 'underline',
    'headings', 'insertImage',
    'importWord',  // Import from Word
    'exportWord',  // Export to Word
    'exportPDF'    // Export to PDF (with download)
  ]}
/>

Technical Details:

Page Format: A4 (210mm x 297mm)
Orientation: Portrait
Quality: High resolution (scale: 2)
Image Support: All images are embedded in PDF
Multi-page: Automatically splits long content across pages

Image Features

Image Upload Methods

Toolbar Button: Click the 🖼️ button to select images from your device
Drag & Drop: Drag images directly into the editor
Paste: Paste images from clipboard (Ctrl+V)

Image Resize Functionality

Images inserted into the editor can be resized:

Click any image to select it (shows blue border with resize handles)
Drag corner handles to resize freely (width and height independently)
Drag edge handles for single-dimension resizing
Click outside to deselect the image

Resize Features:

8 resize handles (4 corners + 4 edges)
No aspect ratio constraints - resize to any dimensions
Minimum size constraints (50px width, 30px height)
Visual feedback during resize operations
Clean HTML output (resize controls are editor-only)

Props API

interface HeliosEditorProps {
  value?: string;
  onChange?: (content: string) => void;
  toolbarOptions?: string[];
  placeholder?: string;
  readOnly?: boolean;
  height?: string;
  width?: string;
  toolbarPosition?: "top" | "bottom";
  stickyToolbar?: boolean;
  stickyOffset?: number;
  debounceTime?: number;
  customClasses?: CustomClasses;
  uploadConfig?: UploadConfig;
}

interface UploadConfig {
  uploadApiUrl?: string;
  clientId?: string;
  clientSecret?: string;
  disableEncryption?: boolean;
}

Core Props

| Prop | Type | Default | Description | | ---------------- | --------------------------- | ------------------- | ----------------------------- | | value | string | '' | HTML content of the editor | | onChange | (content: string) => void | - | Callback when content changes | | toolbarOptions | string[] | All options | Array of toolbar button names | | placeholder | string | 'Start typing...' | Placeholder text | | readOnly | boolean | false | Disable editing | | uploadConfig | UploadConfig | {} | Image upload configuration |

Layout Props

| Prop | Type | Default | Description | | ----------------- | ------------------- | ---------- | --------------------- | | height | string | 'h-64' | CSS height class | | width | string | 'w-full' | CSS width class | | toolbarPosition | 'top' \| 'bottom' | 'top' | Toolbar position | | stickyToolbar | boolean | false | Enable sticky toolbar | | stickyOffset | number | 0 | Sticky toolbar offset |

Performance Props

| Prop | Type | Default | Description | | --------------- | --------------- | ------- | -------------------- | | debounceTime | number | 300 | Debounce delay (ms) | | customClasses | CustomClasses | {} | Override CSS classes |

Toolbar Options

Configure which tools appear in the toolbar:

// Minimal toolbar
<HeliosEditor
  toolbarOptions={['bold', 'italic', 'link']}
  // ... other props
/>

// Full toolbar (default)
<HeliosEditor
  toolbarOptions={[
    'bold', 'italic', 'underline', 'strikethrough', 'subscript', 'superscript',
    'highlight', 'fontColor', 'headings', 'fontFamily',
    'lineSpacing', 'alignLeft', 'alignCenter', 'alignRight',
    'alignJustify', 'unorderedList', 'orderedList', 'todoList',
    'increaseIndent', 'decreaseIndent', 'link', 'insertImage',
    'blockquote', 'codeBlock', 'pageBreak', 'caseChange', 'insertTable',
    'comments', 'mentionUsers', // Collaboration features
    'importWord', 'exportWord', 'exportPDF' // Import/Export features
  ]}
  // ... other props
/>

Available Options

Basic Formatting:

bold, italic, underline, strikethrough, subscript, superscript
highlight, fontColor

Structure:

headings, fontFamily, lineSpacing
alignLeft, alignCenter, alignRight, alignJustify

Lists & Indentation:

unorderedList, orderedList, todoList
increaseIndent, decreaseIndent

Content:

link, insertImage, blockquote, codeBlock
insertTable, pageBreak

Collaboration:

comments - Add, view, and manage comments on selected text
mentionUsers - Tag and mention users in the document

Import/Export:

importWord - Import from Word (.docx) files
exportWord - Export to Word (.doc) format
exportPDF - Export to PDF and download

Utilities:

caseChange

Advanced Examples

Custom Styled Editor

<HeliosEditor
  value={content}
  onChange={setContent}
  height="h-96"
  width="max-w-4xl"
  customClasses={{
    wrapper: "border-2 border-purple-300 rounded-xl",
    toolbar: "bg-purple-50 border-purple-200",
    contentArea: "bg-white min-h-64",
    button: "hover:bg-purple-100",
  }}
  uploadConfig={{
    uploadApiUrl: process.env.REACT_APP_UPLOAD_URL,
    clientId: process.env.REACT_APP_CLIENT_ID,
    clientSecret: process.env.REACT_APP_CLIENT_SECRET,
  }}
/>

Sticky Toolbar Example

<HeliosEditor
  value={content}
  onChange={setContent}
  stickyToolbar={true}
  stickyOffset={60} // Account for fixed header
  height="h-screen"
/>

Blog Editor Example

function BlogEditor({ post, onSave }) {
  const [content, setContent] = useState(post.content);

  const uploadConfig = {
    uploadApiUrl: "/api/blog/upload-image",
    clientId: "blog-client",
    clientSecret: process.env.REACT_APP_BLOG_SECRET,
  };

  return (
    <div className="max-w-4xl mx-auto">
      <HeliosEditor
        value={content}
        onChange={setContent}
        placeholder="Write your blog post..."
        height="h-96"
        uploadConfig={uploadConfig}
        toolbarOptions={[
          "bold",
          "italic",
          "underline",
          "highlight",
          "headings",
          "alignLeft",
          "alignCenter",
          "alignRight",
          "unorderedList",
          "orderedList",
          "link",
          "insertImage",
          "blockquote",
          "insertTable",
        ]}
      />
      <button onClick={() => onSave(content)}>Save Post</button>
    </div>
  );
}

Environment Configuration

For applications using environment variables, you can configure the upload settings:

// .env
REACT_APP_UPLOAD_URL=https://your-api.com/upload
REACT_APP_CLIENT_ID=your-client-id
REACT_APP_CLIENT_SECRET=your-client-secret

// Component
const uploadConfig = {
  uploadApiUrl: process.env.REACT_APP_UPLOAD_URL,
  clientId: process.env.REACT_APP_CLIENT_ID,
  clientSecret: process.env.REACT_APP_CLIENT_SECRET
};

Migration from Environment Variables

If you were previously using environment variables directly (VITE_* variables), update your configuration:

Before:

// .env
VITE_UPLOAD_API_URL=https://api.example.com/upload
VITE_CLIENT_ID=client123
VITE_CLIENT_SECRET=secret456

// No explicit config needed - read automatically
<HeliosEditor value={content} onChange={setContent} />

After:

// .env
REACT_APP_UPLOAD_URL=https://api.example.com/upload
REACT_APP_CLIENT_ID=client123
REACT_APP_CLIENT_SECRET=secret456

// Explicit config required
const uploadConfig = {
  uploadApiUrl: process.env.REACT_APP_UPLOAD_URL,
  clientId: process.env.REACT_APP_CLIENT_ID,
  clientSecret: process.env.REACT_APP_CLIENT_SECRET
};

<HeliosEditor
  value={content}
  onChange={setContent}
  uploadConfig={uploadConfig}
/>

Keyboard Shortcuts

| Shortcut | Action | | -------------- | ------------------- | | Ctrl/Cmd + B | Bold | | Ctrl/Cmd + I | Italic | | Ctrl/Cmd + U | Underline | | Ctrl/Cmd + L | Align Left | | Ctrl/Cmd + E | Align Center | | Ctrl/Cmd + R | Align Right | | Ctrl/Cmd + J | Justify | | Ctrl/Cmd + 1 | Single Line Spacing | | Ctrl/Cmd + 2 | Double Line Spacing | | Ctrl/Cmd + 5 | 1.5 Line Spacing | | Tab | Increase Indent | | Shift + Tab | Decrease Indent |

Browser Support

Chrome 80+
Firefox 75+
Safari 13+
Edge 80+

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

MIT License - see LICENSE file for details.

Version History

v3.4.0 (Current)

📥 NEW: Word Document Import - Import .docx files with full formatting preservation
📄 ENHANCED: PDF Export - Download actual PDF files with high quality
🎨 Improved formatting conversion using mammoth.js
📝 Support for headings, lists, tables, images, and text formatting
🖼️ Automatic image embedding as base64 data URLs
⚡ Loading indicators for import/export/upload operations
📦 Added jsPDF and html2canvas libraries for PDF generation
🔧 Multi-page PDF support for long documents
📅 Automatic filename generation with timestamps
🐛 Enhanced error handling for file imports and exports

v3.2.0

🔄 Minor version bump for publishing updates
📦 Updated package configuration and dependencies

v3.1.0

✨ Added subscript (X₂) and superscript (X²) text formatting buttons
📝 Enhanced text formatting capabilities for mathematical expressions and footnotes
🎯 Added active state detection for subscript/superscript formatting
🔧 Improved toolbar configuration to include new formatting options

v3.0.0

🎉 Major version release with enhanced dropdown components
🎯 Enhanced dropdown components with wider layouts
📝 Added selected value display on dropdown buttons
🎨 Improved visual feedback for active selections
📱 Better responsive design for dropdown components
🔧 Updated CSS structure for improved maintainability

v2.3.2

🎯 Enhanced dropdown components with wider layouts
📝 Added selected value display on dropdown buttons
🎨 Improved visual feedback for active selections
📱 Better responsive design for dropdown components
🔧 Updated CSS structure for improved maintainability

v2.2.x Series

🎨 Improved standalone CSS with better responsive design
📦 Enhanced npm package configuration
🔧 Better build optimization and CSS bundling
📱 Mobile-friendly toolbar and dropdown layouts

v1.3.0

✨ Added configurable upload system via props
🖼️ Implemented image resize functionality
🧹 Clean HTML output (no editor artifacts)
📦 Prepared for npm package distribution
🔧 Added TypeScript definitions

v1.2.0

🎨 Advanced table styling and resizing
📱 Improved responsive design
⚡ Performance optimizations

v1.1.0

🖼️ Image upload via drag & drop and paste
🔗 Enhanced link management
🎯 Improved toolbar customization

v1.0.0

🎉 Initial release
✨ Core rich text editing features
🎨 Tailwind CSS integration