croco-html 20.4.5 → 20.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "croco-html",
-  "version": "20.4.5",
+  "version": "20.5.0",
   "peerDependencies": {
     "@angular/common": "^20.3.15",
     "@angular/core": "^20.3.15",
@@ -14,15 +14,16 @@
     "tslib": ">=2.2.0"
   },
   "module": "fesm2022/croco-html.mjs",
-  "typings": "index.d.ts",
+  "typings": "types/croco-html.d.ts",
   "exports": {
     "./package.json": {
       "default": "./package.json"
     },
     ".": {
-      "types": "./index.d.ts",
+      "types": "./types/croco-html.d.ts",
       "default": "./fesm2022/croco-html.mjs"
     }
   },
-  "sideEffects": false
+  "sideEffects": false,
+  "type": "module"
 }

package/{index.d.ts → types/croco-html.d.ts}

@@ -143,6 +143,94 @@ declare class TagEditorService {
     readonly presentOrEdit$: BehaviorSubject<boolean>;
 }
 
+/**
+ * Types of changes that can occur to a body tag.
+ */
+declare enum ChangeType {
+    /** One or more fields within the tag were modified */
+    Updated = "updated",
+    /** Tag was added to the array */
+    Added = "added",
+    /** Tag was removed from the array */
+    Removed = "removed",
+    /** Tag was moved (reordered) within the array */
+    Moved = "moved",
+    /** Multiple changes batched together */
+    Batch = "batch"
+}
+/**
+ * Describes a change at the field level within an HtmlBodyTag.
+ */
+interface TagFieldChange {
+    fieldName: string;
+    oldValue: unknown;
+    newValue: unknown;
+}
+/**
+ * Granular diff between two HtmlBodyTag instances.
+ */
+interface TagDiff {
+    /** The trackingId of the changed tag */
+    trackingId: string;
+    /** Index where the tag was located */
+    index: number;
+    /** What kind of operation occurred */
+    changeType: ChangeType;
+    /** Which fields changed and their values */
+    fieldChanges: TagFieldChange[];
+    /** Full old tag (before change) */
+    oldTag?: HtmlBodyTag;
+    /** Full new tag (after change) */
+    newTag?: HtmlBodyTag;
+    /** Full HTML snapshot after the change */
+    htmlSnapshot?: string;
+    /** Timestamp of the change */
+    timestamp: number;
+}
+/**
+ * Snapshot of the complete bodyTags array at a point in time.
+ * Used for undo/redo and diff computation.
+ */
+interface ChangeSnapshot {
+    /** Sequential snapshot ID */
+    id: string;
+    /** The bodyTags array at this point */
+    bodyTags: HtmlBodyTag[];
+    /** The HTML string at this point */
+    html: string;
+    /** When this snapshot was taken (ms since epoch) */
+    timestamp: number;
+    /** Optional user/operation label */
+    label?: string;
+}
+/**
+ * A batched set of changes to be applied together.
+ */
+interface ChangeBatch {
+    changes: TagDiff[];
+    batchId: string;
+    timestamp: number;
+}
+/**
+ * Options for the optimized change tracker.
+ */
+interface ChangeTrackerOptions {
+    /** Maximum number of snapshots to keep in history */
+    maxHistorySize?: number;
+    /** Emit changes as they happen (true) or batch them (false) */
+    emitImmediately?: boolean;
+    /** Batching window in ms when emitImmediately is false */
+    batchWindowMs?: number;
+}
+/**
+ * Default snapshot limit to prevent unbounded memory growth.
+ */
+declare const DEFAULT_MAX_HISTORY_SIZE = 100;
+/**
+ * Default batching window in milliseconds.
+ */
+declare const DEFAULT_BATCH_WINDOW_MS = 250;
+
 interface IVisualEditorProps {
     selectedVideoPlayer: string;
     htmlRaw: string;
@@ -912,10 +1000,127 @@ interface IVisualEditorLogger {
     onChange(tag: HtmlBodyTag, index: number): void;
     onRemove(index: number): void;
     onHtmlChanged(html: string): void;
+    /**
+     * Logs a structured diff of what changed within a tag.
+     * Provides granular insight into field-level modifications.
+     */
+    onTagDiff?(diff: TagDiff): void;
+    /**
+     * Logs a batch of changes applied together.
+     */
+    onBatchChanged?(batch: ChangeBatch): void;
+    /**
+     * Logs a full snapshot state.
+     */
+    onSnapshot?(snapshot: ChangeSnapshot): void;
+    /**
+     * Logs an undo operation.
+     */
+    onUndo?(step: ChangeSnapshot): void;
+    /**
+     * Logs a redo operation.
+     */
+    onRedo?(step: ChangeSnapshot): void;
+}
+
+/**
+ * Service responsible for detecting granular differences between two HtmlBodyTag instances.
+ * Avoids unnecessary full re-renders by identifying exactly what changed.
+ */
+declare class TagChangeDetector {
+    /**
+     * Compares two HtmlBodyTag instances and produces a structured diff.
+     */
+    detectDiff(oldTag: HtmlBodyTag, newTag: HtmlBodyTag, index: number, changeType: ChangeType): TagDiff | null;
+    /**
+     * Deep compares two attribute objects and returns field-level changes.
+     */
+    private diffAttributes;
+    /**
+     * Quick check: do two tags have the same content (ignoring trackingId)?
+     * Useful for skip optimization when nothing actually changed.
+     */
+    tagsAreEqual(a: HtmlBodyTag, b: HtmlBodyTag): boolean;
+    static ɵfac: i0.ɵɵFactoryDeclaration<TagChangeDetector, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<TagChangeDetector>;
+}
+
+/**
+ * Stack-based undo/redo service for the visual editor.
+ * Maintains two stacks (undo/redo) and supports keyboard shortcuts (Ctrl+Z / Ctrl+Y).
+ */
+declare class EditorUndoRedoService {
+    private undoStack;
+    private redoStack;
+    /** RxJS observable for canUndo state */
+    readonly canUndoChanged: BehaviorSubject<boolean>;
+    /** RxJS observable for canRedo state */
+    readonly canRedoChanged: BehaviorSubject<boolean>;
+    /** Maximum number of undo steps to keep */
+    private maxHistorySize;
+    /**
+     * Configure the undo/redo service.
+     */
+    configure(options: {
+        maxHistorySize?: number;
+    }): void;
+    /**
+     * Record the current state of the editor.
+     * Call this BEFORE applying changes, so we have a point to undo TO.
+     */
+    pushState(bodyTags: HtmlBodyTag[], html: string, label?: string): void;
+    /**
+     * Undo the last action.
+     * Returns the snapshot to restore, or null if nothing to undo.
+     */
+    undo(): ChangeSnapshot | null;
+    /**
+     * Redo the last undone action.
+     * Returns the snapshot to restore, or null if nothing to redo.
+     */
+    redo(): ChangeSnapshot | null;
+    /**
+     * Clear both undo/redo stacks.
+     * Call this on initial load or fresh state.
+     */
+    clear(): void;
+    /**
+     * Get the bodyTags array from a specific snapshot.
+     */
+    getSnapshotBodyTags(snapshotId: string): HtmlBodyTag[] | null;
+    /**
+     * Get the current undo stack for debugging.
+     */
+    getUndoStack(): ChangeSnapshot[];
+    /**
+     * Get the current redo stack for debugging.
+     */
+    getRedoStack(): ChangeSnapshot[];
+    /**
+     * Check if undo is available.
+     */
+    canUndo(): boolean;
+    /**
+     * Check if redo is available.
+     */
+    canRedo(): boolean;
+    /**
+     * Get the count of available undo steps.
+     */
+    undoCount(): number;
+    /**
+     * Get the count of available redo steps.
+     */
+    redoCount(): number;
+    private updateStates;
+    static ɵfac: i0.ɵɵFactoryDeclaration<EditorUndoRedoService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<EditorUndoRedoService>;
 }
 
 declare class VisualEditorComponent implements OnInit, AfterViewInit {
     private readonly _cdr;
+    private readonly _changeDetector;
+    private readonly _undoRedo;
     private readonly _options;
     textArea: ElementRef;
     imageUploadBtn: UploadFilesBtnComponent;
@@ -955,16 +1160,67 @@ declare class VisualEditorComponent implements OnInit, AfterViewInit {
     bodyTags: HtmlBodyTag[];
     saveBodyTags: HtmlBodyTag[];
     useCustomWidgetsButton: boolean;
-    constructor(_cdr: ChangeDetectorRef, _options: CrocoHtmlOptions);
+    /** History of change snapshots for diff tracking */
+    private historySnapshots;
+    private maxHistorySize;
+    /** Cached last-known bodyTags for diff comparison */
+    private lastKnownTags;
+    /** Destroyed state */
+    private destroyed;
+    constructor(_cdr: ChangeDetectorRef, _changeDetector: TagChangeDetector, _undoRedo: EditorUndoRedoService, _options: CrocoHtmlOptions);
     ngAfterViewInit(): void;
+    ngOnDestroy(): void;
+    /**
+     * Handle keyboard shortcuts for undo/redo:
+     * - Ctrl+Z / Cmd+Z: Undo
+     * - Ctrl+Y / Cmd+Y: Redo
+     * - Ctrl+Shift+Z / Cmd+Shift+Z: Redo (alternative)
+     */
+    onKeyDown(event: KeyboardEvent): void;
     resetTextStyle(): void;
     drop(event: CdkDragDrop<HtmlBodyTag[]>): void;
     addTag(tag: HtmlBodyTag): void;
     addTags(tags: HtmlBodyTag[]): void;
     onTagChangedHandler(data: HtmlBodyTag, index: number): void;
     onTagRemovedHandler(index: number): void;
-    recalculateHtml(): void;
+    /**
+     * Recalculates HTML from bodyTags and emits the result.
+     * @param diff Optional structured diff of what changed (enables downstream consumers to apply incremental updates)
+     */
+    recalculateHtml(diff?: TagDiff | TagDiff[] | null): void;
+    /**
+     * Rebuilds the entire lastKnownTags cache from current bodyTags.
+     * Used for moves or when diff tracking is unreliable.
+     */
+    private rebuildLastKnownTags;
     recalculateBodyTags(): void;
+    /**
+     * Undo the last editor action (Ctrl+Z).
+     * Restores bodyTags and html from the previous state.
+     */
+    undo(): boolean;
+    /**
+     * Redo the last undone action (Ctrl+Y or Ctrl+Shift+Z).
+     * Restores bodyTags and html from the next state.
+     */
+    redo(): boolean;
+    /**
+     * Check if undo is currently available.
+     */
+    isUndoAvailable(): boolean;
+    /**
+     * Check if redo is currently available.
+     */
+    isRedoAvailable(): boolean;
+    /**
+     * Returns the current change history snapshot for debugging.
+     */
+    getChangeHistory(): ChangeSnapshot[];
+    /**
+     * trackBy function for ngFor to use trackingId instead of object reference.
+     * Prevents DOM re-rendering when tags haven't actually moved.
+     */
+    trackByTrackingId(index: number, tag: HtmlBodyTag): string;
     selectTag(data: TagItem): void;
     isTagRequiringForm(): boolean;
     addTagWithForm(): void;
@@ -1025,6 +1281,12 @@ declare class ConsoleVisualEditorLogger implements IVisualEditorLogger {
     onChange(tag: HtmlBodyTag, index: number): void;
     onRemove(index: number): void;
     onHtmlChanged(html: string): void;
+    onTagDiff?(diff: TagDiff): void;
+    onBatchChanged?(batch: ChangeBatch): void;
+    onSnapshot?(snapshot: ChangeSnapshot): void;
+    onUndo?(step: ChangeSnapshot): void;
+    onRedo?(step: ChangeSnapshot): void;
+    private getColorForChangeType;
 }
 
 declare class MainEditorComponent implements OnInit, AfterContentChecked, AfterViewInit {
@@ -1060,10 +1322,13 @@ declare class MainEditorBlockComponent implements OnDestroy {
     private readonly _options;
     textTags: string[];
     private unsubscribe;
+    private _tagSub$;
     private readonly _cdr;
+    private readonly _changeDetector;
     set tag(data: HtmlBodyTag);
     _tag: HtmlBodyTag | null;
     _tagService: TagEditorService;
+    private _originalTagBeforeSet;
     presentOrEdit: boolean;
     onTagSaved: EventEmitter<HtmlBodyTag>;
     onTagRemoved: EventEmitter<HtmlBodyTag>;
@@ -1080,7 +1345,8 @@ declare class MainEditorBlockComponent implements OnDestroy {
 declare class DefinedCustomEditorBlockComponent implements OnInit, OnDestroy {
     private readonly _options;
     private readonly _cdr;
-    private readonly _destroyRef;
+    private readonly _destroy$;
+    private _tagServiceSub$;
     viewContainerRef: ViewContainerRef;
     useDynamicComponent: boolean;
     dynamicContainerRef: ComponentRef<any>;
@@ -1446,5 +1712,5 @@ declare class CrocoHtmlModule {
 
 declare const CrocoHtmlOptionsToken = "croco-html-options";
 
-export { AddFilesBtnComponent, AngularMaterialTableMethods, AudioEditorComponent, AudioMethods, AudioPlayerTagViewComponent, BodyTagsExtensions, BootstrapTableMethods, ButtonTagDataConsts, ButtonTagService, ConsoleVisualEditorLogger, CrocoHtmlFileOptionsService, CrocoHtmlModule, CrocoHtmlOptionsToken, CustomWidgetEditorComponent, CustomWidgetIconComponent, CustomWidgetTagDataConsts, CustomWidgetTagService, DefinedCustomEditorBlockComponent, DefinedCustomTagViewComponent, DownloadButtonTagDataConsts, DownloadButtonTagService, ExternalVideoEditorComponent, ExternalVideoPlayers, ExternalVideoSupportedTypes, ExternalVideoTagDataConsts, ExternalVideoTagService, FileAudioTagDataConsts, FileIdSelectComponent, FileImageTagDataConsts, FileImageTagService, FileImageTagViewComponent, FileType, HtmlPageDataController, HtmlRawEditorComponent, HtmlRawTagDataConsts, HtmlRawTagService, HtmlRawViewComponent, HtmlViewComponent, HtmlViewController, ImageEditorComponent, ImageMethods, LinkEditorComponent, LinkTagAttrs, LinkTagConsts, LinkTagService, MainEditorBlockComponent, MainEditorComponent, NullVisualEditorLogger, TableBuilder, TableMethods, TableTypes, TagBuildExtensions, TagEditorService, TagToSpanPipe, TextAlignment, TextEditorComponent, TextSimpleMethods, TextTag, TextTagDataConsts, TextTagHtmlMarkupTagService, TextTags, ToHtmlBodyTagsPipe, ToPreviewHtmlPipe, ToPreviewPipe, UploadFilesBtnComponent, VisualEditorComponent, XmlExtensions, XmlTagCustomWidgetComponent, XmlTagExternalVideoComponent, XmlTagHeaderInnerTextViewComponent, XmlTagHeaderTextViewComponent, XmlTagHtmlViewComponent, XmlTagTextViewComponent, XmlTagViewComponent };
-export type { AngularMaterialTableData, BaseApiResponse, ButtonTag, ButtonTagData, CommonFileInfoResultModel, CrocoHtmlEditorFileOptions, CrocoHtmlImageOptions, CrocoHtmlOptions, CustomWidgetTag, CustomWidgetTagData, DownloadButtonTag, DownloadButtonTagData, ExternalVideoTag, ExternalVideoTagData, FileAudioTag, FileAudioTagData, FileImageTag, FileImageTagData, FileInfoModel, FilePostingStarted, FileRelationModel, FileSimpleModel, FileUnifiedModel, GenericTextTag, GetListResult, GetListSearchModel, HtmlBodyTag, HtmlRawTag, HtmlRawTagData, IHorizontalAlignmentExtractionResult, IImageMediaRequest, IMarkUpTagService, ITagEditorViewRender, ITagViewViewRender, IVisualEditorLogger, IVisualEditorProps, ImageRestrictions, InterfaceBlock, LinkTagData, SearchFilesRequest, SearchQuestionsFormData, SimpleTextTagData, TableData, TableHeaderData, TableRowColumnData, TableRowData, TableTagData, TagItem };
+export { AddFilesBtnComponent, AngularMaterialTableMethods, AudioEditorComponent, AudioMethods, AudioPlayerTagViewComponent, BodyTagsExtensions, BootstrapTableMethods, ButtonTagDataConsts, ButtonTagService, ChangeType, ConsoleVisualEditorLogger, CrocoHtmlFileOptionsService, CrocoHtmlModule, CrocoHtmlOptionsToken, CustomWidgetEditorComponent, CustomWidgetIconComponent, CustomWidgetTagDataConsts, CustomWidgetTagService, DEFAULT_BATCH_WINDOW_MS, DEFAULT_MAX_HISTORY_SIZE, DefinedCustomEditorBlockComponent, DefinedCustomTagViewComponent, DownloadButtonTagDataConsts, DownloadButtonTagService, EditorUndoRedoService, ExternalVideoEditorComponent, ExternalVideoPlayers, ExternalVideoSupportedTypes, ExternalVideoTagDataConsts, ExternalVideoTagService, FileAudioTagDataConsts, FileIdSelectComponent, FileImageTagDataConsts, FileImageTagService, FileImageTagViewComponent, FileType, HtmlPageDataController, HtmlRawEditorComponent, HtmlRawTagDataConsts, HtmlRawTagService, HtmlRawViewComponent, HtmlViewComponent, HtmlViewController, ImageEditorComponent, ImageMethods, LinkEditorComponent, LinkTagAttrs, LinkTagConsts, LinkTagService, MainEditorBlockComponent, MainEditorComponent, NullVisualEditorLogger, TableBuilder, TableMethods, TableTypes, TagBuildExtensions, TagChangeDetector, TagEditorService, TagToSpanPipe, TextAlignment, TextEditorComponent, TextSimpleMethods, TextTag, TextTagDataConsts, TextTagHtmlMarkupTagService, TextTags, ToHtmlBodyTagsPipe, ToPreviewHtmlPipe, ToPreviewPipe, UploadFilesBtnComponent, VisualEditorComponent, XmlExtensions, XmlTagCustomWidgetComponent, XmlTagExternalVideoComponent, XmlTagHeaderInnerTextViewComponent, XmlTagHeaderTextViewComponent, XmlTagHtmlViewComponent, XmlTagTextViewComponent, XmlTagViewComponent };
+export type { AngularMaterialTableData, BaseApiResponse, ButtonTag, ButtonTagData, ChangeBatch, ChangeSnapshot, ChangeTrackerOptions, CommonFileInfoResultModel, CrocoHtmlEditorFileOptions, CrocoHtmlImageOptions, CrocoHtmlOptions, CustomWidgetTag, CustomWidgetTagData, DownloadButtonTag, DownloadButtonTagData, ExternalVideoTag, ExternalVideoTagData, FileAudioTag, FileAudioTagData, FileImageTag, FileImageTagData, FileInfoModel, FilePostingStarted, FileRelationModel, FileSimpleModel, FileUnifiedModel, GenericTextTag, GetListResult, GetListSearchModel, HtmlBodyTag, HtmlRawTag, HtmlRawTagData, IHorizontalAlignmentExtractionResult, IImageMediaRequest, IMarkUpTagService, ITagEditorViewRender, ITagViewViewRender, IVisualEditorLogger, IVisualEditorProps, ImageRestrictions, InterfaceBlock, LinkTagData, SearchFilesRequest, SearchQuestionsFormData, SimpleTextTagData, TableData, TableHeaderData, TableRowColumnData, TableRowData, TableTagData, TagDiff, TagFieldChange, TagItem };