@sheetxl/sdk 0.7.26 → 0.7.28-beta.1

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

@@ -0,0 +1,115 @@
+import { RangeAxis, AxisSelection, RangeCoords, RunCoordValue } from '@sheetxl/utils';
+import { ISpatialMap } from './ISpatialMap';
+/**
+ * Expands the range size in each direction.
+ */
+export declare function expandRange(range: RangeCoords, maxRange?: RangeCoords, colAmount?: number, rowAmount?: number): RangeCoords;
+/**
+ * Scope-agnostic coordinate equality. A 2D spatial map is single-scope; entries may
+ * inconsistently carry a `scope` so it must not participate in coordinate comparisons.
+ */
+export declare function isEqualCoords(a: RangeCoords, b: RangeCoords): boolean;
+/**
+ * Returns the original range split by the intersecting range.
+ *
+ * @param orig The original RangeCoordValue node.
+ * @param inter The intersecting range.
+ *
+ * @remarks
+ * * The last value is always the intersecting range.
+ * * 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;
+/**
+ * Create a set of non overlapping ranges from a set of existing ranges.
+ *
+ * * **IMPORTANT** - The original nodes also split during insertion.
+ *
+ * @remarks
+ * - The original entries are assume to already not have overlapping ranges but are not
+ *   required to be aligned.
+ * - Will create equal size rectangles to allow for intersecting.
+ * - Does not make an effort to return the fewest nodes possible.
+ * - Does not merge splits; use {@link removeOverlapsAndMerge} or {@link fastMerge}.
+ *
+ * The steps to do this are:
+ * 1. Splits original nodes by the insert node.
+ * 2. Splits the insert node by the split original nodes. (it may split into smaller nodes that the split originals)
+ * 3. Tries to intersect.
+ * 3.  a. the the intersect is not the same size then the original is too large so we split the original again
+ *        and intersect just the parts that match.
+
+ */
+export declare function convertToNonOverlappingRanges<T>(original: ISpatialMap.Entry<T>[], insert: ISpatialMap.Entry<T>, options: ISpatialMap.UpdateOptions<T>): ISpatialMap.Entry<T>[];
+/**
+ * Attempts to merge ranges that are guaranteed to not overlap. For overlapping ranges use {@link removeOverlapsAndMerge}.
+ *
+ *
+ * @defaultValue '2'.
+ *
+ * @remarks
+ * * Setting to '0' will remove overlaps but not attempt to merge.
+ * * Setting to '1' will remove overlaps in the initial axis.
+ * * Setting to '2' will remove most overlaps but may miss overlaps that resulted from the previous iterations.
+ * * Setting to 'Number.MAX_SAFE_INTEGER' will run until no more ranges can be merged.
+ */
+export declare function fastMerge(ranges: RangeCoords[], axis?: RangeAxis, iterations?: number, getMerge?: (from: [a: RangeCoords, b: RangeCoords], destination: RangeCoords, axis: RangeAxis) => RangeCoords | null | undefined, reuseArray?: [RangeCoords | null, RangeCoords | null]): RangeCoords[];
+/**
+ * Simplifies ranges that overlap and merges them.
+ *
+ * This algorithm will continue merging until no more merges can be made. For large data this can be slow
+ *
+ * Useful for operations like count where you don't want to double count selections.
+ *
+ * @remarks
+ * Scope-partitioned: only ranges on the same sheet can overlap or be adjacent to one another.
+ */
+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;
+/**
+ * If the two coords overlap in a way that would required them to be split.
+ *
+ * @param a The first coords.
+ * @param b The second coords.
+ *
+ * @remarks
+ * This can be used for a single direction.
+ */
+export declare function isSplitIntersect(a: RangeCoords, b: RangeCoords, selections?: AxisSelection): boolean;
+/**
+ * Default implementation for {@link RangeShiftProcessor}.
+ *
+ * @param optionsProcess RangeShiftOptions
+ * @param splitExpand Used to tell the ranges not to shift but instead to split when shifting.
+ * @returns Either new RangeNodes or null if the shifted resulted in a delete. (left/up more than size of before)
+ *
+ * @remarks
+ * * Will shift a range in a given direction.
+ * * 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;
+/**
+ * Use to remove spills.
+ *
+ * @param spatial
+ * @param range
+ * @param cloneOnUpdate
+ * @returns The original map or the cloned map if it removed any entries.
+ */
+export declare function removeTopLeftEntries<T = any>(spatial: ISpatialMap<T>, range: RangeCoords, cloneOnUpdate?: boolean): ISpatialMap<T>;
+/**
+ * Converts a set of RunCoords into a set of RangeCoords.
+ */
+export declare function rangeEntriesToRuns<T = any>(entries: ISpatialMap.Entry<T>[], isColumn: boolean, cull?: (entry: ISpatialMap.Entry<T>) => boolean): RunCoordValue<T>[];
+/**
+ * BFS traversal of the dependency graph in either direction.
+ * `visit` is called once per frontier range; returns the next set of ranges.
+ * Terminates when visit returns [] (input cells for dependents, non-formula
+ * cells for precedents) or when all reachable ranges have been visited.
+ * Cycles are broken by exact-key deduplication on the returned ranges.
+ */
+export declare function graphVisit(start: RangeCoords, visit: (coords: RangeCoords) => RangeCoords[]): RangeCoords[];
+//# sourceMappingURL=_SpatialUtils.d.ts.map

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

@@ -0,0 +1,21 @@
+export * from './IReadableList';
+export * from './IWritableList';
+export * from './ISparseList';
+export * from './ISortedMap';
+export * from './IGrid';
+export * from './ISparseGrid';
+export * from './ISpatialMap';
+export * from './ISpatialMap3D';
+export * as IteratorUtils from './IteratorUtils';
+export * from './ImmutableList';
+export * from './IList';
+export * from './OverlappingRangeIterator';
+export * from './SortedMap';
+export * from './SparseGrid';
+export * from './SparseList';
+export * from './SpatialMap';
+export * from './SpatialMap3D';
+export * from './BooleanList';
+export * from './Tuple';
+export * from './MixedTypedArrayList';
+//# sourceMappingURL=index.d.ts.map

package/types/src/color/Color.d.ts

@@ -0,0 +1,120 @@
+import { ColorSpace } from './ColorSpace';
+import { IColor } from './IColor';
+/**
+ * Prefix for the CSS custom properties used for system colors. {@link Color.toCSS} emits
+ * `var(${SYSTEM_COLOR_CSS_PREFIX}windowtext, …)` for bare system/auto colors, and hosts theme
+ * the grid by setting these variables. Shared so the renderer and the host lookup agree.
+ */
+export declare const SYSTEM_COLOR_CSS_PREFIX = "--sxl-sys-color-";
+/**
+ * Capabilities for working with {@link IColor | colors}.
+ *
+ * Advanced color customization and compatibility with CSS and Office color schemes.
+ *
+ * Key features include:
+ * - Accessing a collection of built-in colors (Named, Scheme, Index).
+ * - Creating customized colors with color adjustments.
+ * - Defining and and converting between different color models (RGB, HEX, HSL).
+ *
+ * @see
+ * {@link IColor}
+ */
+export declare class Color implements IColor {
+    private _private;
+    constructor(value: string | IColor | IColor.Definition, schemeLookup?: IColor.SchemeLookup | null, indexedLookup?: IColor.IndexedLookup | null, last?: ColorSpace.RGBA | null, systemLookup?: IColor.SystemLookup | null);
+    private _parse;
+    private _forceDark;
+    private _resolve;
+    /**
+     * @hidden
+     * TODO - Rationalize this. Do we want a constructor a static parse?
+     */
+    static parse(input: string | IColor, schemeLookup?: IColor.SchemeLookup | null, indexedLookup?: IColor.IndexedLookup | null, last?: ColorSpace.RGBA | null, systemLookup?: IColor.SystemLookup | null): IColor | null;
+    /**
+     * Returns `true` if the named color is a system color (e.g. `windowText`, `window`, `btnFace`).
+     *
+     * @remarks
+     * System colors are environment-dependent and are candidates for host theming
+     * (see {@link IColor.SystemLookup}). Non-system named colors (e.g. `red`) and
+     * `transparent` return `false`.
+     */
+    static isSystem(name: string): boolean;
+    /**
+     * Returns the global default {@link IColor.SystemLookup}, or `null` if system colors
+     * resolve to their built-in baked values.
+     */
+    static getDefaultSystemLookup(): IColor.SystemLookup | null;
+    /**
+     * Sets the global default {@link IColor.SystemLookup} used to resolve system colors
+     * (e.g. `windowText`, `window`) when no per-color lookup is supplied.
+     *
+     * @remarks
+     * A host (for example the VSCode extension) calls this once to theme the rendered grid.
+     * Passing `null` restores the built-in baked values. This bumps the system epoch so cached
+     * resolutions are refreshed.
+     * @param lookup The lookup to install, or `null` to clear.
+     * @returns The previous lookup.
+     */
+    static setDefaultSystemLookup(lookup: IColor.SystemLookup | null): IColor.SystemLookup | null;
+    /**
+     * The current system-color epoch. Consumers that cache resolved system colors (such as a
+     * document `Theme`) can compare against this to know when to re-resolve.
+     */
+    static getSystemEpoch(): number;
+    /**
+     * Invalidates cached system-color resolutions (call when the host theme changes but the
+     * lookup function itself stays the same, e.g. CSS variables were updated).
+     */
+    static invalidateSystemColors(): void;
+    /**
+     * Returns the built-in (baked) values for the system colors as a map of
+     * `${name}` (lower-case) -> `#RRGGBB`.
+     *
+     * @remarks
+     * These are the hardcoded system color definitions. A host renderer (`@sheetxl/react`) uses
+     * them to seed the default `--sxl-sys-color-*` CSS variables (which {@link Color.toCSS} references);
+     * a host then overrides those variables to theme the grid.
+     */
+    static getSystemColorDefaults(): Record<string, string>;
+    /**
+     * Returns the default color scheme lookup that Colors will use if none is provided.
+     */
+    static getDefaultSchemeLookup(): IColor.SchemeLookup;
+    /** {@inheritDoc IColor.isEqual} */
+    isEqual(other: any): boolean;
+    /** {@inheritDoc IColor.getVal} */
+    getVal(): string;
+    /** {@inheritDoc IColor.getAdjustments} */
+    getAdjustments(): readonly IColor.Adjustment[];
+    /** {@inheritDoc IColor.getBaseColor} */
+    getBaseColor(): IColor;
+    /** {@inheritDoc IColor.getLastColor} */
+    getLastColor(): string | null;
+    /** {@inheritDoc IColor.getType} */
+    getType(): IColor.Type;
+    /** {@inheritDoc IColor.adjust} */
+    adjust(adjustments: IColor.Adjustment[]): IColor;
+    /**
+     * Returns a CSS `var()` reference for a bare system/auto color, otherwise `null` (resolve
+     * concretely). `toCSS` always emits this for system/auto colors so the browser resolves them
+     * per-subtree (CSS scoping). The `var()` fallback is the static authored/baked value, so it is
+     * correct when the host variable is unset (or headless/SSR).
+     */
+    private _systemCSSVar;
+    /** {@inheritDoc IColor.toCSS} */
+    toCSS(mode?: IColor.CSSMode, alpha?: boolean): string;
+    /** {@inheritDoc IColor.toRGBA} */
+    toRGBA(darkMode?: boolean): IColor.ISpace.RGBA;
+    /** {@inheritDoc IColor.toHSLA} */
+    toHSLA(darkMode?: boolean): IColor.ISpace.HSLA;
+    /** {@inheritDoc IColor.toHex} */
+    toHex(darkMode?: boolean): IColor.ISpace.HEX;
+    /** {@inheritDoc IColor.toBlackOrWhite} */
+    toBlackOrWhite(darkMode?: boolean, threshold?: number): IColor;
+    get [Symbol.toStringTag](): string;
+    /** {@inheritDoc IColor.toString} */
+    toString(): string;
+    /** {@inheritDoc IColor.isIColor} */
+    get isIColor(): true;
+}
+//# sourceMappingURL=Color.d.ts.map

package/types/src/color/ColorSpace.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Color definitions available in various ColorSpaces.
+ */
+export declare namespace ColorSpace {
+    /**
+     * A color in the Red, Green, Blue color space.
+     */
+    class RGBA {
+        protected _private: {
+            red: number;
+            green: number;
+            blue: number;
+            alpha: number;
+        };
+        constructor(red: number, green: number, blue: number, alpha?: number);
+        get red(): number;
+        get green(): number;
+        get blue(): number;
+        get alpha(): number;
+        toString(alpha?: boolean): string;
+        isEqual(other: ColorSpace.RGBA): boolean;
+        isAlmostEqual(other: ColorSpace.RGBA): boolean;
+    }
+    /**
+     * A color in the Hue, Saturation, Luminosity color space.
+     */
+    class HSLA {
+        private _private;
+        constructor(hue: number, sat: number, lum: number, alpha: number);
+        get hue(): number;
+        get sat(): number;
+        get lum(): number;
+        get alpha(): number;
+        toString(alpha?: boolean): string;
+        isEqual(other: ColorSpace.HSLA): boolean;
+        isAlmostEqual(other: ColorSpace.HSLA): boolean;
+    }
+    /**
+     * A color (Red, Green, Blue) encoded in hexadecimal.
+     */
+    class HEX extends ColorSpace.RGBA {
+        toString(alpha?: boolean): string;
+    }
+}
+//# sourceMappingURL=ColorSpace.d.ts.map