@sheetxl/sdk 0.7.21 → 0.7.23-beta.2

package/types/src/numFmt/_NumFmtUtils.d.ts

@@ -0,0 +1,102 @@
+import { IRuntime } from '@sheetxl/primitives';
+import { NumberFormatRef } from './BuiltInFormats';
+import { ParserOptions } from './NumberFormatParser';
+import { Type } from './NumberFormatType';
+export declare const regExpLocaleRule: RegExp;
+export declare const regExHex: RegExp;
+/**
+ * Split a format code into its `;`-separated sections, ignoring separators
+ * inside quoted literals, `[...]` groups (colors/conditions/locales), and after
+ * a `\` escape.
+ */
+export declare function splitFmt(fmt: string): string[];
+/**
+ * Adjust the decimal places in a format code by `amount` (toolbar
+ * increase/decrease decimal). Pure string surgery over the `;` sections.
+ */
+export declare function adjustDecimalPlaces(formatRef: NumberFormatRef, amount: number): string;
+/**
+ * Options for the pure formatting core — explicit workbook context
+ * (`date1904`, `locale`) instead of an `IRuntime`.
+ */
+export interface FormatValueOptions extends ParserOptions {
+    /** @defaultValue false */
+    date1904?: boolean;
+    /** BCP-47 locale tag. @defaultValue 'en-US' */
+    locale?: string;
+}
+/**
+ * Compat wrapper: extracts `date1904`/`locale` from the runtime and delegates
+ * to {@link formatValueCore}.
+ */
+export declare function formatValue(runtime: IRuntime, format: NumberFormatRef, value: string | number, options?: ParserOptions): string;
+export declare function formatValueCore(format: NumberFormatRef, value: string | number, options?: FormatValueOptions): string;
+/**
+ * Compat wrapper: extracts `date1904`/`locale` from the runtime and delegates
+ * to {@link toLocaleDateCore}.
+ */
+export declare function toLocaleDate(runtime: IRuntime, format: NumberFormatRef, value: number, options?: ParserOptions): {
+    fmt: string;
+    date: Date;
+} | null;
+export declare function toLocaleDateCore(format: NumberFormatRef, value: number, options?: FormatValueOptions): {
+    fmt: string;
+    date: Date;
+} | null;
+export declare const XMLFormatMap: Readonly<Record<string, string | number>>;
+/**
+ * Returns a legacy color as an rgb value
+ */
+export declare function convertToLegacyColor(color: string): string | null;
+/**
+ * Colors, spacing, column width adjustments (turning a long number into scientific notation)
+ *
+ * https://docs.microsoft.com/en-us/dotnet/api/documentformat.openxml.spreadsheet.numberingformats?view=openxml-2.8.1
+ *
+ * Rules to accommodate.
+ * 1. Defaults Formatting rules (based on # of parts 1 - 4)
+ *    a. (4) >0;<0;=0; text
+ *    b. (3) >0;<0;=0; (General for text)
+ *    c. (2) >=0;<0; (General for text)
+ *    d. (1) Value is not considered
+ * 2. Custom formatting rules specified with brackets []
+ *    If custom formatting rules are applied then only 1 -3 parts
+      a. 1-2 parts can contain custom rules. last part (if 3rd part can be a default format.
+      b. If a custom eval is used no default and value doesn't match then returns overflow ([Red][<=100]General;[Blue][>100]General)
+  * 3. Color rules
+  *    a. color definition
+  *       i.  8 standard colors [Black],[Blue],[Cyan],[Green],[Magenta],[Red],[White],[Yellow]
+  *       ii. and legacy colors codes - default legacy color palette values are listed in §18.8.27
+  * 4. Adjusting for width
+  *    a. padding should only add the number of characters viewable
+  *    b. Overflow (support for drawing ### when column width is too small)
+*/
+declare const Operator: {
+    readonly Equal: "=";
+    readonly NotEqual: "<>";
+    readonly GreaterThan: ">";
+    readonly LessThan: "<";
+    readonly GreaterThanOrEqual: ">=";
+    readonly LessThanOrEqual: "<=";
+};
+export type Operator = typeof Operator[keyof typeof Operator];
+export declare function getConditionalColor(format: string, value: string | number): string | null;
+export declare function isFraction(fmt: string): boolean;
+/**
+ * Compares the number format types to determine which has a higher priority for default during formula entry.
+ * Excel typically prioritizes formats in this order:
+ * 1. Date/Time formats (highest)
+ * 2. Percentage
+ * 3. Currency/Accounting
+ * 4. Number formats with decimals
+ * 5. General/other formats (lowest)
+ */
+export declare function compareFormatPriorities(a: Type, b: Type): number;
+/**
+ * Determines if a number format string or ID should be treated as 'Text'.
+ * When true, the calculation engine should skip numeric parsing and treat
+ * the input as a literal string.
+ */
+export declare function isTextFormat(formatCode: string | number): boolean;
+export {};
+//# sourceMappingURL=_NumFmtUtils.d.ts.map

package/types/src/numFmt/_NumFmtUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_NumFmtUtils.d.ts","sourceRoot":"","sources":["../../../../src/numFmt/_NumFmtUtils.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAMpD,OAAO,EAA6C,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEnG,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAG1C,eAAO,MAAM,gBAAgB,QAAmB,CAAC;AACjD,eAAO,MAAM,QAAQ,QAAmB,CAAC;AAKzC;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CA2B9C;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAkEtF;AASD;;;GAGG;AACH,MAAM,WAAW,kBAAmB,SAAQ,aAAa;IACvD,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,QAAQ,EACjB,MAAM,EAAE,eAAe,EACvB,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,OAAO,CAAC,EAAE,aAAa,GACtB,MAAM,CAMR;AAED,wBAAgB,eAAe,CAC7B,MAAM,EAAE,eAAe,EACvB,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,MAAM,CAiDR;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,QAAQ,EACjB,MAAM,EAAE,eAAe,EACvB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,aAAa,GACtB;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAE,GAAG,IAAI,CAMpC;AAED,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,eAAe,EACvB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,kBAAkB,GAC3B;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAE,GAAG,IAAI,CA6GpC;AAED,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAyBjE,CAAC;AAcH;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAmBjE;AAED;;;;;;;;;;;;;;;;;;;;;;EAsBE;AAEF,QAAA,MAAM,QAAQ;;;;;;;CAOJ,CAAC;AACX,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,MAAM,OAAO,QAAQ,CAAC,CAAC;AA+G9D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAyBzF;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAK/C;AAaD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,MAAM,CAoBhE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAcjE"}

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

@@ -0,0 +1,105 @@
+import { Type as _Type } from './NumberFormatType';
+import { Parsed as _Parsed, ParsedCharPlaceHolder as _ParsedCharPlaceHolder, ParsedRun as _ParsedRun, ParsedRuns as _ParsedRuns } from './NumberFormatParser';
+import { Style as _Style, Styles as _Styles, StyleConfig as _StyleConfig } from './NumberFormatStyles';
+import { _FindBuiltInNumberFormatId } from './_BuiltInNumberFormats';
+import { getFormatEngine as _getFormatEngine, IFormatEngine as _IFormatEngine, FormatEngineOptions as _FormatEngineOptions, FormatEngineResult as _FormatEngineResult } from './IFormatEngine';
+import { resolveNumberFormat as _resolveNumberFormat, getBuiltInFormatCode as _getBuiltInFormatCode, NumberFormatRef as _NumberFormatRef } from './BuiltInFormats';
+import * as _NumberFormatBuilder from './NumberFormatBuilder';
+/**
+ * Capabilities for defining and applying number formats to cells.
+ *
+ * Number formats control how numeric values are displayed in a spreadsheet,
+ * enabling users to present data in various ways such as currency, percentages, dates, and more.
+ *
+ * Key features include:
+ * - Applying built-in number formats (e.g., currency, date, percentage).
+ * - Creating custom number formats using format codes.
+ * - Setting and retrieving number formats for cells or ranges.
+ */
+export declare namespace NumberFormat {
+    type Parsed = _Parsed;
+    /**
+     * Represents the built-in categorization of a number format, or 'Custom' if the format is not recognized as a built-in type.
+     *
+     * Excel has the following:
+     * @see
+     * {@link https://docs.microsoft.com/en-us/dotnet/api/documentformat.openxml.spreadsheet.numberingformats?view=openxml-2.8.1}
+     */
+    type Type = typeof _Type[keyof typeof _Type];
+    const Type: {
+        readonly General: "General";
+        readonly Number: "Number";
+        readonly Currency: "Currency";
+        readonly Accounting: "Accounting";
+        readonly ShortDate: "Short Date";
+        readonly LongDate: "Long Date";
+        readonly MediumDate: "Medium Date";
+        readonly ShortTime: "Short Time";
+        readonly MediumTime: "Medium Time";
+        readonly LongTime: "Long Time";
+        readonly Comma: "Comma";
+        readonly Percentage: "Percentage";
+        readonly Fraction: "Fraction";
+        readonly Scientific: "Scientific";
+        readonly Text: "Text";
+        readonly Special: "Special";
+        readonly Custom: "Custom";
+    };
+    /**
+     * This interface returns rendering information about the formatted text based on the numberFormat.
+     *
+     *  https://customformats.com/
+     *  https://exceljet.net/custom-number-formats
+     *  https://docs.microsoft.com/en-us/dotnet/api/documentformat.openxml.spreadsheet.numberingformats?view=openxml-2.8.1
+     */
+    const Parser: Readonly<{
+        formatValue: typeof import("./_NumFmtUtils").formatValue;
+        isFractionFormat: (format: string) => boolean;
+        adjustDecimalPlaces: (format: string, amount: number) => string;
+        getFormatInfo: (format: string) => import("./IFormatEngine").FormatInfo | null;
+        getFormatDateInfo: (format: string) => import("./IFormatEngine").FormatDateInfo | null;
+        isValidFormat: (format: string) => boolean;
+    }>;
+    const Styles: _Styles;
+    type Styles = _Styles;
+    type ParsedCharPlaceHolder = _ParsedCharPlaceHolder;
+    const ParseRunType: {
+        readonly Text: "text";
+        readonly Repeat: "repeat";
+        readonly Spacing: "spacing";
+    };
+    type ParsedRun = _ParsedRun;
+    type ParsedRuns = _ParsedRuns;
+    type Style = _Style;
+    type StyleConfig = _StyleConfig;
+    const toBuiltInID: typeof _FindBuiltInNumberFormatId;
+    /**
+     * A number format reference: an ECMA-376 built-in id (number) or a format
+     * code string. Built-ins are STORED as ids (Excel's own model) and resolved
+     * to codes at the render/classification boundary.
+     */
+    type Ref = _NumberFormatRef;
+    /** Resolve a {@link Ref} to a format-code string. */
+    const resolve: typeof _resolveNumberFormat;
+    /** The raw ECMA-376 §18.8.30 table lookup, or `undefined` for unknown ids. */
+    const builtInFormat: typeof _getBuiltInFormatCode;
+    /** Renders format codes to display text, color, and layout placeholders. */
+    type IEngine = _IFormatEngine;
+    /** Options for {@link IEngine.format}. */
+    type EngineOptions = _FormatEngineOptions;
+    /** Result of {@link IEngine.format}. */
+    type EngineResult = _FormatEngineResult;
+    /** Returns the number-format engine. */
+    const getEngine: typeof _getFormatEngine;
+    /**
+     * Format-code builder for the Format Cells → Number dialog: `Builder.build(params)`
+     * synthesizes a code from category + options; `Builder.parse(code)` reverses it.
+     * Also exposes the category list and preset/symbol tables.
+     */
+    const Builder: typeof _NumberFormatBuilder;
+    /** Dialog parameters for {@link Builder}. */
+    type BuilderParams = _NumberFormatBuilder.NumberFormatParams;
+    /** Top-level dialog category. */
+    type Category = _NumberFormatBuilder.NumberFormatCategory;
+}
+//# sourceMappingURL=index.d.ts.map

package/types/src/numFmt/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/numFmt/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,IAAI,IAAI,KAAK,EACd,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAEL,KAAK,MAAM,IAAI,OAAO,EACtB,KAAK,qBAAqB,IAAI,sBAAsB,EAEpD,KAAK,SAAS,IAAI,UAAU,EAC5B,KAAK,UAAU,IAAI,WAAW,EAC/B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,KAAK,KAAK,IAAI,MAAM,EACpB,MAAM,IAAI,OAAO,EACjB,KAAK,WAAW,IAAI,YAAY,EACjC,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AAErE,OAAO,EACL,eAAe,IAAI,gBAAgB,EACnC,KAAK,aAAa,IAAI,cAAc,EACpC,KAAK,mBAAmB,IAAI,oBAAoB,EAChD,KAAK,kBAAkB,IAAI,mBAAmB,EAC/C,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,mBAAmB,IAAI,oBAAoB,EAC3C,oBAAoB,IAAI,qBAAqB,EAC7C,KAAK,eAAe,IAAI,gBAAgB,EACzC,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,oBAAoB,MAAM,uBAAuB,CAAC;AAE9D;;;;;;;;;;GAUG;AACH,yBAAiB,YAAY,CAAC;IAC5B,KAAY,MAAM,GAAG,OAAO,CAAC;IAC7B;;;;;;OAMG;IACH,KAAY,IAAI,GAAG,OAAO,KAAK,CAAC,MAAM,OAAO,KAAK,CAAC,CAAC;IAC7C,MAAM,IAAI;;;;;;;;;;;;;;;;;;KAAQ,CAAC;IAE1B;;;;;;OAMG;IACI,MAAM,MAAM;;;;;;;MAAU,CAAC;IAEvB,MAAM,MAAM,SAAgB,CAAC;IACpC,KAAY,MAAM,GAAG,OAAO,CAAC;IAE7B,KAAY,qBAAqB,GAAG,sBAAsB,CAAC;IAGpD,MAAM,YAAY;;;;KAAgB,CAAC;IAE1C,KAAY,SAAS,GAAG,UAAU,CAAC;IACnC,KAAY,UAAU,GAAG,WAAW,CAAC;IAIrC,KAAY,KAAK,GAAG,MAAM,CAAC;IAE3B,KAAY,WAAW,GAAG,YAAY,CAAC;IAEhC,MAAM,WAAW,mCAA6B,CAAC;IAEtD;;;;OAIG;IACH,KAAY,GAAG,GAAG,gBAAgB,CAAC;IACnC,qDAAqD;IAC9C,MAAM,OAAO,6BAAuB,CAAC;IAC5C,8EAA8E;IACvE,MAAM,aAAa,8BAAwB,CAAC;IAEnD,4EAA4E;IAC5E,KAAY,OAAO,GAAG,cAAc,CAAC;IACrC,0CAA0C;IAC1C,KAAY,aAAa,GAAG,oBAAoB,CAAC;IACjD,wCAAwC;IACxC,KAAY,YAAY,GAAG,mBAAmB,CAAC;IAC/C,wCAAwC;IACjC,MAAM,SAAS,yBAAmB,CAAC;IAE1C;;;;OAIG;IACI,MAAM,OAAO,6BAAuB,CAAC;IAC5C,6CAA6C;IAC7C,KAAY,aAAa,GAAG,oBAAoB,CAAC,kBAAkB,CAAC;IACpE,iCAAiC;IACjC,KAAY,QAAQ,GAAG,oBAAoB,CAAC,oBAAoB,CAAC;CAClE"}

package/types/src/numFmt/vendor/numfmt/_sheetxl.d.ts

@@ -0,0 +1,15 @@
+/**
+ * SHEETXL-PATCH — declarations for `_sheetxl.js`, which (like everything in this
+ * directory) is plain JavaScript. The repo compiles without `allowJs`, so TypeScript can
+ * only resolve a vendored module through a declaration file — this one is hand-carried
+ * next to its source the same way `index.d.ts` is. Keep in sync with the JSDoc there.
+ */
+
+/** §3b — `value` rounded to 15 significant digits (display-only; see `_sheetxl.js`). */
+export declare function clampSignificand(value: number): number;
+
+/** `value` rounded to `places` decimals, then capped at 15 significant digits. */
+export declare function roundDisplay(value: number, places: number): number;
+
+/** §3a — `String(value)` with the exponential form expanded to plain decimal notation. */
+export declare function toDecimalString(value: number): string;