@sheetxl/sdk 0.7.21 → 0.7.23-beta.2

package/types/src/anchored/Anchored.d.ts

@@ -0,0 +1,154 @@
+import { IRange, IRuntime } from '@sheetxl/primitives';
+import { IListener } from '../listener';
+import { ITransaction } from '../transaction';
+import { ICellRange, ICellRanges } from '../cellRange';
+import { ISpatialMap } from '../collections';
+import { IAnchored } from './IAnchored';
+export declare namespace Anchored {
+    /**
+     * Interface for anchored items that need to have callback interactions.
+     */
+    interface Entry<T extends IAnchored> extends ISpatialMap.IUpdatableValue {
+        model: T;
+        callbacks: Anchored.ContainerCallbacks;
+        removeListener?: IListener.Remove;
+        currentName?: string;
+    }
+    /**
+     * This is a hook for creating entries with anchored items.
+     *
+     * @remarks
+     * A model may be anchored to more than one range. Each range is a separate spatial entry that
+     * carries this value; `order` is what makes the set of them an *ordered* list rather than a bag.
+     */
+    interface Entry2<T extends IAnchored> extends ISpatialMap.IUpdatableValue<Anchored.Entry2<T>> {
+        model: T;
+        /**
+         * Sort key for this range within its model's authored range list.
+         *
+         * @remarks
+         * * Only meaningful *within* one model — never compare across models.
+         * * Assigned from a monotonic counter with gaps so a delete never renumbers and a split can
+         *   subdivide without touching its siblings.
+         * * Together with `model` it is the **identity** of a spatial entry. Coordinates are not:
+         *   a split changes them, and one model may legally hold two identical rectangles.
+         */
+        order: number;
+        /**
+         * Size of the order space this entry owns — it spans `[order, order + orderSpan)`.
+         *
+         * @remarks
+         * A split halves the span between the two pieces, so a piece can never be assigned an order
+         * that reaches the next sibling. That is what keeps *recursive* splits stable: the pieces of
+         * a piece stay inside their parent's slice.
+         */
+        orderSpan: number;
+    }
+    interface EntryMeta<T extends IAnchored> {
+        model: T;
+        callbacks: Anchored.ContainerCallbacks;
+        name?: string | null;
+        index: number;
+    }
+    interface MetaAndEntries<T extends IAnchored> {
+        entries: ISpatialMap.Entry<Anchored.Entry2<T>>[];
+        meta: Anchored.EntryMeta<T>;
+    }
+    interface ContainerCallbacks {
+        /**
+         * Called on each entry shift.
+         */
+        processShift?: (options: Anchored.ShiftOptions) => IRange.Coords | null | void;
+        /**
+         * Called after all shifts. Perhaps we need to provide the before and afters?
+         */
+        processAfterShift?: (before: IRange.Coords[] | null, after: IRange.Coords[] | null) => void;
+        processDelete?: () => void;
+        processIndexChange?: () => void;
+        /**
+         * Called to notify the container that a layout update is required.
+         */
+        processLayout?: () => void;
+        processProtection?: () => void;
+    }
+    interface CoordsChangeOptions {
+        before: Readonly<IRange.Coords[]>;
+        after: Readonly<IRange.Coords[]>;
+    }
+    type CoordsChangeCallback = (options: CoordsChangeOptions) => void;
+    interface ShiftOptions {
+        before: IRange.Coords;
+        /** `null` when the shift removes the anchored item. */
+        after: IRange.Coords | null;
+        intersect: IRange.Coords;
+        isSplit: boolean;
+        axis: IRange.Axis;
+        amount: number;
+    }
+    interface ConstructorOptions<J = any> {
+        /**
+         * Return a range from a set of coordinates.
+         */
+        getRanges: (address: ICellRanges.Address, options?: ICellRange.GetRangeOptions) => ICellRanges;
+        /**
+         * Returns the entire range that this anchored item can use.
+         */
+        getEntireRange?: () => ICellRange;
+        /**
+         * Get the index of the current model.
+         * @returns
+         */
+        getContainerIndex: () => number | undefined;
+        /**
+         * The runtime
+         */
+        runtime?: IRuntime;
+        /**
+         * A transaction store that can be used to undo/redo changes.
+         */
+        transactions?: ITransaction.IStore;
+        /**
+         * The anchor used when the item is first created.
+         */
+        coords: IRange.Coords | IRange.Coords[];
+        /**
+         * The initial json
+         */
+        json?: J;
+        /**
+         * If protected the container can protected the item.
+         */
+        isProtected?(): boolean;
+        /**
+         * Notify the container that an area is invalidated.
+         */
+        invalidate?(coords?: IRange.Coords): void;
+        /**
+         * Register container callbacks.
+         */
+        setContainerCallbacks?(callbacks?: Anchored.ContainerCallbacks): void;
+        /**
+         * Notify the container that a anchor change is required.
+         *
+         * @param address Set the anchor on the container
+         */
+        setContainerCoords?(address: ICellRanges.Address, options?: ITransaction.OperationOptions): ICellRanges.Coords | void;
+        /**
+         * Notify the container that the name has changed.
+         *
+         * @param name Set the name on the container
+         */
+        setContainerName?(name: string, options?: ITransaction.OperationOptions): void;
+        /**
+         * Notify the container that the index has changed.
+         *
+         * @param index Set the index on the container
+         */
+        setContainerIndex?(index: number, options?: ITransaction.OperationOptions): void;
+        /**
+         * Delete from the container.
+         */
+        deleteFromContainer?(options?: ITransaction.OperationOptions): void;
+    }
+}
+//# sourceMappingURL=Anchored.d.ts.map

package/types/src/anchored/Anchored.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Anchored.d.ts","sourceRoot":"","sources":["../../../../src/anchored/Anchored.ts"],"names":[],"mappings":"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"}

package/types/src/anchored/AnchoredMap.d.ts

@@ -0,0 +1,178 @@
+import { IRange } from '@sheetxl/primitives';
+import { ISpatialMap, ISpatialQuery } from '../collections';
+import { IAnchored } from './IAnchored';
+import { IAnchoredMap } from './IAnchoredMap';
+import { Anchored } from './Anchored';
+export declare class AnchoredMap<T extends IAnchored, J, P = any> implements IAnchoredMap<T, J>, ISpatialQuery<T> {
+    /**
+     * A map of models to spatial entries.
+     *
+     * @remarks
+     * A model may hold more than one range. The array is **always kept sorted by
+     * {@link Anchored.Entry2.order}** — that is the model's authored range order, and every read
+     * path (`toJSON`, `processAfterShift`, `search`) depends on it.
+     */
+    protected _mapModelToEntries: Map<T, ISpatialMap.Entry<Anchored.Entry2<T>>[]>;
+    protected _mapNameToModel: Map<string, T>;
+    protected _mapModelToMeta: Map<T, Anchored.EntryMeta<T>>;
+    protected _indexToModel: T[];
+    protected _spatial: ISpatialMap<Anchored.Entry2<T>>;
+    protected _options: IAnchoredMap.ConstructorOptions;
+    protected _isEmpty: boolean;
+    /**
+     * Monotonic order stamp allocator. Advances by {@link _ORDER_STEP} per entry created and is
+     * **never** reset — not on delete, not on clone.
+     *
+     * @remarks
+     * Carried by *both* {@link _shallowClone} and {@link clone}. A clone that restarted the counter
+     * would hand out ids that collide with the ones already stored, and the order sort would silently
+     * scramble a model's ranges. Reuse across an abandoned undo branch is harmless: ids only have to
+     * be ordered *within* one model.
+     */
+    protected _nextOrder: number;
+    /**
+     * The `createEntry` hook from the last {@link load}, so {@link setCoords} can mint replacement
+     * entries with the same custom value shape.
+     */
+    protected _createEntry: ((model: T, coords: IRange.Coords) => Anchored.Entry2<T>) | null;
+    /**
+     * Cache key for {@link search}. Always a private copy of the caller's range — never the caller's
+     * object. Callers may hand in a pooled coords that they mutate afterwards (e.g. `_ReuseSearchTable`
+     * in `Sheet._markColumnHeaderTableNames`, rewritten on every selection change); retaining that
+     * reference would let the key silently re-point at a *different* query while
+     * {@link _cacheSearchResults} still held the previous query's results.
+     * `_cacheSearchResults === null` means nothing is cached.
+     */
+    protected _cacheSearchRange: IRange.Coords;
+    protected _cacheSearchFullyContained: boolean;
+    protected _cacheSearchResults: ISpatialMap.Entry<T>[] | null;
+    constructor(options: IAnchoredMap.ConstructorOptions);
+    protected _init(options: IAnchoredMap.ConstructorOptions): void;
+    /**
+     * Allocates the next order stamp.
+     */
+    protected _allocateOrder(): number;
+    /**
+     * Creates a spatial entry for `model` at `coords`, stamped with the next order.
+     */
+    protected _createSpatialEntry(model: T, coords: Readonly<IRange.Coords>): ISpatialMap.Entry<Anchored.Entry2<T>>;
+    /**
+     * Returns a model's spatial entries in authored (order) sequence, or an empty array.
+     *
+     * @remarks
+     * The arrays in {@link _mapModelToEntries} are maintained sorted, so this is a lookup — every
+     * writer is responsible for re-sorting what it stores.
+     */
+    protected _entriesOf(model: T): ISpatialMap.Entry<Anchored.Entry2<T>>[];
+    /** {@inheritDoc IAnchoredMap.all} */
+    all(): readonly T[];
+    /**
+     * The single write point for the model order.
+     *
+     * @param indexToModel A private working array — never one already handed out.
+     *
+     * @remarks
+     * Freezes it, so {@link all} can hand out the live array and any accidental mutation throws
+     * (modules are strict) instead of silently corrupting this map and every clone sharing it. Every
+     * mutator already builds a fresh copy before editing, so this is copy-on-*write*.
+     */
+    protected _setIndexToModel(indexToModel: (T | null)[]): void;
+    /** {@inheritDoc IAnchoredMap.search} */
+    search(range: Readonly<IRange.Coords>, fullyContained?: boolean, _sort?: boolean, results?: ISpatialMap.Entry<T>[]): ISpatialMap.Entry<T>[];
+    /**
+     * The uncached body of {@link search}: one entry per matching **range**, its `value` unwrapped
+     * from the spatial entry to the model that owns it.
+     */
+    protected _searchModels(range: Readonly<IRange.Coords>, fullyContained: boolean): ISpatialMap.Entry<T>[];
+    /** {@inheritDoc IAnchoredMap.getByName} */
+    getByName(name: string): T | null;
+    /** {@inheritDoc IAnchoredMap.setName} */
+    setName(model: T, name: string): this;
+    /** {@inheritDoc IAnchoredMap.getByIndex} */
+    getByIndex(index: number): T | null;
+    /** {@inheritDoc IAnchoredMap.setName} */
+    setIndex(model: T, index: number): this;
+    /** {@inheritDoc IAnchoredMap.getIndex} */
+    getIndex(model: T): number;
+    /** {@inheritDoc IAnchoredMap.getCoords} */
+    getCoords(model: T): IRange.Coords[] | null;
+    /** {@inheritDoc IAnchoredMap.setCoords} */
+    setCoords(model: T, coords: readonly Readonly<IRange.Coords>[]): this;
+    /** {@inheritDoc IAnchoredMap.clone} */
+    clone(): this;
+    /** {@inheritDoc IAnchoredMap.size} */
+    size(): number;
+    /** {@inheritDoc IAnchoredMap.isEmpty} */
+    isEmpty(): boolean;
+    /** {@inheritDoc IAnchoredMap.has} */
+    has(range: Readonly<IRange.Coords>): boolean;
+    /** {@inheritDoc IAnchoredMap.shift} */
+    shift(options: IAnchoredMap.ShiftOptions): this;
+    /**
+     * Applies a per-model entry delta, then notifies each affected model **exactly once**.
+     *
+     * @param deltas The new entry list per model. An empty list deletes the model.
+     * @param originalEntries The pre-operation entries, for the `before` half of the notification.
+     * @param mapModelToEntries Cloned; mutated in place.
+     * @param mapModelToMeta Cloned; mutated in place.
+     * @param mapNameToModel Cloned; mutated in place.
+     * @param indexToModel Cloned; mutated in place, then compacted.
+     *
+     * @remarks
+     * Shared by {@link shift} and {@link deleteRanges} so they cannot drift apart on the two rules
+     * that are easy to get subtly wrong:
+     * * one `processAfterShift(before[], after[])` per model per operation — **not** one per range;
+     * * `processDelete()` only when the model's **last** range goes.
+     */
+    protected _applyEntryDeltas(deltas: Map<T, ISpatialMap.Entry<Anchored.Entry2<T>>[]>, originalEntries: Map<T, ISpatialMap.Entry<Anchored.Entry2<T>>[]>, mapModelToEntries: Map<T, ISpatialMap.Entry<Anchored.Entry2<T>>[]>, mapModelToMeta: Map<T, Anchored.EntryMeta<T>>, mapNameToModel: Map<string, T>, indexToModel: (T | null)[]): void;
+    /** {@inheritDoc IAnchoredMap.deleteRanges} */
+    deleteRanges(ranges: readonly Readonly<IRange.Coords>[], fullContained?: boolean): this;
+    /**
+     * Uses the _reIndexMeta after a remove
+     *
+     * Assumes index and mapModelToMeta are both cloned
+     * Assumes indexed as null records for removes
+     * Assumes mapModelToMeta has indexes remove to match indexed
+     */
+    protected _reIndexMeta(indexed: (T | null)[], mapModelToMeta: Map<T, Anchored.EntryMeta<T>>, from?: number, pruneNulls?: boolean): void;
+    /** {@inheritDoc IAnchoredMap.deleteModel} */
+    deleteModel(model: T): this;
+    /**
+     * A ref that cannot be loaded is user data about to disappear.
+     *
+     * @remarks
+     * Routed through {@link Notifier} rather than `console.*`, and never swallowed silently. Under
+     * {@link AnchoredMap.setStrictLoad} it throws instead: a dropped item is otherwise
+     * indistinguishable from one that was never authored, which is enough to let a round-trip suite
+     * compare an empty result against an empty result and pass.
+     */
+    protected _onLoadFailure(message: string, error: unknown): void;
+    /** {@inheritDoc IAnchoredMap.load} */
+    load(refs: IRange.JSONReference<J>[], createOptions: IAnchoredMap.CreateEntryOptions<T>): this;
+    /** {@inheritDoc IAnchoredMap.getBoundingRange} */
+    getBoundingRange(): IRange.Coords;
+    /** {@inheritDoc IAnchoredMap.toJSON} */
+    toJSON(): IRange.JSONReferenceEntry<J>[] | null;
+    /** {@insertDoc IAnchoredMap.processCallbacks} */
+    processCallbacks(handler: (model: T, callbacks: Anchored.ContainerCallbacks) => void): void;
+    /** {@insertDoc IAnchoredMap.close} */
+    close(): void;
+    protected _shallowClone(): this;
+}
+export declare namespace AnchoredMap {
+    /**
+     * Makes a failed {@link AnchoredMap.load} throw instead of warn.
+     *
+     * @remarks
+     * For tests, which turn it on globally in `config/vitest.setup.ts`. In an application a single
+     * unloadable item must not cost the user the rest of the workbook, so the default is to warn and
+     * carry on — but that same leniency makes a test suite blind to data loss, since a rule that
+     * failed to load looks exactly like a rule that was never authored.
+     */
+    function setStrictLoad(strict: boolean): void;
+    /**
+     * Whether a failed {@link AnchoredMap.load} throws. See {@link setStrictLoad}.
+     */
+    function isStrictLoad(): boolean;
+}
+//# sourceMappingURL=AnchoredMap.d.ts.map

package/types/src/anchored/AnchoredMap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnchoredMap.d.ts","sourceRoot":"","sources":["../../../../src/anchored/AnchoredMap.ts"],"names":[],"mappings":"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"}

package/types/src/anchored/IAnchored.d.ts

@@ -0,0 +1,118 @@
+import { IRange } from '@sheetxl/primitives';
+import { IListener } from '../listener';
+import { ICellRange, ICellRanges } from '../cellRange';
+/**
+ * `IAnchored` objects are anchored to one or more ranges.
+ */
+export interface IAnchored {
+    /**
+     * Returns the ranges this object is anchored to, in authored order.
+     *
+     * @remarks
+     * * **Never `null`.** An item whose last range was removed by a row/column delete returns an
+     *   *invalid* ranges — ask {@link ICellRanges.isInvalid}, the same contract as
+     *   `ITable.getDataRange`.
+     * * This is the general accessor. Most anchored types hold exactly one range and declare their
+     *   own `getRange()` for it, but data validations, conditional formats and protected ranges are
+     *   authored as several, and *any* single range can become several when a delete splits it.
+     */
+    getRanges(options?: ICellRange.GetRangeOptions): ICellRanges;
+    /**
+     * The name of the anchor or `null` if it has none.
+     */
+    getName?(): string | null;
+    /**
+     * Returns how the anchorBounds adjust when inserting/removing rows/columns.
+     *
+     * @defaultValue IAnchored.Type.TwoCell
+     */
+    getAnchorType?(): IAnchored.Type;
+    /**
+     * If the anchor is unable to be modified.
+     */
+    isProtected(): boolean;
+    /**
+     * Add Listeners.
+     *
+     * @see
+     * {@link IListener.ISource.addListeners}
+     */
+    addListeners(listeners: IAnchored.IListeners, options?: IListener.Options): IListener.Remove;
+    /**
+     * Deletes the anchored item.
+     */
+    delete(): void;
+    /**
+     * Returns if the model has been deleted
+     */
+    isDeleted(): boolean;
+    /**
+     * Similar to delete but cleans resources and can't be undone.
+     */
+    close(): void;
+    /**
+     * Returns if the model has been closed
+     */
+    isClosed(): boolean;
+    /**
+     * For runtime type checking.
+     */
+    readonly isIAnchored: true;
+}
+/**
+ * {@inheritDoc IAnchored}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IAnchored}
+ */
+export declare namespace IAnchored {
+    interface Events<T extends IAnchored = IAnchored> {
+        /**
+         * Called when the anchor bounds are updated.
+         */
+        onAnchorCoordsChange?(source: T, prev: IRange.Coords): void;
+        /**
+         * Called when the anchor protection is updated.
+         */
+        onProtectedChange?(source: T): void;
+        /**
+         * Called when the anchor is removed.
+         */
+        onDelete?(source: T): void;
+        /**
+         * Called when the state has been updated due to a undo/redo and a rerender is required.
+         */
+        onInvalidated?(source: T): void;
+        /**
+         * Called when the state has been updated for any reason.
+         */
+        onAnyChange?(source: T): void;
+        /**
+         * Called when the anchor transaction is closed.
+         */
+        onClose?(source: T): void;
+    }
+    interface IListeners extends IListener.Callbacks<IAnchored, IAnchored.Events> {
+    }
+    /**
+     * Describes how an anchored items bounds will adjust if
+     * rows/columns are inserted/removed.
+     */
+    const Type: {
+        /**
+         * Doesn't move when anchors moves.
+         */
+        readonly Absolute: "absolute";
+        /**
+         * Only moves the top left
+         */
+        readonly OneCell: "oneCell";
+        /**
+         * Moves both the top left and the bottom right
+         */
+        readonly TwoCell: "twoCell";
+    };
+    type Type = typeof Type[keyof typeof Type];
+}
+//# sourceMappingURL=IAnchored.d.ts.map

package/types/src/anchored/IAnchored.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IAnchored.d.ts","sourceRoot":"","sources":["../../../../src/anchored/IAnchored.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAElD,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;;;;;;OAUG;IACH,SAAS,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC,eAAe,GAAG,WAAW,CAAC;IAC7D;;OAEG;IACH,OAAO,CAAC,IAAI,MAAM,GAAG,IAAI,CAAC;IAC1B;;;;OAIG;IACH,aAAa,CAAC,IAAI,SAAS,CAAC,IAAI,CAAC;IACjC;;OAEG;IACH,WAAW,IAAI,OAAO,CAAC;IACvB;;;;;OAKG;IACH,YAAY,CAAC,SAAS,EAAE,SAAS,CAAC,UAAU,EAAE,OAAO,CAAC,EAAE,SAAS,CAAC,OAAO,GAAG,SAAS,CAAC,MAAM,CAAC;IAC7F;;OAEG;IACH,MAAM,IAAI,IAAI,CAAC;IACf;;OAEG;IACH,SAAS,IAAI,OAAO,CAAC;IACrB;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;IACd;;OAEG;IACH,QAAQ,IAAI,OAAO,CAAC;IACpB;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,yBAAiB,SAAS,CAAC;IACzB,UAAiB,MAAM,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS;QACrD;;WAEG;QACH,oBAAoB,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC;QAC5D;;WAEG;QACH,iBAAiB,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;QACpC;;WAEG;QACH,QAAQ,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;QAC3B;;WAEG;QACH,aAAa,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;QAChC;;WAEG;QACH,WAAW,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;QAC9B;;WAEG;QACH,OAAO,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;KAC3B;IAED,UAAiB,UAAW,SAAQ,SAAS,CAAC,SAAS,CAAC,SAAS,EAAE,SAAS,CAAC,MAAM,CAAC;KAAG;IAEvF;;;OAGG;IACI,MAAM,IAAI;QACf;;WAEG;;QAEH;;WAEG;;QAEH;;WAEG;;KAEK,CAAC;IACX,KAAY,IAAI,GAAG,OAAO,IAAI,CAAC,MAAM,OAAO,IAAI,CAAC,CAAC;CAEnD"}

package/types/src/anchored/IAnchoredMap.d.ts

@@ -0,0 +1,207 @@
+import { IRange } from '@sheetxl/primitives';
+import { CoordUtils } from '@sheetxl/utils';
+import { ITransaction } from '../transaction';
+import { IListener } from '../listener';
+import { ISpatialMap, ISpatialQuery } from '../collections';
+import { ICellRange, ICellRanges } from '../cellRange';
+import { IAnchored } from './IAnchored';
+import { Anchored } from './Anchored';
+/**
+ * This is a map that wraps anchored entries into spatial maps.
+ *
+ * An anchored map has a set of capabilities:
+ *
+ * * These all support the .clone design
+ * * Shift entries in a spatial and route to IAnchored
+ * * Support deletion
+ * * Maintain order
+ *
+ * *? Return an ICollection
+ *
+ * * Query by:
+ * *   a. Range
+ * *   b. Model
+ * *   c. Name
+ */
+/**
+ * Returns as an ICollection
+ */
+export interface IAnchoredMap<T extends IAnchored, J = any> extends ISpatialQuery<T> {
+    /**
+     * Returns all models within the search range — **one entry per matching range**, each entry's
+     * `value` the model that owns it, ordered by model index then by authored range order.
+     *
+     * @param range The range to search
+     * @param fullyContained Only search for ranges that are completely contained with the search range. DefaultValue `false`.
+     * @param sort Ignored. Results are always ordered by model index.
+     * @param results Optional array to append the results to.
+     *
+     * @remarks
+     * * A model anchored to several ranges appears **once per range that intersects** `range`, so
+     *   every entry's coords are truthful — which is what anything painting or measuring needs.
+     *   Collapsing to one hit per model would have to pick a single range's coords and misreport
+     *   where the rest are; callers wanting one hit per model dedupe on the value (see
+     *   `_SheetStateReader.getRangedEntries`, whose contract is a single instance per item).
+     * * The returned array (when `results` is not supplied) is borrowed from an internal cache:
+     *   read-only, copy before mutating.
+     */
+    search(range: Readonly<IRange.Coords>, fullyContained?: boolean, sort?: boolean, results?: ISpatialMap.Entry<T>[]): ISpatialMap.Entry<T>[];
+    /**
+     * Returns if the map is empty.
+     */
+    isEmpty(): boolean;
+    /**
+     * Returns `true` if any anchored range intersects `range`.
+     *
+     * @remarks
+     * The cheap existence test behind `_SheetStateReader.hasRangedEntries` — it hits the spatial
+     * index and never materializes entries or models.
+     */
+    has(range: Readonly<IRange.Coords>): boolean;
+    /**
+     * Returns the model with the given name.
+     */
+    getByName(name: string): T | null;
+    /**
+     * Sets the name and return a clone.
+     */
+    setName(model: T, name: string): this;
+    /**
+     * Returns the model with the given index.
+     */
+    getByIndex(index: number): T | null;
+    /**
+     * Sets the index and return a clone.
+     */
+    setIndex(model: T, index: number): this;
+    /**
+     * Returns the index for the model
+     */
+    getIndex(model: T): number;
+    /**
+     * Returns the model's ranges in authored order, or `null` if the model is not in the map.
+     */
+    getCoords(model: T): IRange.Coords[] | null;
+    /**
+     * Replaces the model's ranges and returns a clone.
+     *
+     * @param model The model to re-anchor.
+     * @param coords The new ranges, in authored order. An empty array deletes the model.
+     *
+     * @remarks
+     * This is a **replace**, not a merge: the previous ranges are dropped wholesale, so there is no
+     * old-to-new correspondence and the array given here becomes the model's authored order.
+     */
+    setCoords(model: T, coords: readonly Readonly<IRange.Coords>[]): this;
+    /**
+     * Returns all models, in model order.
+     *
+     * @remarks
+     * The map's live, **frozen** model order — not a copy, because this is read on the render path.
+     * Copy before sorting or filtering.
+     */
+    all(): readonly T[];
+    /**
+     * Returns the number of models.
+     */
+    size(): number;
+    /**
+     * Shifts all ranges in a given direction.
+     *
+     * @param options The options for the shift.
+     */
+    shift(options: IAnchoredMap.ShiftOptions): this;
+    /**
+     * Remove all models at range.
+     */
+    deleteRanges(range: Readonly<IRange.Coords[]>): this;
+    /**
+     * Remove item.
+     */
+    deleteModel(model: T): this;
+    /**
+     * Load from a set of references.
+     * @param refs
+     */
+    load(refs: IRange.JSONReference<J>[], createOptions: IAnchoredMap.CreateEntryOptions<T>): this;
+    /**
+     * Escape value to manually process callbacks. Most area handled automatically.
+     *
+     * @remarks
+     * This is being used on protection updated.
+     */
+    processCallbacks(handler: (model: T, callbacks: Anchored.ContainerCallbacks) => void): void;
+    /**
+     * Returns a copy
+     */
+    clone(): this;
+    /**
+     * Serializes to a set of references or `null` if the map is empty.
+     */
+    toJSON(): IRange.JSONReference<J>[] | null;
+    /**
+     * Closes the anchored map and its entries.
+     */
+    close(): void;
+}
+export declare namespace IAnchoredMap {
+    interface ConstructorOptions {
+        /**
+         * Returns a ranges from an address
+         * @returns
+         */
+        getRanges: (address: ICellRanges.Address) => ICellRanges;
+        /**
+         * Get the entire range of the current model.
+         */
+        getEntireRange: () => ICellRange;
+    }
+    interface CreateEntryOptions<T extends IAnchored> {
+        /**
+         * Required to create the model.
+         */
+        createModel: (options: Anchored.ConstructorOptions) => T;
+        /**
+         * If provided then will allow for custom Anchored.Entry.
+         *
+         * @remarks
+         * Useful when the entries have custom merge/split or other spatial logic..
+         */
+        createEntry?: (model: T, coords: IRange.Coords) => Anchored.Entry2<T>;
+        /**
+         * Called once after model creation. Any remove function will be called after delete
+         */
+        addListeners: (model: T) => IListener.Remove;
+        setContainerCoords?: (model: T, coords: readonly Readonly<IRange.Coords>[], options?: ITransaction.OperationOptions) => void;
+        setContainerName?: (model: T, name: string, options?: ITransaction.OperationOptions) => void;
+        setContainerIndex?: (model: T, index: number, options?: ITransaction.OperationOptions) => void;
+        getContainerIndex?: (model: T) => number | undefined;
+        deleteFromContainer?: (model: T, options?: ITransaction.OperationOptions) => void;
+        /**
+         * Notify that an anchor item wants to invalidate a range.
+         */
+        invalidate?: (coords?: IRange.Coords) => void;
+    }
+    /**
+     * Options for the shift method on the Index.
+     */
+    interface ShiftOptions {
+        /**
+         * The range to shift.
+         */
+        ranges: IRange.Coords[];
+        /**
+         * The direction to shift.
+         */
+        direction: IRange.Direction;
+        /**
+         * Allows for a a validation of the range after the shift amount is determined
+         * but before this shift is performed.
+         *
+         * @remarks
+         * * Useful when performing inserts that may fall outside of the bounds.
+         */
+        coordValidator?: CoordUtils.CoordValidator;
+    }
+}
+//# sourceMappingURL=IAnchoredMap.d.ts.map