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

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

@@ -0,0 +1,223 @@
+import { IRange } from '@sheetxl/primitives';
+import { IListener } from '../listener';
+import { ITransaction } from '../transaction';
+import { ICellRange, ICellRanges } from '../cellRange';
+import { ISheet } from '../sheet';
+import { IPerson, IPersonCollection } from '../person';
+import { IMovable } from '../movable';
+import { IRichText } from '../text';
+import { Anchored } from '../anchored/Anchored';
+import { AbstractAnchored } from '../anchored/AbstractAnchored';
+import { IComment } from './IComment';
+import { NoteMovable } from './NoteMovable';
+/**
+ * Implementation of {@link IComment}.
+ *
+ * @remarks
+ * Extends {@link AbstractAnchored} directly: a comment is pinned to one cell and never reads it,
+ * so it subscribes to nothing. The replies are part of this model's state — a reply has no cell
+ * and no transaction of its own — and {@link CommentReply} objects are handles over them, one
+ * per reply id, minted on demand and kept so identity is stable.
+ *
+ * A note's box is a movable the sheet places when the comment becomes a note, with the comment
+ * as its content. Where the box is and whether it is shown are the movable's; the comment saves
+ * them with itself, the anchor restated from its cell, so a note copied to another cell keeps
+ * its box beside it.
+ */
+export declare class Comment extends AbstractAnchored<State, IComment.Events> implements IComment {
+    private _replies;
+    /**
+     * Every box placed for this comment. At most one is live: a reply deletes the box, an undo
+     * brings the same one back, and a note made again from a thread is given a new one.
+     */
+    private _boxes;
+    /** @internal */
+    protected _initialize(options: Comment.ConstructorOptions): void;
+    /** @internal */
+    protected _getActionDescription(action: 'delete' | 'initialize' | 'updateListener'): string | null;
+    /**
+     * Whether the anchor is absolute. See {@link AbstractAnchored._isAnchorAbsolute}.
+     *
+     * @remarks
+     * Always — a comment names the cell it is on, and Excel shows that as an absolute reference.
+     */
+    protected _isAnchorAbsolute(): boolean;
+    /** @internal */
+    protected _processContainerShift(options: Anchored.ShiftOptions): IRange.Coords | null | void;
+    /** @internal */
+    protected _processDelete(): void;
+    /**
+     * {@inheritDoc IComment.getId}
+     *
+     * @remarks
+     * The comment's own id, not the transaction store's: the store keys state by its own id and
+     * never asks the model for it, so this is free to answer the way Office Scripts does.
+     */
+    getId(): string;
+    /** {@inheritDoc IComment.getSheet} */
+    getSheet(): ISheet;
+    /** {@inheritDoc IComment.getRange} */
+    getRange(options?: ICellRange.GetRangeOptions): ICellRange;
+    /** {@inheritDoc IComment.getContent} */
+    getContent(): string;
+    /** {@inheritDoc IComment.setContent} */
+    setContent(content: IComment.Content, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IComment.getRichContent} */
+    getRichContent(): IRichText.JSON | null;
+    /** {@inheritDoc IComment.getAuthor} */
+    getAuthor(): IPerson | null;
+    /** {@inheritDoc IComment.getCreationDate} */
+    getCreationDate(): Date | null;
+    /** {@inheritDoc IComment.isResolved} */
+    isResolved(): boolean;
+    /** {@inheritDoc IComment.setResolved} */
+    setResolved(resolved: boolean, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IComment.isNote} */
+    isNote(): boolean;
+    /** {@inheritDoc IComment.getReplies} */
+    getReplies(): IComment.IReply[];
+    /** {@inheritDoc IComment.getReply} */
+    getReply(id: string): IComment.IReply | null;
+    /** {@inheritDoc IComment.addReply} */
+    addReply(content: IComment.Content, options?: IComment.AddReplyOptions): IComment.IReply;
+    /** {@inheritDoc IComment.update} */
+    update(update: IComment.Modifiers | IComment, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IComment.getType} */
+    getType(): string;
+    /** {@inheritDoc IMovable.IContent.getTypeDescription} */
+    getTypeDescription(): string;
+    /** {@inheritDoc IMovable.IContent.getReferences} */
+    getReferences(): ICellRanges | null;
+    /** {@inheritDoc IMovable.IContent.getDescription} */
+    getDescription(): string | null;
+    /** {@inheritDoc IMovable.IContent.setDescription} */
+    setDescription(description: string | null): this;
+    /** {@inheritDoc IComment.getMovable} */
+    getMovable(): IMovable | null;
+    /**
+     * The live box, if there is one.
+     * @internal
+     */
+    protected _getBox(): NoteMovable | null;
+    /**
+     * Asks the sheet for a box: at `anchor`, its cells counted from this comment's, or where Excel
+     * puts a new note's. A comment with no sheet to place one on has no box.
+     * @internal
+     */
+    protected _placeBox(anchor: IMovable.AnchorOffset | null, hidden: boolean): void;
+    /**
+     * The note is gone, or is a thread now: its box goes with it.
+     * @internal
+     */
+    protected _removeBox(): void;
+    /** {@inheritDoc IListener.ISource.addListeners} */
+    addListeners(listeners: IComment.IListeners, options?: IListener.Options): IListener.Remove;
+    /** {@inheritDoc IComment.toJSON} */
+    toJSON(): IComment.JSON | null;
+    /** @internal */
+    protected _fromJSON(json?: IComment.JSON | null, options?: ITransaction.OperationOptions): void;
+    /** @internal */
+    protected _getPeople(): IPersonCollection | null;
+    /** @internal */
+    protected _resolvePerson(personId: string | null | undefined): IPerson | null;
+    /** @internal */
+    protected _findReplyJSON(id: string): IComment.ReplyJSON | null;
+    /** @internal */
+    protected _replyFor(id: string): CommentReply;
+    /** @internal */
+    protected _updateReply(id: string, content: IComment.Content, options?: ITransaction.OperationOptions): void;
+    /** @internal */
+    protected _deleteReply(id: string, options?: ITransaction.OperationOptions): void;
+    get [Symbol.toStringTag](): string;
+    toString(): string;
+    /** {@inheritDoc IComment.isIComment} */
+    get isIComment(): true;
+}
+/**
+ * Implementation of {@link IComment.IReply}: a handle over one entry in its parent's state.
+ */
+export declare class CommentReply implements IComment.IReply {
+    private readonly _parent;
+    private readonly _id;
+    constructor(parent: Comment, id: string);
+    /** @internal */
+    protected _json(): IComment.ReplyJSON;
+    /** {@inheritDoc IComment.IReply.getId} */
+    getId(): string;
+    /** {@inheritDoc IComment.IReply.getParent} */
+    getParent(): IComment;
+    /** {@inheritDoc IComment.IReply.getRange} */
+    getRange(options?: ICellRange.GetRangeOptions): ICellRange;
+    /** {@inheritDoc IComment.IReply.getContent} */
+    getContent(): string;
+    /** {@inheritDoc IComment.IReply.setContent} */
+    setContent(content: IComment.Content, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IComment.IReply.getAuthor} */
+    getAuthor(): IPerson | null;
+    /** {@inheritDoc IComment.IReply.getCreationDate} */
+    getCreationDate(): Date | null;
+    /** {@inheritDoc IComment.IReply.isResolved} */
+    isResolved(): boolean;
+    /** {@inheritDoc IComment.IReply.delete} */
+    delete(options?: ITransaction.OperationOptions): void;
+    /** {@inheritDoc IComment.IReply.isDeleted} */
+    isDeleted(): boolean;
+    /** {@inheritDoc IComment.IReply.toJSON} */
+    toJSON(): IComment.ReplyJSON;
+    get [Symbol.toStringTag](): string;
+    /** {@inheritDoc IComment.IReply.isICommentReply} */
+    get isICommentReply(): true;
+}
+/**
+ * Interfaces for creating a {@link Comment}.
+ */
+export declare namespace Comment {
+    interface ConstructorOptions extends Anchored.ConstructorOptions<IComment.JSON> {
+        /**
+         * The workbook's people, for resolving authors. Lazy: a sheet is built before its workbook
+         * has finished loading.
+         */
+        getPeople?: () => IPersonCollection | null;
+        /**
+         * What places a note's box. A comment given none has no movable.
+         */
+        boxes?: Comment.Boxes;
+    }
+    /**
+     * What a note's box needs of the sheet it is on: to be placed, and to know whether it is where
+     * a new note's goes.
+     */
+    interface Boxes {
+        /**
+         * Places a note's box among the sheet's movables, with the note as its content.
+         *
+         * @param comment The note.
+         * @param anchor Where the box is, its cells counted from the note's; `null` for where Excel
+         * puts a new note's.
+         * @param hidden Whether the box appears only while its cell is pointed at.
+         */
+        add(comment: Comment, anchor: IMovable.AnchorOffset | null, hidden: boolean): NoteMovable;
+        /**
+         * Whether a box is where a new note's goes, which a note saves nothing for.
+         */
+        isDefault(comment: Comment, box: IMovable): boolean;
+    }
+}
+/** @internal */
+interface State extends AbstractAnchored.State {
+    /** Named apart from the transaction record's own `id`, which the store writes over. */
+    commentId: string;
+    personId: string | null;
+    content: IComment.Content;
+    dt: string | null;
+    done: boolean;
+    asNote: boolean;
+    mentions: IComment.MentionJSON[] | null;
+    replies: readonly IComment.ReplyJSON[];
+    /** The alternative text of a note's box. */
+    description: string | null;
+    /** How a note's box is drawn when not the default: markup a file's writer replays. */
+    boxXml: string | null;
+}
+export {};
+//# sourceMappingURL=Comment.d.ts.map

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

@@ -0,0 +1,40 @@
+import { ICellRange } from '../cellRange';
+import { ICollection, AbstractCollection } from '../type';
+import { IListener } from '../listener';
+import { ICommentCollection } from './ICommentCollection';
+import { IComment } from './IComment';
+/**
+ * Implementation for {@link ICommentCollection}.
+ *
+ * @remarks
+ * A front over storage held elsewhere — the sheet's own comments, or a walk over every sheet's
+ * for the workbook — so the same class serves both. The sheet keeps the store and the events,
+ * this class keeps the API; `onCollectionChange` is the sheet's `onCommentsChange`, forwarded
+ * with this collection as the source.
+ */
+export declare class CommentCollection extends AbstractCollection<IComment, ICommentCollection.GetItemsOptions> implements ICommentCollection {
+    private _add;
+    private _get;
+    private _addListeners;
+    /**
+     * @param add Adds to the store; `null` for a view that cannot add (the workbook's).
+     * @param get Returns the items intersecting the address, or all of them for none.
+     * @param addListeners Forwards the owner's change event.
+     */
+    constructor(add: ((address: ICellRange.Address, content: IComment.Content, options?: ICommentCollection.AddOptions) => IComment) | null, get: (address: ICellRange.Address | null | undefined, ignoreHidden?: boolean, fullyContained?: boolean) => IComment[], addListeners: (listeners: ICollection.IListeners, options?: IListener.Options) => IListener.Remove);
+    /** {@inheritDoc ICommentCollection.add} */
+    add(address: ICellRange.Address, content: IComment.Content, options?: ICommentCollection.AddOptions): IComment;
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(options?: ICommentCollection.GetItemsOptions): IComment[];
+    /** {@inheritDoc ICommentCollection.getById} */
+    getById(id: string): IComment | null;
+    /** {@inheritDoc ICommentCollection.getAt} */
+    getAt(address: ICellRange.Address): IComment | null;
+    /** {@inheritDoc ICommentCollection.getByReplyId} */
+    getByReplyId(replyId: string): IComment | null;
+    /** {@inheritDoc ICollection.addListeners} */
+    addListeners(listeners: ICollection.IListeners, options?: IListener.Options): IListener.Remove;
+    /** {@inheritDoc ICommentCollection.isICommentCollection} */
+    get isICommentCollection(): true;
+}
+//# sourceMappingURL=CommentCollection.d.ts.map