@flogeez/angular-tiptap-editor 0.5.4 → 0.6.0

package/CHANGELOG.md

@@ -5,6 +5,45 @@ All notable changes to `@flogeez/angular-tiptap-editor` will be documented in th
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] - 2026-01-14
+
+### Added
+- **Reactive State Management**: New "Snapshot & Signal" architecture with optimized change detection (OnPush).
+- **Custom Extension Tracking**: Automatic state tracking for custom Tiptap Marks and Nodes (zero-config).
+- **Extensible State**: New `stateCalculators` input to inject custom logic into the reactive editor state.
+- **Intelligent Color Detection**: The editor state now computes the actual visible text and background colors by inspecting the DOM (computed styles). This ensures the color picker accurately reflects the current formatting even when derived from CSS themes or inherited from parent elements.
+- **Link & Color Bubble Menus**: Completely refactored management with dedicated bubble menus.
+- **LinkService**: New dedicated service to manage link state and lifecycle independently.
+- **Improved Visual Feedback**: Menus now preserve the editor's blue selection highlight while choosing colors or preparing to type a link.
+- **Improved Image Selection**: Automatic node selection after insertion or replacement, ensuring resize handles and bubble menus appear instantly.
+- **Danger Button Variant**: New `danger` variant for actions like "Reset Color" or "Remove Link", providing clear visual feedback for destructive operations.
+
+### Fixed
+- **Multi-instance Support**: Full service isolation, allowing multiple editors on the same page without shared state.
+- **Bubble Menu Conflicts**: Fixed overlapping menus by implementing a strict priority system (specialized menus now hide the main text menu).
+- **Image Bubble Menu Persistence**: Corrected Tippy.js behavior to prevent menus from disappearing when re-clicking an already-selected image.
+- **Toolbar-Menu Harmony**: Bubbles now reactively hide when interacting with the main toolbar via a centralized signal.
+- **Anti-Echo Loop**: Implemented a robust "lastEmittedHtml" logic combined with `untracked()` to prevent infinite loops and cursor reset when using two-way binding or FormControls.
+- **Atomic Image Replacement**: Refactored image service to perform atomic updates, fixing the "extra space" bug and preventing layout shifts during asynchronous uploads.
+
+### Changed
+- **Architectural Refactoring**: `EditorCommandsService` is now a clean facade/proxy for specialized services (`ImageService`, `ColorPickerService`, `LinkService`).
+- **Optimized State Performance**: Refactored state calculators (notably `MarksCalculator`) to minimize DOM access and avoid unnecessary layout recalculations (reflow).
+- **Centralized Color Utilities**: Consolidated color normalization, luminance, and contrast calculations into a shared utility for perfect consistency.
+- **Public API Cleanup**: Exported all modular calculators, services, and models for better extensibility.
+- **Color Picker Stability**: Integrated selection capture and locked modes to ensure 100% reliability in color application.
+
+## [0.5.5] - 2026-01-09
+
+### Added
+- **Bubble Menus Confinement**: Menus now properly respect the editor's boundaries and are clipped by the container when scrolling, specifically optimized for `fillContainer` mode.
+- **Unified Command Execution**: Centralized all editor operations within `EditorCommandsService`, ensuring consistent behavior between the toolbar and bubble menus.
+
+### Fixed
+- **Bubble Menus Positionning**: Refactored positioning logic for all bubble menus (Text, Image, Table, Cell, Slash) using Tippy's `sticky` plugin for real-time tracking during resizing and scrolling.
+- **Bubble Menus Performances**: Significant performance boost in `getImageRect` and `getTableRect` using direct ProseMirror DOM lookups.
+- **Performance Optimization**: Implemented `ChangeDetectionStrategy.OnPush` across all library components to minimize change detection cycles. Improved resource management by enabling Tippy's sticky polling only while menus are visible.
+
 ## [0.5.4] - 2026-01-08
 
 ### Added

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 FloGeez
+Copyright (c) 2026 FloGeez
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -114,20 +114,24 @@ export class AdvancedComponent {
   };
 
   // No config needed if you want all commands enabled
-  slashCommands = {
+  slashCommandsConfig = {
     image: true,
     table: true,
     heading1: true
   };
 
+  // Available keys: "heading1", "heading2", "heading3", "bulletList", 
+  // "orderedList", "blockquote", "code", "image", "horizontalRule", "table"
+
   onContentChange(newContent: string) {
     this.content = newContent;
   }
 }
 ```
 
-You can also pass additional TipTap extensions (including custom marks)
-via the `tiptapExtensions` input.
+### 3. Registering Custom Extensions
+
+Easily extend the editor with any standard Tiptap extension or your own custom marks/nodes via the `tiptapExtensions` input.
 
 ```typescript
 import { Component } from "@angular/core";
@@ -156,7 +160,7 @@ export class CustomExtensionsComponent {
 }
 ```
 
-### 3. With Form Integration
+### 4. With Form Integration
 
 ```typescript
 import { Component } from "@angular/core";
@@ -195,9 +199,15 @@ import { EditorCommandsService } from "@flogeez/angular-tiptap-editor";
   standalone: true,
   template: `
     <div>
-      <button (click)="clearContent()">Clear Content</button>
-      <button (click)="focusEditor()">Focus Editor</button>
-      <button (click)="setContent()">Set Content</button>
+      <div class="controls">
+        <button (click)="clearContent()">Clear Content</button>
+        <button (click)="focusEditor()">Focus Editor</button>
+        <button (click)="setContent()">Set Content</button>
+      </div>
+
+      <angular-tiptap-editor 
+        (editorCreated)="onEditorCreated($event)" 
+      />
     </div>
   `,
 })
@@ -232,6 +242,55 @@ export class CommandsComponent {
 }
 ```
 
+### 5. Extending Reactive Editor State
+
+The editor features a dual-layer state architecture: **Automatic Tracking** for simple extensions and **Custom Calculators** for advanced needs.
+
+#### A. Automatic Extension Tracking (Zero Config)
+
+Any TipTap **Mark** or **Node** you add to `tiptapExtensions` is automatically tracked by our `DiscoveryCalculator`. You don't need to write any extra code to make them reactive.
+
+*   **For Marks**: `state().marks.yourExtensionName` (boolean) and `state().can.toggleYourExtensionName` (boolean).
+*   **For Nodes**: `state().nodes.yourExtensionName` (boolean).
+
+#### B. Custom State Calculators (Advanced)
+
+If you need to extract complex data (like attributes, depth, or custom logic), you can provide a custom `StateCalculator`.
+
+1. **Define a Calculator**:
+```typescript
+import { StateCalculator } from "@flogeez/angular-tiptap-editor";
+
+// This function will be called on every editor update
+export const MyCustomCalculator: StateCalculator = (editor) => {
+  return {
+    custom: {
+      hasHighPriority: editor.isActive('priority'),
+      selectionDepth: editor.state.selection.$from.depth,
+      // Any data you need...
+    }
+  };
+};
+```
+
+2. **Register it in the Template**:
+```html
+<angular-tiptap-editor 
+  [stateCalculators]="[MyCustomCalculator]" 
+/>
+```
+
+3. **Consume it anywhere**:
+```typescript
+@Component({ ... })
+export class MyToolbarComponent {
+  private editorCommands = inject(EditorCommandsService);
+  
+  // Access your custom data reactively!
+  isHighPriority = computed(() => this.editorCommands.editorState().custom?.hasHighPriority);
+}
+```
+
 ## ✨ Key Features
 
 ### 📊 Table Management
@@ -254,6 +313,30 @@ Quick content insertion with slash commands:
 - **Media**: `/image`, `/table`
 - **Fully Internationalized**: All commands translated
 
+#### Custom Slash Commands
+
+The `slashCommands` object also allows you to add completely custom command items:
+
+```typescript
+import { SlashCommandsConfig } from "@flogeez/angular-tiptap-editor";
+
+slashCommands: SlashCommandsConfig = {
+  // Toggle native commands
+  heading1: true,
+  image: false,
+  // Add custom ones
+  custom: [
+    {
+      title: 'Magic Action',
+      description: 'Insert some AI magic',
+      icon: 'auto_fix',
+      keywords: ['magic', 'ai'],
+      command: (editor) => editor.commands.insertContent('✨ Magic happened!')
+    }
+  ]
+};
+```
+
 ### 🖼️ Advanced Image Handling
 
 Professional image management:
@@ -403,45 +486,6 @@ Open [http://localhost:4200](http://localhost:4200) to view the demo.
 | `editorFocus`   | `{editor, event}` | Emitted when editor gains focus |
 | `editorBlur`    | `{editor, event}` | Emitted when editor loses focus |
 
-### Configuration Examples
-
-```typescript
-import {
-  DEFAULT_TOOLBAR_CONFIG,
-  DEFAULT_BUBBLE_MENU_CONFIG,
-  SLASH_COMMAND_KEYS,
-} from "@flogeez/angular-tiptap-editor";
-
-// Minimal toolbar
-const minimalToolbar = {
-  bold: true,
-  italic: true,
-  bulletList: true,
-};
-
-// Full toolbar with clear button
-const fullToolbar = {
-  ...DEFAULT_TOOLBAR_CONFIG,
-  clear: true, // Add clear button
-};
-
-// Bubble menu with table support
-const bubbleMenuWithTable = {
-  ...DEFAULT_BUBBLE_MENU_CONFIG,
-  table: true, // Enable table bubble menu
-};
-
-// Slash commands configuration (simple toggle)
-// By default, all commands are enabled and localized.
-const slashCommands = {
-  heading1: true,
-  heading2: true,
-  image: false, // Disable image command
-};
-
-// Available keys: "heading1", "heading2", "heading3", "bulletList", 
-// "orderedList", "blockquote", "code", "image", "horizontalRule", "table"
-```
 
 ## 🌍 Internationalization
 
@@ -469,37 +513,6 @@ The editor supports English and French with automatic browser language detection
   - Error messages
   - Word/character count (with proper pluralization)
 
-### Custom Slash Commands
-
-For advanced usage, you can provide entirely custom command items (titles, icons, logic):
-
-```typescript
-import { 
-  CustomSlashCommands, 
-  SlashCommandItem 
-} from "@flogeez/angular-tiptap-editor";
-
-// Define your custom items
-const myCommands: SlashCommandItem[] = [
-  {
-    title: 'My Action',
-    description: 'Do something cool',
-    icon: 'star',
-    keywords: ['custom', 'cool'],
-    command: (editor) => { /* logic */ }
-  }
-];
-
-// Use in template
-customSlashCommands = {
-  commands: myCommands,
-};
-```
-
-And in template:
-```html
-<angular-tiptap-editor [customSlashCommands]="customSlashCommands" />
-```
 
 ### 🎨 CSS Custom Properties
 
@@ -573,21 +586,30 @@ angular-tiptap-editor {
 
 ## 🏗️ Architecture
 
-### Service-Based Design
+### Reactive State Management
+
+The library uses a **Snapshot & Signal** pattern to bridge Tiptap and Angular.
+
+1.  **State Snapshot**: Every editor transaction triggers a set of "Calculators" that produce a single immutable state object.
+2.  **Specialized Calculators**: Logic is modularized into specialized functions (Marks, Table, Image, etc.) and a **Discovery Calculator** for automatic extension detection.
+3.  **Signals Integration**: This snapshot is stored in a single Angular Signal. Sub-components (toolbar, menus) consume this signal only where needed.
+4.  **Change Detection Optimization**: A custom equality check on the signal prevents unnecessary re-renders when the visual state of the editor hasn't changed.
+
+### Core Services
+
+- **`EditorCommandsService`**: Exposes the `editorState` signal and provides a centralized API for executing Tiptap commands.
+- **`ImageService`**: Manages the image processing pipeline (selection, compression, and server-side upload handling).
+- **`TiptapI18nService`**: Reactive translation service with support for browser locale auto-detection.
 
-The library follows a clean service-based architecture:
+### Isolated Instances
 
-- **`EditorCommandsService`**: Centralized service for all editor commands
-- **`TiptapI18nService`**: Internationalization service with automatic language detection
-- **`ImageService`**: Advanced image handling with compression and resizing
-- **`filterSlashCommands()`**: Utility function for managing slash commands
+Each component instance provides its own set of services (`EditorCommandsService`, `ImageService`, etc.) at the component level. This ensures that multiple editors on the same page maintain independent states and configurations without interference.
 
-### Modern Angular Patterns
+### Modern Angular Integration
 
-- **Signals**: Used throughout for reactive state management
-- **Dependency Injection**: Clean service injection with `inject()`
-- **Standalone Components**: All components are standalone for better tree-shaking
-- **TypeScript**: Strict typing with comprehensive interfaces
+- **Signals**: Native reactivity for efficient UI updates.
+- **OnPush**: Designed for `ChangeDetectionStrategy.OnPush` throughout.
+- **Typed State**: Fully typed interfaces for the editor state and configurations.
 
 ### Default Configurations
 
@@ -649,14 +671,11 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 
 ### Latest Updates
 
-- ✅ **Custom Image Upload Handler**: Upload images to your own server (S3, Cloudinary, etc.)
-- ✅ **Table Support**: Full table management with bubble menus
-- ✅ **Slash Commands**: Intuitive content insertion commands
-- ✅ **Word/Character Count**: Real-time counting with proper pluralization
-- ✅ **Service Architecture**: Clean `EditorCommandsService` for better maintainability
-- ✅ **Default Configurations**: Importable default configs for easy customization
-- ✅ **Office Paste**: Clean pasting from Microsoft Office applications
-- ✅ **Enhanced i18n**: Improved internationalization with better architecture
+- ✅ **Reactive State & Signals**: Optimized state management for a faster, smoother experience.
+- ✅ **Zero-Config Extensions**: Custom Tiptap Marks and Nodes are tracked automatically.
+- ✅ **Multi-Instance Support**: Use multiple independent editors on the same page without state leaks.
+- ✅ **Clean Service Architecture**: Decoupled configurations and isolated services for better stability.
+- ✅ **Refactored Link Management**: Dedicated link bubble menu with smart UI anchoring and real-time URL sync.
 
 ---