@sheetxl/sdk 0.7.28-beta.4 → 0.8.0-beta.10

package/types/src/comment/IComment.d.ts

@@ -1,22 +1,157 @@
+import { IAnchored } from '../anchored';
+import { ICellRange } from '../cellRange';
+import { IListener } from '../listener';
+import { ITransaction } from '../transaction';
+import { IPerson } from '../person';
+import { ISheet } from '../sheet';
+import { IMovable } from '../movable';
+import { IRichText } from '../text';
 /**
- * TODO - Implement IComment.
- * TODO - how to make this threaded?
- * TODO - rationalize this with notes?
- * -Each Comment will have a unique id and a parent that it is a reply to.
+ * A comment on a cell: the root of a thread, with its replies, or a note.
  *
- * ? How to add root range.addComment(content) ? (only allows for 1 root)
-
- * https://learn.microsoft.com/en-us/javascript/api/office-scripts/excelscript/excelscript.contenttype?view=office-scripts
+ * @remarks
+ * Follows Office Scripts' `Comment`: one per cell, the thread's root, resolved as a whole,
+ * with replies ({@link IComment.IReply}) that borrow its cell. A note — Excel's older yellow
+ * box — is a comment that {@link isNote | says so}: it has no replies, no resolved state and no
+ * creation date, and its content may carry formatting runs where a thread's is plain text.
  *
- * Excel has a resolved/done status
- * Excel has mentions?
+ * Anchored to its cell, so it follows a row or column insert or delete and is deleted when its
+ * cell is.
+ *
+ * A note is also the content of a {@link getMovable | movable}: the box it is shown in.
  */
-export interface IComment {
+export interface IComment extends IAnchored, IMovable.IContent {
+    /**
+     * The comment's identifier, unique within the workbook.
+     */
+    getId(): string;
+    /**
+     * `'note'` for a note, `'comment'` for a threaded comment.
+     */
+    getType(): string;
+    /**
+     * The box a note is shown in, or `null` for a threaded comment, which has none.
+     *
+     * @remarks
+     * The box is an ordinary movable: it is selected, moved and resized like a picture's, and is
+     * among the sheet's `getMovables()`. Its content is this comment.
+     *
+     * * **Placement.** A box that has not been moved sits where Excel puts a new note, beside its
+     *   cell, and stores nothing. Moving or resizing it stores where it is, relative to its cell,
+     *   so a note copied to another cell keeps its box beside it.
+     * * **Shown or on hover.** `isHidden()` is `true` for a box that appears only while its cell is
+     *   pointed at, which is how a note starts and which a view decides. `setHidden(false)` keeps
+     *   it on the sheet.
+     *
+     * A reply converts a note to a threaded comment, and its box goes with it.
+     *
+     * @example
+     * ```ts
+     * const note = sheet.getComments().add('B2', 'Check this', { asNote: true });
+     * const box = note.getMovable();
+     * box.setHidden(false); // always shown
+     * box.setBounds({ width: 240 });
+     * ```
+     */
+    getMovable(): IMovable | null;
+    /**
+     * Deletes the comment: its replies with it, or a note's box.
+     */
+    delete(options?: ITransaction.OperationOptions): void;
+    /**
+     * The sheet the comment is on.
+     */
+    getSheet(): ISheet;
+    /**
+     * The cell the comment is on.
+     *
+     * @remarks
+     * Invalid, never null, once the cell has been deleted — see {@link IAnchored.getRanges}.
+     */
+    getRange(options?: ICellRange.GetRangeOptions): ICellRange;
+    /**
+     * The content as plain text.
+     *
+     * @remarks
+     * A note's formatting runs are joined; see {@link getRichContent} for them.
+     */
     getContent(): string;
-    setContent(content: string): void;
-    getUserId(): string;
-    delete(): void;
-    getCreationDate(): Date;
+    /**
+     * Replaces the content.
+     *
+     * @param content Plain text, or formatting runs for a note.
+     *
+     * @remarks
+     * Drops the comment's mentions: each names a span of the text it was made in.
+     */
+    setContent(content: IComment.Content, options?: ITransaction.OperationOptions): this;
+    /**
+     * The content with its formatting runs, or `null` when it is plain text.
+     */
+    getRichContent(): IRichText.JSON | null;
+    /**
+     * The person who wrote the comment, or `null` if the workbook does not know them.
+     */
+    getAuthor(): IPerson | null;
+    /**
+     * When the comment was written, or `null` for a note, which Excel does not date.
+     */
+    getCreationDate(): Date | null;
+    /**
+     * Whether the thread is resolved.
+     *
+     * @remarks
+     * Always `false` for a note.
+     */
+    isResolved(): boolean;
+    /**
+     * Marks the thread resolved, or reopens it.
+     */
+    setResolved(resolved: boolean, options?: ITransaction.OperationOptions): this;
+    /**
+     * Whether this is a note rather than a threaded comment.
+     *
+     * @see {@link IComment.Properties.asNote}
+     */
+    isNote(): boolean;
+    /**
+     * The replies, oldest first.
+     */
+    getReplies(): IComment.IReply[];
+    /**
+     * Returns the reply with the given id, or `null` if there is none.
+     */
+    getReply(id: string): IComment.IReply | null;
+    /**
+     * Adds a reply.
+     *
+     * @param content The reply's text.
+     * @param options The person replying, when not the {@link IPersonCollection.getCurrent | current}
+     * one.
+     *
+     * @remarks
+     * A note has no replies; adding one converts it to a threaded comment, as Excel does.
+     */
+    addReply(content: IComment.Content, options?: IComment.AddReplyOptions): IComment.IReply;
+    /**
+     * Set multiple properties at once.
+     */
+    update(properties: IComment.Modifiers | IComment, options?: ITransaction.OperationOptions): this;
+    /**
+     * Add Listeners.
+     *
+     * @see
+     * {@link IListener.ISource.addListeners}
+     */
+    addListeners(listeners: IComment.IListeners, options?: IListener.Options): IListener.Remove;
+    /**
+     * @returns The current state as a JSON object, or `null` if there is no state.
+     */
+    toJSON(): IComment.JSON | null;
+    /**
+     * For runtime type checking.
+     */
+    readonly isIComment: true;
 }
 /**
  * {@inheritDoc IComment}
@@ -24,85 +159,240 @@ export interface IComment {
  * ### **Interface**
  *
  * {@link IComment}
+ *
+ * **Additional Interfaces**
+ * * {@link ICommentCollection}
+ * * {@link IComment.IReply}
  */
 export declare namespace IComment {
-    interface Properties {
+    /**
+     * A reply within a thread.
+     *
+     * @remarks
+     * Follows Office Scripts' `CommentReply`: it has an author, content and a date of its own, and
+     * borrows everything else — the cell, the resolved state — from its {@link getParent | parent}.
+     */
+    interface IReply {
         /**
-         * The content of the comment.
+         * The reply's identifier, unique within the workbook.
          */
-        content?: any;
-        asNote?: boolean;
+        getId(): string;
+        /**
+         * The comment this replies to.
+         */
+        getParent(): IComment;
+        /**
+         * The cell the thread is on — the parent's.
+         */
+        getRange(options?: ICellRange.GetRangeOptions): ICellRange;
+        /**
+         * The content as plain text.
+         */
+        getContent(): string;
+        /**
+         * Replaces the content, dropping the reply's mentions.
+         */
+        setContent(content: IComment.Content, options?: ITransaction.OperationOptions): this;
+        /**
+         * The person who wrote the reply, or `null` if the workbook does not know them.
+         */
+        getAuthor(): IPerson | null;
+        /**
+         * When the reply was written.
+         */
+        getCreationDate(): Date | null;
+        /**
+         * Whether the thread is resolved — the parent's answer.
+         */
+        isResolved(): boolean;
+        /**
+         * Removes the reply from the thread.
+         */
+        delete(options?: ITransaction.OperationOptions): void;
+        /**
+         * Returns `true` once the reply has been removed.
+         */
+        isDeleted(): boolean;
+        /**
+         * @returns The current state as a JSON object.
+         */
+        toJSON(): IComment.ReplyJSON;
+        /**
+         * For runtime type checking.
+         */
+        readonly isICommentReply: true;
     }
     /**
-     * For persisting.
+     * What a comment says: plain text, or formatting runs for a note.
+     *
+     * @remarks
+     * A note keeps Excel's rich text; a threaded comment is plain text and never carries runs.
      */
-    interface RichJSON extends IComment.Properties {
-        /**
-         * Required for referencing in replies.
-         */
-        id: string;
+    type Content = string | IRichText.JSON;
+    /**
+     * The values that can be set on a comment.
+     */
+    interface Properties {
         /**
-         * The id for author or the comment the comment.
+         * {@inheritDoc IComment.getContent}
          */
-        personId: string;
+        content?: Content;
         /**
-         * If this is a reply, the id of the parent comment.
+         * Whether the comment is a note: displayed in Excel's simple box rather than as a thread,
+         * with no author date, replies or resolved state.
+         *
+         * @defaultValue false
          */
-        parentId?: string;
+        asNote?: boolean;
         /**
-         * An unordered list of mention ids.
-         * @remarks
-         * These are not order dependent.
+         * {@inheritDoc IComment.isResolved}
          */
-        mentionsIds?: string[];
+        resolved?: boolean;
         /**
-         * The date the comment was created.
+         * The author: a person, or a display name. Defaults to the workbook's
+         * {@link IPersonCollection.getCurrent | current} person.
          */
-        dt?: Date | string;
+        person?: IPerson | string;
+    }
+    /**
+     * Modifiers describe a partial list of properties that can be set.
+     */
+    type Modifiers = Partial<IComment.Properties>;
+    /**
+     * Used when updating a comment through a cell or range: modifiers, a plain string as the
+     * content, or `null` to remove.
+     *
+     * @see
+     * `ICellRange.setComments`
+     */
+    type Update = IComment.Modifiers | string | null;
+    /**
+     * Options for {@link IComment.addReply}.
+     */
+    interface AddReplyOptions extends ITransaction.OperationOptions {
         /**
-         * The comment has been marked as done.
+         * {@inheritDoc IComment.Properties.person}
          */
-        done?: boolean;
+        person?: IPerson | string;
     }
-    type JSON = Partial<IComment.RichJSON> | string;
+    /**
+     * A mention of a person within a comment's text.
+     */
     interface MentionJSON {
         /**
          * The id for the mention.
          */
         id: string;
         /**
-         * The id for author or the comment the comment.
+         * The id of the person mentioned.
          */
         personId: string;
         /**
-         * The start of the mention.
+         * Where the mention starts in the text.
          */
         startIndex?: number;
         /**
-         * The length of the mention.
+         * How many characters the mention spans.
          */
         length?: number;
     }
     /**
-     * Represents a reference to person. Either in a comment, protection clause or mention.
+     * The persisted shape shared by a comment and a reply.
      */
-    interface PersonJSON {
+    interface EntryJSON {
         /**
-         * A human readable string for the name.
+         * {@inheritDoc IComment.getId}
          */
-        displayName?: string;
+        id: string;
         /**
-         * A unique identifier.
+         * The id of the author, in the workbook's people.
          */
-        id: string;
+        personId?: string;
         /**
-         * The id for authorizing against the providerId.
+         * {@inheritDoc IComment.getContent}
          */
-        userId?: string;
+        content?: Content;
         /**
-         * The system that provided the person.
+         * When it was written, as an ISO string.
          */
-        providerId?: string;
+        dt?: string;
+        /**
+         * People mentioned in the text.
+         */
+        mentions?: MentionJSON[];
+    }
+    /**
+     * A reply, for persisting.
+     */
+    interface ReplyJSON extends EntryJSON {
+    }
+    /**
+     * A note's box, where it differs from the default.
+     */
+    interface BoxJSON {
+        /**
+         * Where the box is: the cells and pixel offsets of its top-left and bottom-right corners,
+         * the cells counted from the note's own (`r: -1` is the row above it).
+         *
+         * @remarks
+         * Absent for a box that has not been moved or resized, which is placed beside its cell.
+         */
+        anchor?: IMovable.AnchorOffset;
+        /**
+         * How the box is drawn when that is not Excel's default, held as it was read: the VML
+         * `<v:shape>` without its id, its position or its cell.
+         */
+        xml?: string;
+    }
+    /**
+     * A comment, for persisting.
+     */
+    interface JSON extends EntryJSON {
+        /**
+         * {@inheritDoc IComment.isResolved}
+         */
+        done?: boolean;
+        /**
+         * {@inheritDoc IComment.isNote}
+         */
+        asNote?: boolean;
+        /**
+         * The replies, oldest first.
+         */
+        replies?: ReplyJSON[];
+        /**
+         * Whether a note's box stays on the sheet rather than appearing on hover.
+         *
+         * @defaultValue false
+         */
+        shown?: boolean;
+        /**
+         * The alternative text of a note's box.
+         */
+        description?: string;
+        /**
+         * {@inheritDoc IComment.BoxJSON}
+         */
+        box?: BoxJSON;
+    }
+    /**
+     * IListener for {@link IComment} events.
+     */
+    interface Events extends IAnchored.Events<IComment> {
+        /**
+         * Called when the content or author changes.
+         */
+        onContentChange?(source: IComment): void;
+        /**
+         * Called when the thread is resolved or reopened.
+         */
+        onResolvedChange?(source: IComment): void;
+        /**
+         * Called when a reply is added, edited or removed.
+         */
+        onRepliesChange?(source: IComment): void;
+    }
+    interface IListeners extends IListener.Callbacks<IComment, IComment.Events> {
     }
 }
 //# sourceMappingURL=IComment.d.ts.map

package/types/src/comment/ICommentCollection.d.ts

@@ -0,0 +1,90 @@
+import { ICollection } from '../type';
+import { ICellRange } from '../cellRange';
+import { IAnchored } from '../anchored';
+import { IComment } from './IComment';
+/**
+ * Holds {@link IComment | comments} — a sheet's, or every sheet's in the workbook.
+ */
+export interface ICommentCollection extends ICollection<IComment> {
+    /**
+     * Returns items that match the filter criteria.
+     *
+     * If no filter criteria is provided, all items will be returned.
+     *
+     * @param options {@link ICommentCollection.GetItemsOptions}
+     */
+    getItems(options?: ICommentCollection.GetItemsOptions): IComment[];
+    /**
+     * Adds a comment to a cell.
+     *
+     * @param address The cell. An address naming more than one cell throws, as Excel's does.
+     * @param content The text, or formatting runs for a note.
+     * @param options {@link ICommentCollection.AddOptions}
+     *
+     * @remarks
+     * A cell holds one comment; adding to a cell that has one throws unless
+     * {@link ICommentCollection.AddOptions.replaceExisting} is set. Available on a sheet's
+     * collection; the workbook's is a view.
+     */
+    add(address: ICellRange.Address, content: IComment.Content, options?: ICommentCollection.AddOptions): IComment;
+    /**
+     * Returns the comment with the given id, or `null` if there is none.
+     */
+    getById(id: string): IComment | null;
+    /**
+     * Returns the comment on the given cell, or `null` if there is none.
+     *
+     * @param address A cell. For a larger address, the first comment within it in reading order.
+     */
+    getAt(address: ICellRange.Address): IComment | null;
+    /**
+     * Returns the comment a reply belongs to, or `null` if no thread has that reply.
+     */
+    getByReplyId(replyId: string): IComment | null;
+    /** For runtime type checking. */
+    readonly isICommentCollection: true;
+}
+/**
+ * {@inheritDoc ICommentCollection}
+ * @see
+ * ### **Interface**
+ *
+ * {@link ICommentCollection}
+ */
+export declare namespace ICommentCollection {
+    /**
+     * Options for adding a comment.
+     *
+     * @remarks
+     * `replaceExisting` replaces the comment on the cell when there is one, rather than throwing.
+     */
+    interface AddOptions extends Omit<IComment.Properties, 'content'>, Pick<IAnchored.AddOptions, 'replaceExisting' | 'description' | 'autoSelect'> {
+    }
+    interface GetItemsOptions extends ICollection.GetItemsOptions {
+        /**
+         * If provided, the filter will be limited to items that intersect the range.
+         */
+        address?: ICellRange.Address;
+        /**
+         * Indicate if items that are in hidden headers or marked as hidden should be returned.
+         *
+         * @defaultValue false
+         */
+        ignoreHidden?: boolean;
+        /**
+         * Only return items that are completely contained with the search bounds.
+         *
+         * @defaultValue false
+         */
+        fullyContained?: boolean;
+        /**
+         * Only threads with this resolved state.
+         */
+        resolved?: boolean;
+        /**
+         * `true` for notes only, `false` for threaded comments only.
+         */
+        notes?: boolean;
+    }
+}
+//# sourceMappingURL=ICommentCollection.d.ts.map

package/types/src/comment/NoteMovable.d.ts

@@ -0,0 +1,26 @@
+import { Bounds, ReferenceableClipboard } from '@sheetxl/utils';
+import { IHistory } from '../history';
+import { IMovable } from '../movable';
+import { Movable } from '../movable/Movable';
+/**
+ * The box a note is shown in: a movable whose content is the note.
+ *
+ * @remarks
+ * Two things set it apart from a picture's movable. It is not copied by itself, because a note
+ * travels with its cell. And when a shift removes every cell under it, it goes back beside its
+ * note instead of taking the note with it.
+ */
+export declare class NoteMovable extends Movable {
+    /**
+     * Beside its note, where a new note's box goes.
+     */
+    protected _processContainerRemoved(): IMovable.AnchorOffset | null;
+    /**
+     * A box is not copied by itself: a note travels with its cell.
+     *
+     * {@inheritDoc IHistory.ISnapshotSource.getSnapshot}
+     */
+    getSnapshot(_bounds?: Bounds | ReferenceableClipboard.CopyOptions, _options?: ReferenceableClipboard.CopyOptions): IHistory.ISnapshot<IMovable.SnapshotDestination, IMovable, Bounds>;
+    get [Symbol.toStringTag](): string;
+}
+//# sourceMappingURL=NoteMovable.d.ts.map

package/types/src/comment/_CommentUtils.d.ts

@@ -0,0 +1,50 @@
+import { IPerson } from '../person';
+import { IMovable } from '../movable';
+import { IComment } from './IComment';
+/**
+ * Resolve an {@link IComment.Update} to modifiers: a string is the content, `null` is a remove
+ * (returned as `null`), modifiers are copied.
+ * @internal
+ */
+export declare function resolveCommentUpdate(update: IComment.Update | undefined): IComment.Modifiers | null;
+/**
+ * The plain text of a content value.
+ * @internal
+ */
+export declare function contentToText(content: IComment.Content | null | undefined): string;
+/**
+ * Content as it is stored: a string when there are no runs or none sets a font property, otherwise
+ * the runs, copied.
+ *
+ * A run's font also takes the `bold`, `italic` and boolean `underline` spellings a font update
+ * takes. A run in the shape notes were first saved in — `bold`, `italic`, `size`, `color` and a
+ * `font` name beside the text — is read into this one.
+ * @internal
+ */
+export declare function normalizeContent(content: IComment.Content | null | undefined): IComment.Content;
+/**
+ * A copy of stored content, runs and fonts included.
+ * @internal
+ */
+export declare function copyContent(content: IComment.Content): IComment.Content;
+/**
+ * Reads the anchor out of a box saved as its whole shape, which is how a note's box was kept
+ * before it was read into an anchor.
+ *
+ * @returns The anchor, its cells counted from the note's, and whether the box was shown; `null`
+ * for markup that names no cell or anchor.
+ * @internal
+ */
+export declare function readLegacyBox(xml: string): {
+    anchor: IMovable.AnchorOffset;
+    shown: boolean;
+} | null;
+/**
+ * Resolves the author option to a person id.
+ * @internal
+ */
+export declare function resolveAuthorId(person: IPerson | string | undefined, people: {
+    add(person: IPerson.Properties | string): IPerson;
+    getCurrent(): IPerson;
+} | null): string | null;
+//# sourceMappingURL=_CommentUtils.d.ts.map

package/types/src/comment/_NoteBox.d.ts

@@ -0,0 +1,50 @@
+import { IRange } from '@sheetxl/primitives';
+import { Bounds } from '@sheetxl/utils';
+import { IMovable } from '../movable';
+import { Movable } from '../movable/Movable';
+/**
+ * Where a note's box goes when nothing has moved it, and how a note stores where its box is.
+ *
+ * @remarks
+ * The default is Excel's, probed with hidden COM on a 96-DPI machine (2026-09-30): a 144×79 px
+ * box hung 15 px right of its cell and 10 px above its top, flipped to the other side when it
+ * would pass the sheet's last column or row. It is pixel geometry first and the cells those
+ * pixels fall on second, so tall, narrow and hidden rows and columns need no rule of their own.
+ *
+ * A note stores its box's anchor with the cells counted from the note's own, so a note copied
+ * to another cell keeps its box beside it. The box itself is an ordinary movable anchored to the
+ * sheet's cells; these functions convert between the two.
+ * @internal
+ */
+/** The width of a default box, in pixels. */
+export declare const NOTE_DEFAULT_WIDTH = 144;
+/** The height of a default box, in pixels. */
+export declare const NOTE_DEFAULT_HEIGHT = 79;
+/**
+ * The cell geometry placing a box needs: the same three a movable is built with.
+ */
+export type NoteLayout = Required<Pick<Movable.ConstructorOptions, 'getBoundsAtCoords' | 'getCoordsAtBounds' | 'getMaxBounds'>>;
+/**
+ * The bounds of a note's box when nothing has moved or resized it.
+ */
+export declare function defaultNoteBounds(cell: IRange.CellCoords, layout: NoteLayout): Bounds;
+/**
+ * The cells and offsets a box's corners fall on, as a movable is loaded from.
+ */
+export declare function boundsToAnchor(bounds: Bounds, layout: NoteLayout): IMovable.AnchorOffset;
+/**
+ * An anchor with its cells restated relative to the note's cell, which is how a note stores it.
+ */
+export declare function toRelativeAnchor(anchor: IMovable.AnchorOffset, cell: IRange.CellCoords): IMovable.AnchorOffset;
+/**
+ * A stored anchor with its cells restated as the sheet's, held to the sheet.
+ *
+ * @remarks
+ * A corner whose cell would be off the sheet is held to the sheet's edge; its offset is kept.
+ */
+export declare function toAbsoluteAnchor(anchor: IMovable.AnchorOffset, cell: IRange.CellCoords, entire: IRange.Coords): IMovable.AnchorOffset;
+/**
+ * Whether two boxes are drawn in the same place, to the pixel Excel rounds to.
+ */
+export declare function isEqualBounds(a: Bounds, b: Bounds): boolean;
+//# sourceMappingURL=_NoteBox.d.ts.map

package/types/src/comment/index.d.ts

@@ -1,2 +1,3 @@
 export * from './IComment';
+export * from './ICommentCollection';
 //# sourceMappingURL=index.d.ts.map