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

package/types/src/collections/Tuple.d.ts

@@ -1,5 +1,5 @@
 import { ChainedError } from '@sheetxl/utils';
-import { IList, IListLike } from './IList';
+import { IListLike } from './IList';
 /**
  * Namespace for tuples.
  */
@@ -37,22 +37,39 @@ export declare namespace Tuple {
      */
     type GridTuple<T = any> = MajorTuple<T>[];
     /**
-     * Adds precomputed bounds for the `MajorTuple`s.
+     * A block of a grid: the values it stores with their precomputed bounds and, from a builder that
+     * tracks it, what every position it does not store reads as.
      *
      * @remarks
      * In some scenarios the maximum bounds of the tuples is required (e.g., during rendering or calculations),
      * providing precomputed bounds can improve performance by avoiding the need to scan the entire collection.
      */
-    interface BoundedTuples<T = any> {
+    interface Region<T = any> {
         /**
-         * The bounded tuples.
+         * The stored values.
          */
         tuples: Tuple.GridTuple<T>;
         /**
-         * The precomputed bounds encompassing all the `MajorTuple`s.
+         * The precomputed bounds encompassing all the `MajorTuple`s; empty (`majorEnd < majorStart`)
+         * when nothing is stored.
          */
         bounds: Tuple.OrientatedCoords;
+        /**
+         * What a position the tuples do not store reads as. `undefined` from a builder that does not
+         * track it (see {@link Builder}).
+         */
+        absentValue?: T | null;
+        /**
+         * Positions to delete before the tuples are written over a grid that already holds values: the
+         * blanks, and the values not stored because they equal {@link absentValue}. A grid that stores
+         * nothing there can ignore them.
+         */
+        clears?: Tuple.Span[];
     }
+    /**
+     * `length` positions of one major line, starting at `minor`.
+     */
+    type Span = [major: number, minor: number, length: number];
     /**
      * RangeCoords expressed in relative coordinates.
      */
@@ -62,6 +79,38 @@ export declare namespace Tuple {
         majorEnd: number;
         minorEnd: number;
     }
+    /**
+     * What a builder learns about a run as it pushes, as a bitmask handed to `createList`: one
+     * bit per kind of value seen (bits 0-7, aligned with `MixedTypedArrayList.Type` so a run with
+     * no `Object` bit can be encoded without a second look), plus:
+     * - `NotUniform`: some value differs from the run's first;
+     * - `NotFinite`: a number was NaN or infinite (a storage policy the builder does not judge).
+     *
+     * An `Object` is anything else: an error, rich data. The builder cannot tell them apart.
+     */
+    const Hint: {
+        readonly Blank: number;
+        readonly False: number;
+        readonly True: number;
+        readonly Int32: number;
+        readonly Float64: number;
+        readonly String: number;
+        readonly Object: number;
+        /** The bits that describe the kinds of value seen. */
+        readonly KindMask: 255;
+        readonly NotUniform: number;
+        readonly NotFinite: number;
+    };
+    /** The {@link Hint} bits of one value. */
+    const hintOf: (value: unknown) => number;
+    /**
+     * A list for the values of one run, from a builder that collected them into an array.
+     * @param values The run's values, in order, in an array the builder REUSES: it may be longer
+     * than the run, and what the list keeps must be copied out of it.
+     * @param length How many of `values` are the run's. Never 0.
+     * @param hint What the builder saw: {@link Hint} bits.
+     */
+    type CreateList<T = any> = (values: T[], length: number, hint: number) => IListLike<T>;
     /**
      * A builder for easily creating tuples that can be either contiguous or non-contiguous.
      * A builder maintains an ordered structure where major and minor values must always
@@ -100,10 +149,27 @@ export declare namespace Tuple {
          *
          * @returns The built bounded tuples.
          */
-        build(): Tuple.BoundedTuples<T>;
+        build(): Tuple.Region<T>;
+        /**
+         * The value pushed at a position, as `pushAt` was given it.
+         *
+         * @returns `undefined` if no value is stored there.
+         */
+        getAt(major: number, minor: number): T | undefined;
     }
     /**
      * Implementation of {@link IBuilder} that that adds in aligned order.
+     *
+     * @remarks
+     * With `trackAbsent` the builder also decides what the positions it does not store read as, the
+     * built region's {@link Region.absentValue}:
+     * - a value equal to the absent value is not stored once that value is known
+     *   ({@link setAbsentValue}); one pushed before is stored, which reads the same;
+     * - a `null` is a blank and is never stored;
+     * - a blank and a non-null absent value cannot share the unstored state, so when both occur the
+     *   absent positions are written out as runs and the region's absent value is `null`.
+     *
+     * Only a {@link RepeatingList} is read as one value; any other list is stored as given.
      */
     class Builder<T = any> implements IBuilder<T> {
         private _tuples;
@@ -111,18 +177,56 @@ export declare namespace Tuple {
         private _values;
         private _minorMin;
         private _minorMax;
+        /** The major of the last tuple stored, and the last minor stored in it. */
         private _majorIndex;
         private _minorIndex;
+        /** The last position pushed, stored or not: every push must advance past it. */
+        private _lastMajor;
+        private _lastMinor;
+        /** The index in `_tuples` the last {@link getAt} landed on. */
+        private _readIndex;
         private _createList;
+        /**
+         * With a `createList`, runs are collected into ONE reused array and closed as soon as the next
+         * begins; `_run` is the open one, `_filled` how much of `_scratch` is its, `_runMinors` where
+         * it sits (always last). Without one, each run is its own array and is the output.
+         */
+        private _run;
+        private _runMinors;
+        private readonly _scratch;
+        private _filled;
+        private readonly _track;
         private _offsetMajor;
         private _offsetMinor;
-        constructor(createList?: (arr: Array<T>) => IList<T>, offsetMajor?: number, offsetMinor?: number);
+        private readonly _trackAbsent;
+        private _absentValue;
+        private _gaps;
+        private _skips;
+        private _blanks;
+        constructor(createList?: Tuple.CreateList<T>, offsetMajor?: number, offsetMinor?: number, trackAbsent?: boolean);
+        /**
+         * Sets the value the positions this builder does not store read as. Set once, when it is known.
+         * Requires `trackAbsent`.
+         */
+        setAbsentValue(value: T | null): this;
+        /**
+         * Declares `length` positions as reading the absent value over a grid that stores nothing there.
+         * Nothing is written for them unless a blank forces the absent value out. Requires `trackAbsent`.
+         */
+        pushAbsentAt(major: number, minor: number, length: number): this;
         /** {@inheritDoc IBuilder.pushMultipleAt} */
-        pushMultipleAt(major: number, minor: number, value: T[]): IBuilder<T>;
+        pushMultipleAt(major: number, minor: number, value: IListLike<T> | T[]): IBuilder<T>;
         /** {@inheritDoc IBuilder.pushAt} */
         pushAt(major: number, minor: number, value: T): IBuilder<T>;
+        /** The open run becomes the list `createList` makes of the scratch's filled prefix. */
+        private _closeRun;
+        /** {@inheritDoc IBuilder.getAt} */
+        getAt(major: number, minor: number): T | undefined;
+        private _advance;
         /** {@inheritDoc IBuilder.build} */
-        build(): Tuple.BoundedTuples<T>;
+        build(): Tuple.Region<T>;
+        /** {@link build} under `trackAbsent`: never `null`, so the absent value always reaches the caller. */
+        private _buildTracked;
     }
     /**
      * Transposes cell coordinates within tuples to create `MajorTuple` representations
@@ -131,24 +235,32 @@ export declare namespace Tuple {
      * This utility efficiently converts data organized by one axis into the opposite.
      */
     class TransposedBuilder<T> implements IBuilder<T> {
-        private _minors;
-        /** the currentNode the node.minorIndex >= _minorIndex */
-        private _current;
-        private _first;
+        /**
+         * The output lines, one per pushed minor, at `minor - _base`: `[minor, runs]`, where the last
+         * run is the one a push continues. A hole where no minor was pushed; kept in order, so the
+         * build reads them straight through.
+         */
+        private _lines;
+        private _base;
         private _majorMin;
         private _majorMax;
         private _majorIndex;
         private _minorIndex;
         private _createList;
+        private readonly _track;
         private _offsetMajor;
         private _offsetMinor;
-        constructor(createList?: <T>(arr: Array<T>) => IListLike<T>, offsetMajor?: number, offsetMinor?: number);
+        constructor(createList?: Tuple.CreateList<T>, offsetMajor?: number, offsetMinor?: number);
         /** {@inheritDoc IBuilder.pushMultipleAt} */
-        pushMultipleAt(major: number, minor: number, value: T[]): IBuilder<T>;
+        pushMultipleAt(major: number, minor: number, value: IListLike<T> | T[]): IBuilder<T>;
         /** {@inheritDoc IBuilder.pushAt} */
         pushAt(major: number, minor: number, value: T): IBuilder<T>;
+        /** Moves the lines along so `minor` is the first. */
+        private _rebase;
+        /** {@inheritDoc IBuilder.getAt} */
+        getAt(major: number, minor: number): T | undefined;
         /** {@inheritDoc IBuilder.build} */
-        build(): Tuple.BoundedTuples<T>;
+        build(): Tuple.Region<T>;
     }
     /**
      * Thrown when a major minor is set out of order.

package/types/src/collections/_GridUtils.d.ts

@@ -1,5 +1,7 @@
 import { RangeAxis, CellCoords, RangeCoords } from '@sheetxl/utils';
+import { Scalar } from '@sheetxl/primitives';
 import { IGrid } from './IGrid';
+import { ISparseGrid } from './ISparseGrid';
 import { ISpatialMap } from './ISpatialMap';
 import { Tuple } from './Tuple';
 /**
@@ -209,7 +211,7 @@ export declare const MESSAGE_ERROR_REQUIRE_INT = "Tuple indices must be integers
  *
  * @internal
  */
-export declare function valueToTuples<T>(value: T | ((row: number, column: number) => T | null), ranges: Tuple.OrientatedCoords, isColumn: boolean): Tuple.BoundedTuples<T>;
+export declare function valueToTuples<T>(value: T | ((row: number, column: number) => T | null), ranges: Tuple.OrientatedCoords, isColumn: boolean): Tuple.Region<T>;
 /**
  * Entry for a Range iterator or visiting.
  */
@@ -223,7 +225,7 @@ export interface Entry<T extends any> {
  * @remarks
  * This should generally be avoid in preference for zero-copy approaches but exist as a fallback.
  */
-export declare function iteratorToTuples<T>(iterator: IterableIterator<Entry<T>>, axis: RangeAxis, builder: Tuple.IBuilder<T>, topLeft?: CellCoords | null): Tuple.BoundedTuples<T>;
+export declare function iteratorToTuples<T>(iterator: IterableIterator<Entry<T>>, axis: RangeAxis, builder: Tuple.IBuilder<T>, topLeft?: CellCoords | null): Tuple.Region<T>;
 /**
  * Creates an array of Tuple.GridTuple from a 2D array using {@link ITuple.IBuilder}.
  * This adds supports for max bounds and offsetting the indices.
@@ -231,7 +233,7 @@ export declare function iteratorToTuples<T>(iterator: IterableIterator<Entry<T>>
  * @remarks
  * For performance reasons this will not visit ths minor axis but will remove empty major axises.
  */
-export declare function array2DToTuples<T>(array2d: T[][], transpose?: boolean, ranges?: Partial<Tuple.OrientatedCoords> | null, removeEmpty?: boolean): Tuple.BoundedTuples<T>;
+export declare function array2DToTuples<T>(array2d: T[][], transpose?: boolean, ranges?: Partial<Tuple.OrientatedCoords> | null, removeEmpty?: boolean): Tuple.Region<T>;
 /**
  * This is for the edge case where were have a GridTuple but need a bounds.
  * This will iterator through all majors comparing the first and last minor
@@ -242,7 +244,7 @@ export declare function array2DToTuples<T>(array2d: T[][], transpose?: boolean,
  */
 export declare function calcTupleBounds(gridTuples: Tuple.GridTuple): Tuple.OrientatedCoords | null;
 /**
- * Returns a new `BoundedTuples` with all major and minor indices shifted by the given offsets.
+ * Returns a new `Region` with all major and minor indices shifted by the given offsets.
  *
  * @param boundedTuples The source tuples to translate.
  * @param translateMajor Delta added to every major index (and to `bounds.majorStart/End`).
@@ -256,7 +258,7 @@ export declare function calcTupleBounds(gridTuples: Tuple.GridTuple): Tuple.Orie
  * @remarks
  * Run arrays inside each `MinorTuple` are shared by reference; they are immutable `IList`s so this is safe.
  */
-export declare function translateTupleBounds<T = any>(boundedTuples: Tuple.BoundedTuples<T>, translateMajor: number, translateMinor: number): Tuple.BoundedTuples<T>;
+export declare function translateTupleBounds<T = any>(boundedTuples: Tuple.Region<T>, translateMajor: number, translateMinor: number): Tuple.Region<T>;
 /**
  * Returns api for incrementally building ranges against minor and optionally major.
  *
@@ -264,5 +266,16 @@ export declare function translateTupleBounds<T = any>(boundedTuples: Tuple.Bound
  * * Assumes ordered writes.
  * * Allows for reusable ranges.
  */
-export declare function createConflatingRangeValue<T = any>(isColumn?: boolean, canMerge?: (a: T, b: T, isColumn: boolean) => T | undefined): ISpatialMap.IConflatingEntries<T>;
+export declare function createConflatingRangeValue<T = any>(isColumn?: boolean, canMerge?: (a: T, b: T, isColumn: boolean) => T | undefined, combine?: (previous: T, next: T) => T): ISpatialMap.IConflatingEntries<T>;
+/**
+ * A grid's runs as grid tuples, in the grid's own axis: one major tuple per major that holds a
+ * run, the runs shared by reference.
+ *
+ * @remarks
+ * This is the seam the values half of a seed crosses (DESIGN-CALC-SERVICE §6.6): what a grid
+ * holds becomes the tuples another grid is loaded from. Runs are immutable lists, so sharing them
+ * is what the load already does when it hands one set of tuples to the sheet and its grid.
+ * @internal
+ */
+export declare function gridToTuples<T = Scalar>(grid: ISparseGrid<T>): Tuple.GridTuple<T>;
 //# sourceMappingURL=_GridUtils.d.ts.map

package/types/src/collections/_RangeSweep.d.ts

@@ -0,0 +1,97 @@
+import { RangeCoords } from '@sheetxl/utils';
+/**
+ * Pieces: the clipped entries of every searched map, in parallel arrays.
+ * @internal
+ */
+export interface PieceStore {
+    count: number;
+    rowS: Int32Array;
+    rowE: Int32Array;
+    colS: Int32Array;
+    colE: Int32Array;
+    /** Index into `keys`. */
+    type: Uint16Array;
+    value: any[];
+    keys: string[];
+}
+export declare const createPieceStore: (capacity?: number) => PieceStore;
+export declare const growInt32: (arr: Int32Array, size: number) => Int32Array;
+export declare const growPieces: (store: PieceStore, size: number) => void;
+/**
+ * The sweep. Pieces are the input; bands and the regions inside them are computed lazily, one band
+ * at a time, into reusable arrays. The consumer steps regions (`nextRegion`) or cells
+ * (`nextCell` / `seekCell`) and reads the current position from the public fields.
+ * @internal
+ */
+export declare abstract class RangeSweep<T> {
+    private readonly _isColumn;
+    private readonly _isReverse;
+    protected readonly _store: PieceStore;
+    private readonly _n;
+    private readonly _M0;
+    private readonly _M1;
+    private readonly _m0;
+    private readonly _m1;
+    private readonly _order;
+    private _nextOrder;
+    private _active;
+    private _activeLen;
+    private _scratch;
+    private _events;
+    private _hasBand;
+    private _bandStart;
+    private _bandEnd;
+    private _rMinS;
+    private _rMinE;
+    protected _rOff: Int32Array;
+    private _rCount;
+    protected _pool: Int32Array;
+    private _overlaps;
+    private _rInter;
+    private _region;
+    private _major;
+    private _minor;
+    private _done;
+    rowStart: number;
+    rowEnd: number;
+    colStart: number;
+    colEnd: number;
+    cellRow: number;
+    cellCol: number;
+    intersection: T;
+    constructor(store: PieceStore, bounds: RangeCoords, isColumn: boolean, isReverse: boolean);
+    /** Build the value of a region from its overlap set (pieces in `_pool[_rOff[region].._rOff[region+1])`). */
+    protected abstract _materialize(region: number): T;
+    /** Stable id of a piece in scan order (reverse scans invert the push order). */
+    private _stable;
+    /** The minor-event order: closest edge, starts before ends, opposite edge, stable id. */
+    private _compareEvents;
+    /**
+     * Sort `len` events (given in ascending stable order, start before end per piece). Returns the
+     * buffer holding the result, which may be the scratch buffer.
+     *
+     * @remarks
+     * Comparator sort for small groups; LSD counting sort when the minor span is small relative to
+     * the group (the million-fragment case).
+     */
+    private _sortEvents;
+    /** Advance to the next band, materializing its regions. `false` when the sweep is exhausted. */
+    private _advanceBand;
+    /** The minor sweep of the current band: intervals of constant, non-empty overlap set. */
+    private _sweepBand;
+    /** Set the public region fields for the band × region (and the intersection). */
+    private _setRegion;
+    /** Step to the next region. `false` when exhausted. */
+    nextRegion(): boolean;
+    private _setCell;
+    /** Enter a band for cell stepping: the intersection cache is only worth it when majors replay. */
+    private _enterBandByCell;
+    /** Step to the next cell that has an intersection (major, then minor order). `false` when exhausted. */
+    nextCell(): boolean;
+    /**
+     * Step to the first cell at or after (`rowIndex`, `colIndex`) in scan order that has an
+     * intersection; a target at or before the current cell behaves as {@link nextCell}.
+     */
+    seekCell(rowIndex: number, colIndex: number): boolean;
+}
+//# sourceMappingURL=_RangeSweep.d.ts.map

package/types/src/collections/_SpatialUtils.d.ts

@@ -20,7 +20,7 @@ export declare function isEqualCoords(a: RangeCoords, b: RangeCoords): boolean;
  * * If there is no intersect then null is returned. If it is completely contained it will return a 1 value.
  * * All range coords values contain the values from the original splits
  */
-export declare function splitIntersect<T = any>(orig: ISpatialMap.Entry<T>, inter: RangeCoords, getSplit?: ((orig: ISpatialMap.Entry<T>, coords: [RangeCoords, RangeCoords], axis: RangeAxis, offset: number) => [ISpatialMap.Entry<T>, ISpatialMap.Entry<T>] | null | undefined) | null | undefined, updateLastId?: boolean): ISpatialMap.Entry<T>[] | null;
+export declare function splitIntersect<T = any>(orig: ISpatialMap.Entry<T>, inter: RangeCoords, getSplit?: ((orig: ISpatialMap.Entry<T>, coords: [RangeCoords, RangeCoords], axis: RangeAxis, offset: number) => [ISpatialMap.Entry<T>, ISpatialMap.Entry<T>] | null | undefined) | null | undefined): ISpatialMap.Entry<T>[] | null;
 /**
  * Create a set of non overlapping ranges from a set of existing ranges.
  *
@@ -68,6 +68,24 @@ export declare function fastMerge(ranges: RangeCoords[], axis?: RangeAxis, itera
 export declare function removeOverlapsAndMerge(ranges: readonly RangeCoords[], iterations?: number, axis?: RangeAxis, getMerge?: (from: [RangeCoords, b: RangeCoords], destination: RangeCoords, axis: RangeAxis) => RangeCoords | null | undefined, onOverlap?: (intersection: RangeCoords, overlaps: RangeCoords[]) => void, reuseArray?: [RangeCoords | null, RangeCoords | null]): RangeCoords[];
 export declare function delegatingNodeSplitter<T>(from: ISpatialMap.Entry<T>, destination: [ISpatialMap.Entry<T>, ISpatialMap.Entry<T>], axis: RangeAxis, offset: number): [ISpatialMap.Entry<T>, ISpatialMap.Entry<T>] | undefined;
 export declare function delegatingNodeMerger<T>(from: [ISpatialMap.Entry<T>, ISpatialMap.Entry<T>], destination: ISpatialMap.Entry<T>, axis: RangeAxis): ISpatialMap.Entry<T> | undefined;
+/**
+ * Joins `entry` with each neighbor that spans exactly its edge and can join it, repeating with the
+ * joined entry until none can.
+ *
+ * @param search Finds the entries a range intersects.
+ * @param entry The entry just written; it is in the map.
+ * @param join The value of `first` and `second` joined over `coords`, or `undefined` when they
+ * cannot join. `first` is the upper or left one; `axis` is `Row` for a join down, `Column` across.
+ * @param replace Replaces `removes` with `insert` in the map.
+ * @returns The entry `entry` ended up in: itself when nothing joined.
+ *
+ * @remarks
+ * A neighbor joins only when it spans exactly the same columns (above and below) or rows (left
+ * and right), so the result is a rectangle and nothing is split to make it. The map's own merge
+ * (`insertNonOverlapping` without `noMerge`) rejoins everything around the range; this touches
+ * only what is beside the entry.
+ */
+export declare function joinAdjacent<T>(search: (range: RangeCoords) => ISpatialMap.Entry<T>[], entry: ISpatialMap.Entry<T>, join: (first: ISpatialMap.Entry<T>, second: ISpatialMap.Entry<T>, coords: RangeCoords, axis: RangeAxis) => T | undefined, replace: (removes: ISpatialMap.Entry<T>[], insert: ISpatialMap.Entry<T>) => void): ISpatialMap.Entry<T>;
 /**
  * If the two coords overlap in a way that would required them to be split.
  *
@@ -90,7 +108,7 @@ export declare function isSplitIntersect(a: RangeCoords, b: RangeCoords, selecti
  * * May result in either 0, 1, 2, or 3. Nodes.
  */
 export declare function defaultShiftProcessor<T>(before: ISpatialMap.Entry<T>, after: ISpatialMap.Entry<T> | null, optionsProcess: ISpatialMap.ShiftDetails<T>, getShifted: ((orig: ISpatialMap.Entry<T>, after: ISpatialMap.Entry<T>, options: ISpatialMap.ShiftDetails<T>) => ISpatialMap.Entry<T> | undefined) | undefined, getSplit: (orig: ISpatialMap.Entry<T>, coords: [RangeCoords, RangeCoords], axis: RangeAxis, offset: number) => [ISpatialMap.Entry<T>, ISpatialMap.Entry<T>] | null | undefined, onShift: ((options: ISpatialMap.ShiftDetails<T>) => void) | null | undefined, splitExpand: boolean): ISpatialMap.Entry<T>[] | null | undefined;
-export declare function createCopiedSpatialEntries<T = any>(spatial: ISpatialMap, coordsFrom: RangeCoords, coordsTo: RangeCoords, options?: ISpatialMap.CopyOptions, reuseInserts?: ISpatialMap.Entry<T>[], reuseRemoves?: ISpatialMap.Entry<T>[], onSplit?: (from: ISpatialMap.Entry<T>, destination: [ISpatialMap.Entry<T>, ISpatialMap.Entry<T>], axis: RangeAxis, offset: number) => [ISpatialMap.Entry<T>, ISpatialMap.Entry<T>] | null | undefined): ISpatialMap.Updates;
+export declare function createCopiedSpatialEntries<T = any>(spatial: ISpatialMap, coordsFrom: RangeCoords, coordsTo: RangeCoords, options?: ISpatialMap.CopyOptions, reuseInserts?: ISpatialMap.Entry<T>[], reuseRemoves?: ISpatialMap.Entry<T>[], onSplit?: ((from: ISpatialMap.Entry<T>, destination: [ISpatialMap.Entry<T>, ISpatialMap.Entry<T>], axis: RangeAxis, offset: number) => [ISpatialMap.Entry<T>, ISpatialMap.Entry<T>] | null | undefined) | null): ISpatialMap.Updates;
 /**
  * Use to remove spills.
  *

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

@@ -12,6 +12,7 @@ export * from './IList';
 export * from './OverlappingRangeIterator';
 export * from './SortedMap';
 export * from './SparseGrid';
+export * from './ScalarGrid';
 export * from './SparseList';
 export * from './SpatialMap';
 export * from './SpatialMap3D';

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

@@ -0,0 +1,159 @@
+import { IRange } from '@sheetxl/primitives';
+import { IListener } from '../listener';
+import { ITransaction } from '../transaction';
+import { ICellRange } from '../cellRange';
+import { ISheet } from '../sheet';
+import { IPerson, IPersonCollection } from '../person';
+import { Anchored } from '../anchored/Anchored';
+import { AbstractAnchored } from '../anchored/AbstractAnchored';
+import { IComment } from './IComment';
+/**
+ * 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.
+ */
+export declare class Comment extends AbstractAnchored<State, IComment.Events> implements IComment {
+    private _replies;
+    /** @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;
+    /**
+     * {@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(): IComment.RichContent | 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 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;
+    /**
+     * The note's box, as read.
+     * @internal
+     */
+    getBox(): IComment.BoxJSON | null;
+    /** @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;
+    }
+}
+/** @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[];
+    box: IComment.BoxJSON | 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