/**
 * Threaded comments — modern Excel cell discussions with an opening note and replies.
 *
 * Prefer the cell API: {@link Cell.addThreadedComment}, {@link Cell.threadedComment},
 * and sheet helpers to list or remove threads. Author and creation time on a thread
 * or reply are set when created and cannot be reassigned afterward.
 *
 * Citations:
 * - [MS-XLSX] CT_ThreadedComment §2.6.205; ThreadedComments root §2.4.86
 * - Persons store (workbook) via host.persons()
 * - docs/specs/threaded-comments.md; docs/api/THREADED-COMMENTS-PROPOSAL.md
 * - API-RULES R1.1 / R2.1 / R2.4 / R2.5 / R5.1 / R7.1
 *
 * Part CT: application/vnd.ms-excel.threadedcomments+xml
 * Rel: …/2017/10/relationships/threadedComment
 * Placeholder author: tc={uid} per top-level thread id.
 */
import { OpcPackage } from '../core/package/opc-package';
import { OpcRelationship } from '../core/package/relationships';
import { PersonsStore } from '../workbook/persons';
/**
 * Represents a single reply within a cell's discussion thread.
 */
export interface ThreadedCommentReply {
    /** The reply's message text. */
    text: string;
    /** The name of the person who wrote the reply. */
    readonly author: string;
    /** When the reply was written. */
    readonly createdAt: Date;
}
/**
 * Represents a discussion thread attached to a worksheet cell, letting you
 * post the original note, mark it resolved, and add replies.
 */
export interface ThreadedComment {
    /** The comment's message text. */
    text: string;
    /** The name of the person who started the thread. */
    readonly author: string;
    /** When the thread was started. */
    readonly createdAt: Date;
    /**
     * Whether the discussion is marked as resolved. Default `false`.
     */
    isResolved: boolean;
    /** The replies to this thread, in the order they were written. */
    readonly replies: ReadonlyArray<ThreadedCommentReply>;
    /** The row the comment is attached to — 1-based, like Excel rows. */
    readonly row: number;
    /** The column the comment is attached to — 1-based, like Excel columns. */
    readonly column: number;
    /**
     * Add a reply to this discussion.
     *
     * @param text - The reply's message text.
     * @param author - The name of the person replying. Default `""`.
     * @param createdAt - When the reply was written. Default: the time of
     *   the call.
     * @returns the newly created reply.
     */
    addReply(text: string, author?: string, createdAt?: Date): ThreadedCommentReply;
}
/**
 * One wire entry (top-level or reply).
 * @private
 */
export interface ThreadedCommentEntry {
    /** ST_Guid — required `id`. */
    id: string;
    /** ST_Guid — required `personId`. */
    personId: string;
    /** ST_Guid of parent when this is a reply. */
    parentId: string | undefined;
    /** Cell A1 for top-level; optional on replies. */
    ref: string | undefined;
    text: string;
    /** UTC ISO-ish string or undefined. */
    dT: string | undefined;
    /** Top-level resolved flag (`done`). */
    done: boolean;
    /** Opaque residual child XML (mentions/extLst). */
    residualChildrenXml: string;
}
/**
 * Host surface for mutations and package I/O.
 * @private
 */
export interface ThreadedCommentsHost {
    readonly package: OpcPackage;
    readonly sheetPartName: string | undefined;
    markDirty(): void;
    persons(): PersonsStore;
}
/**
 * Result of materializing TC + comments parts on flush.
 * @private
 */
export interface ThreadedCommentsMaterializeResult {
    readonly sheetRelsWithoutTcAndComments: ReadonlyArray<OpcRelationship>;
    readonly tcRel: OpcRelationship | undefined;
    readonly commentsRel: OpcRelationship | undefined;
}
/**
 * Mutable threaded-comments store for one worksheet.
 * @private
 */
export declare class ThreadedCommentsImpl {
    private readonly entries;
    private readonly topLevelHandles;
    private readonly replyHandles;
    private host;
    private tcPartName;
    private commentsPartName;
    private dirty;
    private loaded;
    /** @private */
    bindHost(host: ThreadedCommentsHost): void;
    /**
     * Load threaded comments from the worksheet package relationships.
     */
    loadFromPackage(pkg: OpcPackage, sheetPartName: string | undefined): void;
    /** Snapshot of top-level handles in document order. */
    list(): ReadonlyArray<ThreadedComment>;
    /** Top-level thread for a 1-based cell, or undefined. */
    getForCell(row: number, col: number): ThreadedComment | undefined;
    /**
     * Add a top-level thread at the given 1-based cell.
     *
     * @throws InvalidThreadedCommentError when the cell already has a thread
     * @throws InvalidArgumentError when text is not a string
     */
    addAtCell(row: number, col: number, text: string, author?: string, createdAt?: Date): ThreadedComment;
    /**
     * Append a reply under a top-level entry.
     * @private
     */
    addReplyTo(parent: ThreadedCommentEntry, text: string, author?: string, createdAt?: Date): ThreadedCommentReply;
    /**
     * Remove a top-level thread by handle or 0-based index (and its replies).
     */
    remove(target: ThreadedComment | number): void;
    /** Remove every threaded comment on this sheet. */
    clear(): void;
    /**
     * 0-based cell anchors for VML `ObjectType="Note"` shapes matching top-level
     * threads. Used by worksheet flush **before** form-controls VML materialize
     * so Excel shows the comment indicator for threaded comments.
     *
     * - Returns anchors when top-level threads exist (owned rewrite).
     * - Returns `[]` when dirty and empty (clear owned notes).
     * - Returns `undefined` when clean and empty (leave foreign notes alone).
     *
     * @private
     */
    listCommentNoteAnchorsForFlush(): ReadonlyArray<{
        readonly row0: number;
        readonly col0: number;
    }> | undefined;
    /**
     * Write/remove TC + comments parts and compute sheet relationships.
     * Call during worksheet flush after form-controls materialization.
     *
     * @param sheetRelsCurrent Relationships already retained (drawing/VML/etc.);
     *   TC and comments types are stripped here and re-added when needed.
     * @private
     */
    materializeOnFlush(sheetRelsCurrent: ReadonlyArray<OpcRelationship>): ThreadedCommentsMaterializeResult;
    private topLevelEntries;
    private repliesFor;
    private handleForTop;
    private handleForReply;
    private findTopEntryForHandle;
    private markDirty;
    private requireHost;
    /** @private — used by handles */
    displayNameFor(personId: string): string;
    /** @private — used by handles */
    notifyMutation(): void;
    /** @private — used by handles */
    listReplyHandles(parentId: string): ReadonlyArray<ThreadedCommentReply>;
    private parseThreadedCommentsXml;
}