@syncfusion/ej2-calculate 35.1.37

package/src/common/interface.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Arguments for the {@link Calculate.onFailure} event when parsing or evaluation fails.
+ */
+export interface FailureEventArgs {
+    /** Error message describing the failure. */
+    message: string;
+    /** Underlying exception object or message. */
+    exception: Object;
+    /** Whether the formula can be force-calculated despite the failure. */
+    isForceCalculable: boolean;
+    /** When set by a listener, requests force calculation. */
+    computeForceCalculate?: boolean;
+}
+/**
+ * Metadata and handler for a registered library formula.
+ */
+export interface IFormulaCollection {
+    /** Bound `Compute*` handler invoked by the engine. */
+    handler: Function;
+    /** When `true`, the formula was registered via {@link Calculate.defineFunction}. */
+    isCustom?: boolean;
+    /** Category label for Insert Function UI. */
+    category?: string;
+    /** Short description of the formula. */
+    description?: string;
+}
+/**
+ * Working state for multi-criteria IFS formula evaluation.
+ *
+ * @hidden
+ */
+export interface StoredCellInfo {
+    cellValue: string | string[];
+    cellRange: string[];
+    criteria: string[];
+    argArray: string[];
+    isCriteria: string;
+    storedCells: string[];
+    isCountIfS: string;
+    countVal?: number;
+}
+/**
+ * Catalog entry used when registering built-in formulas with {@link BasicFormulas}.
+ *
+ * @hidden
+ */
+export interface IBasicFormula {
+    /** Excel function name (for example `"SUM"`). */
+    formulaName: string;
+    /** Category label (for example `"Math & Trig"`). */
+    category?: string;
+    /** Short description shown in formula UI. */
+    description?: string;
+}
+/**
+ * Sheet metadata exposed by a calculate host (workbook / xlsx adapter).
+ *
+ */
+export interface CalculateSheetInfo {
+    /** Visible sheet name shown to users. */
+    visibleName: string;
+    /** Internal sheet token/name used in formulas. */
+    sheet: string;
+    /** Zero-based sheet index in the host workbook. */
+    index: number;
+}
+/**
+ * Result of host-provided date / time parsing.
+ *
+ * @hidden
+ */
+export interface CalculateDateParseResult {
+    /** Parsed JavaScript date when available. */
+    dateObj?: Date;
+    /** Whether the value was recognized as a date. */
+    isDate?: boolean;
+    /** Whether the value was recognized as a time. */
+    isTime?: boolean;
+    /** Optional normalized value string. */
+    value?: string;
+}
+/**
+ * Host contract for integrating Calculate with a workbook or xlsx model.
+ *
+ * Spreadsheet Workbook implements this; other libraries can provide their own adapter.
+ */
+export interface ICalculateHost {
+    /**
+     * Reads a cell value at 1-based row/column for a sheet family.
+     *
+     * @param {string | number | Object} sheetFamilyID - Sheet family identifier.
+     * @param {number} row - 1-based row index.
+     * @param {number} col - 1-based column index.
+     * @param {string | number | Object} rest - Host-specific extra arguments.
+     */
+    getValueRowCol?(sheetFamilyID: number, row: number, col: number, ...rest: unknown[]): string | number;
+    /**
+     * Writes a cell value at 1-based row/column for a sheet family.
+     *
+     * @param {string | number | Object} sheetFamilyID - Sheet family identifier.
+     * @param {string | number | boolean | Object} value - Value to store.
+     * @param {number} row - 1-based row index.
+     * @param {number} col - 1-based column index.
+     * @param {string} formula - Optional formula text associated with the value.
+     * @param {string | number | Object} rest - Host-specific extra arguments.
+     */
+    setValueRowCol?(sheetFamilyID: number, value: string | number, row: number, col: number, formula?: string, ...rest: unknown[]): void;
+    /** Returns sheet metadata for name/token resolution. */
+    getSheetInfo?(): CalculateSheetInfo[];
+    /**
+     * Parses locale-aware date/time text.
+     *
+     * @param {string | number | boolean | Object} value - Date or time string.
+     */
+    parseDate?(value: string): CalculateDateParseResult;
+    /** Host module name (for example `"workbook"`). */
+    getModuleName?(): string;
+    /** Culture/locale id used for parsing and formatting. */
+    locale?: string;
+    /** Calculation mode such as `"Automatic"` or `"Manual"`. */
+    calculationMode?: string;
+}

package/src/common/l10n.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Localization defaults for `@syncfusion/ej2-calculate`.
+ *
+ * ## What is localized
+ * Human-readable parser / engine failure prose (wrong argument counts, mismatched
+ * parentheses, and similar messages shown via {@link FailureEventArgs} or returned
+ * from evaluation).
+ *
+ * ## What is intentionally NOT localized
+ * Excel-compatible literals required for formula language and file interchange:
+ * - Error tokens: `#N/A`, `#VALUE!`, `#REF!`, `#DIV/0!`, `#NUM!`, `#NAME?`, `#NULL!`,
+ *   `#CALC!`, `#SPILL!`, `#CIRCULARREF!`
+ * - Logical literals: `TRUE` / `FALSE`
+ * - English function names (`SUM`, `IF`, …)
+ *
+ * Culture-sensitive **separators** (argument, decimal, date) are configured via
+ * {@link Calculate} getters/setters and host `locale`, not via these string keys.
+ *
+ * Load overrides with Syncfusion `L10n.load({ 'fr-FR': { calculate: { ... } } })`.
+ */
+/** Default English locale bag for control name `calculate`. */
+export declare const calculateDefaultLocale: {
+    [key: string]: string;
+};

package/src/common/l10n.js

@@ -0,0 +1,54 @@
+/**
+ * Localization defaults for `@syncfusion/ej2-calculate`.
+ *
+ * ## What is localized
+ * Human-readable parser / engine failure prose (wrong argument counts, mismatched
+ * parentheses, and similar messages shown via {@link FailureEventArgs} or returned
+ * from evaluation).
+ *
+ * ## What is intentionally NOT localized
+ * Excel-compatible literals required for formula language and file interchange:
+ * - Error tokens: `#N/A`, `#VALUE!`, `#REF!`, `#DIV/0!`, `#NUM!`, `#NAME?`, `#NULL!`,
+ *   `#CALC!`, `#SPILL!`, `#CIRCULARREF!`
+ * - Logical literals: `TRUE` / `FALSE`
+ * - English function names (`SUM`, `IF`, …)
+ *
+ * Culture-sensitive **separators** (argument, decimal, date) are configured via
+ * {@link Calculate} getters/setters and host `locale`, not via these string keys.
+ *
+ * Load overrides with Syncfusion `L10n.load({ 'fr-FR': { calculate: { ... } } })`.
+ */
+/** Default English locale bag for control name `calculate`. */
+export var calculateDefaultLocale = {
+    OperatorsCannotStartWithExpression: 'binary operators cannot start an expression',
+    CannotParse: 'cannot parse',
+    BadLibrary: 'bad library',
+    InvalidCharInFrontOf: 'invalid char in front of',
+    NumberContains2DecimalPoints: 'number contains 2 decimal points',
+    ExpressionCannotEndWithAnOperator: 'expression cannot end with an operator',
+    InvalidCharactersFollowingWithOperator: 'invalid characters following an operator',
+    InvalidCharInNumber: 'invalid character in number',
+    MismatchedParentheses: 'mismatched parentheses',
+    UnknownFormulaName: 'unknown formula name',
+    RequiresASingleArgument: 'requires a single argument',
+    Requires3Args: 'requires 3 arguments',
+    InvalidMathArgument: 'invalid Math argument',
+    Requires2Args: 'requires 2 arguments',
+    TooComplex: 'too complex',
+    MissingFormula: 'missing formula',
+    ImproperFormula: 'improper formula',
+    InvalidExpression: 'invalid expression',
+    CellEmpty: 'cell empty',
+    BadFormula: 'bad formula',
+    EmptyExpression: 'empty expression',
+    MismatchedTics: 'mismatched string quotes',
+    WrongNumberArguments: 'wrong number of arguments',
+    InvalidArguments: 'invalid arguments',
+    IterationsDoNotConverge: 'iterations do not converge',
+    AlreadyRegistered: 'Control is already registered',
+    CalculationOverflow: 'Calculation overflow',
+    MissingSheet: 'Missing sheet',
+    CannotParseUnderscore: 'cannot_parse',
+    ExpressionCannotEndWithAnOperatorUnderscore: 'expression_cannot_end_with_an_operator',
+    CategoryAll: 'All'
+};

package/src/common/number-date.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Returns whether `date` is a valid JavaScript `Date` instance.
+ *
+ * @hidden
+ * @param {number | string} date - Value to test.
+ * @returns {Date | Object} - `true` when `date` is a valid `Date`.
+ */
+export declare function isDateTime(date: any): boolean;
+/**
+ * Returns whether `val` is numeric (number or numeric string).
+ *
+ * @hidden
+ * @param {string | number} val - Value to test.
+ * @returns {number} - `true` when numeric.
+ */
+export declare function isNumber(val: string | number): boolean;
+/**
+ * Convert a Date (or date-like value) to an Excel serial number.
+ *
+ * @hidden
+ * @param {any} val - Specifies the value.
+ * @param {boolean} isTime - Include time fraction.
+ * @param {boolean} isTimeOnly - Value is time without date.
+ * @returns {number} - Excel serial number.
+ */
+export declare function dateToInt(val: any, isTime?: boolean, isTimeOnly?: boolean): number;

package/src/common/number-date.js

@@ -0,0 +1,38 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Returns whether `date` is a valid JavaScript `Date` instance.
+ *
+ * @hidden
+ * @param {number | string} date - Value to test.
+ * @returns {Date | Object} - `true` when `date` is a valid `Date`.
+ */
+export function isDateTime(date) {
+    return Object.prototype.toString.call(date) === '[object Date]' && !isNaN(date.valueOf());
+}
+/**
+ * Returns whether `val` is numeric (number or numeric string).
+ *
+ * @hidden
+ * @param {string | number} val - Value to test.
+ * @returns {number} - `true` when numeric.
+ */
+export function isNumber(val) {
+    return val - parseFloat(val) >= 0;
+}
+/**
+ * Convert a Date (or date-like value) to an Excel serial number.
+ *
+ * @hidden
+ * @param {any} val - Specifies the value.
+ * @param {boolean} isTime - Include time fraction.
+ * @param {boolean} isTimeOnly - Value is time without date.
+ * @returns {number} - Excel serial number.
+ */
+export function dateToInt(val, isTime, isTimeOnly) {
+    var startDate = new Date('01/01/1900');
+    var date = isDateTime(val) ? val : new Date(val);
+    var startDateUTC = Date.UTC(startDate.getFullYear(), startDate.getMonth(), startDate.getDate(), startDate.getHours(), startDate.getMinutes(), startDate.getSeconds(), startDate.getMilliseconds());
+    var dateUTC = Date.UTC(date.getFullYear(), date.getMonth(), date.getDate(), date.getHours(), date.getMinutes(), date.getSeconds(), date.getMilliseconds());
+    var diffDays = ((dateUTC - startDateUTC) / (1000 * 3600 * 24));
+    return (isTime ? diffDays : parseInt(diffDays.toString(), 10)) + (isTimeOnly ? 0 : (diffDays > 60 ? 2 : 1));
+}

package/src/common/sheet-info.d.ts

@@ -0,0 +1,10 @@
+import { CalculateSheetInfo } from './interface';
+/**
+ * Find sheet index by internal sheet token name (e.g. 'Sheet1').
+ *
+ * @hidden
+ * @param {string} name - Sheet token name.
+ * @param {CalculateSheetInfo[]} info - Host sheet info list.
+ * @returns {number} - Sheet index, or -1 when not found.
+ */
+export declare function getSheetIndexByName(name: string, info: CalculateSheetInfo[]): number;

package/src/common/sheet-info.js

@@ -0,0 +1,17 @@
+/**
+ * Find sheet index by internal sheet token name (e.g. 'Sheet1').
+ *
+ * @hidden
+ * @param {string} name - Sheet token name.
+ * @param {CalculateSheetInfo[]} info - Host sheet info list.
+ * @returns {number} - Sheet index, or -1 when not found.
+ */
+export function getSheetIndexByName(name, info) {
+    var len = info.length;
+    for (var i = 0; i < len; i++) {
+        if (info[i].sheet.toUpperCase() === name.toUpperCase()) {
+            return info[i].index;
+        }
+    }
+    return -1;
+}

package/src/common/sort.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Ascending / descending comparer compatible with former DataUtil.fnSort usage.
+ *
+ * @hidden
+ * @param {string} order - 'Ascending' or 'Descending' (empty defaults to ascending numeric compare).
+ * @returns {Function} - Comparer (a, b) => number.
+ */
+export declare function createSortComparer(order?: string): (a: Object, b: Object) => number;
+/**
+ * Sort a collection with an optional order string.
+ *
+ * @template T
+ * @param {T[]} collection - Items to sort.
+ * @param {string} order - 'Ascending' or 'Descending'.
+ * @returns {T[]} - Sorted shallow copy.
+ */
+export declare function sortCollection<T>(collection: T[], order?: string): T[];

package/src/common/sort.js

@@ -0,0 +1,44 @@
+/**
+ * Ascending / descending comparer compatible with former DataUtil.fnSort usage.
+ *
+ * @hidden
+ * @param {string} order - 'Ascending' or 'Descending' (empty defaults to ascending numeric compare).
+ * @returns {Function} - Comparer (a, b) => number.
+ */
+export function createSortComparer(order) {
+    var descending = order === 'Descending';
+    return function (a, b) {
+        if (a === b) {
+            return 0;
+        }
+        if (a === null || a === undefined) {
+            return 1;
+        }
+        if (b === null || b === undefined) {
+            return -1;
+        }
+        var result = 0;
+        if (typeof a === 'string') {
+            result = a.localeCompare(b);
+        }
+        else if (a > b) {
+            result = 1;
+        }
+        else if (a < b) {
+            result = -1;
+        }
+        return descending ? -result : result;
+    };
+}
+/**
+ * Sort a collection with an optional order string.
+ *
+ * @template T
+ * @param {T[]} collection - Items to sort.
+ * @param {string} order - 'Ascending' or 'Descending'.
+ * @returns {T[]} - Sorted shallow copy.
+ */
+export function sortCollection(collection, order) {
+    var comparer = createSortComparer(order);
+    return collection.slice().sort(comparer);
+}

package/src/formulas/array.d.ts

@@ -0,0 +1,47 @@
+import { IBasicFormula } from '../common/index';
+import { FormulaOwner } from './formula-owner';
+import { FormulaModuleBase } from './formula-module-base';
+/**
+ * Array formula helpers for dynamic spill-style range operations.
+ *
+ * Registered functions: UNIQUE, SORT.
+ *
+ * @hidden
+ */
+export declare class ArrayFormulas extends FormulaModuleBase {
+    /** Formula definitions registered with {@link BasicFormulas}. */
+    formulas: IBasicFormula[];
+    /**
+     * @hidden
+     * @param {FormulaOwner} owner - Formula registration owner ({@link BasicFormulas}).
+     */
+    constructor(owner: FormulaOwner);
+    /**
+     * Returns a unique values from a range or array.
+     *
+     * Excel: `UNIQUE(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     *
+     * @example
+     * ```ts
+     * engine.computeFormula('=UNIQUE(1)');
+     * ```
+     */
+    ComputeUNIQUE(...args: string[]): number | string | number[] | string[];
+    private setValueRefresh;
+    private checkSpill;
+    clearDependency(value: string): void;
+    /**
+     * Sorts a range of an array.
+     *
+     * Excel: `SORT(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     */
+    ComputeSORT(...args: string[]): number | string;
+}