@sheetxl/sdk 0.7.27 → 0.7.28-beta.2

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

@@ -0,0 +1,168 @@
+import { IColor } from '../color';
+import { formatValue as _formatValue } from './_NumFmtUtils';
+import { FormatInfo, FormatDateInfo } from './IFormatEngine';
+/**
+ * Options for parsing a NumberFormat.
+ */
+export interface ParserOptions {
+    /**
+     * Call when a repeat char
+     */
+    onRepeatChar?: (offset: number, character: string) => void;
+    /**
+     * The character to add to the formatted string when a spacing character is
+     * introduced.
+     *
+     * @defaultValue ' '
+     */
+    spacingCharacter?: string;
+    /**
+     * When '_' is encountered this is called.
+     */
+    onSpacingChar?: (offset: number, character: string) => void;
+    /**
+     * When '?' this encountered this is called.
+     *
+     * @defaultValue ' '
+     */
+    digitCharacter?: string;
+    onDigitChar?: (offset: number) => void;
+}
+export interface ParsedCharPlaceHolder {
+    offset: number;
+    char: string;
+}
+export declare const ParseRunType: {
+    /**
+     * Contains text.
+     */
+    readonly Text: "text";
+    /**
+     * Indicates the text at this run should repeat.
+     */
+    readonly Repeat: "repeat";
+    /**
+     * Indicates the text at this run should not be displayed but used for measuring white-space.
+     */
+    readonly Spacing: "spacing";
+};
+export type ParseRunType = typeof ParseRunType[keyof typeof ParseRunType];
+export interface ParsedRun {
+    type: ParseRunType;
+    width: number;
+    text: string;
+}
+export interface ParsedRuns {
+    runs: readonly ParsedRun[];
+    readonly length: number;
+    readonly width: number;
+    readonly lastRepeatIndex: number;
+}
+/**
+ * This interface returns rendering information about the formatted text based on the numberFormat.
+ *
+ *  @see
+ *  * {@link https://customformats.com/}
+ *  * {@link https://exceljet.net/custom-number-formats}
+ *  * {@link https://docs.microsoft.com/en-us/dotnet/api/documentformat.openxml.spreadsheet.numberingformats?view=openxml-2.8.1}
+ */
+export interface Parsed {
+    /**
+     * @remarks
+     * Never null
+     */
+    readonly displayText: string;
+    /**
+     * If provided then there was a formatting error.
+     *
+     * @remarks
+     * If this is not `null` then a character should be displayed.
+     *
+     * This is different then repeatChars in that it will only display the value
+     * and not any additional.
+     */
+    readonly errorPlaceholder: string | null;
+    /**
+     * If there is a conditional color then this is the color to use.
+     */
+    readonly conditionalColor: IColor | null;
+    /**
+     * From the '*' formatChar.
+     * A single character (usually a ' ' but can be anything)
+     *
+     * Repeats the next character in the format enough times to fill the column to its current width.
+     * There shall not be more than one asterisk in one section of the format. If more than one asterisk
+     * appears in one section of the format, all but the last asterisk shall be ignored.
+     * [Example: if the number format is 0*x, and the value 3 is in the cell, the value 3xxxxxx is displayed.
+     * The number of x characters that are displayed in the cell varies based on the width of the column. end example]
+     */
+    readonly repeatChars: ParsedCharPlaceHolder[];
+    /**
+     * From the '_' formatChar.
+     * An array of single characters.
+     *
+     * Skips the width of the next character.
+     * Useful for lining up negative and positive values in different cells of the same column.
+     * [Example: The number format _(0.0_);(0.0) aligns the numbers 2.3 and the column even though the
+     * negative number is enclosed by parentheses. end example]
+     */
+    readonly spacingChars: ParsedCharPlaceHolder[];
+    /**
+     * The displayText broken down into runs. Useful for more complex layouts.
+     */
+    readonly formattedRuns: ParsedRuns;
+    /**
+     * If true then the text could wrap if it doesn't fit.
+     */
+    readonly canWrap: boolean;
+    /**
+     * Returns the value as a javascript date if possible. Will
+     * return null if not possible.
+     */
+    readonly asDate: Date | null;
+    /**
+     * If the format is a date format then this is true.
+     */
+    readonly isDateFormat: boolean;
+    /**
+     * If the format is a time format then this is true.
+     */
+    readonly isTimeFormat: boolean;
+}
+export declare const Parser: Readonly<{
+    /**
+     * Language Code Identifier (LCIDs) are 'embedded' within numberFormat.
+     *
+     * There is the original (being deprecated) format and the new 'locale names' format.
+     * The original format (most widely used at time of writing but being deprecated). Is an 8 digit hex number (xxyyzzzz). If the number is less than this then it is assumed to have
+     * leading 0s. The hex is broken down into 3 parts.
+     * xx - appearance of the number (see)
+     *
+     * Also modern Excel 365 now allows this syntax: [$-lg-CN,xxyy] where lg-CN is the language and country of the locale (replacing zzzz), and xxyy are as defined in the prior answer. Leading zeros are not needed and the whole ,xxyy part is optional.
+     * In addition, a gannen suffix -x-gannen is allowed on Japanese locale codes, which replaces a 1 value (first year of emperor reign) for e formats with 元. For example:
+     */
+    formatValue: typeof _formatValue;
+    /**
+     * Returns true if the format contains fraction formatting.
+     */
+    isFractionFormat: (format: string) => boolean;
+    /**
+     * Adjust the decimal in a format by an amount.
+     *
+     * @param format The format string.
+     * @param amount The number of decimals to adjust by.
+     */
+    adjustDecimalPlaces: (format: string, amount: number) => string;
+    /**
+     * Structural metadata about a format code (category, decimals, grouping, ...),
+     * for format dialogs and classification. `null` if the code is invalid.
+     */
+    getFormatInfo: (format: string) => FormatInfo | null;
+    /**
+     * Which date/time components a date format renders. `null` for non-date codes.
+     */
+    getFormatDateInfo: (format: string) => FormatDateInfo | null;
+    /** True if a format code parses (for live custom-code validation). */
+    isValidFormat: (format: string) => boolean;
+}>;
+//# sourceMappingURL=NumberFormatParser.d.ts.map

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

@@ -0,0 +1,43 @@
+import { Type } from './NumberFormatType';
+/**
+ * These are only returned if all segments have the same values.
+ */
+export interface StyleConfig {
+    separator?: boolean;
+    decimalPlaces?: number;
+    currencySymbol?: string;
+}
+/**
+ * Returns meta data about the number format.
+ */
+export interface Style {
+    numberFormat: string;
+    /**
+     * Category of format/
+     */
+    formatType: Type;
+    /**
+     * If used in a menu it's the sort oder.
+     * TODO - enrich this since excel and drawMl (charts are slightly different. Union these?)
+     */
+    primary?: number;
+    args?: StyleConfig;
+    regMatch?: RegExp;
+}
+export declare class Styles {
+    /**
+     * Find the style for a numberFormat.
+     */
+    lookupStyle(numberFormat: string | number): Style;
+    /**
+     * Returns an ordered list of a select set of the builtIn FormatCodes.
+     */
+    lookupPrimary(): Style[];
+    /**
+     * Returns all catalog styles for a category (`formatType`), in catalog order.
+     * Used by the format dialog to list a category's preset variants.
+     */
+    lookupByType(formatType: string | Type): Style[];
+    lookupDefault(numberFormatKey: string | Type): string | undefined;
+}
+//# sourceMappingURL=NumberFormatStyles.d.ts.map

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

@@ -0,0 +1,79 @@
+/**
+ * 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}
+ */
+export declare const Type: {
+    /**
+     * The default format, displays numbers as entered.
+     */
+    readonly General: "General";
+    /**
+     * Displays numbers with a thousands separator and two decimal places.
+     */
+    readonly Number: "Number";
+    /**
+     * Formats numbers as currency with a currency symbol and two decimal places.
+     */
+    readonly Currency: "Currency";
+    /**
+     * Formats numbers as currency, aligning currency symbols and decimal points in a column.
+     */
+    readonly Accounting: "Accounting";
+    /**
+     * Displays dates in a short format (e.g., "M/d/yyyy").
+     */
+    readonly ShortDate: "Short Date";
+    /**
+     * Displays dates in a long format (e.g., "dddd, MMMM d, yyyy").
+     */
+    readonly LongDate: "Long Date";
+    /**
+     * Displays dates in a medium format (e.g., "d-mmm-yy").
+     */
+    readonly MediumDate: "Medium Date";
+    /**
+     * Displays times in a short format (e.g., "h:mm AM/PM").
+     */
+    readonly ShortTime: "Short Time";
+    /**
+     * Displays times in a medium format (e.g., "h:mm:ss AM/PM").
+     */
+    readonly MediumTime: "Medium Time";
+    /**
+     * Displays times in a long format (e.g., "h:mm:ss.000 AM/PM").
+     */
+    readonly LongTime: "Long Time";
+    /**
+     * Displays numbers with a thousands separator.
+     */
+    readonly Comma: "Comma";
+    /**
+     * Displays numbers as percentages with a percent symbol.
+     */
+    readonly Percentage: "Percentage";
+    /**
+     * Displays numbers as fractions.
+     */
+    readonly Fraction: "Fraction";
+    /**
+     * Displays numbers in scientific notation.
+     */
+    readonly Scientific: "Scientific";
+    /**
+     * Treats the cell content as text, even if it appears to be a number.
+     */
+    readonly Text: "Text";
+    /**
+     * A placeholder for special or custom number formats.
+     */
+    readonly Special: "Special";
+    /**
+     * Indicates a user-defined or custom number format.
+     */
+    readonly Custom: "Custom";
+};
+export type Type = typeof Type[keyof typeof Type];
+//# sourceMappingURL=NumberFormatType.d.ts.map

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

@@ -0,0 +1,33 @@
+import { NumberFormatRef } from './BuiltInFormats';
+import { FormatEngineOptions, FormatEngineResult, FormatInfo, FormatDateInfo, IFormatEngine } from './IFormatEngine';
+/**
+ * The SheetXL number-format engine.
+ *
+ * Renders Excel format codes — and ECMA-376 built-in ids — to display text,
+ * section color, and the fill/skip placeholders the cell renderer uses for
+ * width-aware alignment.
+ *
+ * Locale-adaptive presets (`Short Date`, `[$-F800]`, ...) are resolved before
+ * the format code reaches the formatter, so built-ins such as `14`/`22` render
+ * per the viewer's locale rather than their canonical codes.
+ */
+export declare class NumfmtFormatEngine implements IFormatEngine {
+    readonly key: string;
+    /** @inheritdoc IFormatEngine.format */
+    format(format: NumberFormatRef, value: string | number, options?: FormatEngineOptions): FormatEngineResult;
+    /** @inheritdoc IFormatEngine.isDateFormat */
+    isDateFormat(format: NumberFormatRef): boolean;
+    /** @inheritdoc IFormatEngine.isTimeFormat */
+    isTimeFormat(format: NumberFormatRef): boolean;
+    /** @inheritdoc IFormatEngine.isFractionFormat */
+    isFractionFormat(format: NumberFormatRef): boolean;
+    /** @inheritdoc IFormatEngine.adjustDecimalPlaces */
+    adjustDecimalPlaces(format: NumberFormatRef, amount: number): string;
+    /** @inheritdoc IFormatEngine.getFormatInfo */
+    getFormatInfo(format: NumberFormatRef): FormatInfo | null;
+    /** @inheritdoc IFormatEngine.getFormatDateInfo */
+    getFormatDateInfo(format: NumberFormatRef): FormatDateInfo | null;
+    /** @inheritdoc IFormatEngine.isValidFormat */
+    isValidFormat(format: NumberFormatRef): boolean;
+}
+//# sourceMappingURL=NumfmtFormatEngine.d.ts.map

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

@@ -0,0 +1,12 @@
+import { NumberFormatRef } from './BuiltInFormats';
+/**
+ * Find the default number format string for a format id as defined in OOXML.
+ */
+export declare function _BuiltInNumberFormats(fmtId: number): string;
+/**
+ * Returns the built-in numeric id for a format code, or the code itself if it
+ * is not a built-in. Numeric refs (already ids) pass through unchanged, which
+ * keeps stored ids lossless through the xlsx writer.
+ */
+export declare function _FindBuiltInNumberFormatId(fmtString: NumberFormatRef): string | number | undefined;
+//# sourceMappingURL=_BuiltInNumberFormats.d.ts.map

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

@@ -0,0 +1,52 @@
+import { ScalarType, Scalar, IRuntime } from '@sheetxl/primitives';
+import { IColor } from '../color';
+import { IStyle } from '../style';
+import { NumberFormatRef } from './BuiltInFormats';
+import { Parsed, ParserOptions } from './NumberFormatParser';
+export declare function parseNumberFormat(runtime: IRuntime, value: Scalar, style: IStyle, type: ScalarType, numberFormat: NumberFormatRef, parseColor: (val: any) => IColor): Parsed;
+/**
+ * The unformatted text for a number.
+ *
+ * Excel's binary→decimal conversion is 15 significant digits, rounded (`PI()` echoes in the
+ * formula bar as `3.14159265358979`, `2/3` as `0.666666666666667`); JavaScript's `String()`
+ * emits the shortest round-trip form — up to 17 digits. Round through `toPrecision(15)` to
+ * match (`Number()` strips the trailing zeros it pads with).
+ *
+ * JavaScript also switches to exponential notation outside `1e-7 .. 1e21` and writes the
+ * exponent marker in lowercase (`1e+30`). Excel spells it uppercase with a signed,
+ * at-least-two-digit exponent (`1E+30`, `1E-07`), so normalize to Excel's spelling.
+ *
+ * Exported for the SHOW FORMULAS text frame, which strips formatting down to the raw value
+ * (measured — see `unformattedNumberText`'s use in `SheetCell.csTextFrame`) and so needs this
+ * number spelling WITHOUT the date/percent conversions `unformattedTextFromCell` applies.
+ *
+ * @internal
+ */
+export declare function unformattedNumberText(value: Scalar): string;
+/**
+ * The text a value shows with formatting stripped ENTIRELY — SHOW FORMULAS' non-formula cell.
+ *
+ * @remarks
+ * A different rule from {@link unformattedTextFromCell} (the formula bar), and the difference is
+ * the point: measured over COM, Excel strips all formatting to the raw value here — a `m/d/yyyy`
+ * cell shows `45292`, `0.00%` shows `0.125` — while the formula bar keeps the date and the percent.
+ * Only the NUMBER SPELLING is shared ({@link unformattedNumberText}).
+ *
+ * The ONE definition of that text: the show-formulas text frame (`SheetCell.csTextFrame`'s
+ * `disabledFormatting` path, which both paint and autoFit measure go through) and
+ * `ICell.GetTextOptions.showFormulas` (what the clipboard writes) both resolve it here, so
+ * what is copied cannot drift from what is painted.
+ *
+ * "Stripped" is about the NUMBER FORMAT, not about localization: a boolean and an error are words,
+ * and Excel shows the spreadsheet language's word (`WAHR`, `#WERT!`) in formula view exactly as it
+ * does everywhere else. JavaScript's own spelling — `'' + value`, i.e. `true`, and an error's
+ * MESSAGE in preference to its label — is never what a cell paints.
+ *
+ * @internal
+ */
+export declare function rawTextFromValue(value: Scalar, type: ScalarType): string;
+/**
+ * Note - Even in the case of unformatted text we do a 'minimum' amount. For example we convert dates and percentages
+ */
+export declare function unformattedTextFromCell(runtime: IRuntime, value: Scalar, type: ScalarType, numberFormat: NumberFormatRef, options?: ParserOptions): string;
+//# sourceMappingURL=_FormatCell.d.ts.map

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/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/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;