@sheetxl/sdk 0.7.12 → 0.7.14

package/node/esm/{Dy616gUfJgTEn2Lk.mjs → myjs_Lwk8vlrSFNh.mjs}

@@ -1,5 +1,5 @@
 /**
- * @license @sheetxl/sdk - SDK - A high-performance, embeddable spreadsheet engine. - v0.7.12
+ * @license @sheetxl/sdk - SDK - A high-performance, embeddable spreadsheet engine. - v0.7.14
  *
  * (C) 2025-present SheetXL Inc. & Michael T. Ford
  * License: The license can be found at https://www.sheetxl.com/license.

package/node/esm/{CSrVbEwBx2NnAYvL.mjs → tO5paHU0QdSdv1Jc.mjs}

@@ -1,5 +1,5 @@
 /**
- * @license @sheetxl/sdk - SDK - A high-performance, embeddable spreadsheet engine. - v0.7.12
+ * @license @sheetxl/sdk - SDK - A high-performance, embeddable spreadsheet engine. - v0.7.14
  *
  * (C) 2025-present SheetXL Inc. & Michael T. Ford
  * License: The license can be found at https://www.sheetxl.com/license.

package/node/esm/{ClxQXzVr71QV--QR.mjs → yS3knP21QkdRIsvW.mjs}

@@ -1,5 +1,5 @@
 /**
- * @license @sheetxl/sdk - SDK - A high-performance, embeddable spreadsheet engine. - v0.7.12
+ * @license @sheetxl/sdk - SDK - A high-performance, embeddable spreadsheet engine. - v0.7.14
  *
  * (C) 2025-present SheetXL Inc. & Michael T. Ford
  * License: The license can be found at https://www.sheetxl.com/license.

package/node/esm/{CaxUhEKBf5-rWlgP.mjs → zY-nSDUmnavhQata.mjs}

@@ -1,5 +1,5 @@
 /**
- * @license @sheetxl/sdk - SDK - A high-performance, embeddable spreadsheet engine. - v0.7.12
+ * @license @sheetxl/sdk - SDK - A high-performance, embeddable spreadsheet engine. - v0.7.14
  *
  * (C) 2025-present SheetXL Inc. & Michael T. Ford
  * License: The license can be found at https://www.sheetxl.com/license.

package/{browser/esm/jAZwRNd8wzT9q-Kf.mjs → node/esm/zeLLXOAGHLwXQiRi.mjs}

@@ -1,5 +1,5 @@
 /**
- * @license @sheetxl/sdk - SDK - A high-performance, embeddable spreadsheet engine. - v0.7.12
+ * @license @sheetxl/sdk - SDK - A high-performance, embeddable spreadsheet engine. - v0.7.14
  *
  * (C) 2025-present SheetXL Inc. & Michael T. Ford
  * License: The license can be found at https://www.sheetxl.com/license.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sheetxl/sdk",
   "description": "SDK - A high-performance, embeddable spreadsheet engine.",
-  "version": "0.7.12",
+  "version": "0.7.14",
   "license": "SEE LICENSE IN <LICENSE>",
   "type": "module",
   "exports": {
@@ -43,9 +43,9 @@
     "automation"
   ],
   "dependencies": {
-    "@sheetxl/primitives": "^0.7.12",
-    "@sheetxl/scripting": "^0.7.12",
-    "@sheetxl/utils": "^0.7.12",
+    "@sheetxl/primitives": "^0.7.14",
+    "@sheetxl/scripting": "^0.7.14",
+    "@sheetxl/utils": "^0.7.14",
     "bahttext": "^2.3.0",
     "bessel": "^1.0.2",
     "chalk": "^5.6.2",

package/types/index.d.ts

@@ -1042,10 +1042,21 @@ declare const DateUnit: {
 
 declare type DateUnit = typeof DateUnit[keyof typeof DateUnit];
 
+export declare namespace DateUtils {
+    export {
+        nowWithPrecision
+    }
+}
+
 declare const deepCull: (value: any, _min: number, _max: number) => boolean;
 
 declare const deepUpdate: (prevValue: any | null, newValue: any | null) => any | null;
 
+/**
+ * A list of font sizes for showing in drop downs.
+ */
+declare const DefaultFontSizes: readonly number[];
+
 declare class DefaultProtection<T, P extends IProtection.Properties, J extends IProtection.JSON> implements IProtection<T, P, J> {
     protected _emitter: ListenerEmitter<this, IProtection.IListeners>;
     protected _isPaused: boolean;
@@ -1174,6 +1185,11 @@ declare const findIntersectMath: (p1: Point, p2: Point, min: number, max: number
     max: number;
 };
 
+/**
+ * Searches an array of numbers for the next value.
+ */
+declare const findNextFontSize: (size: number, increase?: boolean, steps?: readonly number[]) => number;
+
 /**
  * Looks for a run going in a certain direction. If there isn't a run for this it will look for the next
  * run. If you only want the run if it is found then use {@link findRun}.
@@ -1227,6 +1243,13 @@ declare interface FontHandle {
     loaded: boolean;
 }
 
+export declare namespace FontUtils {
+    export {
+        DefaultFontSizes,
+        findNextFontSize
+    }
+}
+
 declare class FormulaBlockEntry implements ISpatialMap.IUpdatableEntry<FormulaBlockEntry> {
     ref: IRange.Coords;
     formula: ICalcGraph.IFormulaBlock;
@@ -3975,29 +3998,41 @@ export declare interface ICellHeaderRange {
     /**
      * The RunCoords for the range.
      */
-    getCoords(): RunCoords;
+    getCoords(): ICellHeaderRange.Coords;
     /**
      * Iterate over cells headers.
+     *
      * @remarks
      * * Callbacks can return a 'break' value to stop the visit.
      */
     forEach<T = any>(callback: ICellHeaderRange.ForEachCallback<T>, options?: ICellHeaderRange.IteratorOptions): T | void;
     /**
      * Returns the header at a location relative to the range.
+     *
      * @param index
      */
     at(index: number): ICellHeader;
     /**
      * Set the size of the headers.
-     * @param size
+     *
+     * @param size This can be a number of a string with units
      * @param options {@link ICellHeaderRange.SetSizeOptions}
      */
     setSize(size?: number | string, options?: ICellHeaderRange.SetSizeOptions): this;
     /**
      * Hides or show the columns for the given range.
+     *
      * @defaultValue false
      */
     setHidden(hidden?: boolean): this;
+    /**
+     * Provides a convenient method for setting values with a range of calls.
+     *
+     * @remarks
+     * If an array is provided then values will be in row-major order and will
+     * repeat if the range is larger than the array
+     */
+    updateHeaders(values: ICellHeader.Update, options?: ICellHeaderRange.UpdateHeadersOptions): this;
     /**
      * Returns the data ranges for headers that contain information.
      *
@@ -4014,6 +4049,10 @@ export declare interface ICellHeaderRange {
      * Returns the number of headers included in the range.
      */
     getCount(): number;
+    /**
+     * Returns the number of headers.
+     */
+    getHeaderCount(): number;
     /**
      * Returns the number of visible headers in the range.
      */
@@ -4028,6 +4067,7 @@ export declare interface ICellHeaderRange {
     getOrientation(): IRange.Orientation;
     /**
      * Similar to {@link forEach} but only spans that are different.
+     *
      * @remarks
      * * Callbacks can return a 'break' value to stop the visit.
      */
@@ -4039,20 +4079,13 @@ export declare interface ICellHeaderRange {
      * * If there are no hidden headers this will still be called once.
      */
     forEachVisibleSpan<T = any>(callback: ICellHeaderRange.ForEachVisibleSpanCallback<T>, options?: ICellHeaderRange.ForEachVisibleSpanOptions): T | void;
-    /**
-     * Provides a convenient method for setting values with a range of calls.
-     *
-     * @remarks
-     * If an array is provided then values will be in row-major order and will
-     * repeat if the range is larger than the array
-     */
-    updateHeaders(values: ICellHeader.Update, options?: ICellHeaderRange.UpdateHeadersOptions): this;
     /**
      * {@inheritDoc ICellRange.getSnapshot}
      */
     getSnapshot(options?: ICellHeaderRange.CopyOptions): ICellHeaderRange.ISnapshot;
     /**
      * Perform operation on all ranges.
+     *
      * @see
      * {@link ICellRange.doBatch}
      */
@@ -4083,6 +4116,10 @@ export declare interface ICellHeaderRange {
  * {@link ICellHeaderRange}
  */
 export declare namespace ICellHeaderRange {
+    /**
+     * The coord type for a header range.
+     */
+    export type Coords = RunCoords;
     /**
      * Specify either a range a run or a string.
      * @remarks
@@ -4220,11 +4257,13 @@ export declare namespace ICellHeaderRange {
         relativeSize?: boolean;
         /**
          * If this is set to `true` then the value will not be an autoSize value.
+         *
          * @defaultValue false
          */
         autoSize?: boolean;
         /**
          * If this is set to `true` then any headers that have custom sizes will be ignored.
+         *
          * @defaultValue false
          */
         skipCustomSize?: boolean;
@@ -4269,6 +4308,109 @@ export declare namespace ICellHeaderRange {
     }
 }
 
+/**
+ * An `ICellHeaderRanges` is a collection of {@link ICellHeaderRange}s.
+ *
+ * Useful when working with a discontinuous set of headers.
+ */
+export declare interface ICellHeaderRanges {
+    /**
+     * The RunCoords for the range.
+     */
+    getCoords(): Readonly<ICellHeaderRanges.Coords>;
+    /**
+     * Returns the header range at a location relative to the range.
+     *
+     * @param index
+     */
+    at(index: number): ICellHeaderRange;
+    /**
+     * Returns the number of headers ranges.
+     */
+    getCount(): number;
+    /**
+     * {@inheritDoc ICellHeaderRange.setSize}
+     */
+    setSize(size?: number | string, options?: ICellHeaderRange.SetSizeOptions): this;
+    /**
+     * {@inheritDoc ICellHeaderRange.setHidden}
+     */
+    setHidden(hidden?: boolean): this;
+    /**
+     * {@inheritDoc ICellHeaderRange.clear}
+     */
+    clear(): this;
+    /**
+     * Returns the number of headers.
+     *
+     * @remarks
+     * This will remove overlaps.
+     */
+    getHeaderCount(): number;
+    /**
+     * {@inheritDoc ICellHeaderRange.getVisibleCount}
+     */
+    getVisibleCount(): number;
+    /**
+     * Returns true if all of the ranges cover the entire headers.
+     */
+    isEntireHeaders(): boolean;
+    /**
+     * Returns true if any of the ranges cover entire headers.
+     */
+    isEntireHeadersAny(): boolean;
+    /**
+     * {@inheritDoc ICellHeaderRange.getOrientation}
+     */
+    getOrientation(): IRange.Orientation;
+    /**
+     * {@inheritDoc ICellHeaderRange.updateHeaders}
+     */
+    updateHeaders(values: ICellHeader.Update, options?: ICellHeaderRange.UpdateHeadersOptions): this;
+    /**
+     * {@inheritDoc ICellHeaderRange.doBatch}
+     */
+    doBatch<R>(callback: (commit: ITransaction.ICommit) => R | Promise<R>, options?: string | ICellHeaderRange.UpdateHeadersOptions): R | Promise<R>;
+    /**
+     * {@inheritDoc ICellHeaderRange.getSheetHeader}
+     */
+    getSheetHeader<S>(): S;
+    /**
+     * {@inheritDoc ICellHeaderRange.getA1}
+     */
+    getA1(): string;
+    /**
+     * {@inheritDoc ICellHeaderRange.toString}
+     */
+    toString(): string;
+    /**
+     * For runtime type checking.
+     */
+    readonly isICellHeaderRanges: true;
+}
+
+/**
+ * {@inheritDoc ICellHeaderRanges}
+ * @see
+ * ### **Interface**
+ *
+ * {@link ICellHeaderRanges}
+ */
+export declare namespace ICellHeaderRanges {
+    /**
+     * The coord type for a header ranges.
+     */
+    export type Coords = RunCoords[];
+    /**
+     * Address for multiple {@link ICellHeaderRange}s.
+     */
+    export type Address = ICellHeaderRanges | string | ICellHeaderRange.Address | readonly ICellHeaderRange.Address[];
+    /**
+     * Shorthand for persisting.
+     */
+    export type RefJSON = RunCoords[] | RunCoords | string;
+}
+
 /**
  * Additional cell protection properties.
  *
@@ -6009,6 +6151,14 @@ export declare interface ICellRanges {
      * {@inheritDoc ICellRange.getEntireColumns}
      */
     getEntireColumns(shiftRows?: boolean, options?: ICellRange.GetRangeOptions): this;
+    /**
+     * {@inheritDoc ICellRange.getRowHeaders}
+     */
+    getRowHeaders(options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRanges;
+    /**
+     * {@inheritDoc ICellRange.getColumnHeaders}
+     */
+    getColumnHeaders(options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRanges;
     /**
      * {@inheritDoc ICellRange.getDefaultShiftOrientation}
      */
@@ -6121,15 +6271,6 @@ export declare interface ICellRanges {
      * The RangeCoords.
      */
     getCoords(): readonly Readonly<IRange.FixableCoords>[];
-    /**
-     * Returns the total number of contiguous ranges in this collection.
-     */
-    getCount(): number;
-    /**
-     * Returns the range at a specific index.
-     * @param index
-     */
-    at(index: number): ICellRange;
     /**
      * Returns true if the range is invalid.
      * This can occur if a range is removed or created with invalid coordinates.
@@ -11219,6 +11360,14 @@ export declare interface IRangeSelection {
      * @returns The selection coordinates.
      */
     getCoords(): IRangeSelection.Coords;
+    /**
+     * Returns the selection as an array of IRange.Coords.
+     *
+     * @param coords Optional coordinates to convert. If not provided, uses the current selection.
+     * @remarks
+     * The first element is always the active range.
+     */
+    getRangesCoords(coord?: Partial<IRangeSelection.Coords>): IRange.Coords[];
     /**
      * Updates the selection coordinates.
      * @param coords The new coordinates.
@@ -12479,17 +12628,41 @@ export declare namespace ISheetCollection {
  * allowing for actions such as inserting, deleting, resizing, and applying formatting changes.
  */
 export declare interface ISheetHeader extends ITransaction.ITransactional, IListener.ISource<ISheetHeader> {
+    /**
+     * Returns the header at a given offset. Will only return null for invalid header offset. To get a list of headers use {@link getRange}.
+     *
+     * @param index 0-based absolute index.
+     */
+    at(index: number): ICellHeader;
+    /**
+     * Returns a displayable title for the given index.
+     * @param index 0-based absolute index.
+     */
+    getTextAt(index: number): string;
     /**
      * Returns a range of cells for the specified range.
      *
+     * @param address The address or addresses of the header range to retrieve.
+     * @param options Options for retrieving the header ranges.
      * @see
      * {@link ICellHeaderRange}
      */
     getRange(address: ICellHeaderRange.Address, options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRange;
     /**
-     * Returns the actives that are used in the selection.
+     * Returns a collection of header ranges for the specified ranges.
+     *
+     * @param address The address or addresses of the header ranges to retrieve.
+     * @param options Options for retrieving the header ranges.
+     */
+    getRanges(address: ICellHeaderRanges.Address, options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRanges;
+    /**
+     * Returns the active header range that is used in the selection.
      */
     getSelectedRange(options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRange;
+    /**
+     * Returns the active header ranges that are used in the selection.
+     */
+    getSelectedRanges(options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRanges;
     /**
      * Returns the data ranges for headers that contain information.
      *
@@ -12508,46 +12681,6 @@ export declare interface ISheetHeader extends ITransaction.ITransactional, IList
      * The orientation the headers manage.
      */
     getOrientation(): IRange.Orientation;
-    /**
-     * @see
-     * {@link ICellHeaderRange.setSize}
-     */
-    setSize(address: ICellHeaderRange.Address | readonly ICellHeaderRange.Address[], size?: number | string, options?: ICellHeaderRange.SetSizeOptions): this;
-    /**
-     * @see
-     * {@link ICellHeaderRange.setHidden}
-     */
-    setHidden(address: ICellHeaderRange.Address | readonly ICellHeaderRange.Address[], hidden?: boolean): this;
-    /**
-     * Bulk update api.
-     * @remarks
-     * This only supports one range at a time but offers a few flavors
-     * * update(5, { size: '100px' }); // 0-based index
-     * * update({ min: 3, max: 4 }, { size: '100px' }); // 0-based index
-     * * update('e:f', { size: '100px' }); // 1-based a1 style
-     * * update({ colStart: 3, colEnd: 4 }, { size: '100px' }); // 0-based index
-     * * update('5:7', { size: '100px' }); // 1-based a1 style
-     * * update({ rowStart: 3, rowEnd: 4 }, { size: '100px' }); // 0-based index
-     */
-    update(address: ICellHeaderRange.Address | readonly ICellHeaderRange.Address[], update: ICellHeader.Update, options?: ICellHeaderRange.UpdateHeadersOptions): this;
-    /**
-     * Sets the headers. This supports setting values as a batch.
-     * @remarks
-     * When setting headers the cells references by this sheet will not update.
-     * To ensure they are updated on the sheet call updateHeaderPairs with the range from the header.
-     */
-    updateHeaderPairs(pairs: ICellHeaderRange.AddressUpdatePair[], options?: ICellHeaderRange.UpdateHeadersOptions): RunCoords[] | null;
-    /**
-     * Returns the header at a given offset. Will only return null for invalid header offset. To get a list of headers use {@link getRange}.
-     *
-     * @param index 0-based absolute index.
-     */
-    at(index: number): ICellHeader;
-    /**
-     * Returns a displayable title for the given index.
-     * @param index 0-based absolute index.
-     */
-    getTextAt(index: number): string;
     /**
      * Returns a flag indicating if the headers are protected by the sheet.
      */
@@ -12630,6 +12763,14 @@ export declare interface ISheetHeader extends ITransaction.ITransactional, IList
      * Returns a list of SelectedRuns.
      */
     getSelectedRuns(): readonly ITypes.RunCoordValue<ISheetHeader.SelectedRun>[];
+    /**
+     * Sets the headers. This supports setting values as a batch.
+     *
+     * @remarks
+     * When setting headers the cells references by this sheet will not update.
+     * To ensure they are updated on the sheet call updateHeaderPairs with the range from the header.
+     */
+    updateHeaderPairs(pairs: ICellHeaderRange.AddressUpdatePair[], options?: ICellHeaderRange.UpdateHeadersOptions): RunCoords[] | null;
     /**
      * Returns the sheet model used for the header.
      */
@@ -13275,7 +13416,7 @@ export declare namespace ISort {
     export interface DefaultSortCriteria {
         /**
          * The cords that will be sorted.
-         * This may ignore the header.
+         * This will include headers even if the are ignored.
          */
         coords: IRange.Coords;
         /**
@@ -13289,6 +13430,10 @@ export declare namespace ISort {
          * If no headers are found this will be empty.
          */
         headers: Map<number, string>;
+        /**
+         * The coords without any headers.
+         */
+        sortCoords: IRange.Coords;
     }
     /**
      * Extends sort options to include options for sorting a range.
@@ -17970,6 +18115,14 @@ declare interface NotifyOptions<T = any> {
     transactional?: boolean;
 }
 
+/**
+ * Returns Date.now() rounded to a nearest time.
+ *
+ * @param precision The precision of time. Set to 1 if exact.
+ * @defaultValue The nearest minute.
+ */
+declare const nowWithPrecision: (precision?: number) => Date;
+
 /**
  * Capabilities for defining and applying number formats to cells.
  *
@@ -18221,6 +18374,8 @@ declare interface ParsedRuns {
 
 /* Excluded from this release type: parseHeaderRangeAddress */
 
+/* Excluded from this release type: parseHeaderRangesAddress */
+
 /**
  * Options for parsing a NumberFormat.
  */
@@ -18509,6 +18664,11 @@ declare type RangeToString<R extends IRange.Coords = IRange.Coords, C extends IR
  */
 declare const rangeUnionFromSelection: (selection: IRangeSelection.Coords) => IRange.Coords;
 
+/**
+ * Returns a list of merged and non-overlapping run coordinates.
+ */
+declare const removeOverlappingRuns: (runs: readonly Readonly<Partial<RunCoords>>[], merge?: boolean) => RunCoords[];
+
 export declare class Resource implements IResource {
     private _name;
     private _refs;
@@ -18561,6 +18721,11 @@ export declare class ResourceCollection implements IResourceCollection {
  */
 declare const rotatePoints: (points: Point[], deg: number, center?: Point) => Point[];
 
+/**
+ * Converts a set of RunCoords into a set of Ranges.
+ */
+declare const runCoordsToRangeCoords: (runs: readonly Readonly<Partial<RunCoords>>[], entireRange: IRange.Coords, isColumn: boolean) => Partial<IRange.FixableCoords>[];
+
 /**
  * Use for tracking the accumulated sizes from the beginning of the headers.
  * @remarks
@@ -19057,8 +19222,12 @@ declare class SheetHeader implements ISheetHeader {
     } | void;
     /** {@inheritDoc ISheetHeader.getRange} */
     getRange(address: ICellHeaderRange.Address, options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRange;
+    /** {@inheritDoc ISheetHeader.getRanges} */
+    getRanges(address: ICellHeaderRanges.Address, options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRanges;
     /** {@inheritDoc ISheetHeader.getSelectedRange} */
     getSelectedRange(options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRange;
+    /** {@inheritDoc ISheetHeader.getSelectedRanges} */
+    getSelectedRanges(options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRanges;
     /** {@inheritDoc ISheetHeader.getUsedRange} */
     getUsedRange(options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRange;
     /** {@inheritDoc ISheetHeader.getEntireRange} */
@@ -19068,9 +19237,9 @@ declare class SheetHeader implements ISheetHeader {
     /** {@inheritDoc ISheetHeader.updateHeaderPairs} */
     updateHeaderPairs(pairs: ICellHeaderRange.AddressUpdatePair[], options?: ICellHeaderRange.UpdateHeadersOptions): RunCoords[] | null;
     protected _parseHeaderRangeAddress(address: ICellHeaderRange.Address): RunCoords;
-    update(addresses: ICellHeaderRange.Address | ICellHeaderRange.Address[], update: ICellHeader.Update, options?: ICellHeaderRange.UpdateHeadersOptions): this;
-    setSize(address: ICellHeaderRange.Address | ICellHeaderRange.Address[], size?: number | string, options?: ICellHeaderRange.SetSizeOptions): this;
-    setHidden(address: ICellHeaderRange.Address | ICellHeaderRange.Address[], hidden?: boolean): this;
+    protected _update(addresses: ICellHeaderRange.Address | ICellHeaderRange.Address[], update: ICellHeader.Update, options?: ICellHeaderRange.UpdateHeadersOptions): this;
+    protected _setSize(address: ICellHeaderRange.Address | ICellHeaderRange.Address[], size?: number | string, options?: ICellHeaderRange.SetSizeOptions): this;
+    protected _setHidden(address: ICellHeaderRange.Address | ICellHeaderRange.Address[], hidden?: boolean): this;
     protected _clear(coords: RunCoords, options?: ICellHeaderRange.UpdateHeadersOptions): void;
     protected _getSnapshot(coordsFrom?: RunCoords, optionsMark?: ICellHeaderRange.CopyOptions): ICellHeaderRange.ISnapshot;
     /** {@inheritDoc ISheetHeader.isProtected} */
@@ -20834,7 +21003,9 @@ declare namespace _Utils {
         findRunningHiddenRuns,
         findRunningSpanLength,
         rangeUnionFromSelection,
-        createRunsFromSelection
+        createRunsFromSelection,
+        runCoordsToRangeCoords,
+        removeOverlappingRuns
     }
 }