@fileverse-dev/ddoc 3.1.7-linkCaption-0 → 3.1.7-sg-1

package/dist/package/stores/comment-store.d.ts

@@ -0,0 +1,263 @@
+import { Editor } from '@tiptap/react';
+import { default as React } from 'react';
+import { CommentAnchor } from '../extensions/comment/comment-decoration-plugin';
+import { CommentFloatingCard, EnsCache, InlineCommentData, InlineCommentDraft, InlineDraftLocation } from '../components/inline-comment/context/types';
+import { EnsStatus } from '../components/inline-comment/types';
+import { IComment } from '../extensions/comment';
+import { CommentMutationMeta, CommentMutationType } from '../types';
+
+import * as Y from 'yjs';
+export interface CommentExternalDeps {
+    editor: Editor | null;
+    ydoc: Y.Doc;
+    setActiveCommentId: (id: string | null) => void;
+    focusCommentWithActiveId: (id: string) => void;
+    setInitialComments?: React.Dispatch<React.SetStateAction<IComment[]>>;
+    setUsername?: React.Dispatch<React.SetStateAction<string>>;
+    onNewComment?: (comment: IComment, meta?: CommentMutationMeta) => void;
+    onEditComment?: (commentId: string, meta?: CommentMutationMeta) => void;
+    onEditReply?: (commentId: string, replyId: string, meta?: CommentMutationMeta) => void;
+    onCommentReply?: (activeCommentId: string, reply: IComment) => void;
+    onResolveComment?: (commentId: string, meta?: CommentMutationMeta) => void;
+    onUnresolveComment?: (commentId: string, meta?: CommentMutationMeta) => void;
+    onDeleteComment?: (commentId: string, meta?: CommentMutationMeta) => void;
+    onInlineComment?: () => void;
+    onComment?: () => void;
+    setCommentDrawerOpen?: (open: boolean) => void;
+    connectViaWallet?: () => Promise<void>;
+    connectViaUsername?: (username: string) => Promise<void>;
+    ensResolutionUrl: string;
+    commentAnchorsRef?: React.MutableRefObject<CommentAnchor[]>;
+    refreshCommentAnchorState?: () => void;
+    /**
+     * Derived anchor list for in-progress suggestion drafts. Maintained by the
+     * store (not the consumer) — draft actions upsert into this ref whenever
+     * state.drafts changes. The decoration extension reads this ref alongside
+     * commentAnchorsRef to render both layers identically.
+     */
+    draftAnchorsRef?: React.MutableRefObject<CommentAnchor[]>;
+}
+/**
+ * A suggestion draft is the viewer's in-progress proposed edit — kept local
+ * until Submit. Drafts live in memory only (lost on refresh). Derived into
+ * a CommentAnchor for decoration rendering via deriveDraftAnchor(). The
+ * suggestion type ('add' | 'delete' | 'replace') is not stored; it is derived
+ * at use time from hadDeletion + insertedText.
+ */
+export interface DraftSuggestion {
+    id: string;
+    anchorFrom: Y.RelativePosition;
+    anchorTo: Y.RelativePosition;
+    /** The text that was selected at draft creation (for Delete/Replace strikethrough). */
+    originalContent: string;
+    /** Accumulated text the viewer has typed. Empty for a pure Delete draft. */
+    insertedText: string;
+    /** Per-keystroke history for undo — each entry is one typed character. */
+    keystrokes: string[];
+    /** True when the draft was created via select+delete or select+type. */
+    hadDeletion: boolean;
+}
+type FloatingCardsUpdater = React.SetStateAction<CommentFloatingCard[]>;
+type InlineCommentDataUpdater = Partial<InlineCommentData> | ((prev: InlineCommentData) => Partial<InlineCommentData> | InlineCommentData);
+type InlineDraftRecordMap = Record<string, InlineCommentDraft>;
+type CreateInlineDraftOptions = {
+    location?: InlineDraftLocation;
+    tabId?: string;
+    allowEmptySelection?: boolean;
+};
+type CommentEditRequest = {
+    requestId: string;
+    kind: 'comment' | 'reply';
+    commentId: string;
+    replyId?: string;
+    text: string;
+};
+type ReplyEditTarget = {
+    kind: 'comment' | 'reply';
+    commentId: string;
+    replyId?: string;
+    originalText: string;
+};
+type CommentEditCompletion = {
+    nonce: number;
+    kind: 'comment' | 'reply';
+    commentId: string;
+    replyId?: string;
+};
+type FocusCommentInEditorOptions = {
+    source?: 'explicit-ui' | 'passive';
+};
+type ReconcileFloatingThreadsForActiveTabOptions = {
+    hydrationReady: boolean;
+};
+export declare const EXPLICIT_COMMENT_FOCUS_META = "inlineCommentExplicitFocus";
+export interface CommentStoreState {
+    initialComments: IComment[];
+    tabComments: IComment[];
+    activeComments: IComment[];
+    activeComment: IComment | undefined;
+    activeCommentIndex: number;
+    username: string | null;
+    activeCommentId: string | null;
+    activeTabId: string;
+    isConnected: boolean;
+    isLoading: boolean;
+    isDDocOwner: boolean;
+    onComment: (() => void) | null;
+    setCommentDrawerOpen: ((open: boolean) => void) | null;
+    connectViaWallet: (() => Promise<void>) | null;
+    connectViaUsername: ((username: string) => Promise<void>) | null;
+    isCommentActive: boolean;
+    isCommentResolved: boolean;
+    showResolved: boolean;
+    reply: string;
+    comment: string;
+    openReplyId: string | null;
+    selectedText: string;
+    isCommentOpen: boolean;
+    isBubbleMenuSuppressed: boolean;
+    inlineCommentData: InlineCommentData;
+    floatingCards: CommentFloatingCard[];
+    pendingPrehydrationFloatingThreadIds: string[];
+    /** In-progress suggestion drafts — keyed by suggestionId. Viewer-local, lost on refresh. */
+    drafts: Record<string, DraftSuggestion>;
+    /**
+     * Suggestion IDs submitted from this session. Used to show the withdraw (X)
+     * action for viewers even when they don't have a persistent username set.
+     * Session-local, lost on refresh.
+     */
+    mySubmittedSuggestionIds: Set<string>;
+    inlineDrafts: InlineDraftRecordMap;
+    activeDraftId: string | null;
+    isDesktopFloatingEnabled: boolean;
+    ensCache: EnsCache;
+    inProgressFetch: string[];
+    editRequest: CommentEditRequest | null;
+    replyEditTarget: ReplyEditTarget | null;
+    editCompletion: CommentEditCompletion | null;
+    _externalDepsRef: React.RefObject<CommentExternalDeps | null> | null;
+    setExternalDepsRef: (ref: React.RefObject<CommentExternalDeps | null>) => void;
+    _recomputeDerived: () => void;
+    setInitialComments: (comments: IComment[]) => void;
+    setUsername: (username: string | null) => void;
+    setActiveCommentId: (id: string | null) => void;
+    setActiveTabId: (tabId: string) => void;
+    setIsConnected: (connected: boolean) => void;
+    setIsLoading: (loading: boolean) => void;
+    setIsDDocOwner: (isOwner: boolean) => void;
+    setOnComment: (fn: (() => void) | null) => void;
+    setCommentDrawerOpenFn: (fn: ((open: boolean) => void) | null) => void;
+    setConnectViaWallet: (fn: (() => Promise<void>) | null) => void;
+    setConnectViaUsername: (fn: ((username: string) => Promise<void>) | null) => void;
+    setIsCommentActive: (active: boolean) => void;
+    setIsCommentResolved: (resolved: boolean) => void;
+    getTabComments: () => IComment[];
+    getActiveComment: () => IComment | undefined;
+    getActiveComments: () => IComment[];
+    getActiveCommentIndex: () => number;
+    getIsCommentActive: () => boolean;
+    getIsCommentResolved: () => boolean;
+    setShowResolved: (show: boolean) => void;
+    setReply: (reply: string) => void;
+    setComment: (comment: string) => void;
+    setOpenReplyId: (id: string | null) => void;
+    setSelectedText: (text: string) => void;
+    setIsCommentOpen: (open: boolean) => void;
+    setIsBubbleMenuSuppressed: (suppressed: boolean) => void;
+    setInlineCommentData: (data: InlineCommentDataUpdater) => void;
+    setFloatingCards: (floatingCards: FloatingCardsUpdater) => void;
+    clearFloatingCards: () => void;
+    setActiveDraftId: (draftId: string | null) => void;
+    setIsDesktopFloatingEnabled: (enabled: boolean) => void;
+    toggleResolved: () => void;
+    clearEditRequest: (requestId: string) => void;
+    setReplyEditTarget: (target: ReplyEditTarget | null) => void;
+    cancelReplyEdit: () => void;
+    handleInput: (e: React.FormEvent<HTMLTextAreaElement>, content: string) => void;
+    handleReplyChange: (e: React.ChangeEvent<HTMLTextAreaElement>) => void;
+    handleCommentChange: (e: React.ChangeEvent<HTMLTextAreaElement>) => void;
+    handleCommentKeyDown: (e: React.KeyboardEvent<HTMLTextAreaElement>, tabId?: string) => void;
+    handleReplyKeyDown: (e: React.KeyboardEvent<HTMLTextAreaElement>) => void;
+    handleReplySubmit: () => void;
+    handleCommentSubmit: (tabId?: string) => void;
+    handleInlineComment: () => void;
+    addComment: (content?: string, usernameProp?: string) => string | undefined;
+    createFloatingDraft: (options?: CreateInlineDraftOptions) => string | null;
+    updateInlineDraftText: (draftId: string, value: string) => void;
+    cancelInlineDraft: (draftId: string) => void;
+    submitInlineDraft: (draftId: string) => void;
+    updateFloatingDraftText: (draftId: string, value: string) => void;
+    cancelFloatingDraft: (draftId: string) => void;
+    submitFloatingDraft: (draftId: string) => void;
+    openFloatingThread: (commentId: string) => void;
+    closeFloatingCard: (floatingCardId: string) => void;
+    blurFloatingCard: (floatingCardId: string) => void;
+    focusFloatingCard: (floatingCardId: string) => void;
+    removeInvalidFloatingDrafts: () => void;
+    reconcileFloatingThreadsForActiveTab: (options: ReconcileFloatingThreadsForActiveTabOptions) => void;
+    syncFloatingThreadCardWithActiveComment: () => void;
+    submitPendingFloatingDrafts: () => void;
+    /**
+     * Apply anchor edits to local comment state.
+     * Called after transaction analysis identifies edited anchors.
+     * Updates selectedContent for each affected comment
+     * so thread display stays in sync immediately, before consumer rehydration.
+     */
+    applyCommentAnchorEdits: (edits: Array<{
+        commentId: string;
+        selectedContent: string;
+    }>) => void;
+    resolveComment: (commentId: string) => void;
+    unresolveComment: (commentId: string) => void;
+    deleteComment: (commentId: string, options?: {
+        skipExternalCallback?: boolean;
+    }) => void;
+    acceptSuggestion: (commentId: string) => void;
+    /**
+     * Append typed characters to the draft at the current cursor position.
+     * Creates a new Add draft if no draft exists at the cursor.
+     */
+    appendToDraftAtCursor: (text: string) => void;
+    /**
+     * Create a Delete (or pending Replace) draft from a selection range.
+     * Captures originalContent, leaves insertedText empty; type becomes 'replace'
+     * as soon as the viewer types.
+     */
+    startDeleteDraft: (from: number, to: number) => void;
+    /**
+     * Undo the last keystroke in the draft at the current cursor position.
+     * When the draft has no keystrokes left, it is discarded.
+     * For a pure Delete draft (no keystrokes ever), calling this discards.
+     */
+    undoLastKeystrokeInActiveDraft: () => void;
+    /** Drop a draft entirely — removes the inline overlay and draft card. */
+    discardDraft: (suggestionId: string) => void;
+    /**
+     * Refresh the `originalContent` (and the suggestion-draft card's selectedText)
+     * for a Delete/Replace draft whose anchored range still resolves but now
+     * covers different text — happens when the owner edits within the anchored
+     * range while the viewer's draft is open.
+     */
+    refreshDraftOriginalContent: (suggestionId: string, currentText: string) => void;
+    /**
+     * Promote a draft to a submitted suggestion. Pushes the anchor into
+     * commentAnchorsRef, calls onNewComment, removes the draft, and swaps the
+     * suggestion-draft floating card for a thread card (same floatingCardId).
+     */
+    submitDraft: (suggestionId: string) => void;
+    deleteReply: (commentId: string, replyId: string) => void;
+    requestEditComment: (commentId: string) => void;
+    requestEditReply: (commentId: string, replyId: string) => void;
+    editCommentContent: (commentId: string, content: string) => void;
+    editReplyContent: (commentId: string, replyId: string, content: string) => void;
+    handleAddReply: (activeCommentId: string, replyContent: string, replyCallback?: (activeCommentId: string, reply: IComment) => void) => void;
+    focusCommentInEditor: (commentId: string, options?: FocusCommentInEditorOptions) => void;
+    onPrevComment: () => void;
+    onNextComment: () => void;
+    getEnsStatus: (walletAddress: string, setEnsStatus: React.Dispatch<React.SetStateAction<EnsStatus>>) => void;
+    createMutationMeta: (type: CommentMutationType, mutate: () => boolean) => CommentMutationMeta | undefined;
+}
+export declare const createCommentStore: () => import('zustand').StoreApi<CommentStoreState>;
+export declare const CommentStoreContext: React.Context<import('zustand').StoreApi<CommentStoreState> | null>;
+export declare function useCommentStore<T>(selector: (state: CommentStoreState) => T): T;
+export {};

package/dist/package/types.d.ts

@@ -19,10 +19,29 @@ export type InlineCommentData = {
     highlightedTextContent: string;
     handleClick: boolean;
 };
-export type CommentMutationType = 'create' | 'resolve' | 'unresolve' | 'delete';
+export type CommentMutationType = 'create' | 'edit' | 'resolve' | 'unresolve' | 'delete';
+export type SuggestionType = 'add' | 'replace' | 'delete';
 export interface CommentMutationMeta {
     type: CommentMutationType;
-    updateChunk: string;
+    updateChunk?: string;
+    anchorFrom?: string;
+    anchorTo?: string;
+    selectedContent?: string;
+    content?: string;
+    suggestionType?: SuggestionType;
+    originalContent?: string;
+    suggestedContent?: string;
+}
+export interface SerializedCommentAnchor {
+    id: string;
+    anchorFrom: string;
+    anchorTo: string;
+    resolved: boolean;
+    deleted: boolean;
+    isSuggestion?: boolean;
+    suggestionType?: SuggestionType;
+    originalContent?: string;
+    suggestedContent?: string;
 }
 export interface CommentAccountProps {
     isConnected?: boolean;
@@ -107,9 +126,12 @@ export interface DdocProps extends CommentAccountProps {
     commentDrawerOpen?: boolean;
     setCommentDrawerOpen?: React.Dispatch<SetStateAction<boolean>>;
     initialComments?: IComment[];
+    initialCommentAnchors?: SerializedCommentAnchor[];
     setInitialComments?: React.Dispatch<SetStateAction<IComment[]>>;
     onCommentReply?: (activeCommentId: string, reply: IComment) => void;
     onNewComment?: (newComment: IComment, meta?: CommentMutationMeta) => void;
+    onEditComment?: (activeCommentId: string, meta?: CommentMutationMeta) => void;
+    onEditReply?: (activeCommentId: string, replyId: string, meta?: CommentMutationMeta) => void;
     onResolveComment?: (activeCommentId: string, meta?: CommentMutationMeta) => void;
     onUnresolveComment?: (activeCommentId: string, meta?: CommentMutationMeta) => void;
     onDeleteComment?: (activeCommentId: string, meta?: CommentMutationMeta) => void;
@@ -130,6 +152,7 @@ export interface DdocProps extends CommentAccountProps {
     editorCanvasClassNames?: string;
     isCommentSectionOpen?: boolean;
     isPreviewMode: boolean;
+    viewerMode?: 'suggest' | 'view-only';
     ensResolutionUrl?: string;
     ipfsImageUploadFn?: (file: File) => Promise<IpfsImageUploadResponse>;
     enableIndexeddbSync?: boolean;

package/dist/package/use-ddoc-editor.d.ts

@@ -1,7 +1,9 @@
 import { DdocProps } from './types';
 import { Editor } from '@tiptap/react';
 
-export declare const useDdocEditor: ({ isPreviewMode, initialContent, versionHistoryState, collaboration, onChange, onCollaboratorChange, onCommentInteraction, onError, setCharacterCount, setWordCount, setPageCount, ipfsImageUploadFn, ddocId, enableIndexeddbSync, unFocused, theme, zoomLevel, onInvalidContentError, ignoreCorruptedData, isPresentationMode, metadataProxyUrl, extensions: externalExtensions, onCopyHeadingLink, ipfsImageFetchFn, fetchV1ImageFn, isConnected, activeModel, maxTokens, isAIAgentEnabled, onIndexedDbError, disableInlineComment, ...rest }: Partial<DdocProps>) => {
+export declare const useDdocEditor: ({ isPreviewMode, viewerMode, initialContent, versionHistoryState, collaboration, onChange, onCollaboratorChange, onCommentInteraction, onError, setCharacterCount, setWordCount, setPageCount, ipfsImageUploadFn, ddocId, enableIndexeddbSync, unFocused, isFocusMode, theme, zoomLevel, onInvalidContentError, ignoreCorruptedData, isPresentationMode, metadataProxyUrl, extensions: externalExtensions, onCopyHeadingLink, ipfsImageFetchFn, fetchV1ImageFn, isConnected, activeModel, maxTokens, isAIAgentEnabled, onIndexedDbError, disableInlineComment, initialCommentAnchors, ...rest }: Partial<DdocProps> & {
+    isFocusMode?: boolean;
+}) => {
     ydoc: import('yjs').Doc;
     awareness: import('y-protocols/awareness.js').Awareness | null;
     refreshYjsIndexedDbProvider: () => Promise<void>;
@@ -38,4 +40,7 @@ export declare const useDdocEditor: ({ isPreviewMode, initialContent, versionHis
     activeCommentId: string | null;
     setActiveCommentId: import('react').Dispatch<import('react').SetStateAction<string | null>>;
     focusCommentWithActiveId: (id: string) => void;
+    commentAnchorsRef: import('react').MutableRefObject<import('./extensions/comment/comment-decoration-plugin').CommentAnchor[]>;
+    draftAnchorsRef: import('react').MutableRefObject<import('./extensions/comment/comment-decoration-plugin').CommentAnchor[]>;
+    storeApiRef: import('react').MutableRefObject<import('zustand').StoreApi<import('./stores/comment-store').CommentStoreState> | null>;
 };

package/dist/package/utils/comment-anchor-serialization.d.ts

@@ -0,0 +1,5 @@
+import { CommentAnchor } from '../extensions/comment/comment-decoration-plugin';
+import { SerializedCommentAnchor } from '../types';
+
+export declare const getSerializedCommentAnchorsKey: (anchors?: SerializedCommentAnchor[]) => string | null;
+export declare const deserializeCommentAnchors: (anchors?: SerializedCommentAnchor[]) => CommentAnchor[];

package/dist/package/utils/comment-scroll-into-view.d.ts

@@ -0,0 +1,21 @@
+import { MutableRefObject } from 'react';
+import { Editor } from '@tiptap/react';
+import { CommentAnchor } from '../extensions/comment/comment-decoration-plugin';
+
+export declare const MOBILE_COMMENT_DRAWER_CANVAS_OFFSET_VAR = "--mobile-comment-drawer-canvas-offset";
+type CommentSelectionRange = {
+    from: number;
+    to: number;
+};
+export declare const clearMobileCommentDrawerCanvasOffset: (editorRoot?: HTMLElement | null) => void;
+export declare const resolveCommentSelectionRange: ({ editor, commentId, commentAnchorsRef, }: {
+    editor: Editor;
+    commentId: string;
+    commentAnchorsRef?: MutableRefObject<CommentAnchor[]>;
+}) => CommentSelectionRange | null;
+export declare const scrollCommentSelectionRangeIntoView: ({ editor, selectionRange, behavior, }: {
+    editor: Editor;
+    selectionRange: CommentSelectionRange;
+    behavior?: ScrollBehavior;
+}) => void;
+export {};