@flogeez/angular-tiptap-editor 2.3.0 → 2.4.1

package/lib/models/ate-editor-config.model.d.ts

@@ -0,0 +1,100 @@
+import { Type } from "@angular/core";
+import { AteToolbarConfig } from "./ate-toolbar.model";
+import { RegisterAngularComponentOptions } from "../node-view/ate-node-view.models";
+import { AteBubbleMenuConfig, AteImageBubbleMenuConfig, AteTableBubbleMenuConfig, AteCellBubbleMenuConfig } from "./ate-bubble-menu.model";
+import { AteSlashCommandsConfig } from "../config/ate-slash-commands.config";
+import { AteImageUploadConfig } from "./ate-image.model";
+import { Extension, Node, Mark, EditorOptions } from "@tiptap/core";
+import { AteStateCalculator } from "./ate-editor-state.model";
+import { AteCustomSlashCommands } from "../components/slash-commands/ate-slash-commands.component";
+/**
+ * Type representing an Angular component that can be registered as an editor node.
+ * Can be a direct Component class or a full registration options object.
+ */
+export type AteAngularNode = Type<unknown> | RegisterAngularComponentOptions<unknown>;
+/**
+ * Global configuration interface for Angular Tiptap Editor.
+ * Uses a flat structure for common settings and objects for complex configurations.
+ */
+export interface AteEditorConfig {
+    /** Editor theme: light, dark, or system auto-detection */
+    theme?: "light" | "dark" | "auto";
+    /** Display mode: classic or seamless (no borders/background) */
+    mode?: "classic" | "seamless";
+    /** Editor height (e.g., '300px', 'auto') */
+    height?: string;
+    /** Focus position on initialization */
+    autofocus?: "start" | "end" | "all" | boolean | number;
+    /** Placeholder text displayed when the editor is empty */
+    placeholder?: string;
+    /** Initial editing state (if false, the editor is read-only) */
+    editable?: boolean;
+    /** Minimum editor height (e.g., '200px') */
+    minHeight?: string;
+    /** Maximum editor height (e.g., '500px') */
+    maxHeight?: string;
+    /** If true, the editor takes 100% of the parent container's height */
+    fillContainer?: boolean;
+    /** Disabled state (often used with forms) */
+    disabled?: boolean;
+    /** Editor locale (overrides the global i18n service) */
+    locale?: string;
+    /** Enable browser spellcheck */
+    spellcheck?: boolean;
+    /** Enable smart cleanup when pasting from Office/Word */
+    enableOfficePaste?: boolean;
+    /** Show or hide the toolbar */
+    showToolbar?: boolean;
+    /** Show or hide the footer (counters area) */
+    showFooter?: boolean;
+    /** Show or hide the character count */
+    showCharacterCount?: boolean;
+    /** Show or hide the word count */
+    showWordCount?: boolean;
+    /** Show or hide the read-only/edit toggle button */
+    showEditToggle?: boolean;
+    /** Show or hide the text context menu */
+    showBubbleMenu?: boolean;
+    /** Show or hide the image context menu */
+    showImageBubbleMenu?: boolean;
+    /** Show or hide the table menu */
+    showTableMenu?: boolean;
+    /** Show or hide the cell menu */
+    showCellMenu?: boolean;
+    /** Enable or disable slash commands (/) */
+    enableSlashCommands?: boolean;
+    /** Maximum number of characters allowed */
+    maxCharacters?: number;
+    /** Detailed toolbar configuration (items, groups) */
+    toolbar?: AteToolbarConfig;
+    /** Text context menu configuration */
+    bubbleMenu?: AteBubbleMenuConfig;
+    /** Image context menu configuration */
+    imageBubbleMenu?: AteImageBubbleMenuConfig;
+    /** Table context menu configuration */
+    tableBubbleMenu?: AteTableBubbleMenuConfig;
+    /** Cell context menu configuration */
+    cellBubbleMenu?: AteCellBubbleMenuConfig;
+    /** Slash commands configuration (/) */
+    slashCommands?: AteSlashCommandsConfig;
+    /** If true, shows the floating toolbar on focus */
+    floatingToolbar?: boolean;
+    /** Technical configuration for image uploads */
+    imageUpload?: AteImageUploadConfig;
+    /**
+     * List of Angular components to automatically register as interactive editor nodes.
+     * This is the preferred way to extend the editor with custom Angular logic.
+     */
+    angularNodes?: AteAngularNode[];
+    /** Standard TipTap extensions (Nodes, Marks, or Plugins) */
+    tiptapExtensions?: (Extension | Node | Mark)[];
+    /** Raw TipTap editor options (e.g., enableInputRules, injectCSS, etc.) */
+    tiptapOptions?: Partial<EditorOptions>;
+    /** Reactive state calculators to extend the editor's live state */
+    stateCalculators?: AteStateCalculator[];
+    /**
+     * Fully custom slash commands configuration.
+     * When provided, it replaces the default groups based on toolbar toggles.
+     */
+    customSlashCommands?: AteCustomSlashCommands;
+}

package/lib/models/ate-editor-state.model.d.ts

@@ -0,0 +1,109 @@
+import { Editor } from "@tiptap/core";
+export type AteStateCalculator = (editor: Editor) => Partial<{
+    [K in keyof AteEditorStateSnapshot]: AteEditorStateSnapshot[K] extends object ? Partial<AteEditorStateSnapshot[K]> : AteEditorStateSnapshot[K];
+}>;
+export interface AteEditorStateSnapshot {
+    /** Global editor states */
+    isFocused: boolean;
+    isEditable: boolean;
+    /**
+     * Detailed selection information to avoid overlap between menus
+     */
+    selection: {
+        type: "text" | "node" | "cell" | "none";
+        from: number;
+        to: number;
+        empty: boolean;
+        /** Specific for CellSelection */
+        isSingleCell: boolean;
+    };
+    /** Text formatting states (Marks) */
+    marks: {
+        bold: boolean;
+        italic: boolean;
+        underline: boolean;
+        strike: boolean;
+        code: boolean;
+        superscript: boolean;
+        subscript: boolean;
+        highlight: boolean;
+        link: boolean;
+        linkHref: string | null;
+        color: string | null;
+        computedColor: string | null;
+        background: string | null;
+        computedBackground: string | null;
+        linkOpenOnClick: boolean;
+    };
+    /** Capability states (canExecute) */
+    can: {
+        toggleBold: boolean;
+        toggleItalic: boolean;
+        toggleUnderline: boolean;
+        toggleStrike: boolean;
+        toggleCode: boolean;
+        toggleHighlight: boolean;
+        toggleLink: boolean;
+        toggleSuperscript: boolean;
+        toggleSubscript: boolean;
+        setColor: boolean;
+        setHighlight: boolean;
+        undo: boolean;
+        redo: boolean;
+        /** Table specific capabilities */
+        addRowBefore: boolean;
+        addRowAfter: boolean;
+        deleteRow: boolean;
+        addColumnBefore: boolean;
+        addColumnAfter: boolean;
+        deleteColumn: boolean;
+        deleteTable: boolean;
+        mergeCells: boolean;
+        splitCell: boolean;
+        toggleHeaderRow: boolean;
+        toggleHeaderColumn: boolean;
+        /** Structure/Node capabilities */
+        toggleHeading1: boolean;
+        toggleHeading2: boolean;
+        toggleHeading3: boolean;
+        toggleBulletList: boolean;
+        toggleOrderedList: boolean;
+        toggleBlockquote: boolean;
+        toggleCodeBlock: boolean;
+        setTextAlignLeft: boolean;
+        setTextAlignCenter: boolean;
+        setTextAlignRight: boolean;
+        setTextAlignJustify: boolean;
+        insertHorizontalRule: boolean;
+        insertTable: boolean;
+        insertImage: boolean;
+    };
+    /** Current node context */
+    nodes: {
+        isTable: boolean;
+        isTableNodeSelected: boolean;
+        isTableCell: boolean;
+        isImage: boolean;
+        isBlockquote: boolean;
+        isCodeBlock: boolean;
+        isBulletList: boolean;
+        isOrderedList: boolean;
+        /** Headings */
+        h1: boolean;
+        h2: boolean;
+        h3: boolean;
+        /** Alignment */
+        alignLeft: boolean;
+        alignCenter: boolean;
+        alignRight: boolean;
+        alignJustify: boolean;
+        /** Table specific */
+        isTableHeaderRow: boolean;
+        isTableHeaderColumn: boolean;
+        /** Name of the active node at selection head */
+        activeNodeName: string | null;
+    };
+    /** Placeholder for custom extension states */
+    custom: Record<string, unknown>;
+}
+export declare const ATE_INITIAL_EDITOR_STATE: AteEditorStateSnapshot;

package/lib/models/ate-image.model.d.ts

@@ -0,0 +1,104 @@
+import { Observable } from "rxjs";
+export interface AteImageData {
+    src: string;
+    alt?: string;
+    title?: string;
+    width?: number;
+    height?: number;
+}
+export interface AteImageUploadResult {
+    src: string;
+    name: string;
+    size: number;
+    type: string;
+    width?: number;
+    height?: number;
+    originalSize?: number;
+}
+export interface AteResizeOptions {
+    width?: number;
+    height?: number;
+    maintainAspectRatio?: boolean;
+}
+export interface AteImageUploadOptions {
+    quality?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+    maxSize?: number;
+    allowedTypes?: string[];
+}
+/**
+ * Context passed to the image upload handler containing information about the image
+ */
+export interface AteImageUploadContext {
+    /** Original file being uploaded */
+    file: File;
+    /** Width of the processed image */
+    width: number;
+    /** Height of the processed image */
+    height: number;
+    /** MIME type of the image */
+    type: string;
+    /** Base64 data URL of the processed image (after compression/resize) */
+    base64: string;
+}
+/**
+ * Result expected from a custom image upload handler.
+ * Must contain at least the `src` property with the image URL.
+ */
+export interface AteImageUploadHandlerResult {
+    /** URL of the uploaded image (can be a remote URL or any string) */
+    src: string;
+    /** Optional custom alt text */
+    alt?: string;
+    /** Optional custom title */
+    title?: string;
+}
+/**
+ * Custom handler function for image uploads.
+ * Allows users to implement their own image storage logic (e.g., upload to S3, Cloudinary, etc.)
+ *
+ * Can return either a Promise or an Observable (Angular-friendly).
+ *
+ * @param context - Context containing the image file and metadata
+ * @returns Promise or Observable resolving to ImageUploadHandlerResult
+ *
+ * @example Using Promise (async/await)
+ * ```typescript
+ * uploadHandler: ImageUploadHandler = async (ctx) => {
+ *   const formData = new FormData();
+ *   formData.append('image', ctx.file);
+ *   const result = await firstValueFrom(this.http.post<{url: string}>('/api/upload', formData));
+ *   return { src: result.url };
+ * };
+ * ```
+ *
+ * @example Using Observable (Angular HttpClient)
+ * ```typescript
+ * uploadHandler: ImageUploadHandler = (ctx) => {
+ *   const formData = new FormData();
+ *   formData.append('image', ctx.file);
+ *   return this.http.post<{url: string}>('/api/upload', formData).pipe(
+ *     map(result => ({ src: result.url }))
+ *   );
+ * };
+ * ```
+ */
+export type AteImageUploadHandler = (context: AteImageUploadContext) => Promise<AteImageUploadHandlerResult> | Observable<AteImageUploadHandlerResult>;
+/**
+ * Interface dedicated to image upload configuration.
+ */
+export interface AteImageUploadConfig {
+    /** Callback function to handle upload (Promise or Observable) */
+    handler?: AteImageUploadHandler;
+    /** Compression quality (0 to 1) */
+    quality?: number;
+    /** Maximum allowed width in pixels */
+    maxWidth?: number;
+    /** Maximum allowed height in pixels */
+    maxHeight?: number;
+    /** Maximum allowed size in MB */
+    maxSize?: number;
+    /** Accepted file types (e.g., ['image/jpeg', 'image/png']) */
+    allowedTypes?: string[];
+}

package/lib/models/ate-toolbar.model.d.ts

@@ -0,0 +1,18 @@
+import { Editor } from "@tiptap/core";
+/**
+ * Clés des boutons de la barre d'outils native
+ */
+export declare const ATE_TOOLBAR_KEYS: readonly ["bold", "italic", "underline", "strike", "code", "codeBlock", "superscript", "subscript", "highlight", "highlightPicker", "heading1", "heading2", "heading3", "bulletList", "orderedList", "blockquote", "alignLeft", "alignCenter", "alignRight", "alignJustify", "link", "image", "horizontalRule", "table", "undo", "redo", "clear", "textColor", "separator"];
+export type AteToolbarKey = (typeof ATE_TOOLBAR_KEYS)[number];
+export interface AteToolbarConfig extends Partial<Record<AteToolbarKey, boolean>> {
+    /**
+     * Boutons personnalisés à ajouter
+     */
+    custom?: AteCustomToolbarItem[];
+}
+export interface AteCustomToolbarItem {
+    key: string;
+    label: string;
+    icon: string;
+    command: (editor: Editor) => void | Promise<void>;
+}

package/lib/node-view/ate-angular-node-view.d.ts

@@ -0,0 +1,115 @@
+import { Signal } from "@angular/core";
+import { Node as ProseMirrorNode } from "@tiptap/pm/model";
+import { Decoration } from "@tiptap/pm/view";
+import { Editor } from "@tiptap/core";
+import * as i0 from "@angular/core";
+/**
+ * Props that are injected into Angular NodeView components
+ */
+export interface AteAngularNodeViewProps {
+    editor: Editor;
+    node: ProseMirrorNode;
+    decorations: readonly Decoration[];
+    selected: boolean;
+    extension: unknown;
+    getPos: () => number | undefined;
+    updateAttributes: (attrs: Record<string, unknown>) => void;
+    deleteNode: () => void;
+}
+/**
+ * Base abstract class for custom 'Angular Nodes'.
+ *
+ * Extend this class in your custom components to automatically receive TipTap editor
+ * properties (node attributes, selection state, etc.) as reactive Signals.
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   selector: 'app-counter',
+ *   template: `
+ *     <div>
+ *       <button (click)="increment()">Count: {{ node().attrs['count'] }}</button>
+ *     </div>
+ *   `
+ * })
+ * export class CounterComponent extends AteAngularNodeView {
+ *   increment() {
+ *     const count = this.node().attrs['count'] || 0;
+ *     this.updateAttributes({ count: count + 1 });
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class AteAngularNodeView {
+    /**
+     * The TipTap editor instance
+     */
+    editor: Signal<Editor>;
+    /**
+     * The ProseMirror node
+     */
+    node: Signal<ProseMirrorNode>;
+    /**
+     * Decorations applied to this node
+     */
+    decorations: Signal<readonly Decoration[]>;
+    /**
+     * Whether the node is currently selected
+     */
+    selected: Signal<boolean>;
+    /**
+     * The extension instance that created this node
+     */
+    extension: Signal<unknown>;
+    /**
+     * Function to get the current position of this node in the document
+     */
+    getPos: () => number | undefined;
+    /**
+     * Update the attributes of this node
+     *
+     * @param attrs - Partial attributes to update
+     *
+     * @example
+     * ```typescript
+     * this.updateAttributes({ count: 5, color: 'blue' });
+     * ```
+     */
+    updateAttributes: (attrs: Record<string, unknown>) => void;
+    /**
+     * Delete this node from the document
+     */
+    deleteNode: () => void;
+    /** @internal */
+    private _writableSignals?;
+    /**
+     * Internal method to initialize the component with NodeView props.
+     * This is called by the AngularNodeViewRenderer.
+     *
+     * @internal
+     */
+    _initNodeView(props: AteAngularNodeViewProps): void;
+    /**
+     * Internal method to update the component when the node changes.
+     * This is called by the AngularNodeViewRenderer.
+     *
+     * @internal
+     */
+    _updateNodeView(node: ProseMirrorNode, decorations: readonly Decoration[]): void;
+    /**
+     * Internal method to update the selection state.
+     * This is called by the AngularNodeViewRenderer.
+     *
+     * @internal
+     */
+    _selectNodeView(): void;
+    /**
+     * Internal method to update the deselection state.
+     * This is called by the AngularNodeViewRenderer.
+     *
+     * @internal
+     */
+    _deselectNodeView(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AteAngularNodeView, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<AteAngularNodeView, never, never, {}, {}, never, never, false, never>;
+}

package/lib/node-view/ate-injector.registry.d.ts

@@ -0,0 +1,3 @@
+import { Injector } from "@angular/core";
+export declare function setGlobalInjector(injector: Injector): void;
+export declare function getGlobalInjector(): Injector;

package/lib/node-view/ate-node-view.factory.d.ts

@@ -0,0 +1,10 @@
+import { Injector } from "@angular/core";
+import { Node } from "@tiptap/core";
+import { RegisterAngularComponentOptions } from "./ate-node-view.models";
+/**
+ * Factory to transform an Angular component into a TipTap Node extension.
+ * Supports both "TipTap-Aware" and "Standard" modes.
+ *
+ * @internal
+ */
+export declare function createAngularComponentExtension<T = unknown>(injector: Injector, options: RegisterAngularComponentOptions<T>): Node;

package/lib/node-view/ate-node-view.models.d.ts

@@ -0,0 +1,138 @@
+import { Injector, Type } from "@angular/core";
+import { NodeConfig } from "@tiptap/core";
+import { Node as ProseMirrorNode } from "@tiptap/pm/model";
+/**
+ * Common options for rendering any Angular component as a TipTap NodeView
+ */
+export interface AteComponentRenderOptions {
+    /**
+     * Angular injector to use for creating the component
+     */
+    injector: Injector;
+    /**
+     * Additional inputs to pass to the component
+     */
+    inputs?: Record<string, unknown>;
+    /**
+     * Custom wrapper element tag (default: 'div')
+     */
+    wrapperTag?: string;
+    /**
+     * CSS classes to add to the wrapper element
+     */
+    wrapperClass?: string;
+    /**
+     * Whether the node should be treated as an atom (not editable)
+     * Default: true
+     */
+    atom?: boolean;
+    /**
+     * Enables editable content for <ng-content>.
+     * If true, TipTap will treat the component's content as editable.
+     * @default false
+     */
+    editableContent?: boolean;
+    /**
+     * Optional CSS selector to target an internal element of the component as the editable area.
+     */
+    contentSelector?: string;
+    /**
+     * Type of content allowed in the editable area.
+     */
+    contentMode?: "block" | "inline";
+    /**
+     * Whether to ignore mutations in the component's DOM.
+     * If true, TipTap won't try to sync changes from the component's DOM back to the editor state.
+     * @default true
+     */
+    ignoreMutation?: boolean | ((mutation: MutationRecord | {
+        type: "selection";
+        target: Node;
+    }) => boolean);
+    /**
+     * Callback called when an Output event is emitted by the component.
+     */
+    onOutput?: (outputName: string, value: unknown) => void;
+    /**
+     * Callback called when the node is updated.
+     */
+    onUpdate?: (node: ProseMirrorNode) => void;
+    /**
+     * Callback called when the component is destroyed.
+     */
+    onDestroy?: () => void;
+}
+/**
+ * Unified configuration for registering an Angular component as an interactive 'Angular Node'.
+ * This provides high-level options to map Angular component logic (inputs, outputs, lifestyle)
+ * directly to TipTap's document structure.
+ */
+export interface RegisterAngularComponentOptions<T = unknown> {
+    /**
+     * The Angular component to register
+     */
+    component: Type<T>;
+    /**
+     * Unique name for the TipTap node
+     */
+    name?: string;
+    /**
+     * Default inputs (for standard components)
+     */
+    defaultInputs?: Record<string, unknown>;
+    /**
+     * TipTap attributes (for TipTap-aware components)
+     */
+    attributes?: Record<string, {
+        default?: unknown;
+        parseHTML?: (element: HTMLElement) => unknown;
+        renderHTML?: (attributes: Record<string, unknown>) => Record<string, unknown> | null;
+    }>;
+    /**
+     * CSS selector for the editable area inside the component
+     */
+    contentSelector?: string;
+    /**
+     * Content mode for the editable area
+     */
+    contentMode?: "block" | "inline";
+    /**
+     * Enable editable content via <ng-content> or contentSelector
+     * @default false
+     */
+    editableContent?: boolean;
+    /**
+     * Node group (block or inline)
+     * @default 'block'
+     */
+    group?: "block" | "inline";
+    /**
+     * Is the node draggable?
+     * @default true
+     */
+    draggable?: boolean;
+    /**
+     * Whether to ignore mutations in the component's DOM.
+     * @default true
+     */
+    ignoreMutation?: boolean | ((mutation: MutationRecord | {
+        type: "selection";
+        target: Node;
+    }) => boolean);
+    /**
+     * Custom HTML attributes for the wrapper
+     */
+    HTMLAttributes?: Record<string, unknown>;
+    /**
+     * Custom parseHTML rules
+     */
+    parseHTML?: NodeConfig["parseHTML"];
+    /**
+     * Custom renderHTML function
+     */
+    renderHTML?: NodeConfig["renderHTML"];
+    /**
+     * Callback called when an Output event is emitted by the component.
+     */
+    onOutput?: (outputName: string, value: unknown) => void;
+}

package/lib/node-view/ate-node-view.renderer.d.ts

@@ -0,0 +1,23 @@
+import { Type } from "@angular/core";
+import { NodeView, Decoration, EditorView } from "@tiptap/pm/view";
+import { Node as ProseMirrorNode } from "@tiptap/pm/model";
+import { Editor } from "@tiptap/core";
+import { AteComponentRenderOptions } from "./ate-node-view.models";
+/**
+ * Universal Renderer for Angular Components as TipTap NodeViews.
+ *
+ * Supports:
+ * - TipTap-Aware components (extending AteAngularNodeView)
+ * - Standard library components (automatic @Input() sync)
+ * - Signal-based inputs and outputs (Angular 18+)
+ * - Content projection (editableContent)
+ * - Unified lifecycle and event management
+ */
+export declare function AteNodeViewRenderer<T>(component: Type<T>, options: AteComponentRenderOptions): (props: {
+    node: ProseMirrorNode;
+    view: EditorView;
+    getPos: () => number | undefined;
+    decorations: readonly Decoration[];
+    editor: Editor;
+    extension: unknown;
+}) => NodeView;

package/lib/node-view/ate-register-angular-component.d.ts

@@ -0,0 +1,35 @@
+import { Injector } from "@angular/core";
+import { Node } from "@tiptap/core";
+import { RegisterAngularComponentOptions } from "./ate-node-view.models";
+/**
+ * Registers ANY Angular component as a TipTap node extension.
+ *
+ * This function is the single public entry point for adding custom components.
+ * It supports two distinct modes:
+ *
+ * 1. **TipTap-Aware Mode** (the component extends `AteAngularNodeView`):
+ *    Grants direct access to the TipTap API (`editor`, `node`, `updateAttributes`, etc.) within the component.
+ *
+ * 2. **Standard Mode** (library or legacy components):
+ *    Allows using any existing Angular component. Its `@Input()` properties are automatically
+ *    synchronized with TipTap node attributes.
+ *
+ * @param injectorOrOptions - The Angular Injector OR the configuration options
+ * @param maybeOptions - Configuration options (if the first param was an injector)
+ * @returns A TipTap Node extension ready to be used
+ *
+ * @example
+ * ```typescript
+ * // Modern way (requires provideAteEditor())
+ * registerAngularComponent({
+ *   component: MyComponent,
+ *   name: 'myComponent'
+ * });
+ *
+ * // Classic way
+ * registerAngularComponent(injector, {
+ *   component: MyComponent
+ * });
+ * ```
+ */
+export declare function registerAngularComponent<T = unknown>(injectorOrOptions: Injector | RegisterAngularComponentOptions<T>, maybeOptions?: RegisterAngularComponentOptions<T>): Node;