@guiexpert/table 1.1.93 → 1.1.96

package/lib/table/factory/row-group-table-model-para.if.d.ts

@@ -0,0 +1,66 @@
+import { ColumnDefIf } from '../data/tablemodel/column/column-def.if.js';
+import { TableOptionsIf } from '../data/options/table-options.if.js';
+import { DefaultRowHeightsIf } from '../data/options/default-row-heights.if.js';
+import { GetT } from '../data/common/get-t.js';
+import { SelectionModelIf } from '../selection/selection-model.if.js';
+import { RowNumberOptionsIf } from '../data/common/row-number-options.if.js';
+import { AggregateSpecMap } from '../aggregation/aggregate-spec.if.js';
+import { AggregateFooterConfig } from '../data/tablemodel/areamodel/aggregate-footer-options.if.js';
+import { RowGroupField } from '../rowgroup/row-group-field.type.js';
+import { RowGroupColumnOptionsIf } from '../rowgroup/row-group-column-options.if.js';
+import { RowGroupExpanded } from '../rowgroup/row-group-model-options.if.js';
+
+/**
+ * Parameters of {@link RowGroupFactory.createTableModel}.
+ *
+ * @example
+ * const para: RowGroupTableModelParaIf<Sale> = {
+ *   rows: sales,
+ *   columnDefs,
+ *   groupBy: ["region", "produkt"],
+ *   aggregations: { umsatz: "sum" },
+ *   expanded: 1                      // regions open, products closed
+ * };
+ * const tableModel = RowGroupFactory.createTableModel(para);
+ *
+ * @typeParam T - the row type
+ * @since 1.1.94
+ * @category Row grouping
+ */
+export interface RowGroupTableModelParaIf<T = any> {
+    /** The flat rows (not changed). */
+    rows: T[];
+    /** The levels, top first: property paths (`"region"`), functions (`o => o.date.getFullYear()`) or {@link RowGroupFieldIf}. */
+    groupBy: RowGroupField<T>[];
+    /** The columns. Default: one per key of the first row. The group column is added in front of them. */
+    columnDefs?: ColumnDefIf[];
+    /** Aggregates in the group rows; the key is the property of the column (`{ umsatz: "sum" }`, see {@link AggregateSpecMap}). */
+    aggregations?: AggregateSpecMap<T>;
+    /**
+     * The total row: `true` = the `aggregations`, `false` = none, or an own configuration ({@link AggregateFooterConfig}).
+     * Default: `true` if there are aggregations.
+     */
+    footerAggregates?: boolean | AggregateFooterConfig<T>;
+    /** The group column: header, width, count, own label, fixed. */
+    groupColumn?: Partial<RowGroupColumnOptionsIf<T>>;
+    /** Hide the columns of the grouped properties. Default true. */
+    hideGroupedColumns?: boolean;
+    /** Expanded groups: `true` (default), `false`, open levels as a number (`0` = all closed) or a function per group. */
+    expanded?: RowGroupExpanded<T>;
+    /** The label of the group of empty keys (`null`, `undefined`, `""`). Default `"(empty)"`. */
+    emptyLabel?: string;
+    /** Options of the table (row heights, selection model, filter …). */
+    tableOptions?: TableOptionsIf;
+    /** Columns fixed on the left besides the group column (which is fixed by itself). Default 0. */
+    fixedLeftColumnCount?: number;
+    /** Columns fixed on the right. Default 0. */
+    fixedRightColumnCount?: number;
+    /** Row numbers in front of all columns (counted per displayed row, group rows included). */
+    rowNumbersVisible?: boolean | Partial<RowNumberOptionsIf>;
+    /** Set with a {@link CheckboxColumnDef} in `columnDefs` (default: detected). */
+    rowCheckboxVisible?: boolean;
+    /** Row heights of header, body and footer. Default: `tableOptions.defaultRowHeights`. */
+    defaultRowHeights?: DefaultRowHeightsIf;
+    /** Selection model factory. Default: `tableOptions.getSelectionModel`. */
+    getSelectionModel?: GetT<SelectionModelIf>;
+}

package/lib/table/factory/table-factory.d.ts

@@ -6,6 +6,8 @@ import { TableOptionsIf } from '../data/options/table-options.if.js';
 import { TableModelIf } from '../data/tablemodel/table-model.if.js';
 import { TableModel } from '../data/tablemodel/table-model.js';
 import { SelectionModelIf } from '../selection/selection-model.if.js';
+import { RowNumberOptionsIf } from '../data/common/row-number-options.if.js';
+import { AggregateFooterConfig } from '../data/tablemodel/areamodel/aggregate-footer-options.if.js';
 
 /**
  * Parameters of {@link TableFactory.createTableModel} – pass any subset (`Partial<CreateTableModelPara>`).
@@ -37,14 +39,56 @@ export interface CreateTableModelPara {
     headerAreaModel: AreaModelIf;
     /** Model of the body. Default: built from `rows` (objects or tree rows) or `bodyData`. See {@link AreaModel} for own models. */
     bodyAreaModel: AreaModelIf;
-    /** Model of the footer. Default: `footerData`, otherwise no footer. Totals that follow the filter: an own {@link AreaModel}. */
+    /** Model of the footer. Default: `footerAggregates`, `footerData`, otherwise no footer. */
     footerAreaModel: AreaModelIf;
+    /**
+     * A footer with totals that follow filter and sorting ({@link AreaModelAggregateFooter}): `{ total: "sum" }` (one
+     * row – the key is the property of the column), `[{ label, aggregates }, …]` (several rows) or full
+     * {@link AggregateFooterOptionsIf}. Row height: `defaultRowHeights.footer`. Ignored with an own `footerAreaModel`
+     * (warning); `footerData` is ignored with it (warning).
+     *
+     * @example
+     * const tableModel = TableFactory.createTableModel({
+     *   rows: orders,
+     *   columnDefs,
+     *   footerAggregates: { quantity: "sum", total: "sum" }       // footer: "100,000 rows" | … | 549,812 | 27,481,033.5
+     * });
+     *
+     * @since 1.1.94
+     */
+    footerAggregates: AggregateFooterConfig;
     /** Number of columns fixed on the left (side "west"). Default 0. */
     fixedLeftColumnCount: number;
     /** Number of columns fixed on the right (side "east"). Default 0. */
     fixedRightColumnCount: number;
     /** Show a checkbox column for every row. Default false. */
     rowCheckboxVisible: boolean;
+    /**
+     * Row numbers (1, 2, 3 …) in a column in front of all others, fixed on the left: `true` or options
+     * ({@link RowNumberOptionsIf}). Puts a {@link RowNumberColumnDef} in front of `columnDefs` and adds 1 to
+     * `fixedLeftColumnCount`; `headerData`/`footerData` get an empty cell in front. Default false.
+     *
+     * The column is a real column: the indices of all other columns are one higher – use properties where you can
+     * ({@link TableApi.getColumnIndex}). With `bodyData` or own area models the flag is ignored (with a warning), because
+     * their columns would shift – put a `RowNumberColumnDef` into the column definitions of your models yourself.
+     *
+     * @example
+     * const tableModel = TableFactory.createTableModel({ rows: orders, columnDefs, rowNumbersVisible: true });
+     *
+     * @since 1.1.93
+     */
+    rowNumbersVisible: boolean | Partial<RowNumberOptionsIf>;
+    /**
+     * Row drag: `true` puts a drag handle into the first data column (behind row numbers and checkboxes) –
+     * sets {@link ColumnDefIf.rowDrag} on that column definition. Options: {@link TableOptionsIf.rowDragOptions}.
+     * Default false.
+     *
+     * @example
+     * const tableModel = TableFactory.createTableModel({ rows: orders, rowDrag: true });
+     *
+     * @since 1.1.95
+     */
+    rowDrag: boolean;
     /** Row heights of header, body and footer in px. Default: `tableOptions.defaultRowHeights`, otherwise 34 / 34 / 34. */
     defaultRowHeights: DefaultRowHeightsIf;
     /** The columns: property, header label, width, classes, renderers, sorting, editing. See {@link ColumnDef}. */
@@ -120,6 +164,17 @@ export declare class TableFactory {
      * });
      */
     static createTableModel(p: Partial<CreateTableModelPara>): TableModelIf;
+    /**
+     * `footerAggregates`: returns the configuration if the factory builds an aggregate footer (after the body model),
+     * `undefined` if there is none or an own `footerAreaModel` wins.
+     */
+    private static checkFooterAggregates;
+    /**
+     * `rowNumbersVisible`: puts a RowNumberColumnDef in front of the column definitions (and an empty cell in front of
+     * `headerData`/`footerData`) and fixes it on the left. Only where the factory builds the models from the column
+     * definitions – with `bodyData` or own area models every column would shift by one.
+     */
+    private static addRowNumberColumn;
     /**
      * Constructs a table model (an instance of `TableModelIf`) by using provided parameters.
      *

package/lib/table/fill/compute-fill-changes.d.ts

@@ -0,0 +1,67 @@
+import { CellRange } from '../data/common/cell-range.js';
+import { CellValueChangeIf } from '../batch-edit/cell-value-change.if.js';
+import { FillDirection } from './fill-direction.type.js';
+import { FillValueContextIf } from './fill-value-context.if.js';
+import { FillMode } from './fill-series.js';
+
+/**
+ * Input of {@link computeFillChanges}.
+ *
+ * @category Fill handle & batch edit
+ * @since 1.1.96
+ */
+export interface FillRequestIf {
+    /** The selected source range (body display indices, `r1 <= r2`, `c1 <= c2`). */
+    source: CellRange;
+    /** Where the range is extended to. */
+    direction: FillDirection;
+    /** The number of rows (down/up) or columns (right/left) to fill. */
+    count: number;
+    /** Series or copy, see {@link FillMode}. */
+    mode?: FillMode;
+    /** The shown value of a cell (batch edit: the pending value). */
+    getValue: (rowIndex: number, columnIndex: number) => unknown;
+    /** `false` skips a target cell (not editable, hidden column …); the series keeps counting. */
+    isFillable?: (rowIndex: number, columnIndex: number) => boolean;
+    /** Own fill function, see {@link FillHandleOptionsIf.fillValue}. */
+    fillValue?: (ctx: FillValueContextIf) => unknown;
+    /** Row object and property of a cell – for `fillValue`. */
+    getCellInfo?: (rowIndex: number, columnIndex: number) => {
+        row: unknown;
+        property: string;
+    };
+}
+/**
+ * The cells a fill covers: the source range extended by `count` rows or columns in `direction`.
+ *
+ * @param {CellRange} source - the selected range
+ * @param {FillDirection} direction - the direction of the fill
+ * @param {number} count - rows or columns added
+ * @returns {CellRange} source and filled cells together
+ *
+ * @example
+ * getFillRange(new CellRange(2, 1, 3, 1), "down", 3);   // rows 2…6 of column 1
+ *
+ * @category Fill handle & batch edit
+ * @since 1.1.96
+ */
+export declare function getFillRange(source: CellRange, direction: FillDirection, count: number): CellRange;
+/**
+ * The values a fill writes: per line of the source range (each column when filling down/up, each row when filling
+ * right/left) the continuation of its values ({@link computeFillValues}) – DOM-free, the table applies the result with
+ * {@link TableApi.applyCellChanges}.
+ *
+ * @param {FillRequestIf} request - source range, direction, count, value access
+ * @returns {CellValueChangeIf[]} one change per fillable target cell (column = model index)
+ *
+ * @example
+ * const values = [[1], [2]];                                    // a 2 × 1 source range
+ * computeFillChanges({
+ *   source: new CellRange(0, 0, 1, 0), direction: "down", count: 2,
+ *   getValue: (r, c) => values[r]?.[c],
+ * });   // [{ rowIndex: 2, column: 0, value: 3 }, { rowIndex: 3, column: 0, value: 4 }]
+ *
+ * @category Fill handle & batch edit
+ * @since 1.1.96
+ */
+export declare function computeFillChanges(request: FillRequestIf): CellValueChangeIf[];

package/lib/table/fill/fill-direction.type.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The direction of a fill: the fill handle was dragged down, up, right or left of the selected range.
+ *
+ * @category Fill handle & batch edit
+ * @since 1.1.96
+ */
+export type FillDirection = "down" | "up" | "right" | "left";

package/lib/table/fill/fill-handle-options.d.ts

@@ -0,0 +1,29 @@
+import { FillHandleOptionsIf } from './fill-handle-options.if.js';
+import { FillValueContextIf } from './fill-value-context.if.js';
+
+/**
+ * The defaults of {@link FillHandleOptionsIf}.
+ *
+ * @example
+ * const options = FillHandleOptions.create(true);
+ * options?.direction;   // "both"
+ *
+ * @category Fill handle & batch edit
+ * @since 1.1.96
+ */
+export declare class FillHandleOptions implements FillHandleOptionsIf {
+    direction: "vertical" | "horizontal" | "both";
+    fillValue?: (ctx: FillValueContextIf) => unknown;
+    maxCells: number;
+    dragThresholdInPx: number;
+    autoScrollZoneInPx: number;
+    autoScrollMaxSpeedInPx: number;
+    /**
+     * The options of {@link TableOptionsIf.fillHandle}: `undefined`/`false` = no fill handle, `true` = the defaults, an
+     * object = the defaults overridden by its values (`undefined` keeps the default).
+     *
+     * @param {boolean | Partial<FillHandleOptionsIf>} [option] - `tableOptions.fillHandle`
+     * @returns {FillHandleOptionsIf | undefined} complete options, `undefined` if the fill handle is off
+     */
+    static create(option?: boolean | Partial<FillHandleOptionsIf>): FillHandleOptionsIf | undefined;
+}

package/lib/table/fill/fill-handle-options.if.d.ts

@@ -0,0 +1,35 @@
+import { FillValueContextIf } from './fill-value-context.if.js';
+
+/**
+ * Options of the fill handle ({@link TableOptionsIf.fillHandle}): the small square at the bottom right corner of the
+ * selected range. Dragging it fills the neighbouring cells – copies values or continues series (1, 2, 3 …; dates;
+ * `Item 1` → `Item 2`). Needs a {@link SelectionModel} of the type `"range"`.
+ *
+ * @example
+ * const selectionModel = new SelectionModel("range", "multi");   // one model – not a new one per call
+ * const tableOptions: TableOptionsIf = {
+ *   ...new TableOptions(),
+ *   getSelectionModel: () => selectionModel,
+ *   fillHandle: { direction: "vertical" },
+ * };
+ *
+ * @category Fill handle & batch edit
+ * @since 1.1.96
+ */
+export interface FillHandleOptionsIf {
+    /** Allowed directions: `"vertical"` (down/up), `"horizontal"` (right/left) or `"both"` (default). */
+    direction: "vertical" | "horizontal" | "both";
+    /**
+     * Own fill function, called for every filled cell. Return the value – or `undefined` for the default
+     * (`ctx.defaultValue`).
+     */
+    fillValue?: (ctx: FillValueContextIf) => unknown;
+    /** At most this many cells are filled at once (default 100,000); a bigger fill is refused and announced. */
+    maxCells: number;
+    /** Distance in px the pointer has to move before a fill starts (default 3). */
+    dragThresholdInPx: number;
+    /** Width in px of the zone at the edges of the body that scrolls automatically (default 40). */
+    autoScrollZoneInPx: number;
+    /** Maximum auto-scroll speed in px per animation frame (default 24). */
+    autoScrollMaxSpeedInPx: number;
+}

package/lib/table/fill/fill-handle-service.d.ts

@@ -0,0 +1,55 @@
+import { TableScope } from '../table-scope.js';
+
+/**
+ * The fill handle of one table (`tableScope.fillHandleService`): the square at the bottom right corner of the selected
+ * range, the pointer drag with preview and auto-scroll, Escape. The values come from {@link TableScope.fillRange}.
+ * Use {@link TableApi.fillRange}, {@link TableApi.isFilling} and {@link TableApi.cancelFill} instead.
+ *
+ * Pointer Events (mouse, touch, pen) only on the handle; its `pointerdown` is prevented, so the mouse handler of the
+ * table (range selection, column drag) never sees it.
+ *
+ * @category Internals
+ * @since 1.1.96
+ */
+export declare class FillHandleService {
+    private readonly tableScope;
+    private handle?;
+    private preview?;
+    private pending?;
+    private session?;
+    private sessionAbortController?;
+    private autoScrollFrame;
+    private suppressClick;
+    private shortcutsSet;
+    constructor(tableScope: TableScope);
+    /** true while the handle is dragged. */
+    isFilling(): boolean;
+    /**
+     * Places the handle at the bottom right corner of the last selected range (called after every render pass) – or
+     * hides it: no fill handle option, no range, the corner scrolled out, an open editor, a blocking overlay.
+     */
+    update(): void;
+    /** The handle's position (the corner of the range) in host coordinates – `undefined` if it is not visible. */
+    private getCornerOf;
+    private ensureHandle;
+    private removeHandle;
+    /** Keyboard alternative on the grid: Ctrl/⌘+D, Ctrl/⌘+R (only directions the options allow). */
+    private updateHostShortcuts;
+    private isHandle;
+    private onPointerDown;
+    private listenToDocument;
+    private onPointerMove;
+    private onPointerUp;
+    private suppressNextClick;
+    private onClickCapture;
+    /** Target cell under the pointer → direction and count; preview; auto-scroll. */
+    private updateTarget;
+    private renderPreview;
+    private updateAutoScroll;
+    private autoScrollStep;
+    /** Cancels a running fill (Escape, `pointercancel`, {@link TableApi.cancelFill}): nothing is changed. */
+    cancel(): void;
+    private stopListening;
+    /** Releases everything (TableScope.destroy). */
+    destroy(): void;
+}

package/lib/table/fill/fill-series.d.ts

@@ -0,0 +1,60 @@
+/**
+ * How {@link computeFillValues} continues the source values:
+ * - `"auto"`: the default rules – one number is copied, several numbers continue as a linear series, dates and texts
+ *   with a trailing number count up, everything else repeats;
+ * - `"alternate"`: the other choice for numbers, dates and texts with a number (⌥/Alt or Ctrl while dragging the fill
+ *   handle): one number counts up by 1, a series is copied;
+ * - `"copy"`: always repeat the source values (Ctrl/⌘+D, Ctrl/⌘+R).
+ *
+ * @category Fill handle & batch edit
+ * @since 1.1.96
+ */
+export type FillMode = "auto" | "alternate" | "copy";
+/**
+ * Computes the values of a fill (fill handle, Ctrl/⌘+D): `count` values that continue `sourceValues` – forward
+ * (down/right) or backward (up/left: the value directly in front of the source first).
+ *
+ * | source | `"auto"` | `"alternate"` |
+ * |---|---|---|
+ * | one number `5` | 5, 5, 5 | 6, 7, 8 |
+ * | numbers `1, 2` | 3, 4, 5 (linear; uneven steps: best-fit line) | 1, 2, 1 |
+ * | date `2026-10-14` (`Date` or ISO text) | +1 day each; several dates a month apart: +1 month (month ends stay month ends) | copied |
+ * | text with a trailing number `Item 9` | `Item 10`, `Item 11` (leading zeros stay) | copied |
+ * | anything else | repeated: `A, B` → `A, B, A, B` | repeated |
+ *
+ * The type stays: a date text stays a text in the same format, a `Date` stays a `Date`, a number written as text
+ * stays a text. Decimal noise is rounded (0.1, 0.2 → 0.3, not 0.30000000000000004).
+ *
+ * @param {unknown[]} sourceValues - the values of one line (column or row) of the source range, in display order
+ * @param {number} count - the number of values to compute
+ * @param {boolean} [backward=false] - fill up/left: the values in front of the source, nearest first
+ * @param {FillMode} [mode="auto"] - see {@link FillMode}
+ * @returns {unknown[]} `count` values, nearest to the source first
+ *
+ * @example
+ * computeFillValues([1, 2], 3);                       // [3, 4, 5]
+ * computeFillValues([5], 3);                          // [5, 5, 5]
+ * computeFillValues([5], 3, false, "alternate");      // [6, 7, 8]
+ * computeFillValues(["2026-10-14"], 2);               // ["2026-10-15", "2026-10-16"]
+ * computeFillValues(["Item 9"], 2);                   // ["Item 10", "Item 11"]
+ * computeFillValues([1, 2], 2, true);                 // [0, -1]  (filled upwards)
+ *
+ * @category Fill handle & batch edit
+ * @since 1.1.96
+ */
+export declare function computeFillValues(sourceValues: unknown[], count: number, backward?: boolean, mode?: FillMode): unknown[];
+/**
+ * `true` if {@link computeFillValues} continues the values as a series, `false` if it repeats them.
+ *
+ * @param {unknown[]} sourceValues - the values of one line of the source range
+ * @param {FillMode} [mode="auto"] - see {@link FillMode}
+ * @returns {boolean} whether the fill is a series
+ *
+ * @example
+ * isFillSeries([5]);        // false – one number is copied
+ * isFillSeries([1, 2]);     // true
+ *
+ * @category Fill handle & batch edit
+ * @since 1.1.96
+ */
+export declare function isFillSeries(sourceValues: unknown[], mode?: FillMode): boolean;

package/lib/table/fill/fill-value-context.if.d.ts

@@ -0,0 +1,36 @@
+import { FillDirection } from './fill-direction.type.js';
+
+/**
+ * What an own fill function ({@link FillHandleOptionsIf.fillValue}) gets for each filled cell.
+ *
+ * @example
+ * const weekdays = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"];
+ * const fillValue = (ctx: FillValueContextIf) => {
+ *   const last = ctx.sourceValues[ctx.sourceValues.length - 1];
+ *   const i = weekdays.indexOf(String(last));
+ *   return i < 0 || ctx.copy ? undefined : weekdays[(((i + ctx.step) % 7) + 7) % 7];   // undefined = default
+ * };
+ *
+ * @category Fill handle & batch edit
+ * @since 1.1.96
+ */
+export interface FillValueContextIf {
+    /** The values of the source line (the column when filling down/up, the row when filling right/left), as shown. */
+    sourceValues: unknown[];
+    /** 1, 2, 3 … after the source (down/right), −1, −2 … in front of it (up/left). */
+    step: number;
+    /** The direction of the fill. */
+    direction: FillDirection;
+    /** Display index of the filled cell's row. */
+    rowIndex: number;
+    /** Model index of the filled cell's column. */
+    columnIndex: number;
+    /** The property of the column (`""` without a column definition). */
+    property: string;
+    /** The row object of the filled cell (`undefined` for own area models without row objects). */
+    row: unknown;
+    /** The value the table would use (series or copy). */
+    defaultValue: unknown;
+    /** `true` if the values are copied (⌥/Alt on a series, Ctrl/⌘+D, Ctrl/⌘+R). */
+    copy: boolean;
+}

package/lib/table/formula/compile-formula.d.ts

@@ -0,0 +1,86 @@
+import { FormulaNode } from './formula-ast.if.js';
+import { FormulaError } from './formula-error.js';
+import { FormulaOptionsIf, FormulaValue } from './formula-options.if.js';
+import { ValueGetterContextIf } from '../calc/value-getter-context.if.js';
+import { ValueGetter } from '../calc/value-getter.type.js';
+
+/**
+ * The names of the built-in formula functions (upper case), e.g. for the help text of an own formula input.
+ *
+ * @example
+ * hint.textContent = `Functions: ${FORMULA_FUNCTION_NAMES.join(", ")}`;
+ *
+ * @since 1.1.95
+ * @category Calculated columns & formulas
+ */
+export declare const FORMULA_FUNCTION_NAMES: readonly string[];
+/**
+ * A formula compiled once ({@link compileFormula}): the AST, the referenced fields and `evaluate()` for a row.
+ * A formula with a syntax error or an unknown function has `error` set; `evaluate()` then always returns it.
+ *
+ * @example
+ * const f = compileFormula("[price] * [quantity] * 1.19");
+ * f.fields;                                    // ["price", "quantity"]
+ * f.evaluate({ price: 1299, quantity: 2 });    // 3091.62
+ *
+ * @since 1.1.95
+ * @category Calculated columns & formulas
+ */
+export interface CompiledFormula {
+    /** The formula text as given. */
+    readonly source: string;
+    /** The syntax tree; `undefined` if the formula has an error. */
+    readonly ast?: FormulaNode;
+    /** The error of the formula itself (`#ERROR!`, `#NAME?` for an unknown function); `undefined` if it is valid. */
+    readonly error?: FormulaError;
+    /** The referenced fields (`[price]` → `"price"`), each once, in order of appearance. */
+    readonly fields: readonly string[];
+    /** True if the formula uses a column aggregate (`SUM([total])` …). */
+    readonly usesAggregates: boolean;
+    /**
+     * Evaluates the formula for a row. Never throws: errors are returned as {@link FormulaError}.
+     * Without a context, column aggregates (`SUM([x])`) return `#VALUE!`.
+     */
+    evaluate(row: unknown, context?: ValueGetterContextIf): FormulaValue;
+}
+/**
+ * Compiles a formula once – no `eval`, no `new Function` (works with a strict Content-Security-Policy, user input
+ * cannot run code). The result evaluates rows; never throws.
+ *
+ * Syntax (details: instructions.md „Formulas“):
+ * - fields in brackets: `[price]`, `[address.city]`, `[Unit price]` – own properties of the row or calculated columns
+ * - numbers `12`, `1.5`, `1e3`, texts `"a"` / `'a'`, `TRUE`, `FALSE`
+ * - operators: `+ - * / ^` (power), `&` (text), `= <> < <= > >=`; `-2^2 = -4`
+ * - functions: `ROUND(x, 2)`, `IF(c, a, b)`, `IFERROR`, `AND`, `OR`, `NOT`, `ABS`, `MOD`, `SQRT`, `POWER`, `FLOOR`,
+ *   `CEILING`, `CONCAT`, `LEN`, `UPPER`, `LOWER`, `TRIM`, `ISBLANK`; `SUM AVG MIN MAX COUNT` – with one field the
+ *   aggregate of the column (`[total] / SUM([total])`), otherwise of the arguments
+ *
+ * @param {string} source - the formula, e.g. `"[price] * [quantity] * 1.19"` (a leading `=` is ignored)
+ * @param {FormulaOptionsIf} [options] - own functions
+ * @returns {CompiledFormula} the compiled formula
+ *
+ * @example
+ * const gross = compileFormula("ROUND([price] * [quantity] * 1.19, 2)");
+ * gross.evaluate({ price: 25, quantity: 10 });         // 297.5
+ * compileFormula("[price] / 0").evaluate({ price: 1 }); // FormulaError #DIV/0!
+ * compileFormula("[price] *").error?.code;             // "#ERROR!"
+ *
+ * @since 1.1.95
+ * @category Calculated columns & formulas
+ */
+export declare function compileFormula(source: string, options?: FormulaOptionsIf): CompiledFormula;
+/**
+ * The {@link ValueGetter} of a formula – what `ColumnDef.create({ formula })` sets as `valueGetter`.
+ *
+ * @param {CompiledFormula | string} formula - a compiled formula or its text
+ * @param {FormulaOptionsIf} [options] - own functions (only with a text)
+ * @returns {ValueGetter} the getter
+ *
+ * @example
+ * const column = ColumnDef.create({ property: "gross", headerLabel: "Gross" });
+ * column.valueGetter = createFormulaValueGetter("[net] * 1.19");
+ *
+ * @since 1.1.95
+ * @category Calculated columns & formulas
+ */
+export declare function createFormulaValueGetter(formula: CompiledFormula | string, options?: FormulaOptionsIf): ValueGetter;

package/lib/table/formula/evaluator.d.ts

@@ -0,0 +1,19 @@
+import { FormulaNode } from './formula-ast.if.js';
+import { FormulaFunction, FormulaValue } from './formula-options.if.js';
+import { ValueGetterContextIf } from '../calc/value-getter-context.if.js';
+
+type Evaluate = (row: unknown, context: ValueGetterContextIf | undefined) => FormulaValue;
+/** Reads a field: own properties only (no prototype chain), path segments separated by ".". */
+export declare function readField(row: unknown, name: string, context?: ValueGetterContextIf, path?: string[]): FormulaValue;
+/** Compiles an AST into closures. Never throws at evaluation time (see {@link FormulaEvaluator.evaluate}). */
+export declare class FormulaEvaluator {
+    private readonly functions;
+    constructor(functions: Map<string, FormulaFunction>);
+    /** The evaluation function of a (checked) AST. */
+    compile(node: FormulaNode): Evaluate;
+    /** Evaluates an AST once (compiles it each time – for single use). */
+    evaluate(node: FormulaNode, row: unknown, context?: ValueGetterContextIf): FormulaValue;
+    private node;
+    private call;
+}
+export {};

package/lib/table/formula/formula-ast.if.d.ts

@@ -0,0 +1,42 @@
+/**
+ * A node of a compiled formula (abstract syntax tree). Read-only; the evaluator walks it – no code is generated
+ * (no `eval`, no `new Function`).
+ *
+ * @example
+ * const ast = compileFormula("[price] * 2").ast;
+ * // { kind: "binary", op: "*", left: { kind: "field", name: "price" }, right: { kind: "literal", value: 2 } }
+ *
+ * @since 1.1.95
+ * @category Calculated columns & formulas
+ */
+export type FormulaNode = {
+    readonly kind: "literal";
+    readonly value: number | string | boolean;
+} | {
+    readonly kind: "field";
+    readonly name: string;
+} | {
+    readonly kind: "unary";
+    readonly op: "-" | "+";
+    readonly operand: FormulaNode;
+} | {
+    readonly kind: "binary";
+    readonly op: FormulaBinaryOperator;
+    readonly left: FormulaNode;
+    readonly right: FormulaNode;
+} | {
+    readonly kind: "call";
+    readonly name: string;
+    readonly args: readonly FormulaNode[];
+};
+/**
+ * The binary operators of a formula: arithmetic (`+ - * / ^`), text concatenation (`&`) and comparisons
+ * (`=`/`==`, `<>`/`!=`, `<`, `<=`, `>`, `>=`; normalized to `=` and `<>`).
+ *
+ * @example
+ * const op: FormulaBinaryOperator = "&";   // "Total: " & [total]
+ *
+ * @since 1.1.95
+ * @category Calculated columns & formulas
+ */
+export type FormulaBinaryOperator = "+" | "-" | "*" | "/" | "^" | "&" | "=" | "<>" | "<" | "<=" | ">" | ">=";

package/lib/table/formula/formula-error.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The error codes of a formula – like in a spreadsheet:
+ *
+ * | Code | Meaning |
+ * |---|---|
+ * | `#ERROR!` | syntax error (the whole column shows it) |
+ * | `#NAME?` | unknown field or function |
+ * | `#VALUE!` | wrong type, e.g. `"abc" * 2` |
+ * | `#DIV/0!` | division by zero |
+ * | `#NUM!` | the result is not a finite number (`SQRT(-1)`, overflow) |
+ * | `#CIRC!` | circular reference between calculated columns |
+ *
+ * @since 1.1.95
+ * @category Calculated columns & formulas
+ */
+export type FormulaErrorCode = "#ERROR!" | "#NAME?" | "#VALUE!" | "#DIV/0!" | "#NUM!" | "#CIRC!";
+/**
+ * An error value of a formula. Formulas never throw: a cell shows the {@link FormulaErrorCode} (`toString()`), the
+ * table adds the CSS class `ge-table-cell-error` and shows the message as tooltip. Errors propagate through
+ * operators and functions (`[a] / 0 + 1` → `#DIV/0!`), `IFERROR(x, fallback)` catches them, aggregators skip them.
+ *
+ * @example
+ * const result = compileFormula("[price] / [quantity]").evaluate({ price: 10, quantity: 0 });
+ * if (isFormulaError(result)) {
+ *   console.log(result.code, result.message);   // "#DIV/0!" "Division by zero"
+ * }
+ *
+ * @since 1.1.95
+ * @category Calculated columns & formulas
+ */
+export declare class FormulaError {
+    readonly code: FormulaErrorCode;
+    readonly message: string;
+    readonly position?: number | undefined;
+    /** Marker (works across copies of the core): {@link isFormulaError}. */
+    readonly type = "FormulaError";
+    /**
+     * @param {FormulaErrorCode} code - the code shown in the cell
+     * @param {string} message - a short English explanation (tooltip); never contains HTML
+     * @param {number} [position] - for syntax errors: the position in the formula text (0-based)
+     */
+    constructor(code: FormulaErrorCode, message: string, position?: number | undefined);
+    /** The code, e.g. `"#DIV/0!"` – what a cell shows. */
+    toString(): string;
+}
+/**
+ * True for an error value of a formula ({@link FormulaError}) – also for one created by another copy of the core.
+ *
+ * @param {unknown} value - any value
+ * @returns {boolean} whether it is a formula error
+ *
+ * @example
+ * const value = tableApi.getRowValue(row, "margin");
+ * if (!isFormulaError(value)) console.log(value);
+ *
+ * @since 1.1.95
+ * @category Calculated columns & formulas
+ */
+export declare function isFormulaError(value: unknown): value is FormulaError;