ngx-rich-text-pro 1.0.0

package/README.md

@@ -0,0 +1,525 @@
+<div align="center">
+
+# 📝 ngx-rich-text-pro
+
+**The Modern, Lightweight, Zero-Dependency Rich Text & Social Post Editor for Angular.**
+
+Built for modern Angular (17, 18, 19, 20, 21+), Standalone Components, Reactive Forms, Signals, and Headless Custom UI.
+
+[![npm version](https://img.shields.io/npm/v/ngx-rich-text-pro.svg?color=0069FF&style=flat-square)](https://www.npmjs.com/package/ngx-rich-text-pro)
+[![Angular](https://img.shields.io/badge/Angular-17%20|%2018%20|%2019%20|%2020%20|%2021+-dd0031.svg?style=flat-square&logo=angular)](https://angular.dev)
+[![License: MIT](https://img.shields.io/badge/License-MIT-success.svg?style=flat-square)](LICENSE)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg?style=flat-square)](#)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
+
+</div>
+
+---
+
+## ✨ Why ngx-rich-text-pro?
+
+- 🚀 **Zero External Dependencies**: Built-in, clean vector SVG icons. No heavy FontAwesome or Material font stylesheets required.
+- 🎯 **Modern Angular Native**: Fully standalone, zoneless/signals compatible, designed for Angular 17 through 21+.
+- 📝 **First-Class Angular Forms**: Seamless `ControlValueAccessor` integration with Reactive Forms (`[formControl]`), `FormGroup`, and `[(ngModel)]`.
+- 🎛️ **Array-Driven Custom Toolbar**: Pick only the tools you need with a simple array (`[tools]="['bold', 'italic', 'underline', 'bulletList', 'orderedList']"`).
+- 🧩 **Headless / Callable API**: Don't want the default toolbar? Hide it and trigger `editor.bold()`, `editor.italic()`, `editor.insertOrderedList()` from your own custom UI anywhere in the DOM.
+- 🏷️ **Real-Time Hashtag Highlight**: Automatically highlights `#hashtags` with customizable colors (`[hashtagColor]="'#0069FF'"`), automatic space breakout, and 100% editable/selectable text.
+- 🔢 **Smart Collision-Free Placeholder**: The placeholder cleanly hides when lists (`1.`, `•`), tables, quotes, or code blocks are active so text never overlaps with list markers.
+- 🎨 **Typography & Theming**: Custom font family (`'Open Sans'`, `'Poppins'`, `'Inter'`), custom font dropdown list, transparent or custom backgrounds, and CSS variables.
+- 📊 **Live Stats & Character Limits**: Built-in word counter, character counter, and hard/soft character limit warnings.
+- 🖼️ **Images & Links**: Insert images via URL or local file upload (automatic Base64 conversion) and insert links with new-tab toggle.
+- ⌨️ **Keyboard Shortcuts**: Built-in support for `Ctrl+B`, `Ctrl+I`, `Ctrl+U`, `Ctrl+Z`, `Ctrl+Y`, `Ctrl+K`, `Tab`, and `Shift+Tab`.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install ngx-rich-text-pro
+```
+
+---
+
+## 🚀 Getting Started
+
+### 1. Import the Component
+
+Import `NgxRichTextProComponent` (or `NgxRichTextEditorComponent`) into your standalone component:
+
+```typescript
+import { Component } from '@angular/core';
+import { FormControl, ReactiveFormsModule } from '@angular/forms';
+import { NgxRichTextProComponent, ToolbarItem } from 'ngx-rich-text-pro';
+
+@Component({
+  selector: 'app-example',
+  standalone: true,
+  imports: [ReactiveFormsModule, NgxRichTextProComponent],
+  template: `
+    <!-- Show ONLY Bold, Italic, Underline, Lists, Emoji, and a custom AI button -->
+    <ngx-rich-text-pro
+      [formControl]="contentControl"
+      [tools]="tools"
+      [maxCharacters]="3000"
+      placeholder="What do you want to talk about?"
+    ></ngx-rich-text-pro>
+  `
+})
+export class ExampleComponent {
+  contentControl = new FormControl('');
+
+  // Define ONLY the tools you want in an array!
+  tools: ToolbarItem[] = [
+    'bold',
+    'italic',
+    'underline',
+    'bulletList',
+    'orderedList',
+    'emoji',
+    '|',
+    {
+      label: 'Write with AI',
+      icon: '✨',
+      customClass: 'btn-ai',
+      action: (editor) => editor.insertHtml('<p>✨ Smart draft from AI...</p>')
+    }
+  ];
+}
+```
+
+---
+
+## 💡 Popular Use-Case Recipes
+
+### Recipe 1: Social Media Post Creator (LinkedIn, Twitter/X, Threads)
+
+Build a clean post composer with real-time blue hashtags, custom font, and transparent background:
+
+```html
+<ngx-rich-text-pro
+  [formControl]="postControl"
+  [tools]="['bold', 'italic', 'underline', 'orderedList', 'bulletList', 'emoji']"
+  [fontFamily]="'\'Open Sans\', sans-serif'"
+  [hashtagColor]="'#0069FF'"
+  [editorStyle]="{ 'background-color': 'transparent' }"
+  [contentStyle]="{ 'background-color': 'transparent', 'min-height': '220px' }"
+  [maxCharacters]="3000"
+  placeholder="What do you want to share today?"
+></ngx-rich-text-pro>
+```
+
+### Recipe 2: Headless / Custom External Buttons Anywhere in your UI
+
+You can completely hide the built-in toolbar (`[showToolbar]="false"`) and trigger formatting from **your own custom buttons or modals anywhere in the DOM**:
+
+```html
+<!-- Your own custom toolbar layout -->
+<div class="my-custom-toolbar">
+  <button 
+    type="button" 
+    [class.active]="editor.isFormatActive('bold')" 
+    (mousedown)="$event.preventDefault(); editor.bold()"
+  >
+    Bold
+  </button>
+
+  <button 
+    type="button" 
+    [class.active]="editor.isFormatActive('italic')" 
+    (mousedown)="$event.preventDefault(); editor.italic()"
+  >
+    Italic
+  </button>
+
+  <button 
+    type="button" 
+    [class.active]="editor.isFormatActive('underline')" 
+    (mousedown)="$event.preventDefault(); editor.underline()"
+  >
+    Underline
+  </button>
+
+  <button 
+    type="button" 
+    [class.active]="editor.isFormatActive('insertOrderedList')" 
+    (mousedown)="$event.preventDefault(); editor.insertOrderedList()"
+  >
+    1. Numbered List
+  </button>
+
+  <button 
+    type="button" 
+    [class.active]="editor.isFormatActive('insertUnorderedList')" 
+    (mousedown)="$event.preventDefault(); editor.insertUnorderedList()"
+  >
+    • Bullet List
+  </button>
+
+  <button 
+    type="button" 
+    (mousedown)="$event.preventDefault(); editor.insertHtml('<strong>✨ AI Draft</strong>')"
+  >
+    Insert AI Snippet
+  </button>
+</div>
+
+<!-- Editor with built-in toolbar hidden -->
+<ngx-rich-text-pro
+  #editor
+  [showToolbar]="false"
+  [showStatusBar]="false"
+  [formControl]="postControl"
+  [hashtagColor]="'#0069FF'"
+  placeholder="What do you want to talk about?"
+></ngx-rich-text-pro>
+```
+
+---
+
+## 🏷️ Real-Time Hashtag Engine
+
+`ngx-rich-text-pro` includes a real-time hashtag parsing engine:
+- **Instant Highlighting**: Any word preceded by `#` (e.g., `#angular`, `#developer`) is styled with `[hashtagColor]` (default: `#0069FF`).
+- **Clean Space Breakout**: When the user presses `Space` or `Enter` after a hashtag, subsequent words automatically return to the default font color.
+- **100% Editable & Selectable**: Unlike rigid token tags, users can freely click inside the hashtag, select letters, backspace, and fix typos just like standard text.
+- **Smart Unwrap**: Deleting the `#` prefix immediately unwraps the word and restores regular text styling.
+
+---
+
+## 🔢 Collision-Free Smart Placeholder
+
+Standard rich text editors often suffer from placeholders overlapping list numbers (e.g. `1. What do you want to share...`). 
+
+`ngx-rich-text-pro` includes smart structural detection:
+- The placeholder displays on empty paragraphs.
+- As soon as the user starts an ordered list (`1.`), bullet list (`•`), blockquote, code block, or table, the placeholder is **cleanly suppressed**.
+- If the list item is deleted (e.g. pressing `Backspace`), the placeholder naturally reappears.
+
+---
+
+## 📦 Using with `[(ngModel)]`
+
+```typescript
+import { Component } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { NgxRichTextProComponent } from 'ngx-rich-text-pro';
+
+@Component({
+  selector: 'app-model-example',
+  standalone: true,
+  imports: [FormsModule, NgxRichTextProComponent],
+  template: `
+    <ngx-rich-text-pro [(ngModel)]="htmlContent"></ngx-rich-text-pro>
+  `
+})
+export class ModelExampleComponent {
+  htmlContent = '<p>Initial content</p>';
+}
+```
+
+---
+
+## ⚙️ Configuration & Customization
+
+You can customize the toolbar and editor behavior via the `[config]` input:
+
+```typescript
+import { Component } from '@angular/core';
+import { NgxRichTextProComponent, NgxEditorConfig } from 'ngx-rich-text-pro';
+
+@Component({
+  selector: 'app-custom-editor',
+  standalone: true,
+  imports: [NgxRichTextProComponent],
+  template: `
+    <ngx-rich-text-pro [config]="customConfig"></ngx-rich-text-pro>
+  `
+})
+export class CustomEditorComponent {
+  customConfig: Partial<NgxEditorConfig> = {
+    placeholder: 'Write something amazing...',
+    minHeight: '300px',
+    showStatusBar: true,
+    showWordCount: true,
+    showCharCount: true,
+    toolbar: {
+      history: true,
+      format: true,
+      fontSize: true,
+      fontName: true,
+      inline: {
+        bold: true,
+        italic: true,
+        underline: true,
+        code: true
+      },
+      color: {
+        textColor: true,
+        backgroundColor: true
+      },
+      alignment: {
+        left: true,
+        center: true,
+        right: true,
+        justify: true
+      },
+      list: {
+        unordered: true,
+        ordered: true,
+        indent: true,
+        outdent: true
+      },
+      insert: {
+        link: true,
+        image: true,
+        horizontalRule: true
+      },
+      extra: {
+        clearFormat: true,
+        sourceView: true
+      }
+    }
+  };
+}
+```
+
+---
+
+## 🎨 Custom Styling & Custom Font Family
+
+`ngx-rich-text-pro` supports full typography and styling customization out of the box.
+
+### 1. Custom Font Family via Input
+Apply any Google font or design system font directly to the editor:
+
+```html
+<ngx-rich-text-pro
+  [fontFamily]="'Poppins, sans-serif'"
+  [fontSize]="'16px'"
+  [tools]="['fontFamily', 'fontSize', '|', 'bold', 'italic', 'underline']"
+></ngx-rich-text-pro>
+```
+
+### 2. Custom Font Family Dropdown List (`[fontFamilies]`)
+Provide your own custom font families to the dropdown in the toolbar:
+
+```typescript
+customFonts = [
+  { label: 'Poppins (Google Font)', value: "'Poppins', sans-serif" },
+  { label: 'Inter (UI Sans)', value: "'Inter', sans-serif" },
+  { label: 'Playfair Display (Serif)', value: "'Playfair Display', Georgia, serif" },
+  { label: 'Fira Code (Code)', value: "'Fira Code', monospace" },
+  { label: 'Roboto', value: "'Roboto', sans-serif" }
+];
+```
+
+In your template:
+```html
+<ngx-rich-text-pro
+  [fontFamilies]="customFonts"
+  [tools]="['fontFamily', 'fontSize', '|', 'bold', 'italic', 'underline']"
+></ngx-rich-text-pro>
+```
+
+### 3. Custom Theming via CSS Custom Properties
+The editor automatically inherits your app's font family by default (`inherit`), or you can define design tokens:
+
+```scss
+ngx-rich-text-pro {
+  --ngx-editor-font-family: 'Poppins', sans-serif;
+  --ngx-editor-font-size: 16px;
+  --ngx-editor-line-height: 1.7;
+  --ngx-editor-border: #cbd5e1;
+  --ngx-editor-border-focus: #6366f1;
+  --ngx-editor-radius: 12px;
+  --ngx-editor-bg: #ffffff;
+  --ngx-editor-text: #0f172a;
+  --ngx-editor-toolbar-bg: #f8fafc;
+  --ngx-editor-toolbar-btn-active: #e0e7ff;
+  --ngx-editor-toolbar-btn-active-color: #4338ca;
+}
+```
+
+### 4. Custom Classes & Inline Styles
+```html
+<ngx-rich-text-pro
+  [customClass]="'my-brand-editor'"
+  [editorStyle]="{ 'border-radius': '16px', 'box-shadow': '0 4px 6px -1px rgba(0,0,0,0.1)' }"
+  [contentStyle]="{ 'min-height': '350px', 'line-height': '1.8' }"
+></ngx-rich-text-pro>
+```
+
+### 5. Direct Callable API for Fonts & Colors
+```typescript
+// Call from anywhere:
+editor.setFontFamily("'Poppins', sans-serif");
+editor.setFontSize(4); // Or 1-7
+editor.setTextColor('#4f46e5');
+editor.setBackgroundColor('#fef08a');
+```
+
+---
+
+## 📖 API Reference
+
+### Component Inputs (`ngx-rich-text-pro`)
+
+*(Note: `<ngx-rich-text-editor>` is also supported as an alias for backwards compatibility).*
+
+| Input | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `value` | `string` | `''` | Initial HTML content (or bind with `formControl` / `ngModel`) |
+| `placeholder` | `string` | `'Compose your content here...'` | Placeholder text when editor is empty |
+| `tools` | `ToolbarItem[]` | `undefined` | Array of tools to display. Overrides default toolbar |
+| `showToolbar` | `boolean` | `true` | Show or hide the top toolbar (set `false` for headless mode) |
+| `showStatusBar` | `boolean` | `true` | Show or hide the bottom character/word counter bar |
+| `fontFamily` | `string` | `''` | Custom base font family (e.g. `'Open Sans', sans-serif`) |
+| `fontSize` | `string` | `''` | Custom base font size (e.g. `'15px'`) |
+| `fontFamilies` | `Array<FontFamilyOption \| string>` | `DEFAULT_FONT_FAMILIES` | Font family options in the toolbar dropdown |
+| `hashtagColor` | `string` | `'#0069FF'` | Color used for highlighted `#hashtags` |
+| `highlightHashtags` | `boolean` | `true` | Enable or disable real-time hashtag highlighting |
+| `maxCharacters` | `number` | `undefined` | Hard maximum character limit |
+| `characterCountWarn` | `number` | `undefined` | Threshold to show a warning badge as limit approaches |
+| `customClass` | `string` | `''` | Custom CSS class applied to host container |
+| `editorStyle` | `Record<string, string> \| string` | `''` | Custom styles for editor outer container |
+| `contentStyle` | `Record<string, string> \| string` | `''` | Custom styles for editable content area |
+| `disabled` | `boolean` | `false` | Whether editor is disabled |
+| `readonly` | `boolean` | `false` | Read-only mode (disables editing & toolbar) |
+| `config` | `Partial<NgxEditorConfig>` | `{}` | Complete configuration options object |
+
+### Component Outputs
+
+| Output | Event Type | Description |
+| :--- | :--- | :--- |
+| `valueChange` | `EventEmitter<string>` | Emits updated HTML string on every change |
+| `textChange` | `EventEmitter<{ html: string; text: string }>` | Emits both HTML and plain-text representation |
+
+### Callable Public Methods (`#editorRef`)
+
+| Method | Parameters | Description |
+| :--- | :--- | :--- |
+| `bold()` | - | Toggles bold on selection |
+| `italic()` | - | Toggles italic on selection |
+| `underline()` | - | Toggles underline on selection |
+| `strike()` | - | Toggles strikethrough on selection |
+| `subscript()` | - | Toggles subscript on selection |
+| `superscript()` | - | Toggles superscript on selection |
+| `insertOrderedList()` | - | Toggles numbered list (`1.`) |
+| `insertUnorderedList()` | - | Toggles bullet list (`•`) |
+| `indent()` | - | Indents current line/list item |
+| `outdent()` | - | Outdents current line/list item |
+| `alignLeft()` / `alignCenter()` / `alignRight()` / `alignJustify()` | - | Sets text alignment |
+| `setHeading(level)` | `level: 1 \| 2 \| 3 \| 4 \| 5 \| 6` | Formats current block as heading |
+| `setParagraph()` | - | Formats current block as paragraph |
+| `setBlockquote()` | - | Formats current block as blockquote |
+| `setCodeBlock()` | - | Formats current block as preformatted code |
+| `setFontFamily(font)` | `font: string` | Applies font family to selection or editor |
+| `setFontSize(size)` | `size: string \| number` | Applies font size to selection |
+| `setTextColor(color)` | `color: string` | Sets text color |
+| `setBackgroundColor(color)` | `color: string` | Sets text background/highlight color |
+| `setHashtagColor(color)` | `color: string` | Changes the hashtag highlight color |
+| `insertHtml(html)` | `html: string` | Inserts arbitrary HTML string at cursor |
+| `insertText(text)` | `text: string` | Inserts plain text at cursor |
+| `insertEmoji(emoji)` | `emoji: string` | Inserts emoji at cursor |
+| `insertLink(url, text?, newTab?)` | `url: string, ...` | Inserts hyperlink |
+| `removeLink()` | - | Removes link from selection |
+| `insertImage(url, alt?)` | `url: string, ...` | Inserts image |
+| `insertHorizontalRule()` | - | Inserts horizontal rule (`<hr>`) |
+| `clearFormatting()` | - | Strips all formatting from selection |
+| `undo()` / `redo()` | - | History undo / redo |
+| `focus()` | - | Focuses the editor content area |
+| `getHtml()` | - | Returns current HTML content |
+| `getText()` | - | Returns plain text representation |
+| `isFormatActive(format)` | `format: string` | Checks if a format (`'bold'`, `'italic'`, `'insertOrderedList'`, etc.) is currently active |
+
+### Supported Toolbar Tool Identifiers
+
+When providing an array to `[tools]`, you can use any of these identifiers:
+
+| Identifier | Action |
+| :--- | :--- |
+| `'bold'` | Bold formatting button |
+| `'italic'` | Italic formatting button |
+| `'underline'` | Underline formatting button |
+| `'strikeThrough'` | Strikethrough button |
+| `'orderedList'` | Numbered list button |
+| `'bulletList'` | Bullet list button |
+| `'indent'` | Indent button |
+| `'outdent'` | Outdent button |
+| `'alignLeft'` | Align text left |
+| `'alignCenter'` | Align text center |
+| `'alignRight'` | Align text right |
+| `'alignJustify'` | Justify text |
+| `'format'` | Headings & paragraph dropdown |
+| `'fontFamily'` | Font family selector dropdown |
+| `'fontSize'` | Font size selector dropdown |
+| `'textColor'` | Text color picker |
+| `'backgroundColor'` | Background highlight color picker |
+| `'link'` | Insert link modal |
+| `'image'` | Insert image modal |
+| `'emoji'` | Insert emoji picker |
+| `'horizontalRule'` | Insert divider line |
+| `'clear'` | Clear formatting button |
+| `'undo'` | Undo button |
+| `'redo'` | Redo button |
+| `'sourceView'` | Toggle raw HTML source view |
+| `'\|'` | Visual toolbar divider |
+| `CustomToolbarButton` | `{ label, icon, customClass, action: (editor) => ... }` |
+
+---
+
+## 🎨 CSS Variables & Theming
+
+```scss
+ngx-rich-text-pro,
+ngx-rich-text-editor {
+  --ngx-editor-border: #e2e8f0;
+  --ngx-editor-border-focus: #3b82f6;
+  --ngx-editor-radius: 8px;
+  --ngx-editor-bg: #ffffff;
+  --ngx-editor-text: #1e293b;
+  --ngx-editor-toolbar-bg: #f8fafc;
+  --ngx-editor-toolbar-border: #e2e8f0;
+  --ngx-editor-toolbar-btn-active: #dbeafe;
+  --ngx-editor-toolbar-btn-active-color: #1d4ed8;
+  --ngx-editor-hashtag-color: #0069FF;
+}
+```
+
+---
+
+## 🚀 How to Publish to npm
+
+Ready to publish this package to npm? Follow these simple steps:
+
+### 1. Login to your npm account
+```bash
+npm login
+```
+
+### 2. Build the package
+```bash
+npm run build:lib
+```
+*This compiles the Angular library into standard Angular Package Format (APF) inside the `dist/ngx-rich-text-editor` directory.*
+
+### 3. Verify the package output (Optional)
+```bash
+npm run pack:lib
+```
+*Creates `ngx-rich-text-pro-1.0.0.tgz` for local inspection.*
+
+### 4. Publish to npm!
+```bash
+cd dist/ngx-rich-text-editor
+npm publish --access public
+```
+
+Your package will immediately be live on **`https://www.npmjs.com/package/ngx-rich-text-pro`**! 🎉
+
+---
+
+## 📄 License
+
+MIT License © 2026. Free for commercial and personal use.
+