@pixerate/editor 0.18.0 → 0.20.0

package/dist/track-changes-G8JcWB8b.d.ts

@@ -0,0 +1,306 @@
+import * as _tiptap_core from '@tiptap/core';
+import { Extension, Mark, Editor } from '@tiptap/core';
+import * as _tiptap_extension_mention from '@tiptap/extension-mention';
+import { MentionOptions as MentionOptions$1 } from '@tiptap/extension-mention';
+import { SuggestionOptions } from '@tiptap/suggestion';
+import { EditorState, PluginKey } from '@tiptap/pm/state';
+import { Node } from '@tiptap/pm/model';
+
+interface MentionEntity {
+    id: string;
+    label: string;
+    type?: string;
+    avatarUrl?: string;
+    color?: string;
+    handle?: string;
+    name?: string;
+    hexColor?: string;
+    aliases?: string[];
+    [key: string]: any;
+}
+interface MentionOptions extends Partial<MentionOptions$1> {
+    HTMLAttributes?: Record<string, any>;
+    suggestion?: Partial<SuggestionOptions<MentionEntity>>;
+}
+/**
+ * First-class native Mention extension for @pixerate/editor.
+ * Creates atomic inline <span data-type="mention"> nodes with full suggestion support.
+ */
+declare const Mention: _tiptap_core.Node<MentionOptions$1<any, _tiptap_extension_mention.MentionNodeAttrs>, any>;
+/**
+ * Helper to configure the Mention extension with preset defaults.
+ */
+declare function createMentionExtension(options?: Partial<MentionOptions>): _tiptap_core.Node<MentionOptions$1<any, _tiptap_extension_mention.MentionNodeAttrs>, any>;
+
+/**
+ * Who made a comment, reply or tracked change.
+ */
+interface ReviewAuthor {
+    id: string;
+    name: string;
+    color?: string;
+    avatarUrl?: string;
+}
+/**
+ * Where a comment thread is attached in the document. `from`/`to` are
+ * ProseMirror positions and `quote` is the commented text at the time the
+ * anchor was last synced. Positions are only meaningful for the current
+ * document; the `comment` mark in the document is the source of truth.
+ */
+interface CommentAnchor {
+    from: number;
+    to: number;
+    quote: string;
+}
+interface CommentReply {
+    id: string;
+    author: ReviewAuthor;
+    body: string;
+    createdAt: number;
+    editedAt?: number;
+}
+interface CommentThread {
+    id: string;
+    /** `null` while the thread has no text in the document (see `orphaned`). */
+    anchor: CommentAnchor | null;
+    author: ReviewAuthor;
+    createdAt: number;
+    /** An empty body marks a draft that has not been posted yet. */
+    body: string;
+    editedAt?: number;
+    replies: CommentReply[];
+    resolved: boolean;
+    resolvedAt?: number;
+    resolvedBy?: ReviewAuthor;
+    /**
+     * True when the commented text was deleted from the document. Undoing the
+     * deletion re-attaches the thread.
+     */
+    orphaned: boolean;
+    /** The quote the thread had before it was orphaned. */
+    lastQuote?: string;
+}
+interface CommentStoreSnapshot {
+    /** Threads in document order (anchored first), then orphaned threads. */
+    threads: readonly CommentThread[];
+    activeThreadId: string | null;
+}
+/** JSON shape produced by `CommentStore.toJSON()`. */
+interface SerializedComments {
+    version: 1;
+    threads: CommentThread[];
+}
+interface CommentStoreOptions {
+    threads?: CommentThread[] | SerializedComments;
+    generateId?: () => string;
+    now?: () => number;
+}
+interface CreateThreadInput {
+    id?: string;
+    body: string;
+    author: ReviewAuthor;
+    anchor?: CommentAnchor | null;
+    createdAt?: number;
+}
+type CommentStoreListener = (snapshot: CommentStoreSnapshot) => void;
+/**
+ * Generates a reasonably unique id without depending on `crypto`.
+ */
+declare function createReviewId(prefix?: string): string;
+/**
+ * Headless, framework-agnostic store of comment threads.
+ *
+ * The store never talks to a server: persist `toJSON()` yourself and pass it
+ * back via `new CommentStore({ threads })` or `load()`. Snapshots are
+ * immutable and only replaced when something changes, so `getSnapshot` is safe
+ * to use with React's `useSyncExternalStore`. `subscribe` calls the listener
+ * immediately (Svelte store contract).
+ */
+declare class CommentStore {
+    private threads;
+    private activeThreadId;
+    private snapshot;
+    private listeners;
+    /** Deleted threads, kept so undoing a "Delete Comment" can restore them. */
+    private deleted;
+    private generateId;
+    private now;
+    constructor(options?: CommentStoreOptions);
+    /** Parses `toJSON()` output (or a plain thread array). */
+    static parse(json: string | CommentThread[] | SerializedComments): CommentThread[];
+    subscribe: (listener: CommentStoreListener) => (() => void);
+    getSnapshot: () => CommentStoreSnapshot;
+    getThread(id: string): CommentThread | undefined;
+    createThread(input: CreateThreadInput): CommentThread;
+    /** Edits the thread's body, or one of its replies when `replyId` is given. */
+    editComment(threadId: string, body: string, replyId?: string): boolean;
+    addReply(threadId: string, input: {
+        body: string;
+        author: ReviewAuthor;
+        id?: string;
+    }): CommentReply | null;
+    deleteReply(threadId: string, replyId: string): boolean;
+    resolveThread(id: string, resolved?: boolean, by?: ReviewAuthor): boolean;
+    deleteThread(id: string): boolean;
+    /** Deletes every thread whose text is no longer in the document. */
+    removeOrphanedThreads(): string[];
+    setActiveThread(id: string | null): void;
+    /**
+     * Updates anchors from the document. Threads missing from `anchors` become
+     * orphaned. Threads that were deleted but whose mark re-appeared (e.g. after
+     * undoing "Delete Comment") are restored. Returns true if anything changed.
+     */
+    syncAnchors(anchors: Map<string, CommentAnchor>): boolean;
+    /** Replaces all threads, e.g. with data loaded from a server. */
+    load(json: string | CommentThread[] | SerializedComments): void;
+    clear(): void;
+    toJSON(): SerializedComments;
+    private updateThread;
+    private computeSnapshot;
+    private emit;
+}
+declare function createCommentStore(options?: CommentStoreOptions): CommentStore;
+/**
+ * Short, human-readable timestamp for review UIs ("just now", "5m ago",
+ * "3h ago", then a locale date). Shared by the React and Svelte components.
+ */
+declare function formatReviewTime(timestamp: number, now?: number): string;
+
+declare const INSERTION_MARK_NAME = "insertion";
+declare const DELETION_MARK_NAME = "deletion";
+/**
+ * Set this transaction meta to `true` to apply a change without tracking it,
+ * e.g. `editor.chain().command(({ tr }) => { tr.setMeta(TRACK_CHANGES_SKIP_META, true); return true; }).setContent(…).run()`.
+ */
+declare const TRACK_CHANGES_SKIP_META = "trackChangesSkip";
+type TrackedChangeType = "insertion" | "deletion";
+/**
+ * How tracked content is rendered by serializers:
+ * - `accepted` (default): as if every change were accepted (deleted text is
+ *   dropped, inserted text kept).
+ * - `original`: as if every change were rejected.
+ * - `all`: both inserted and deleted text.
+ */
+type TrackedChangesView = "accepted" | "original" | "all";
+interface TrackedChangeAttributes {
+    changeId: string;
+    authorId: string;
+    authorName: string;
+    authorColor: string | null;
+    createdAt: number;
+}
+interface TrackedChange {
+    id: string;
+    type: TrackedChangeType;
+    author: ReviewAuthor;
+    createdAt: number;
+    /** Start of the first range. */
+    from: number;
+    /** End of the last range. */
+    to: number;
+    /** A change can be split into several ranges by other marks or blocks. */
+    ranges: {
+        from: number;
+        to: number;
+    }[];
+    text: string;
+}
+interface TrackChangesSnapshot {
+    enabled: boolean;
+    author: ReviewAuthor;
+    /** Changes in document order. */
+    changes: readonly TrackedChange[];
+    /** The change at the selection, if any. */
+    currentChangeId: string | null;
+}
+interface TrackChangesOptions {
+    /** Whether tracking is on when the editor is created. */
+    enabled: boolean;
+    author: ReviewAuthor;
+    now: () => number;
+    generateId: () => string;
+    insertionHTMLAttributes: Record<string, any>;
+    deletionHTMLAttributes: Record<string, any>;
+}
+/**
+ * External store over the editor's tracked-change state. Snapshots only
+ * change when the document, selection or tracking state changes, so they can
+ * be used with `useSyncExternalStore`. `subscribe` calls the listener
+ * immediately (Svelte store contract).
+ */
+declare class TrackChangesStore {
+    private snapshot;
+    private listeners;
+    constructor(initial: TrackChangesSnapshot);
+    subscribe: (listener: (snapshot: TrackChangesSnapshot) => void) => (() => void);
+    getSnapshot: () => TrackChangesSnapshot;
+    /** @internal Called by the extension's plugin view. */
+    set(snapshot: TrackChangesSnapshot): void;
+}
+interface TrackChangesStorage {
+    store: TrackChangesStore;
+}
+interface TrackChangesPluginState {
+    enabled: boolean;
+    author: ReviewAuthor;
+}
+declare const trackChangesPluginKey: PluginKey<TrackChangesPluginState>;
+declare module "@tiptap/core" {
+    interface Commands<ReturnType> {
+        trackChanges: {
+            setTrackChanges: (enabled: boolean) => ReturnType;
+            toggleTrackChanges: () => ReturnType;
+            setTrackChangesAuthor: (author: ReviewAuthor) => ReturnType;
+            /** Accepts one change (single undo step). */
+            acceptChange: (id: string) => ReturnType;
+            /** Rejects one change (single undo step). */
+            rejectChange: (id: string) => ReturnType;
+            acceptAllChanges: () => ReturnType;
+            rejectAllChanges: () => ReturnType;
+            /** Selects the next change after the selection, wrapping around. */
+            selectNextChange: () => ReturnType;
+            /** Selects the previous change before the selection, wrapping around. */
+            selectPreviousChange: () => ReturnType;
+        };
+    }
+}
+/**
+ * Text inserted while tracking was on. Rendered as `<ins>`.
+ */
+declare const TrackedInsertion: Mark<{
+    HTMLAttributes: Record<string, any>;
+}, any>;
+/**
+ * Text deleted while tracking was on. The text stays in the document until
+ * the change is accepted. Rendered as `<del>` (struck through).
+ */
+declare const TrackedDeletion: Mark<{
+    HTMLAttributes: Record<string, any>;
+}, any>;
+/**
+ * Lists tracked changes in document order. Accepts an editor, an editor
+ * state or a ProseMirror document.
+ */
+declare function getTrackedChanges(source: Editor | EditorState | Node | null | undefined): TrackedChange[];
+/** The change containing `pos` (defaults to the selection start). */
+declare function getTrackedChangeAt(state: EditorState, pos?: number, changes?: readonly TrackedChange[]): TrackedChange | null;
+declare function isTrackChangesEnabled(source: Editor | EditorState | null | undefined): boolean;
+/** Returns the tracked-changes store of an editor using `TrackChanges`. */
+declare function getTrackChangesStore(editor: Editor | null | undefined): TrackChangesStore | null;
+/**
+ * Returns a copy of `doc` with tracked changes resolved for `view`
+ * (`accepted` by default). The input document is not modified.
+ */
+declare function resolveTrackedChanges(doc: Node, view?: TrackedChangesView): Node;
+/**
+ * Suggestion mode / track changes. When enabled, typed and pasted content is
+ * marked as an insertion and deleted content is kept but marked as a
+ * deletion (struck through) until the change is accepted or rejected.
+ *
+ * Deleting your own insertion really deletes it. Formatting-only changes and
+ * block-structure changes (splitting/joining paragraphs, lists) are not
+ * tracked. IME composition is tracked once the composition ends.
+ */
+declare const TrackChanges: Extension<TrackChangesOptions, TrackChangesStorage>;
+
+export { getTrackedChanges as A, isTrackChangesEnabled as B, type CommentAnchor as C, DELETION_MARK_NAME as D, resolveTrackedChanges as E, trackChangesPluginKey as F, INSERTION_MARK_NAME as I, Mention as M, type ReviewAuthor as R, type SerializedComments as S, TRACK_CHANGES_SKIP_META as T, type CommentReply as a, CommentStore as b, type CommentStoreListener as c, type CommentStoreOptions as d, type CommentStoreSnapshot as e, type CommentThread as f, type CreateThreadInput as g, type MentionEntity as h, type MentionOptions as i, TrackChanges as j, type TrackChangesOptions as k, type TrackChangesSnapshot as l, type TrackChangesStorage as m, TrackChangesStore as n, type TrackedChange as o, type TrackedChangeAttributes as p, type TrackedChangeType as q, type TrackedChangesView as r, TrackedDeletion as s, TrackedInsertion as t, createCommentStore as u, createMentionExtension as v, createReviewId as w, formatReviewTime as x, getTrackChangesStore as y, getTrackedChangeAt as z };

package/dist/types-BZgcDsC5.d.cts

@@ -0,0 +1,42 @@
+interface Command {
+    execute: () => void;
+    undo: () => void;
+    redo?: () => void;
+    name: string;
+    tag?: string;
+    timestamp?: number;
+}
+interface HistoryState {
+    canUndo: boolean;
+    canRedo: boolean;
+    undoName: string;
+    redoName: string;
+    undoCount: number;
+    redoCount: number;
+}
+interface HistoryManagerOptions {
+    /**
+     * Maximum number of undo states to keep. Defaults to 50.
+     */
+    maxDepth?: number;
+    /**
+     * Optional callback fired whenever the history state changes.
+     */
+    onStateChange?: (state: HistoryState) => void;
+}
+interface SnapshotCommandOptions<T> {
+    name: string;
+    before: T;
+    after: T;
+    apply: (state: T) => void;
+    tag?: string;
+}
+interface MergedExecutionOptions {
+    /**
+     * Window in milliseconds during which commands with the same tag will be coalesced.
+     * Defaults to 300ms.
+     */
+    windowMs?: number;
+}
+
+export type { Command as C, HistoryManagerOptions as H, MergedExecutionOptions as M, SnapshotCommandOptions as S, HistoryState as a };

package/dist/types-BZgcDsC5.d.ts

@@ -0,0 +1,42 @@
+interface Command {
+    execute: () => void;
+    undo: () => void;
+    redo?: () => void;
+    name: string;
+    tag?: string;
+    timestamp?: number;
+}
+interface HistoryState {
+    canUndo: boolean;
+    canRedo: boolean;
+    undoName: string;
+    redoName: string;
+    undoCount: number;
+    redoCount: number;
+}
+interface HistoryManagerOptions {
+    /**
+     * Maximum number of undo states to keep. Defaults to 50.
+     */
+    maxDepth?: number;
+    /**
+     * Optional callback fired whenever the history state changes.
+     */
+    onStateChange?: (state: HistoryState) => void;
+}
+interface SnapshotCommandOptions<T> {
+    name: string;
+    before: T;
+    after: T;
+    apply: (state: T) => void;
+    tag?: string;
+}
+interface MergedExecutionOptions {
+    /**
+     * Window in milliseconds during which commands with the same tag will be coalesced.
+     * Defaults to 300ms.
+     */
+    windowMs?: number;
+}
+
+export type { Command as C, HistoryManagerOptions as H, MergedExecutionOptions as M, SnapshotCommandOptions as S, HistoryState as a };

package/dist/{types-JV3S8VeR.d.cts → types-DMe0vFB1.d.cts}

@@ -214,4 +214,4 @@ interface CanvasDockingCallbacks<TNode extends CanvasNode = CanvasNode> {
     onDockDrop?: (dockTarget: TNode, draggedNode: TNode) => void;
 }
 
-export type { CanvasNode as C, DirectionalDisplacementOptions as D, ExplodeNodeOptions as E, FanOutTrajectoryOptions as F, GraphDifferences as G, IncrementalLayoutOptions as I, NodeTransition as N, PlaceBesideOptions as P, Rect as R, Side as S, TrajectoryFunction as T, XYPosition as X, CanvasEdge as a, CanvasLayoutOptions as b, CanvasNodeStyle as c, ReflowDisplacementOptions as d, CanvasClipboardPayload as e, CanvasDockingCallbacks as f, CollapseNodeOptions as g, DisplacementDirection as h, DockStrategy as i, ExplosionSnapshot as j, Point as k, Position as l, TrajectoryPoint as m };
+export type { CanvasNode as C, DirectionalDisplacementOptions as D, ExplodeNodeOptions as E, FanOutTrajectoryOptions as F, GraphDifferences as G, IncrementalLayoutOptions as I, NodeTransition as N, PlaceBesideOptions as P, Rect as R, Side as S, TrajectoryFunction as T, XYPosition as X, CanvasEdge as a, CanvasLayoutOptions as b, CanvasNodeStyle as c, ReflowDisplacementOptions as d, CanvasClipboardPayload as e, Position as f, CanvasDockingCallbacks as g, CollapseNodeOptions as h, DisplacementDirection as i, DockStrategy as j, ExplosionSnapshot as k, Point as l, TrajectoryPoint as m };

package/dist/{types-JV3S8VeR.d.ts → types-DMe0vFB1.d.ts}

@@ -214,4 +214,4 @@ interface CanvasDockingCallbacks<TNode extends CanvasNode = CanvasNode> {
     onDockDrop?: (dockTarget: TNode, draggedNode: TNode) => void;
 }
 
-export type { CanvasNode as C, DirectionalDisplacementOptions as D, ExplodeNodeOptions as E, FanOutTrajectoryOptions as F, GraphDifferences as G, IncrementalLayoutOptions as I, NodeTransition as N, PlaceBesideOptions as P, Rect as R, Side as S, TrajectoryFunction as T, XYPosition as X, CanvasEdge as a, CanvasLayoutOptions as b, CanvasNodeStyle as c, ReflowDisplacementOptions as d, CanvasClipboardPayload as e, CanvasDockingCallbacks as f, CollapseNodeOptions as g, DisplacementDirection as h, DockStrategy as i, ExplosionSnapshot as j, Point as k, Position as l, TrajectoryPoint as m };
+export type { CanvasNode as C, DirectionalDisplacementOptions as D, ExplodeNodeOptions as E, FanOutTrajectoryOptions as F, GraphDifferences as G, IncrementalLayoutOptions as I, NodeTransition as N, PlaceBesideOptions as P, Rect as R, Side as S, TrajectoryFunction as T, XYPosition as X, CanvasEdge as a, CanvasLayoutOptions as b, CanvasNodeStyle as c, ReflowDisplacementOptions as d, CanvasClipboardPayload as e, Position as f, CanvasDockingCallbacks as g, CollapseNodeOptions as h, DisplacementDirection as i, DockStrategy as j, ExplosionSnapshot as k, Point as l, TrajectoryPoint as m };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",