@odoo/o-spreadsheet 19.2.11 → 19.4.0-alpha.4

package/dist/types/constants.d.ts

@@ -0,0 +1,172 @@
+import { ChartColorScale } from "./types/chart/chart";
+import { Currency } from "./types/currency";
+import { BorderDescr, Color } from "./types/misc";
+export declare const CANVAS_SHIFT = 0.5;
+export declare const HIGHLIGHT_COLOR = "#017E84";
+export declare const SELECTION_BORDER_COLOR = "#3266ca";
+export declare const DEFAULT_COLOR_SCALE_MIDPOINT_COLOR = 11982760;
+export declare const LINK_COLOR = "#017E84";
+export declare const FILTERS_COLOR = "#188038";
+export declare const FROZEN_PANE_HEADER_BORDER_COLOR = "#BCBCBC";
+export declare const FROZEN_PANE_BORDER_COLOR = "#DADFE8";
+export declare const COMPOSER_ASSISTANT_COLOR = "light-dark(#9B359B, #B972A6)";
+export declare const COLOR_TRANSPARENT = "#00000000";
+export declare const TABLE_HOVER_BACKGROUND_COLOR = "#017E8414";
+export declare const CHART_WATERFALL_POSITIVE_COLOR = "#4EA7F2";
+export declare const CHART_WATERFALL_NEGATIVE_COLOR = "#EA6175";
+export declare const CHART_WATERFALL_SUBTOTAL_COLOR = "#AAAAAA";
+export declare const MIN_BUBBLE_RADIUS = 10;
+export declare const DEFAULT_BUBBLE_RADIUS = 2;
+export declare const MAX_BUBBLE_RADIUS = 30;
+export declare const GRAY_900 = "#111827";
+export declare const GRAY_400 = "#ced4da";
+export declare const GRAY_300 = "#D8DADD";
+export declare const GRAY_200 = "#E7E9ED";
+export declare const TEXT_BODY = "#374151";
+export declare const TEXT_BODY_MUTED: string;
+export declare const ACTION_COLOR = "#017E84";
+export declare const CHART_PADDING = 20;
+export declare const CHART_PADDING_BOTTOM = 10;
+export declare const CHART_PADDING_TOP = 15;
+export declare const CHART_TITLE_FONT_SIZE = 16;
+export declare const CHART_AXIS_TITLE_FONT_SIZE = 12;
+export declare const MASTER_CHART_HEIGHT = 60;
+export declare const CHART_COLORSCALE_WIDTH = 70;
+export declare const DEFAULT_CHART_COLOR_SCALE: ChartColorScale;
+export declare const SCORECARD_CHART_TITLE_FONT_SIZE = 14;
+export declare const PIVOT_TOKEN_COLOR = "#F28C28";
+export declare const COLOR_PICKER_DEFAULTS: Color[];
+export declare const MIN_ROW_HEIGHT = 10;
+export declare const MIN_COL_WIDTH = 5;
+export declare const HEADER_HEIGHT = 26;
+export declare const HEADER_WIDTH = 48;
+export declare const DESKTOP_TOPBAR_TOOLBAR_HEIGHT = 34;
+export declare const DESKTOP_BOTTOMBAR_HEIGHT = 36;
+export declare const DEFAULT_CELL_WIDTH = 96;
+export declare const DEFAULT_CELL_HEIGHT = 23;
+export declare const SCROLLBAR_WIDTH = 15;
+export declare const AUTOFILL_EDGE_LENGTH = 8;
+export declare const ICON_EDGE_LENGTH = 18;
+export declare const MIN_CF_ICON_MARGIN = 4;
+export declare const MIN_CELL_TEXT_MARGIN = 4;
+export declare const PADDING_AUTORESIZE_VERTICAL = 3;
+export declare const PADDING_AUTORESIZE_HORIZONTAL = 4;
+export declare const GROUP_LAYER_WIDTH = 21;
+export declare const GRID_ICON_MARGIN = 2;
+export declare const GRID_ICON_EDGE_LENGTH = 17;
+export declare const FOOTER_HEIGHT: number;
+export declare const DATA_VALIDATION_CHIP_MARGIN = 5;
+export declare const MOBILE_WIDTH_BREAKPOINT = 768;
+export declare const MENU_WIDTH = 250;
+export declare const MENU_VERTICAL_PADDING = 6;
+export declare const DESKTOP_MENU_ITEM_HEIGHT = 26;
+export declare const MENU_SEPARATOR_BORDER_WIDTH = 1;
+export declare const MENU_SEPARATOR_PADDING = 5;
+export declare const MENU_SEPARATOR_HEIGHT: number;
+export declare const ZOOM_VALUES: number[];
+export declare const DEFAULT_STYLE: {
+    align: "left";
+    verticalAlign: "bottom";
+    wrapping: "overflow";
+    bold: false;
+    italic: false;
+    strikethrough: false;
+    underline: false;
+    fontSize: number;
+    fillColor: string;
+    textColor: string;
+    rotation: number;
+    hideGridLines: false;
+};
+export declare const ROTATION_EPSILON = 0.001;
+export declare const DEFAULT_NUMBER_STYLE: {
+    align: "right";
+    verticalAlign: "bottom";
+    wrapping: "overflow";
+    bold: false;
+    italic: false;
+    strikethrough: false;
+    underline: false;
+    fontSize: number;
+    fillColor: string;
+    textColor: string;
+    rotation: number;
+    hideGridLines: false;
+};
+export declare const DEFAULT_VERTICAL_ALIGN: "bottom";
+export declare const DEFAULT_WRAPPING_MODE: "overflow";
+export declare const DEFAULT_FONT_WEIGHT = "400";
+export declare const DEFAULT_FONT_SIZE: number;
+export declare const HEADER_FONT_SIZE = 11;
+export declare const DEFAULT_FONT = "'Roboto', arial";
+export declare const DEFAULT_BORDER_DESC: BorderDescr;
+export declare const DEFAULT_FILTER_BORDER_DESC: BorderDescr;
+export declare const MAX_HISTORY_STEPS = 99;
+export declare const DEFAULT_REVISION_ID = "START_REVISION";
+export declare const DEFAULT_FIGURE_HEIGHT = 335;
+export declare const DEFAULT_FIGURE_WIDTH = 536;
+export declare const FIGURE_BORDER_WIDTH = 1;
+export declare const ACTIVE_BORDER_WIDTH = 2;
+export declare const MIN_FIG_SIZE = 80;
+export declare const MAX_CHAR_LABEL = 20;
+export declare const FIGURE_ID_SPLITTER = "??";
+export declare const DEFAULT_GAUGE_LOWER_COLOR = "#EA6175";
+export declare const DEFAULT_GAUGE_MIDDLE_COLOR = "#FFD86D";
+export declare const DEFAULT_GAUGE_UPPER_COLOR = "#43C5B1";
+export declare const DEFAULT_SCORECARD_BASELINE_MODE = "difference";
+export declare const DEFAULT_SCORECARD_BASELINE_COLOR_UP = "#43C5B1";
+export declare const DEFAULT_SCORECARD_BASELINE_COLOR_DOWN = "#EA6175";
+export declare const DEFAULT_SCORECARD_KEY_VALUE_FONT_SIZE = 32;
+export declare const DEFAULT_SCORECARD_BASELINE_FONT_SIZE = 16;
+export declare const LINE_FILL_TRANSPARENCY = 0.4;
+export declare const LINE_DATA_POINT_RADIUS = 3;
+export declare const DEFAULT_WINDOW_SIZE = 2;
+export declare const MESSAGE_VERSION = 1;
+export declare const FORBIDDEN_SHEETNAME_CHARS: readonly ["'", "*", "?", "/", "\\", "[", "]"];
+export declare const FORBIDDEN_SHEETNAME_CHARS_IN_EXCEL_REGEX: RegExp;
+export declare const FORMULA_REF_IDENTIFIER = "|";
+export declare const LOADING = "Loading...";
+/**
+ * The viewport dimensions are usually set by one of the components
+ * (i.e. when grid component is mounted) to properly reflect its state in the DOM.
+ * In the absence of a component (standalone model), is it mandatory to set reasonable default values
+ * to ensure the correct operation.
+ */
+export declare function getDefaultSheetViewSize(): number;
+export declare function setDefaultSheetViewSize(size: number): void;
+export declare const MAXIMAL_FREEZABLE_RATIO = 0.85;
+export declare const NEWLINE = "\n";
+export declare const FONT_SIZES: number[];
+export declare const PIVOT_STATIC_TABLE_CONFIG: {
+    hasFilters: boolean;
+    totalRow: boolean;
+    firstColumn: boolean;
+    lastColumn: boolean;
+    numberOfHeaders: number;
+    bandedRows: boolean;
+    bandedColumns: boolean;
+    styleId: string;
+    automaticAutofill: boolean;
+};
+export declare const PIVOT_INSERT_TABLE_STYLE_ID = "PivotTableStyleMedium12";
+export declare const PIVOT_INDENT = 15;
+export declare const PIVOT_COLLAPSE_ICON_SIZE = 12;
+export declare const PIVOT_MAX_NUMBER_OF_CELLS = 500000;
+export declare const DEFAULT_CURRENCY: Currency;
+export declare const DEFAULT_CAROUSEL_TITLE_STYLE: {
+    fontSize: number;
+    color: string;
+};
+export declare const DEFAULT_TOKEN_COLOR: Color;
+export declare const tokenColors: {
+    readonly OPERATOR: "#3da4ab";
+    readonly NUMBER: "#02c39a";
+    readonly STRING: "#00a82d";
+    readonly FUNCTION: Color;
+    readonly DEBUGGER: "#3da4ab";
+    readonly LEFT_PAREN: Color;
+    readonly RIGHT_PAREN: Color;
+    readonly ARG_SEPARATOR: Color;
+    readonly ORPHAN_RIGHT_PAREN: "#ff0000";
+};
+export declare const DRAG_THRESHOLD = 5;

package/dist/types/formulas/code_builder.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Block of code that produces a value.
+ */
+export interface FunctionCode {
+    readonly returnExpression: string;
+    /**
+     * Return the same function code but with the return expression assigned to a variable.
+     */
+    assignResultToVariable(): FunctionCode;
+}
+export declare class FunctionCodeBuilder {
+    private scope;
+    private code;
+    constructor(scope?: Scope);
+    append(...lines: (string | FunctionCode)[]): void;
+    return(expression: string): FunctionCode;
+    toString(): string;
+}
+export declare class Scope {
+    private nextId;
+    private declaredVariables;
+    nextVariableName(): string;
+    isAlreadyDeclared(name: string): boolean;
+}

package/dist/types/formulas/compiler.d.ts

@@ -0,0 +1,108 @@
+import { CoreGetters } from "../types/core_getters";
+import { ApplyRangeChange, ApplyRenameNamedRange, FormulaToExecute, LiteralValues, NamedRange, UID } from "../types/misc";
+import { Range, RangeStringOptions } from "../types/range";
+import { AST } from "./parser";
+import { Token } from "./tokenizer";
+export declare const OPERATOR_MAP: {
+    "=": string;
+    "+": string;
+    "-": string;
+    "*": string;
+    "/": string;
+    ">=": string;
+    "<>": string;
+    ">": string;
+    "<=": string;
+    "<": string;
+    "^": string;
+    "&": string;
+};
+export declare const UNARY_OPERATOR_MAP: {
+    "-": string;
+    "+": string;
+    "%": string;
+    "#": string;
+};
+interface ICompiledFormula {
+    execute: FormulaToExecute;
+    tokens: Token[];
+    dependencies: string[];
+    isBadExpression: boolean;
+    normalizedFormula: string;
+    literalValues: LiteralValues;
+    symbols: string[];
+}
+export declare const functionCache: {
+    [key: string]: FormulaToExecute;
+};
+/**
+ * A compiled formula is the result of the compilation of a formula string.
+ * It contains all the information needed to execute the formula, as well as some metadata
+ * about the formula (dependencies, literal values, symbols...) that can be used to rebuild a slightly different formula
+ * without recompiling it (for example when the formula is copied to another cell, or when we want to replace literal values but keep the same structure).
+ * */
+export declare class CompiledFormula implements Omit<ICompiledFormula, "tokens" | "dependencies"> {
+    readonly sheetId: UID;
+    private readonly tokens;
+    readonly literalValues: LiteralValues;
+    readonly symbols: string[];
+    readonly isBadExpression: boolean;
+    readonly normalizedFormula: string;
+    readonly execute: FormulaToExecute;
+    readonly rangeDependencies: Range[];
+    hasDependencies: boolean;
+    private constructor();
+    private getTokens;
+    getAst(getters: CoreGetters): AST;
+    /**
+     * Return the string representation of the formula, with the current dependencies and literal values.
+     * This is a heavy operation as it converts the rangeDependencies to string on each call.
+     * */
+    toFormulaString(getters: CoreGetters, referenceOption?: RangeStringOptions): string;
+    getNamedRangesInFormula(getters: CoreGetters): NamedRange[];
+    usesSymbol(symbol: string): boolean;
+    areAllFunctionsExportableToExcel(): boolean;
+    getFunctionsFromTokens(functionNames: string[], getters: CoreGetters): {
+        functionName: string;
+        args: AST[];
+    }[];
+    isFirstNonWhitespaceSymbol(tokenValue: string): boolean;
+    adaptCompiledFormula(applyChange: ApplyRangeChange, applyUpdateNamedRange: ApplyRenameNamedRange): CompiledFormula;
+    /** Change the symbols and tokens on a named range change. Return undefined if nothing has changed. */
+    private renameNamedRangeTokens;
+    static IsBadExpression(formula: string): boolean;
+    /**
+     * Recreates a CompiledFormula based on `base` with adapted dependencies.
+     * */
+    static CopyWithDependencies(base: CompiledFormula, sheetId: UID, dependencies: Range[]): CompiledFormula;
+    /**
+     * Recreates a CompiledFormula based on `base` with adapted dependencies and/or different literal values.
+     * */
+    static CopyWithDependenciesAndLiteral(base: CompiledFormula, sheetId: UID, dependencies: Range[], literalNumbers: {
+        value: number;
+    }[], literalStrings: {
+        value: string;
+    }[]): CompiledFormula;
+    /**
+     * When copy/pasting a formula across sheets, the formula is serialized (all it's serializable properties are kept) and deserialized on the new sheet.
+     * This function allows to recompile the formula based on the serializable properties.
+     * */
+    static CompileForSerializedFormula(sheetId: UID, base: SerializedCompiledFormula): CompiledFormula;
+    /**
+     * Make a new instance of CompiledFormula by compiling the formula string as input by the user.
+     * */
+    static Compile(formula: string, sheetId: UID, getters: CoreGetters): CompiledFormula;
+}
+/**
+ * A compiled formula serialized
+ * */
+export type SerializedCompiledFormula = {
+    sheetId: UID;
+    tokens: Token[];
+    literalValues: LiteralValues;
+    symbols: string[];
+    rangeDependencies: Range[];
+    isBadExpression: boolean;
+    normalizedFormula: string;
+};
+export {};

package/dist/types/formulas/composer_tokenizer.d.ts

@@ -0,0 +1,54 @@
+import { Locale } from "../types/locale";
+import { Color } from "../types/misc";
+import { AST } from "./parser";
+import { Token } from "./tokenizer";
+interface FunctionContext {
+    /**
+     * The parent function name of the token.
+     */
+    parent: string;
+    /**
+     * The position of the token within the argument list of its parent function.
+     */
+    argPosition: number;
+    /**
+     * An array of parsed arguments, possibly containing undefined values if the argument
+     * is empty or is an invalid expression.
+     */
+    args: (AST | undefined)[];
+    /**
+     * Array of token arrays representing the tokens for each argument.
+     * Needed as an intermediate step to parse the arguments AST (see `args` property).
+     */
+    argsTokens?: Token[][];
+}
+/**
+ * Enriched Token is used by the composer to add information on the tokens that
+ * are only needed during the edition of a formula.
+ *
+ * The information added are:
+ * - start, end and length of each token
+ * - parenthesesCode (a code indicating the position of the token in the parentheses tree)
+ * - functionContext (only for tokens surrounded by a function)
+ * - color (the base color of the token, without fading modification)
+ * - isBlurred (indicates whether the text should be highlighted or not, useful to know if the token matches the same formula as the cursor token)
+ * - isParenthesisLinkedToCursor (Useful for highlighting tokens related to the current token, such as matching parentheses)
+ */
+export interface EnrichedToken extends Token {
+    start: number;
+    end: number;
+    length: number;
+    parenthesesCode?: string;
+    functionContext?: FunctionContext;
+    color?: Color;
+    isBlurred?: boolean;
+    isParenthesisLinkedToCursor?: boolean;
+    isInHoverContext?: boolean;
+}
+/**
+ * Take the result of the tokenizer and transform it to be usable in the composer.
+ *
+ * @param formula
+ */
+export declare function composerTokenize(formula: string, locale: Locale): EnrichedToken[];
+export {};

package/dist/types/formulas/formula_formatter.d.ts

@@ -0,0 +1,18 @@
+import { AST } from "./parser";
+/**
+ * Pretty-prints formula ASTs into readable formulas.
+ *
+ * Implements a Wadler-inspired pretty printer:
+ * it converts an AST into a `Doc` structure,
+ * and then chooses between compact (flat) or expanded (with
+ * line breaks and indentation) layouts depending on space.
+ *
+ * References:
+ * - https://lik.ai/blog/how-a-pretty-printer-works/
+ * - Wadler, "A prettier printer": https://homepages.inf.ed.ac.uk/wadler/papers/prettier/prettier.pdf
+ */
+export declare function prettify(ast: AST, width?: number): string;
+/**
+ * Converts an ast formula to the corresponding string
+ */
+export declare function astToFormula(ast: AST): string;

package/dist/types/formulas/parser.d.ts

@@ -0,0 +1,107 @@
+import { Token } from "./tokenizer";
+interface RichToken extends Token {
+    tokenIndex: number;
+}
+export declare class TokenList {
+    private tokens;
+    currentIndex: number;
+    current: RichToken | undefined;
+    length: number;
+    constructor(tokens: RichToken[]);
+    shift(): RichToken;
+    get next(): RichToken | undefined;
+}
+interface ASTBase {
+    debug?: boolean;
+    tokenStartIndex: number;
+    tokenEndIndex: number;
+}
+interface ASTNumber extends ASTBase {
+    type: "NUMBER";
+    value: number;
+}
+interface ASTReference extends ASTBase {
+    type: "REFERENCE";
+    value: string;
+}
+export interface ASTString extends ASTBase {
+    type: "STRING";
+    value: string;
+}
+interface ASTBoolean extends ASTBase {
+    type: "BOOLEAN";
+    value: boolean;
+}
+export interface ASTUnaryOperation extends ASTBase {
+    type: "UNARY_OPERATION";
+    value: any;
+    operand: AST;
+    postfix?: boolean;
+}
+export interface ASTOperation extends ASTBase {
+    type: "BIN_OPERATION";
+    value: any;
+    left: AST;
+    right: AST;
+}
+export interface ASTFuncall extends ASTBase {
+    type: "FUNCALL";
+    value: string;
+    args: AST[];
+}
+export interface ASTSymbol extends ASTBase {
+    type: "SYMBOL";
+    value: string;
+}
+export interface ASTArray extends ASTBase {
+    type: "ARRAY";
+    value: AST[][];
+}
+interface ASTEmpty extends ASTBase {
+    type: "EMPTY";
+    value: "";
+}
+export type AST = ASTOperation | ASTUnaryOperation | ASTFuncall | ASTSymbol | ASTArray | ASTNumber | ASTBoolean | ASTString | ASTReference | ASTEmpty;
+export declare const OP_PRIORITY: {
+    "#": number;
+    "%": number;
+    "^": number;
+    "*": number;
+    "/": number;
+    "+": number;
+    "-": number;
+    "&": number;
+    ">": number;
+    "<>": number;
+    ">=": number;
+    "<": number;
+    "<=": number;
+    "=": number;
+};
+/**
+ * Parse an expression (as a string) into an AST.
+ */
+export declare function parse(str: string): AST;
+export declare function parseTokens(tokens: readonly Token[]): AST;
+/**
+ * Allows to visit all nodes of an AST and apply a mapping function
+ * to nodes of a specific type.
+ * Useful if you want to convert some part of a formula.
+ *
+ * @example
+ * convertAstNodes(ast, "FUNCALL", convertFormulaToExcel)
+ *
+ * function convertFormulaToExcel(ast: ASTFuncall) {
+ *   // ...
+ *   return modifiedAst
+ * }
+ */
+export declare function convertAstNodes<T extends AST["type"]>(ast: AST, type: T, fn: (ast: Extract<AST, {
+    type: T;
+}>) => AST): AST;
+export declare function iterateAstNodes(ast: AST): AST[];
+export declare function mapAst<T extends AST["type"]>(ast: AST, fn: (ast: Extract<AST, {
+    type: T;
+}>) => AST): AST;
+export declare function isFuncallToken(currentToken: Token, nextToken: Token | undefined): boolean;
+export {};

package/dist/types/formulas/range_tokenizer.d.ts

@@ -0,0 +1,8 @@
+import { Token } from "./tokenizer";
+/**
+ * Take the result of the tokenizer and transform it to be usable in the
+ * manipulations of range
+ *
+ * @param formula
+ */
+export declare function rangeTokenize(formula: string, locale?: import("..").Locale): Token[];

package/dist/types/formulas/tokenizer.d.ts

@@ -0,0 +1,26 @@
+import { type Locale } from "../types/locale";
+/**
+ * Tokenizer
+ *
+ * A tokenizer is a piece of code whose job is to transform a string into a list
+ * of "tokens". For example, "(12+" is converted into:
+ *   [{type: "LEFT_PAREN", value: "("},
+ *    {type: "NUMBER", value: "12"},
+ *    {type: "OPERATOR", value: "+"}]
+ *
+ * As the example shows, a tokenizer does not care about the meaning behind those
+ * tokens. It only cares about the structure.
+ *
+ * The tokenizer is usually the first step in a compilation pipeline.  Also, it
+ * is useful for the composer, which needs to be able to work with incomplete
+ * formulas.
+ */
+export declare const POSTFIX_UNARY_OPERATORS: string[];
+export declare const DEBUGGER_CHAR = "?";
+type TokenType = "OPERATOR" | "NUMBER" | "STRING" | "SYMBOL" | "SPACE" | "DEBUGGER" | "ARG_SEPARATOR" | "ARRAY_ROW_SEPARATOR" | "LEFT_PAREN" | "RIGHT_PAREN" | "LEFT_BRACE" | "RIGHT_BRACE" | "REFERENCE" | "INVALID_REFERENCE" | "UNKNOWN";
+export interface Token {
+    readonly type: TokenType;
+    value: string;
+}
+export declare function tokenize(str: string, locale?: Locale): Token[];
+export {};

package/dist/types/functions/arguments.d.ts

@@ -0,0 +1,90 @@
+import { AddFunctionDescription, ArgDefinition, ArgProposal, FunctionDescription } from "../types/functions";
+import { Immutable } from "../types/misc";
+export declare function arg(definition: string, description?: string, proposals?: ArgProposal[]): ArgDefinition;
+/**
+ * This function adds on description more general information derived from the
+ * arguments.
+ *
+ * This information is useful during compilation.
+ */
+export declare function addMetaInfoFromArg(name: string, addDescr: AddFunctionDescription): FunctionDescription;
+type ArgToFocus = Immutable<Record<number, {
+    index: number;
+    repeatingGroupIndex?: number;
+}>>;
+/**
+ * Returns a function that maps the position of a value in a function to its corresponding argument index.
+ *
+ * In most cases, the task is straightforward:
+ *
+ * In the formula "=SUM(11, 55, 66)" which is defined like this "SUM(value1, [value2, ...])":
+ * - 11 corresponds to the value1 argument => position will be 0
+ * - 55 and 66 correspond to the [value2, ...] argument => position will be 1
+ *
+ * In other cases, optional arguments could be defined after repeatable arguments,
+ * or even optional and required arguments could be mixed in unconventional ways.
+ *
+ * The next function has been designed to handle all possible configurations.
+ * The only restriction is if repeatable arguments are present in the function definition:
+ * - they must be defined consecutively
+ * - they must be in a quantity greater than the optional arguments.
+ *
+ * The markdown tables below illustrate how values are mapped to positions based on the number of values supplied.
+ * Each table represents a different function configuration, with columns representing the number of values supplied as arguments
+ * and rows representing the correspondence with the argument index.
+ *
+ * The tables are built based on the following conventions:
+ * - `m`: Mandatory argument (count as one argument)
+ * - `o`: Optional argument (count as zero or one argument)
+ * - `r`: Repeating argument (count as one or more arguments)
+ *
+ *
+ * Configuration 1: (m, o) like the CEILING function
+ *
+ * |   | 1 | 2 |
+ * |---|---|---|
+ * | m | 0 | 0 |
+ * | o |   | 1 |
+ *
+ *
+ * Configuration 2: (m, m, m, r, r) like the SUMIFS function
+ *
+ * |   | 5 | 7    | 3 + 2n     |
+ * |---|---|------|------------|
+ * | m | 0 | 0    | 0          |
+ * | m | 1 | 1    | 1          |
+ * | m | 2 | 2    | 2          |
+ * | r | 3 | 3, 5 | 3 + 2n     |
+ * | r | 4 | 4, 6 | 3 + 2n + 1 |
+ *
+ *
+ * Configuration 3: (m, m, m, r, r, o) like the SWITCH function
+ *
+ * |   | 5 | 6 | 7    | 8    | 3 + 2n     | 3 + 2n + 1     |
+ * |---|---|---|------|------|------------|----------------|
+ * | m | 0 | 0 | 0    | 0    | 0          | 0              |
+ * | m | 1 | 1 | 1    | 1    | 1          | 1              |
+ * | m | 2 | 2 | 2    | 2    | 2          | 2              |
+ * | r | 3 | 3 | 3, 5 | 3, 5 | 3 + 2n     | 3 + 2n         |
+ * | r | 4 | 4 | 4, 6 | 4, 6 | 3 + 2n + 1 | 3 + 2n + 1     |
+ * | o |   | 5 |      | 7    |            | 3 + 2N + 2     |
+ *
+ *
+ * Configuration 4: (m, o, m, o, r, r, r, m) a complex case to understand subtleties
+ *
+ * |   | 6 | 7 | 8 | 9    | 10   | 11   | ... |
+ * |---|---|---|---|------|------|------|-----|
+ * | m | 0 | 0 | 0 | 0    | 0    | 0    | ... |
+ * | o |   | 1 | 1 |      | 1    | 1    | ... |
+ * | m | 1 | 2 | 2 | 1    | 2    | 2    | ... |
+ * | o |   |   | 3 |      |      | 3    | ... |
+ * | r | 2 | 3 | 4 | 2, 5 | 3, 6 | 4, 7 | ... |
+ * | r | 3 | 4 | 5 | 3, 6 | 4, 7 | 5, 8 | ... |
+ * | r | 4 | 5 | 6 | 4, 7 | 5, 8 | 6, 9 | ... |
+ * | m | 5 | 6 | 7 | 8    | 9    | 10   | ... |
+ *
+ */
+export declare function argTargeting(functionDescription: FunctionDescription, nbrArgSupplied: number): ArgToFocus;
+export declare function _argTargeting(functionDescription: FunctionDescription, nbrArgSupplied: number): ArgToFocus;
+export declare function validateArguments(descr: FunctionDescription): void;
+export {};

package/dist/types/functions/autocomplete_arguments_provider.d.ts

@@ -0,0 +1,13 @@
+import { CellComposerStore } from "../components/composer/composer/cell_composer_store";
+import { EnrichedToken } from "../formulas/composer_tokenizer";
+import { AutoCompleteProposal } from "../registries/auto_completes/auto_complete_registry";
+import { ArgDefinition } from "../types/functions";
+export declare function createAutocompleteArgumentsProvider(formulaName: string, args: ArgDefinition[]): void;
+/**
+ * Perform the autocomplete of the composer by inserting the value
+ * at the cursor position, replacing the current token if necessary.
+ * Must be bound to the autocomplete provider.
+ */
+export declare function insertTokenAtArgStartingPosition(this: {
+    composer: CellComposerStore;
+}, tokenAtCursor: EnrichedToken, proposal: AutoCompleteProposal): void;

package/dist/types/functions/create_compute_function.d.ts

@@ -0,0 +1,42 @@
+import { ComputeFunction, EvalContext, FunctionDescription } from "../types/functions";
+import { Arg, FunctionResultObject, Matrix } from "../types/misc";
+/**
+ * Enables a formula function to accept matrix or vector inputs instead of simple value, computing results across multiple dimensions.
+ *
+ * ```
+ *                    /         |‾                 ‾| \        |‾                                                    ‾|
+ *                   |          | [A]               |  |       | compute(A, D, E), compute(A, D, F), compute(A, D, G) |
+ * applyVectorization| compute, | [B], D, [E, F, G] |  |  <=>  | compute(B, D, E), compute(B, D, F), compute(B, D, G) |
+ *                   |          | [C]               |  |       | compute(C, D, E), compute(C, D, F), compute(C, D, G) |
+ *                    \         |_                 _| /        |_                                                    _|
+ * ```
+ *
+ * By default, all arguments are vectorized. To control which arguments are vectorized,
+ * pass an `acceptToVectorize` boolean array of the same length as `args`:
+ * - `true`  enables vectorization for that argument
+ * - `false` disables vectorization for that argument
+ *
+ * For example, with `[true, true, false]` on previous example you get:
+ *
+ * ```
+ * |‾                        ‾|
+ * | compute(A, D, [E, F, G]) |
+ * | compute(B, D, [E, F, G]) |
+ * | compute(C, D, [E, F, G]) |
+ * |_                        _|
+ * ```
+ *
+ * @remarks
+ * This helper is automatically applied (by default) to **all** `compute` functions
+ * across the various spreadsheet formula modules:
+ * - If an argument is declared **scalar** (not `"range"`), it is vectorized.
+ * - If **all** arguments are declared **ranges**, no vectorization occurs.
+ *   - e.g. `SUM(A1:B2)` returns a 1×1 sum over the range.
+ *   - e.g. `COS(A1:B2)` over `A1:B2` returns a 2×2 element-wise result.
+ * - For special behaviors (e.g. the `IF` function), you may declare all arguments
+ *   as ranges and invoke this helper directly within your `compute` implementation.
+ */
+export declare function applyVectorization(context: EvalContext, descr: FunctionDescription, args: Arg[], acceptToVectorize?: boolean[] | undefined): FunctionResultObject | Matrix<FunctionResultObject>;
+export declare function createComputeFunction(descr: FunctionDescription): ComputeFunction<Matrix<FunctionResultObject> | FunctionResultObject>;
+export declare function handleError(e: unknown, functionName: string): FunctionResultObject;
+export declare const implementationErrorMessage: string;