@sheetxl/sdk 0.7.27 → 0.7.28-beta.2

package/types/src/sheet/_SheetStateTypes.d.ts

@@ -0,0 +1,446 @@
+import { Scalar, IRange } from '@sheetxl/primitives';
+import { IProperties } from '../type';
+import { ITable } from '../table';
+import { IComment } from '../comment';
+import { IHyperlink } from '../hyperlink';
+import { IStyle } from '../style';
+import { ICellRange } from '../cellRange';
+import { OverlappingRange, ISparseGrid, ISpatialMap } from '../collections';
+import { MergeEntry } from './spatial';
+import { SpillEntry, ContentfulSpatialValue } from '../calculation/spatial';
+import { IConditionalFormat } from '../conditionalFormat';
+import { IDataValidation } from '../dataValidation';
+import { IProtectedRange } from '../protectedRange';
+import { IFormulaBlock } from '../calculation/formula';
+import { IAnchoredMap } from '../anchored/IAnchoredMap';
+import { Anchored } from '../anchored/Anchored';
+import { ICalcGrid } from '../calculation/grid';
+import { IUsedRangeSpatialMap } from './style/UsedRangeSpatialMap';
+import { SheetDirectStyle } from './style/SheetDirectStyle';
+import { IMovable } from '../movable';
+import { Movable } from '../movable/Movable';
+import { IPicture } from '../picture';
+import { IListener } from '../listener';
+import { RangesListener, RangesListenerEntry } from './listener';
+export declare const BreakTrue: Readonly<{
+    break: true;
+}>;
+export type WellKnownIterator<T, TReturn = any, TNext = undefined> = Iterator<T, TReturn, TNext>;
+export type WellKnownIteratorResult<T, TReturn = any> = IteratorResult<T, TReturn>;
+export declare namespace CellState {
+    /**
+     * Entries iterators are arrays of fixed length 5.
+     */
+    type Entry = [
+        coords: IRange.CellCoords,
+        v: Scalar,
+        rs: RangeState.Intersection,
+        prev: IRange.CellCoords,
+        next: IRange.CellCoords
+    ];
+    /**
+     * Shorthand type.
+     */
+    type IteratorResult = WellKnownIteratorResult<CellState.Entry>;
+    /**
+     * Shorthand type.
+     */
+    type Iterator = WellKnownIterator<CellState.Entry, CellState.Entry, IRange.CellCoords>;
+    /**
+     * To reduce the number of objects we just extend ICellRange.IteratorOptions with new properties.
+     * This will make a number of them redundant.
+     *
+     * @internal
+     */
+    interface IteratorOptions extends Omit<ICellRange.IteratorOptions, 'address'> {
+        /**
+         * When scanning for values includes ranges.
+         * If `true` than will include all, `false` will include none but still honor hidden headers
+         *
+         * @remarks
+         * If a string array is provided than this will only query those types of ranges.
+         * @defaultValue false
+         */
+        searchTypes?: boolean | RangeState.SearchTypes;
+        /**
+         * parsed address
+         */
+        bounds?: IRange.Coords;
+        /**
+         * If `true` then empty values will be ignored.
+         *
+         * @defaultValue false
+         *
+         * @remarks
+         * This is used when iterating a cell values but that need intersection details
+         * but we don't want to iterative non valued intersections.
+         */
+        ignoreEmptyIntersections?: boolean;
+    }
+}
+export declare namespace RangeState {
+    /**
+     * The boolean is used to indicate if the search result must full contained to return
+     */
+    type SearchTypes = Partial<Record<RangeState.Type, boolean>>;
+    interface IteratorOptions extends OverlappingRange.IteratorOptions {
+        searchTypes: boolean | SearchTypes;
+        injectReferences?: IRange.JSONReference<any>[][];
+        bounds?: IRange.Coords;
+        /**
+         * Only yield blocks completely contained within `bounds`.
+         *
+         * @remarks
+         * NOT the `SearchTypes` per-type boolean, which has the opposite orientation (the QUERY
+         * inside the block — merge-check semantics). This is the public `getRegions` containment.
+         */
+        fullyContained?: boolean;
+        ignoreHidden?: boolean | IRange.Axis;
+        includeMergeOverflow?: boolean;
+    }
+    interface Entry {
+        /**
+         * If byCell. Else null
+         */
+        cell: IRange.CellCoords;
+        /**
+         * The cell that starts the range.
+         */
+        start: IRange.CellCoords;
+        /**
+         * The cell that ends the range.
+         */
+        end: IRange.CellCoords;
+        /**
+         * The CellState.Ranged. We could also make this a lazy function
+         */
+        intersection: RangeState.Intersection;
+    }
+    /**
+   * Shorthand type.
+   */
+    type IteratorResult = WellKnownIteratorResult<RangeState.Entry>;
+    /**
+     * Shorthand type.
+     */
+    type Iterator = WellKnownIterator<RangeState.Entry, RangeState.Entry, IRange.Coords>;
+    /**
+     * Dynamic state. These are values associated to a range of cells that
+     * get realized at time of cell iterator.
+     *
+     * @internal
+     */
+    interface Intersection {
+        /**
+         * The merge state.
+         */
+        merge?: MergeEntry;
+        /**
+         * A table that this cell belongs to.
+         */
+        table?: ITable;
+        /**
+         * A table that this cell belongs to.
+         */
+        autoTable?: ITable;
+        /**
+         * Conditional styles.
+         *
+         * @remarks
+         * Overlaps are allowed
+         */
+        conditionals?: IConditionalFormat | IConditionalFormat[];
+        /**
+         * The per-feature direct styles for a collection of cells (SHEET-STYLE-SPLIT). These are the
+         * user-authored style, kept DISCRETE — `borderStyle` carries `border`, `fillStyle` carries `fill`,
+         * `contentStyle` carries font / numberFormat / alignment / quotePrefix / named / insets.
+         * `CompositeRangedStyle` bag-merges the three; single-category consumers read just one.
+         * Public API should use IStyle.
+         */
+        borderStyle?: IProperties.ICellRanged<IStyle.Properties>;
+        fillStyle?: IProperties.ICellRanged<IStyle.Properties>;
+        contentStyle?: IProperties.ICellRanged<IStyle.Properties>;
+        /**
+         * The hyperlink.
+         */
+        hyperlink?: IHyperlink.Properties;
+        /**
+         * Directives for unlocking a range. (Only applies if the sheet is protected).
+         *
+         * @remarks
+         * * Overlaps are allowed — a cell may sit in several protected ranges, each with its own
+         *   password. **Any** of them being unlocked makes the cell editable, which is Excel's rule.
+         * * `updateTuples` only requests this type when the sheet IS locked and a protected range
+         *   intersects the write bounds, so in practice it is only populated then.
+         */
+        unlock?: IProtectedRange | IProtectedRange[];
+        /**
+         * Range contentful ranges.
+         *
+         * @remarks
+         * Used for selectRegion merge contentful checks and other aggregation counting.
+         * We are going to expand this for all of the aggregation counting.
+         */
+        contentful?: ContentfulSpatialValue;
+        /**
+         * Styles that have a continuous alignment.
+         *
+         * @remarks
+         * * These are just copies of directStyle for fast lookup.
+         * * A continuous alignment is an alignment that spans multiple horizontal cells.
+         */
+        continuous?: IProperties.ICellRanged<IStyle.Properties>;
+        /**
+         * The comments.
+         *
+         * @remarks
+         * A block of comments for the range.
+         */
+        comments?: IComment.Properties;
+        /**
+         * A block of R1C1 formulas.
+         */
+        formula?: IFormulaBlock;
+        /**
+         * Spills.
+         *
+         * @remarks
+         * There can be multiple spills on a cell but only one will be valid.
+         */
+        spills?: SpillEntry[];
+        /**
+         * The date format as a string
+         */
+        dateFormat?: string;
+        /**
+         * Pending calcs.
+         */
+        pending?: boolean;
+        /**
+         * Errors during calculation.
+         */
+        calcError?: string;
+        /**
+         * An error VALUE lives here (the `Error` scalar kind — from the reconciled error spatial).
+         */
+        error?: boolean;
+        /**
+         * Non overlapping data validation entries.
+         */
+        dataValidations?: IDataValidation | IDataValidation[];
+        /**
+         * Overlapping named ranges.
+         */
+        namedRange?: any[];
+        /**
+         * Used for injected layers.
+         */
+        [key: string]: any;
+    }
+    /**
+     * Range types are stored with a sheet range.
+     * @internal
+     */
+    const Type: {
+        readonly BorderStyle: "borderStyle";
+        readonly FillStyle: "fillStyle";
+        readonly ContentStyle: "contentStyle";
+        readonly Continuous: "continuous";
+        readonly DateFormat: "dateFormat";
+        readonly Table: "table";
+        readonly AutoTable: "autoTable";
+        readonly DataValidations: "dataValidations";
+        readonly Merge: "merge";
+        readonly Hyperlink: "hyperlink";
+        readonly Comments: "comments";
+        readonly Unlock: "unlock";
+        readonly Contentful: "contentful";
+        readonly Conditionals: "conditionals";
+        /**
+         * Has a formula
+         */
+        readonly Formula: "formula";
+        readonly Spills: "spills";
+        readonly Pending: "pending";
+        readonly CalcError: "calcError";
+        /**
+         * Error VALUES (the `Error` scalar kind). Backed by the RECONCILED view
+         * (`SheetReadContext.getErrorSpatial`), not `state.errorSpatial` directly — resolving it may
+         * lazily build (a value scan, cached per state version), so it is opt-in only: never part of
+         * {@link AllRangeTypes} / the all-types sweep.
+         */
+        readonly Error: "error";
+        readonly Validation: "dataValidation";
+    };
+    type Type = typeof Type[keyof typeof Type];
+}
+/**
+ * Public feature → internal state map — where `ICellRange.Feature` (the agent-facing read
+ * vocabulary) meets `RangeState.Type` (the engine's index keys).
+ *
+ * Deliberately not one-to-one, and `null` is meaningful:
+ * - `NumberFormat` / `Alignment` / `Font` all project from the `ContentStyle` map — a partition
+ *   refines only where the *projected* payload changes. The projection discriminator arrives
+ *   with the `getRegions` promotion; the shared backing is recorded here.
+ * - `null` = no backing index at all — nothing left in the public vocabulary hits this today.
+ *   `String`/`Number`/`Boolean` used to (scalar kinds count from values, not state); they were
+ *   retired from the vocabulary entirely rather than kept as a permanent `null` — a stats scan
+ *   already answers the same question, richer.
+ * - `DateFormat` and `Error` are both real, directly indexed state now — `DateFormat` off its own
+ *   spatial map (`dateFormatSpatial`, no longer internal-only), `Error` off the reconciled error
+ *   view. Neither needs the value-scan special-casing the old derived `Date` feature did.
+ *
+ * Internal-only members of `RangeState.Type` (`Pending`, `Continuous`, the legacy `Validation`
+ * alias) deliberately have no public feature.
+ */
+export declare const FeatureToRangeState: Readonly<Record<ICellRange.Feature, RangeState.Type | null>>;
+/**
+ * Translates a public `features` selection into the iterator's `SearchTypes`.
+ *
+ * `undefined` = everything (today's default). Every remaining feature has a direct state-map
+ * backing (see `FeatureToRangeState`) — there is no special-cased derived feature left to carry
+ * separately, the way the old `Date` used to need `DateFormat` pulled in as a scan-time carrier.
+ */
+export declare function featuresToSearchTypes(features?: ICellRange.Feature | readonly ICellRange.Feature[]): boolean | RangeState.SearchTypes;
+/**
+ * The CELL-iteration flavor of {@link featuresToSearchTypes} — mirrors what
+ * {@link CellStateRangeTypes} does for the `true` case:
+ * - `Contentful` is DROPPED: cell values ride the value grid, and carrying the contentful map
+ *   would put an intersection on every valued cell (the null-check optimization dies).
+ * - `Continuous` rides along with any content-style projection (it is the continuous-alignment
+ *   fast path — internal, so no public feature can name it).
+ * - `Pending` rides along with `Formula`/`CalcError` (calc status accompanies calc state).
+ */
+export declare function cellFeaturesToSearchTypes(features?: ICellRange.Feature | readonly ICellRange.Feature[]): boolean | RangeState.SearchTypes;
+/**
+ * The used extent a single public feature contributes — the `getUsedRange` counterpart to
+ * {@link FeatureToRangeState}.
+ *
+ * @remarks
+ * A separate mapping because a used extent is a bounding question, not a per-cell query: the
+ * style maps answer it with `getContentfulCoords()` (a full-width header row is not "used"),
+ * everything else with its bounding range. `null` = contributes nothing beyond the value grid,
+ * which the caller always includes — that covers `Error` and `Contentful`, which ride the values
+ * themselves.
+ * @internal
+ */
+export declare function featureToUsedCoords(state: State, feature: ICellRange.Feature): IRange.Coords | null;
+export declare const AllRangeTypes: RangeState.SearchTypes;
+export declare const CellStateRangeTypes: RangeState.SearchTypes;
+/**
+ * We don't want to copy TextOverflows.
+ * TODO - create a more generalize Type (Eager vs on demand.)
+ * @internal
+ */
+export declare const CopyRangeTypes: RangeState.SearchTypes;
+/**
+ * Used by merge redirect lookup.
+ * @internal
+ */
+export declare const NoMergeRangeTypes: RangeState.SearchTypes;
+/**
+ * Used by overlaps lookup
+ * @internal
+ */
+export declare const OverflowsRangeTypes: RangeState.SearchTypes;
+/**
+ * A movable's spatial entry (anchor + container callbacks + z-order).
+ * @internal
+ */
+export interface MovableEntry extends Anchored.Entry<IMovable> {
+    callbacks: Movable.ContainerCallbacks;
+    zIndex: number;
+}
+/** @internal */
+export interface ICellRangeListenerEntry {
+    id: number;
+    offset: number;
+    options: ICellRange.ListenerOptions;
+}
+/** @internal */
+export interface ICellRangesListenerEntry {
+    id: number;
+    /**
+     * We have to track the range because we can't use the node coords
+     * as shift/split can change the coords. and our range has fixed dimensions.
+     */
+    ranges: (Readonly<IRange.FixableCoords> | null)[];
+    handler: ICellRange.Listener | null;
+    handlerW: WeakRef<ICellRange.Listener> | null;
+    removeListener: IListener.Remove;
+    options: ICellRange.ListenerOptions;
+}
+/**
+ * The versioned per-sheet state record held in the transaction store (see `Sheet._getState`).
+ * A pure data record: sparse grids, spatial maps, and anchored maps. Behaviour lives beside it in
+ * the read/mutation modules, never on it (it is cloned/partial-merged by the store).
+ * @internal
+ */
+export interface State {
+    cellValuesGrid: ISparseGrid<Scalar>;
+    contentfulSpatial: ISpatialMap<ContentfulSpatialValue>;
+    calcGrid: ICalcGrid;
+    spillSpatial: ISpatialMap<SpillEntry>;
+    pendingSpatial: ISpatialMap<boolean>;
+    calcErrorsSpatial: ISpatialMap<string>;
+    /**
+     * Error VALUES (`#DIV/0!`, `#N/A`, …) — the `Error` scalar kind, NOT engine failures
+     * (those are {@link calcErrorsSpatial} / `CalcError`). Deliberately not per-type: `true`
+     * means "an error value lives here".
+     *
+     * WRITE-PATH ONLY (merge-on-READ): maintained on load, `updateTuples`, content clears and
+     * structural shifts — calc realize NEVER touches it, so it is STALE for formula cells after
+     * a recalc (a fixed formula stays flagged; a new computed error is absent). Do not query it
+     * directly — the reconciled, state-version-cached view (`Sheet._getErrorSpatialReconciled`)
+     * is the only reader. It becomes fully fresh (and the reconcile scan retires) when the calc
+     * executor emits error deltas for realize to apply, O(errors) like `calcErrorsSpatial`.
+     */
+    errorSpatial: ISpatialMap<boolean>;
+    borderSpatial: IUsedRangeSpatialMap<SheetDirectStyle>;
+    fillSpatial: IUsedRangeSpatialMap<SheetDirectStyle>;
+    contentSpatial: IUsedRangeSpatialMap<SheetDirectStyle>;
+    mergeSpatial: IUsedRangeSpatialMap<MergeEntry>;
+    continuousFillSpatial: ISpatialMap<SheetDirectStyle>;
+    dateFormatSpatial: ISpatialMap<string>;
+    hyperlinkSpatial: ISpatialMap<IHyperlink.Properties>;
+    commentsSpatial: ISpatialMap<IComment.Properties>;
+    movableSpatial: ISpatialMap<MovableEntry>;
+    movableMapModel: Map<IMovable, ISpatialMap.Entry<MovableEntry>>;
+    picture?: IPicture | null;
+    autoTables: IAnchoredMap<ITable, ITable.JSON>;
+    tables: IAnchoredMap<ITable, ITable.JSON>;
+    conditionalFormats: IAnchoredMap<IConditionalFormat, IConditionalFormat.JSON>;
+    dataValidations: IAnchoredMap<IDataValidation, IDataValidation.JSON>;
+    /**
+     * Ranges that stay editable while the sheet is protected ("Allow Edit Ranges").
+     *
+     * @remarks
+     * Read through `RangeState.Type.Unlock` — see {@link RangeState.Intersection.unlock}.
+     */
+    protectedRanges: IAnchoredMap<IProtectedRange, IProtectedRange.JSON>;
+    rangesListenerSpatial2: ISpatialMap<RangesListenerEntry>;
+    rangesListenerMap2: Map<string, RangesListener>;
+    rangeListenerSpatial: ISpatialMap<ICellRangeListenerEntry>;
+    rangesListenerMap: Map<number, ICellRangesListenerEntry>;
+    entireCoords: IRange.Coords;
+    deleted: boolean;
+}
+/**
+ * Tracks a range listener's before/after state for the undo stack when the change is not part of the
+ * transaction (non-transactional listeners).
+ * @internal
+ */
+export interface BeforeAfterRange {
+    beforeState: ICellRangesListenerEntry;
+    afterState: ICellRangesListenerEntry | null;
+}
+/**
+ * Internal flags threaded through the cell-update path (`updateTuples` / `createSparseBuilder`) to
+ * mark the origin of the update (a full cell paste, or a hyperlink display-text write).
+ * @internal
+ */
+export interface InternalTupleUpdate {
+    isCell?: boolean;
+    isHyperlink?: boolean;
+}
+//# sourceMappingURL=_SheetStateTypes.d.ts.map