@sheetxl/sdk 0.7.27 → 0.7.28-beta.1

package/types/src/utils/GeomUtils.d.ts

@@ -0,0 +1,61 @@
+import { Point, Size, Bounds } from '@sheetxl/utils';
+/**
+ * Return the union of to 2 bounds.
+ *
+ * @param a The first bounds.
+ * @param b The second bounds.
+ *
+ * @remarks
+ * Not null same.
+ */
+export declare function unionBounds(a: Bounds, b: Bounds): Bounds;
+/**
+ * Return the absolute center of the bounds.
+ *
+ * @param bounds The bounds to calculate the center for.
+ * @returns The center point of the bounds.
+ */
+export declare function centerPoint(bounds: Bounds): Point;
+/**
+ * Points are return tl, tr, br, bl
+ *
+ * @param bounds {@link Bounds}
+ * @returns A array of points [tl, tr, br, bl]
+ */
+export declare function boundsToPoints(bounds: Bounds): Point[];
+/**
+ * Returns the minimum bounds for all the containing points.
+ *
+ * @param points The array of points to calculate the bounds for.
+ * @returns The minimum bounds containing all points.
+ */
+export declare function minBoundingRect(points: readonly Point[]): Bounds;
+/**
+ * Rotate all points around a center point.
+ *
+ * @param points The array of points to rotate.
+ * @param deg The rotation angle in degrees.
+ * @param center The center point to rotate around. If not provided, the center of the bounding box of the points is used.
+ * @returns An array of rotated points [tl, tr, br, bl].
+ */
+export declare function rotatePoints(points: Point[], deg: number, center?: Point): Point[];
+/**
+ * Computes the largest unrotated size for an inner rectangle such that, when rotated by
+ * `rotation` degrees about its own centre, it fits entirely within the outer rectangle.
+ *
+ * The algorithm centres `dimInner` inside `dimOuter`, rotates the inner rectangle, then
+ * clips its edges against the four sides of the outer rectangle using line–line intersection.
+ * The clipped points are un-rotated and their axis-aligned bounding box is returned.
+ *
+ * Axis-aligned special cases (0°, 90°, 180°, 270°) are handled analytically and do not
+ * go through the intersection path.
+ *
+ * @param dimInner The width and height of the inner rectangle before rotation.
+ * @param dimOuter The width and height of the bounding outer rectangle (unrotated).
+ * @param rotation Clockwise rotation angle in degrees to apply to the inner rectangle.
+ *   Negative values are normalized to the [0, 360) range. Defaults to `0`.
+ * @returns The unrotated `Size` (width × height) of the inner rectangle after it has been
+ *   clipped to fit within `dimOuter` at the given rotation.
+ */
+export declare function clipToOuterRect(dimInner: Size, dimOuter: Size, rotation?: number): Size;
+//# sourceMappingURL=GeomUtils.d.ts.map

package/types/src/utils/ObjectPath.d.ts

@@ -0,0 +1,9 @@
+declare class ObjectPath {
+    parse(str: string): string[];
+    stringify(arr: string[], quote: string, forceQuote: boolean): string;
+    normalize(data: string, quote: string, forceQuote: boolean): string;
+    simpleString(arr: string[], finalPart: boolean): string;
+}
+declare const DEFAULT_OBJECT_PATH: ObjectPath;
+export default DEFAULT_OBJECT_PATH;
+//# sourceMappingURL=ObjectPath.d.ts.map

package/types/src/utils/Profiler.d.ts

@@ -0,0 +1,38 @@
+/**
+ * A utility class for detailed performance profiling with support for nested operations.
+ */
+export declare class Profiler {
+    private static _enabled;
+    private static _data;
+    private static _stack;
+    /**
+     * Enables or disables the profiler.
+     */
+    static setEnabled(enabled: boolean): void;
+    /**
+     * Starts timing an operation.
+     * @param name The name of the operation
+     */
+    static start(name: string): void;
+    /**
+     * Ends timing the current operation and records the results.
+     */
+    static end(): void;
+    /**
+     * Gets the current profiling data.
+     */
+    static getData(): Record<string, {
+        count: number;
+        time: number;
+        children: Record<string, number>;
+    }>;
+    /**
+     * Resets all profiling data.
+     */
+    static reset(): void;
+    /**
+     * Prints a formatted report of the profiling data.
+     */
+    static report(): void;
+}
+//# sourceMappingURL=Profiler.d.ts.map

package/types/src/utils/_CSSUtils.d.ts

@@ -0,0 +1,156 @@
+import { TextDecoration as CSSTextDecoration } from 'csstype';
+import { Size } from '@sheetxl/utils';
+import { IColor } from '../color';
+import { IFill } from '../fill';
+import { IFont } from '../font';
+import { ITextFrame } from '../text';
+import { IBorder } from '../border';
+export interface ParsedFont {
+    family: string | null;
+    size?: string | null;
+    fallbacks?: string[] | null;
+}
+export declare function fromMsoRotate(value: number | string): number;
+export declare function toMsoRotate(value: number): number;
+export declare function parseFont(value: string): ParsedFont | null;
+export declare function toRGB(color: IColor, darkMode?: boolean): string;
+export declare function toHex(color: IColor, darkMode?: boolean): string;
+/** Baked modes keep the historical hex output; `'adaptive'` defers to `IColor.toCSS` (`light-dark()`). */
+export declare function toCSSColor(color: IColor, mode?: IColor.CSSMode): string;
+export declare function toCSSFontSize(size: number | null | undefined): string | null;
+export declare function toCSSTextDecoration(underline: IFont.UnderlineStyle | boolean, strike: boolean): CSSTextDecoration;
+export declare function toCSSTextUnderlineStyle(underline: IFont.UnderlineStyle): string;
+export declare const noDecoration: Readonly<{
+    underline: "none";
+    strike: false;
+}>;
+export declare function parseCSSTextDecoration(decoration: string): {
+    underline: IFont.UnderlineStyle;
+    strike: boolean;
+};
+export declare function parseCSSTextUnderlineStyle(underline: string): IFont.UnderlineStyle;
+/**
+ * Not this does not support super and sub. This are in
+ * @param align {@link ITextFrame.VerticalAlignment}
+ * @returns A css string for 'vertical-align'.
+ */
+export declare function toCSSVerticalAlign(align: ITextFrame.VerticalAlignment): string | null;
+export declare function toCSSWhiteSpace(overflow: ITextFrame.Overflow): string | null | undefined;
+export declare function toCSSFontFamily(fontFamily: string, fallbacks: string[]): string;
+export declare function toCSSNumberFormat(numberFormat: string): string;
+export declare function unicodeToChar(text: string): string;
+export declare function charToUnicode(text: string): string;
+/**
+ * @see
+ * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight}
+ */
+export declare const FontWeightClass: {
+    readonly Thin: "Thin";
+    readonly Hairline: "Hairline";
+    readonly ExtraLight: "Extra Light";
+    readonly UltraLight: "Ultra Light";
+    readonly Light: "Light";
+    readonly Normal: "Normal";
+    readonly Regular: "Regular";
+    readonly Medium: "Medium";
+    readonly SemiBold: "Semi Bold";
+    readonly DemiBold: "Demi Bold";
+    readonly Bold: "Bold";
+    readonly ExtraBold: "Extra Bold";
+    readonly UltraBold: "Ultra Bold";
+    readonly Black: "Black";
+    readonly Heavy: "Heavy";
+    readonly ExtraBlack: "Extra Black";
+    readonly UltraBlack: "Ultra Black";
+};
+export type FontWeightClass = typeof FontWeightClass[keyof typeof FontWeightClass];
+/**
+ * @see
+ * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight}
+ */
+export declare const FontWeightNamed: {
+    readonly Lighter: "lighter";
+    readonly Normal: "normal";
+    readonly Bold: "bold";
+    readonly Bolder: "bolder";
+};
+export type FontWeightNamed = typeof FontWeightNamed[keyof typeof FontWeightNamed];
+/**
+ * Returns as numbered weight
+ * https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight
+ * @param value
+ */
+export declare function parseFontWeight(value: string | number): number;
+/**
+ * @see
+ * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight}
+ */
+export declare const FontSizeClass: {
+    readonly XXSmall: "xx-small";
+    readonly XSmal: "x-small";
+    readonly Small: "small";
+    readonly Medium: "medium";
+    readonly Large: "large";
+    readonly XLarge: "x-large";
+    readonly XXLarge: "xx-large";
+    readonly XXXLarge: "xxx-large";
+    readonly Smaller: "smaller";
+    readonly Larger: "larger";
+    readonly Math: "math";
+};
+export type FontSizeClass = typeof FontSizeClass[keyof typeof FontSizeClass];
+export declare function parseFontSize(value: string, normalSize?: number, defaultUnit?: string): number | null;
+/**
+ * Looks for a color and then a supported pattern stye.
+ *
+ * @param value
+ * @returns A `IFill.PatternProperties`.
+ */
+export declare function parsePattern(value: string): Partial<IFill.PatternProperties> | null;
+/**
+ * Create a css compatible gradient string from the gradient fill.
+ *
+ * @param gradientFill The gradient fill
+ * @param mode The color rendering mode (see {@link IColor.CSSMode}); `'adaptive'` stops nest
+ * `light-dark()` inside the gradient string.
+ * @param size The size of the area being filled (needed for angle skewing)
+ * @returns A css gradient string
+ */
+export declare const toCSSGradient: (gradientFill: IFill.IGradient, mode?: IColor.CSSMode, size?: Size | null) => string | null;
+export declare function toCSSPattern(patternType: IFill.BuiltInSheetPattern): string;
+export declare function toCSSBorderStroke(stroke: IBorder.IStroke): string | null;
+export declare function parseBorderStroke(value: string, parseColor?: (str: string) => string): IBorder.StrokeProperties | null;
+/**
+ * @see
+ * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/text-align}
+ */
+export declare const TextAlignClass: {
+    readonly Start: "start";
+    readonly End: "end";
+    readonly Left: "left";
+    readonly Right: "right";
+    readonly Center: "center";
+    readonly Justify: "justify";
+    readonly JustifyAll: "justify-all";
+    readonly MatchParent: "match-parent";
+};
+export type TextAlignClass = typeof TextAlignClass[keyof typeof TextAlignClass];
+/**
+ * @see
+ * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/vertical-align}
+ */
+export declare const VerticalAlignClass: {
+    readonly Baseline: "baseline";
+    readonly Top: "top";
+    readonly Middle: "middle";
+    readonly Bottom: "bottom";
+    readonly Sub: "sub";
+    readonly Super: "super";
+    readonly TextTop: "text-top";
+    readonly Justify: "justify";
+    readonly Distributed: "distributed";
+};
+export type VerticalAlignClass = typeof VerticalAlignClass[keyof typeof VerticalAlignClass];
+export declare function parseCSSTextAlign(value: string): ITextFrame.HorizontalAlignment | null;
+export declare const parseCSSVerticalAlign: (value: string) => ITextFrame.VerticalAlignment | null;
+//# sourceMappingURL=_CSSUtils.d.ts.map

package/types/src/utils/_GeomUtils.d.ts

@@ -0,0 +1,14 @@
+import { Bounds } from '@sheetxl/utils';
+/**
+ * Rotate a bound by a given degree using the center as the origin.
+ */
+export declare function rotateBounds(bounds: Bounds, deg: number): Bounds;
+/**
+ * Adapted from https://medium.com/@sahirnambiar/linear-least-squares-a-javascript-implementation-and-a-definitional-question-e3fba55a6d4b
+ * @internal @hidden
+ */
+export declare function leastSquaresSlopeAndIntercept(values: readonly number[]): {
+    m: number;
+    b: number;
+};
+//# sourceMappingURL=_GeomUtils.d.ts.map

package/types/src/utils/_RangeCoordUtils.d.ts

@@ -0,0 +1,84 @@
+import { IRange } from '@sheetxl/primitives';
+/**
+ * This is a more advanced use case of ranges that takes an array of ranges and uses an r-tree algo to
+ * determine if the ranges intersects.
+ *
+ * @param ranges The array of ranges to check for intersections.
+ * @returns A flag indicating if any of the ranges intersect.
+ */
+export declare function rangesArrayIntersect(ranges: readonly IRange.Coords[]): boolean;
+/**
+ * converts a list of values into a 2D array.
+ *
+ * @param values The values to convert.
+ * @param width The width of the 2D array.
+ * @param onVisit An optional callback to modify values as they are visited.
+ */
+export declare function build2DArray<T>(values: T[], width: number, onVisit?: (val: T) => T): T[][];
+/**
+ * Returns true if the outer span encloses the inner span.
+ *
+ * @remarks
+ * Assumes isSplitSpan is false
+ */
+export declare function isWithinSpan(outerStart: number, outerEnd: number, innerStart: number, innerEnd: number): boolean;
+/**
+ * Returns true if the range intersections in an axis.
+ */
+export declare function isSplitRangeSpan(outerRange: IRange.Coords, innerRange: IRange.Coords, isColumn: boolean): boolean;
+/**
+ * Subtract Range b from from a.
+ *
+ * @param range The range.
+ * @param rangeToRemove The range to remove
+ * @param axis Determines the priority of the ranges
+ *
+ * @remarks
+ * Will always return either 0 - 4 ranges.
+ * * If no interaction then b will be returned.
+ * * If beforeSplit === rangeToRemove then empty array is returned.
+ */
+export declare function subtractRange(beforeSplit: IRange.Coords, rangeToRemove: IRange.Coords, axis?: IRange.Axis): IRange.Coords[];
+/**
+ * Visit ranges looking to see if range intersects. If so then onOverlap will be called.
+ *
+ * @param ranges The array of ranges to check against.
+ * @param range The range to check for intersections.
+ * @param onOverlap callback to call when overlap is found.
+ */
+export declare function visitRangeIntersects(ranges: IRange.Coords[], range: IRange.Coords, onOverlap: (range: IRange.Coords, isSplit: boolean, index: number) => void): void;
+/**
+ * Returns a CellCoords that is the top left.
+ *
+ * @param range A RangeCoord to check.
+ */
+export declare function topLeft(range: IRange.Coords | undefined): IRange.CellCoords | null;
+export declare function createColOffsetComparator(aRange: IRange.Coords, bRange: IRange.Coords): (a: IRange.CellCoords, b: IRange.CellCoords) => number;
+export declare function createRowOffsetComparator(aRange: IRange.Coords, bRange: IRange.Coords): (a: IRange.CellCoords, b: IRange.CellCoords) => number;
+/**
+ * Resolves the effective destination `Coords` when copying a source range into a target area.
+ *
+ * The result is always anchored at `dest.colStart / dest.rowStart`. The width and height
+ * are determined as follows:
+ *
+ * - **`fit = false` (default — tiling mode)**: the result expands to fill the full `dest`
+ *   only when `dest` is an integer multiple of the source in *both* dimensions (even tiling).
+ *   Otherwise the result is sized to the source dimensions (i.e. a single copy at the top-left
+ *   of `dest`).
+ * - **`fit = true`**: tiling is skipped. If `dest` is a single cell the result is sized to the
+ *   source; if `dest` is multi-cell the result is clipped/padded to the `dest` dimensions.
+ *
+ * @param dest Target area that supplies the top-left anchor (and, in tiling mode, the
+ *   candidate extent to fill).
+ * @param size Source range whose dimensions drive the output size. Defaults to `dest` when
+ *   `null`/`undefined`.
+ * @param fit When `true`, return the source-sized result without attempting tiling expansion.
+ *   Defaults to `false`.
+ * @param transpose When `true`, swap the row and column dimensions of the source before
+ *   computing the output. Defaults to `false`.
+ * @returns The resolved `Coords` for the destination.
+ */
+export declare function fitCoordsTo(dest: IRange.Coords, // destination (for top, left)
+size: IRange.Coords, // source (for sizing)
+fit?: boolean, transpose?: boolean): IRange.Coords;
+//# sourceMappingURL=_RangeCoordUtils.d.ts.map

package/types/src/utils/_RangeSetUtils.d.ts

@@ -0,0 +1,55 @@
+import { IRange } from '@sheetxl/primitives';
+type RangeCoords = IRange.Coords;
+/**
+ * Subtracts `subtract` from `range`, returning the remaining parts.
+ *
+ * @param range The range to subtract from.
+ * @param subtract The range to remove. `null` safe.
+ * @returns The remaining parts of `range` as 0-4 new ranges: an empty array when `subtract`
+ * covers `range` entirely, and a single copy of `range` when they do not intersect.
+ *
+ * @remarks
+ * Bands rows first: full-width strips above and below `subtract`, then pinched strips to its
+ * left and right.
+ */
+export declare function subtractRange(range: RangeCoords, subtract: RangeCoords | null): RangeCoords[];
+/**
+ * Subtracts every range in `subtract` from every range in `ranges`.
+ *
+ * @param ranges The ranges to subtract from.
+ * @param subtract The ranges to remove.
+ * @returns The remaining parts as new ranges. May be empty; never the input objects.
+ */
+export declare function subtractRangeArrays(ranges: readonly RangeCoords[], subtract: readonly RangeCoords[]): RangeCoords[];
+/**
+ * Adds `added` to `ranges`, merging into larger rectangles wherever the union is exact.
+ *
+ * @param ranges The ranges already held.
+ * @param added The ranges to add.
+ * @returns New ranges covering exactly the cells of `ranges` plus `added`, with `ranges`
+ * first and in their original order.
+ *
+ * @remarks
+ * Two rules keep this safe to run over authored data (anchored models never auto-merge —
+ * see `AnchoredMap`):
+ * - Added cells already covered are dropped, so re-adding is a no-op and nothing
+ *   double-covers.
+ * - Only merges involving added cells — directly, or transitively through an earlier
+ *   merge — occur. Pre-existing ranges that merely touch stay separate, but an added range
+ *   bridging two of them fuses all three.
+ *
+ * The first range's coordinates may grow; callers anchoring anything to the first range's
+ * top-left (conditional format formulas) must compare it before and after.
+ *
+ * Neither of those rules is what `_SpatialUtils.fastMerge` does: it needs input already free
+ * of overlaps, fuses every adjacent pair it can, and re-emits the set from a sweep — which
+ * would both dissolve the authored fragmentation and lose the held ranges' identity and
+ * order, and with it the anchor above.
+ *
+ * Small inputs run a plain pairwise scan. Larger ones — a striped fill or paste down a full
+ * column hands this hundreds of thousands of ranges — index by row band instead, keeping
+ * both the "already covered?" pass and the merge pass near-linear rather than quadratic.
+ */
+export declare function coalesceRangeArrays(ranges: readonly RangeCoords[], added: readonly RangeCoords[]): RangeCoords[];
+export {};
+//# sourceMappingURL=_RangeSetUtils.d.ts.map

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

@@ -0,0 +1,2 @@
+export * as GeomUtils from './GeomUtils';
+//# sourceMappingURL=index.d.ts.map