@sheetxl/sdk 0.8.0-beta.1 → 0.8.0-beta.3

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

@@ -1,22 +1,117 @@
+import { IAnchored } from '../anchored';
+import { ICellRange } from '../cellRange';
+import { IListener } from '../listener';
+import { ITransaction } from '../transaction';
+import { IPerson } from '../person';
+import { ISheet } from '../sheet';
 /**
- * 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.
  */
-export interface IComment {
+export interface IComment extends IAnchored {
+    /**
+     * The comment's identifier, unique within the workbook.
+     */
+    getId(): string;
+    /**
+     * 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.
+     */
+    setContent(content: IComment.Content, options?: ITransaction.OperationOptions): this;
+    /**
+     * The content with its formatting runs, or `null` when it is plain text.
+     */
+    getRichContent(): IComment.RichContent | 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 +119,261 @@ 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.
+         */
+        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.
+     * One formatted span of a note's content.
+     *
+     * @remarks
+     * A note keeps Excel's rich text; a threaded comment is plain text and never carries these.
+     * Every property but `text` is optional and inherits the note's default when absent.
      */
-    interface RichJSON extends IComment.Properties {
+    interface Run {
         /**
-         * Required for referencing in replies.
+         * The text of the span.
          */
-        id: string;
+        text: string;
         /**
-         * The id for author or the comment the comment.
+         * The font name.
          */
-        personId: string;
+        font?: string;
+        /**
+         * The font size in points.
+         */
+        size?: number;
+        bold?: boolean;
+        italic?: boolean;
         /**
-         * If this is a reply, the id of the parent comment.
+         * The color as a hex string.
          */
-        parentId?: string;
+        color?: string;
+    }
+    /**
+     * Content with formatting: a list of {@link Run | runs}.
+     */
+    interface RichContent {
+        runs: Run[];
+    }
+    /**
+     * What a comment says: plain text, or formatting runs for a note.
+     */
+    type Content = string | RichContent;
+    /**
+     * The values that can be set on a comment.
+     */
+    interface Properties {
         /**
-         * An unordered list of mention ids.
-         * @remarks
-         * These are not order dependent.
+         * {@inheritDoc IComment.getContent}
          */
-        mentionsIds?: string[];
+        content?: Content;
         /**
-         * The date the comment was created.
+         * 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
          */
-        dt?: Date | string;
+        asNote?: boolean;
         /**
-         * The comment has been marked as done.
+         * {@inheritDoc IComment.isResolved}
          */
-        done?: boolean;
+        resolved?: boolean;
+        /**
+         * The author: a person, or a display name. Defaults to the workbook's
+         * {@link IPersonCollection.getCurrent | current} person.
+         */
+        person?: IPerson | string;
     }
-    type JSON = Partial<IComment.RichJSON> | 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 {
+        /**
+         * {@inheritDoc IComment.Properties.person}
+         */
+        person?: IPerson | 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 {
+    }
+    /**
+     * The note's box: the shape Excel draws the note in, held as it was read.
+     *
+     * @remarks
+     * Only ever present on a comment read from a file. A comment authored here has none, and is
+     * written with Excel's default box (hidden until hovered, hung to the right of its cell); a
+     * comment that has one is written with that box, its cell rewritten from the comment's so it
+     * stays with the note, its size, fill and offsets replayed as they were.
+     *
+     * Opaque markup, as a half-house — the VML `<v:shape>`, not a {@link IShape.JSON}, whose own
+     * `xml` is DrawingML. What it holds is a movable's worth: the cells and offsets of its corners
+     * (an {@link IMovable.AnchorOffset}), whether it is hidden, and a shape's fill and size. That
+     * is where it graduates to — an anchor, a `hidden` flag and an {@link IShape.JSON} — once the
+     * VML can be read into them; the offsets are the authoring machine's pixels, which is what
+     * keeps them opaque today.
+     */
+    interface BoxJSON {
+        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[];
+        /**
+         * {@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/_CommentUtils.d.ts

@@ -0,0 +1,28 @@
+import { IPerson } from '../person';
+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 carries formatting, otherwise
+ * the runs, copied.
+ * @internal
+ */
+export declare function normalizeContent(content: IComment.Content | null | undefined): IComment.Content;
+/**
+ * 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/index.d.ts

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