@rowsncolumns/utils 9.2.44 → 9.4.0

package/dist/esm/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/esm/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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"}

package/dist/esm/index.d.ts

@@ -24,4 +24,8 @@ export * from "./content-hash";
 export * from "./shared-string-canonical";
 export * from "./keyboard";
 export * from "./sheet-span";
+export * from "./formula-locale";
+export * from "./table-names";
+export * from "./table-totals";
+export * from "./sparkline-groups";
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,OAAO,CAAC;AACtB,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,OAAO,CAAC;AACtB,cAAc,SAAS,CAAC;AACxB,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,QAAQ,CAAC;AACvB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,OAAO,CAAC;AACtB,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,OAAO,CAAC;AACtB,cAAc,SAAS,CAAC;AACxB,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,QAAQ,CAAC;AACvB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC"}

package/dist/esm/index.js

@@ -24,3 +24,7 @@ export * from "./content-hash";
 export * from "./shared-string-canonical";
 export * from "./keyboard";
 export * from "./sheet-span";
+export * from "./formula-locale";
+export * from "./table-names";
+export * from "./table-totals";
+export * from "./sparkline-groups";

package/dist/esm/sparkline-groups.d.ts

@@ -0,0 +1,102 @@
+import type { CellInterface, GridRange, SparkLineResultOptions } from "@rowsncolumns/common-types";
+/**
+ * Excel sparkline groups (Insert → Sparklines → Line / Column / Win-Loss) on top of the
+ * `=SPARKLINE(dataRange, {options})` cell formula — the shape the XLSX importers of BOTH engines
+ * produce for an `<x14:sparklineGroup>` (one formula per `<x14:sparkline>`, the group's attributes
+ * as the option literal) and the shape the exporters fold back into a group (cells sharing one option
+ * fingerprint share one `<x14:sparklineGroup>`). A group therefore has no separate document object:
+ * it is the connected run of location cells whose SPARKLINE formulas carry identical options. That
+ * keeps live recalc, reference shifting on insert/delete and the round-trip as ordinary formula
+ * behavior on both engines.
+ */
+export type SparklineGroupType = "line" | "column" | "winloss";
+/** One sparkline of a group: the cell it paints in and the data range it charts. */
+export type SparklineGroupMember = {
+    cell: CellInterface;
+    /** As written in the formula (optionally sheet-qualified, e.g. `Data!A2:E2`). */
+    dataRange: string;
+};
+/** The group options (everything but `charttype`, which is the group's `type`). */
+export type SparklineGroupOptions = Omit<SparkLineResultOptions, "charttype">;
+export type SparklineGroup = {
+    sheetId: number;
+    type: SparklineGroupType;
+    options: SparklineGroupOptions;
+    /** In location order (top → bottom, then left → right). */
+    members: SparklineGroupMember[];
+};
+export type ParsedSparklineFormula = {
+    dataRange: string;
+    options: SparkLineResultOptions;
+};
+export declare const isSparklineFormula: (formula: unknown) => formula is string;
+/**
+ * `=SPARKLINE(A1:E1,{"charttype","column","color","#FF0000"})` → its data range and options with the
+ * keys canonicalized to `SparkLineResultOptions` (both option-literal shapes and the legacy
+ * `highpoint`/… spellings are accepted). `null` when the formula is not a SPARKLINE call.
+ */
+export declare const parseSparklineFormula: (formula: string) => ParsedSparklineFormula | null;
+/**
+ * The inverse of {@link parseSparklineFormula}: `=SPARKLINE(range)` when no option is set, else
+ * `=SPARKLINE(range,{"k",v,…})` in the importers' emission order. Unset, `false` and `line`
+ * (the default type) options are omitted.
+ */
+export declare const buildSparklineFormula: (dataRange: string, options?: SparkLineResultOptions) => string;
+export declare const sparklineTypeFromOptions: (options: SparkLineResultOptions | undefined) => SparklineGroupType;
+/** Group identity: two SPARKLINE cells belong to one group when this string matches. */
+export declare const sparklineOptionsFingerprint: (options: SparkLineResultOptions) => string;
+export type ResolveSparklineGroupArgs = {
+    sheetId: number;
+    cell: CellInterface;
+    /** The user-entered formula of a cell (`undefined` for a non-formula cell). */
+    getFormula: (sheetId: number, rowIndex: number, columnIndex: number) => string | undefined;
+    /** Upper bound on the cells walked (a runaway sheet-wide fill would freeze the UI). */
+    maxCells?: number;
+};
+/**
+ * The sparkline group containing `cell`: the 4-connected run of SPARKLINE cells around it whose
+ * options match the cell's. `undefined` when the cell holds no SPARKLINE formula.
+ */
+export declare const resolveSparklineGroup: ({ sheetId, cell, getFormula, maxCells, }: ResolveSparklineGroupArgs) => SparklineGroup | undefined;
+export type ParsedRangeAddress = {
+    /** The sheet name as typed (quotes removed), `undefined` for a local reference. */
+    sheetName?: string;
+    range: GridRange;
+};
+/** `'Q1 Data'!A1:E5` / `Sheet1!A1` / `$A$1:$E$5` → its sheet name and grid range. */
+export declare const parseRangeAddress: (address: string) => ParsedRangeAddress | null;
+/** A grid range → `A1:E5` (a single cell → `A1`), optionally sheet-qualified. */
+export declare const rangeToA1: (range: GridRange, sheetName?: string) => string;
+export type PlanSparklineGroupArgs = {
+    /** Excel's "Data Range" (may be sheet-qualified). */
+    dataRange: string;
+    /** Excel's "Location Range" — a single row or column of cells on the group's sheet. */
+    locationRange: string;
+};
+export type SparklineGroupPlan = {
+    members: SparklineGroupMember[];
+    error?: undefined;
+} | {
+    members?: undefined;
+    error: string;
+};
+/**
+ * Excel's Create Sparklines rule: one sparkline per location cell, each charting one row (or one
+ * column) of the data range. A single location cell charts the whole data range; otherwise the data
+ * range must span exactly as many rows, or exactly as many columns, as the location has cells.
+ */
+export declare const planSparklineGroup: ({ dataRange, locationRange, }: PlanSparklineGroupArgs) => SparklineGroupPlan;
+/**
+ * The location Excel's dialog is seeded with for a data selection: the column just right of the
+ * data (one sparkline per data row), or the cell right of a single-row selection.
+ */
+export declare const defaultSparklineLocation: (data: GridRange) => GridRange;
+/** The bounding range of a group's location cells (its members are a single row or column run). */
+export declare const sparklineGroupLocation: (group: SparklineGroup) => GridRange;
+/**
+ * The group's "Data Range" as Excel's Edit Group dialog shows it: the union of the members' ranges
+ * when they tile one rectangle by rows or columns; otherwise `undefined` (members chart unrelated
+ * ranges — Excel then shows the individual ranges only).
+ */
+export declare const sparklineGroupDataRange: (group: SparklineGroup) => string | undefined;
+//# sourceMappingURL=sparkline-groups.d.ts.map

package/dist/esm/sparkline-groups.d.ts.map

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