@rowsncolumns/utils 9.2.43 → 9.3.0

package/dist/cjs/formula-locale.d.ts

@@ -0,0 +1,159 @@
+import type { CalculatorFunction } from "@rowsncolumns/common-types";
+import { type FormulaLocaleSyntaxData } from "./formula-locale/formula-locale-data.generated";
+export type { FormulaLocaleDataEntry, FormulaLocaleSyntaxData, } from "./formula-locale/formula-locale-data.generated";
+export { FORMULA_LOCALE_DATA, FORMULA_LOCALE_DATA_SOURCES, } from "./formula-locale/formula-locale-data.generated";
+/**
+ * Locale-aware formula SYNTAX (rowsncolumns/spreadsheet#655), the way Excel does it: a workbook
+ * stores and evaluates every formula in one canonical dialect — English function names, `.` decimal
+ * mark, `,` argument separator, `{1,2;3,4}` array constants, `#VALUE!` error values — while the cell
+ * editor, formula bar, autocomplete, argument hints and error display speak the user's language
+ * (`=СУММ(1,5;A1)` in ru-RU, `=SUMME(1,5;A1)` in de-DE, `=SUMA(1,5;A1)` in es-ES).
+ *
+ * `localizeFormula` / `canonicalizeFormula` are exact inverses on well-formed canonical formulas: they
+ * rewrite ONLY the characters Excel localizes (number literals, separators, function names, TRUE/FALSE,
+ * error values) and copy everything else verbatim — strings, quoted sheet names, structured references
+ * (`Table1[[#Headers],[Qty]]` stays as typed), R1C1 text, operators, whitespace.
+ *
+ * Dictionaries come from the generated table (`formula-locale/formula-locale-data.generated.ts`,
+ * built from PhpSpreadsheet's Excel translations + Microsoft's localized function reference) and can be
+ * extended or overridden per application through {@link registerFormulaLocale} or an inline
+ * {@link FormulaLocaleDefinition}.
+ */
+/** The separators that vary per locale, plus Excel's union operator (always the argument separator). */
+export interface FormulaSyntax extends FormulaLocaleSyntaxData {
+    /** Reference-union operator (`SUM((A1:A2,B1:B2))`) — Excel uses the argument separator for it. */
+    unionOperator: string;
+}
+/** A resolved formula locale: syntax + bidirectional function/error dictionaries. */
+export interface FormulaLocale extends FormulaSyntax {
+    /** The tag this locale was resolved from (`"de"`, `"pt-BR"`, or a registered custom id). */
+    id: string;
+    /** Display name of the language, in the language. */
+    name: string;
+    /** Canonical (uppercase English) function name → localized name. Names without an entry keep
+     * their English spelling. */
+    functions: ReadonlyMap<string, string>;
+    /** Case-folded localized function name → canonical name. */
+    canonicalFunctions: ReadonlyMap<string, string>;
+    /** Canonical error value (`#VALUE!`) → localized error value (`#ЗНАЧ!`). */
+    errors: ReadonlyMap<string, string>;
+    /** Case-folded localized error value → canonical error value. */
+    canonicalErrors: ReadonlyMap<string, string>;
+    /** `true` when the locale IS the canonical dialect (every translation is the identity), so
+     * callers can skip the scanner altogether. */
+    isCanonical: boolean;
+}
+/**
+ * An application-supplied locale: a new language, or overrides layered on a built-in one via
+ * `extends`. Every field is optional; omitted syntax fields inherit from the base (or from `en`), and
+ * a `null` dictionary entry removes the inherited translation so the name falls back to English.
+ */
+export interface FormulaLocaleDefinition {
+    /** Identifier reported as {@link FormulaLocale.id}; defaults to the tag it is registered under. */
+    id?: string;
+    name?: string;
+    /** Built-in or registered tag whose syntax and dictionaries this definition starts from. */
+    extends?: string;
+    decimalSeparator?: string;
+    argumentSeparator?: string;
+    arrayColumnSeparator?: string;
+    arrayRowSeparator?: string;
+    /** Canonical function name → localized name (`null` = use the English name). */
+    functions?: Readonly<Record<string, string | null>>;
+    /** Canonical error value → localized error value (`null` = use the English value). */
+    errors?: Readonly<Record<string, string | null>>;
+}
+/** What {@link getFormulaLocale} accepts: a BCP-47 tag, an already-resolved locale, or an inline
+ * definition (resolved once per object identity). */
+export type FormulaLocaleInput = string | FormulaLocale | FormulaLocaleDefinition;
+/** Excel error values, in their canonical (English) spelling. */
+export declare const CANONICAL_ERROR_VALUES: readonly string[];
+/** The canonical dialect every formula is stored and evaluated in. */
+export declare const CANONICAL_FORMULA_LOCALE: FormulaLocale;
+/**
+ * Resolve a locale for formula syntax. Accepts a BCP-47 tag (`"ru-RU"` → the `ru` table, `"de-AT"` →
+ * `de`, `"de-CH"` → the Swiss row; unknown languages → canonical English), an already-resolved
+ * {@link FormulaLocale} (returned as-is), or an inline {@link FormulaLocaleDefinition} (resolved once
+ * per object). Resolution is memoized.
+ */
+export declare const getFormulaLocale: (locale?: FormulaLocaleInput | null) => FormulaLocale;
+/**
+ * Add a formula locale or override a built-in one for the whole application: `registerFormulaLocale
+ * ("de", { functions: { SUM: "SUMMEX" } })` layers onto the German table, `registerFormulaLocale("xx",
+ * { extends: "fr", argumentSeparator: "," })` derives a new language. Later registrations for the
+ * same tag replace earlier ones. Resolved locales are re-derived lazily.
+ */
+export declare const registerFormulaLocale: (tag: string, definition: FormulaLocaleDefinition) => void;
+/** Remove an application registration (built-in tables are never removed). */
+export declare const unregisterFormulaLocale: (tag: string) => void;
+/** Every tag with a formula-syntax table: the built-in languages plus application registrations. */
+export declare const getFormulaLocaleTags: () => string[];
+/** Localized spelling of a canonical function name (`SUM` → `СУММ`); names without a translation
+ * are returned unchanged. */
+export declare const localizeFunctionName: (name: string, locale?: FormulaLocaleInput | null) => string;
+/** Canonical (English, uppercase) spelling of a localized function name (`СУММ` → `SUM`); names
+ * without a translation are returned unchanged, so English names are accepted in every locale. */
+export declare const canonicalizeFunctionName: (name: string, locale?: FormulaLocaleInput | null) => string;
+/** Localized spelling of a canonical error value (`#VALUE!` → `#ЗНАЧ!`); other text passes through. */
+export declare const localizeErrorValue: <T>(value: T, locale?: FormulaLocaleInput | null) => T | string;
+/** Canonical spelling of a localized error value (`#ЗНАЧ!` → `#VALUE!`); other text passes through. */
+export declare const canonicalizeErrorValue: <T>(value: T, locale?: FormulaLocaleInput | null) => T | string;
+export interface TranslateFormulaOptions {
+    /**
+     * `preserve` (default) keeps the typed casing of names that have no translation in either
+     * direction; `upper` normalizes every known function name to uppercase, the way Excel does on
+     * commit (used to canonicalize test corpora).
+     */
+    functionNameCase?: "preserve" | "upper";
+    /** Build the offset maps (see {@link TranslatedFormula}); off by default. */
+    trackOffsets?: boolean;
+}
+export interface TranslatedFormula {
+    text: string;
+    /**
+     * `toOutput[i]` is the output offset of source offset `i` (`0 ≤ i ≤ source.length`). Inside a
+     * rewritten segment (a translated name, a swapped separator) every interior offset maps to the
+     * segment's start; segment boundaries map exactly. Present when `trackOffsets` was requested.
+     */
+    toOutput?: Int32Array;
+    /** Inverse of {@link toOutput}: `toSource[j]` for `0 ≤ j ≤ text.length`. */
+    toSource?: Int32Array;
+}
+/**
+ * Rewrite formula text from one locale's syntax to another's. This is the single scanner behind
+ * {@link localizeFormula} (canonical → locale) and {@link canonicalizeFormula} (locale → canonical);
+ * see the module comment for what is and is not rewritten.
+ */
+export declare const translateFormula: (text: string, from: FormulaLocaleInput, to: FormulaLocaleInput, options?: TranslateFormulaOptions) => TranslatedFormula;
+/**
+ * Canonical (stored) formula text → the locale's display syntax: `=SUM(1.5,A1)` → `=СУММ(1,5;A1)`
+ * (ru), `=SUMME(1,5;A1)` (de). Identity for the canonical locale.
+ */
+export declare const localizeFormula: (formula: string, locale?: FormulaLocaleInput | null, options?: TranslateFormulaOptions) => string;
+/**
+ * Text typed in the locale's syntax → canonical formula text for storage and evaluation:
+ * `=СУММ(1,5;A1)` → `=SUM(1.5,A1)`. Exact inverse of {@link localizeFormula} on canonical input;
+ * lenient on mixed input (an English name or `,` argument separator typed in a `;` locale is
+ * accepted as long as it is unambiguous).
+ */
+export declare const canonicalizeFormula: (formula: string, locale?: FormulaLocaleInput | null, options?: TranslateFormulaOptions) => string;
+/**
+ * What the editor / formula bar SHOWS for a stored cell entry: a formula in the locale's syntax, a
+ * typed error value in the locale's spelling, any other text unchanged (`1,5` typed in de-DE is a
+ * number literal the datatype parser already reads with the locale's separators).
+ */
+export declare const localizeCellInput: (text: string, locale?: FormulaLocaleInput | null) => string;
+/** Inverse of {@link localizeCellInput}: what the editor COMMITS — canonical formula text / error value. */
+export declare const canonicalizeCellInput: (text: string, locale?: FormulaLocaleInput | null) => string;
+/**
+ * Localize a function's documented syntax (`SUM(value1, [value2, ...])` → `СУММ(value1; [value2;
+ * ...])`): the leading name through the dictionary, every `,` outside double quotes through the
+ * argument separator. The square brackets here mark OPTIONAL arguments (not structured references),
+ * so — unlike {@link localizeFormula} — the separators inside them are localized too.
+ */
+export declare const localizeFunctionSyntax: (syntax: string, locale?: FormulaLocaleInput | null) => string;
+/** A {@link CalculatorFunction} with its name, syntax, example and usage lines localized. */
+export declare const localizeFunctionDescription: (fn: CalculatorFunction, locale?: FormulaLocaleInput | null) => CalculatorFunction;
+/** {@link localizeFunctionDescription} over a catalog; the same array instance for the canonical locale. */
+export declare const localizeFunctionDescriptions: <T extends CalculatorFunction[] | null | undefined>(functions: T, locale?: FormulaLocaleInput | null) => T;
+//# sourceMappingURL=formula-locale.d.ts.map

package/dist/cjs/formula-locale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formula-locale.d.ts","sourceRoot":"","sources":["../../formula-locale.ts"],"names":[],"mappings":"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"}