@guiexpert/table 1.1.94 → 1.1.97

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;

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

@@ -0,0 +1,41 @@
+import { FormulaError } from './formula-error.js';
+
+/**
+ * A value inside a formula: a number, a text, a boolean, blank (`null`) or an error.
+ *
+ * @example
+ * const fn: FormulaFunction = (x: FormulaValue) => typeof x === "number" ? x * 1.19 : x;
+ *
+ * @since 1.1.95
+ * @category Calculated columns & formulas
+ */
+export type FormulaValue = number | string | boolean | null | FormulaError;
+/**
+ * An own function for formulas. It gets the evaluated arguments (never an error – an error argument is returned
+ * without calling the function) and returns a number, text, boolean or `null`. Anything else, an exception or
+ * `NaN` becomes `#VALUE!` resp. `#NUM!`.
+ *
+ * @example
+ * const VAT: FormulaFunction = (net) => Number(net) * 0.19;
+ * compileFormula("VAT([price])", { functions: { VAT } });
+ *
+ * @since 1.1.95
+ * @category Calculated columns & formulas
+ */
+export type FormulaFunction = (...args: FormulaValue[]) => unknown;
+/**
+ * Options of {@link compileFormula}.
+ *
+ * @example
+ * const options: FormulaOptionsIf = {
+ *   functions: { NET: (gross) => Number(gross) / 1.19 }
+ * };
+ * ColumnDef.create({ property: "net", headerLabel: "Net", formula: "NET([gross])", formulaOptions: options });
+ *
+ * @since 1.1.95
+ * @category Calculated columns & formulas
+ */
+export interface FormulaOptionsIf {
+    /** Own functions by name (case-insensitive). They may replace built-in ones. */
+    functions?: Record<string, FormulaFunction>;
+}

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

@@ -0,0 +1,13 @@
+import { FormulaError } from './formula-error.js';
+import { FormulaValue } from './formula-options.if.js';
+
+export declare function isBlank(v: FormulaValue): boolean;
+/** A value from the data (a field) as formula value: Date → ms, function/object → #VALUE!. */
+export declare function fromData(v: unknown, name: string, trusted?: boolean): FormulaValue;
+export declare function toNumber(v: FormulaValue): number | FormulaError;
+export declare function toText(v: FormulaValue): string | FormulaError;
+export declare function toBoolean(v: FormulaValue): boolean | FormulaError;
+/** A number result: NaN / ±Infinity → #NUM!, -0 → 0. */
+export declare function numberResult(n: number): number | FormulaError;
+/** Compares two values: numbers numerically, texts case-insensitively, blank = 0 = "" = FALSE. */
+export declare function compareValues(a: FormulaValue, b: FormulaValue): number | FormulaError;

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

@@ -0,0 +1,18 @@
+import { FormulaValue } from './formula-options.if.js';
+
+/** A built-in function with eagerly evaluated arguments (errors are returned before the call). */
+export interface BuiltInFunction {
+    readonly min: number;
+    readonly max: number;
+    readonly fn: (args: FormulaValue[]) => FormulaValue;
+}
+/** Functions with lazily evaluated arguments – handled by the evaluator itself. */
+export declare const LAZY_FUNCTIONS: Record<string, {
+    min: number;
+    max: number;
+}>;
+/** SUM, AVG … with exactly one field reference: an aggregate over the (filtered) rows of the table. */
+export declare const AGGREGATE_FUNCTIONS: Record<string, "sum" | "avg" | "min" | "max" | "count">;
+/** Rounds half away from zero (like Excel) without binary artefacts: ROUND(1.005, 2) = 1.01. */
+export declare function roundHalfAwayFromZero(x: number, digits: number): number;
+export declare const BUILT_IN_FUNCTIONS: Record<string, BuiltInFunction>;

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

@@ -0,0 +1,10 @@
+import { FormulaNode } from './formula-ast.if.js';
+
+/** The maximum length of a formula (characters). */
+export declare const MAX_FORMULA_LENGTH = 10000;
+/** The maximum nesting depth (parentheses, function calls, unary operators). */
+export declare const MAX_FORMULA_DEPTH = 64;
+/** The maximum number of binary operators (a long chain is a deep tree, too). */
+export declare const MAX_FORMULA_OPERATORS = 1000;
+/** Parses a formula into an AST. Throws a {@link FormulaSyntaxError}. */
+export declare function parseFormula(source: string): FormulaNode;

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

@@ -0,0 +1,22 @@
+import { FormulaError } from './formula-error.js';
+
+/** The kinds of tokens of a formula. */
+export type FormulaTokenKind = "number" | "string" | "field" | "ident" | "op" | "(" | ")" | "," | "eof";
+/** One token: kind, text (number/string already decoded) and position in the source. */
+export interface FormulaToken {
+    readonly kind: FormulaTokenKind;
+    readonly text: string;
+    readonly value?: number;
+    readonly pos: number;
+}
+/** Thrown by tokenizer and parser, caught by `compileFormula` – never leaves the formula module. */
+export declare class FormulaSyntaxError extends Error {
+    readonly pos: number;
+    constructor(message: string, pos: number);
+    toFormulaError(): FormulaError;
+}
+/**
+ * Splits a formula into tokens. Whitespace is ignored. Throws a {@link FormulaSyntaxError} for an unknown character,
+ * an unterminated string or field reference.
+ */
+export declare function tokenize(source: string): FormulaToken[];

package/lib/table/master-detail/detail-renderer.if.d.ts

@@ -0,0 +1,99 @@
+import { TableApi } from '../table-api.js';
+import { TableModelIf } from '../data/tablemodel/table-model.if.js';
+import { TableOptionsIf } from '../data/options/table-options.if.js';
+import { EventListenerIf } from '../event-listener.if.js';
+
+/**
+ * What {@link DetailRenderContextIf.createTable} needs for a nested table in a detail row.
+ *
+ * @category Master/detail
+ * @since 1.1.97
+ */
+export interface DetailTableParamsIf {
+    /** The model of the nested table, e.g. `TableFactory.createTableModel({ rows: order.items, properties: [...] })`. */
+    tableModel: TableModelIf;
+    /** Its options (default: `new TableOptions()`). */
+    tableOptions?: TableOptionsIf;
+    /** Its event listener (default: none). */
+    eventListener?: EventListenerIf;
+    /**
+     * The height of the nested table: px or a CSS length. Default: `"100%"` with a fixed
+     * {@link MasterDetailOptionsIf.detailHeight}, otherwise {@link MasterDetailOptionsIf.estimatedDetailHeight} px.
+     */
+    height?: number | string;
+}
+/**
+ * The context a {@link DetailRendererIf} gets: the master row, the outer table and helpers whose resources are released
+ * together with the detail row.
+ *
+ * @example
+ * const renderDetail: DetailRenderFnType<Order> = (container, order, ctx) => {
+ *   const button = document.createElement("button");
+ *   button.textContent = `Open order ${order.id}`;
+ *   button.addEventListener("click", () => ctx.tableApi.announce(`Order ${order.id}`), { signal: ctx.signal });
+ *   container.appendChild(button);
+ * };
+ *
+ * @category Master/detail
+ * @since 1.1.97
+ */
+export interface DetailRenderContextIf<T = any> {
+    /** The master row (the row object of the body model). */
+    readonly row: T;
+    /** The display index of the master row when the detail was created (it changes with sorting and filtering). */
+    readonly rowIndex: number;
+    /** The API of the outer (master) table. */
+    readonly tableApi: TableApi;
+    /**
+     * `true` if the content of this detail row existed before and was destroyed (too many rendered details, see
+     * {@link MasterDetailOptionsIf.maxRenderedDetails}, or {@link TableApi.refreshDetail}) – state that lives only in the
+     * DOM (inputs, scroll positions) is gone then.
+     */
+    readonly recreated: boolean;
+    /** Aborted when the detail row is destroyed – pass it to `addEventListener(…, { signal })`. */
+    readonly signal: AbortSignal;
+    /**
+     * Creates a GuiExpert table inside the detail row; it is destroyed (`TableScope.destroy()`) together with the detail
+     * row. The CSS variables of the page (light/dark theme) apply to it as well.
+     *
+     * @param {DetailTableParamsIf} params - model, options, listener, height
+     * @returns {TableApi} the API of the nested table
+     */
+    createTable(params: DetailTableParamsIf): TableApi;
+}
+/**
+ * Renders the content of a detail row – a function (see {@link DetailRendererIf}). It may return a cleanup function,
+ * called when the detail row is destroyed (collapsed, too many rendered details, new table model).
+ *
+ * @example
+ * const renderDetail: DetailRenderFnType<Order> = (container, order) => {
+ *   container.textContent = `${order.items.length} items, ordered on ${order.date}`;  // textContent: no HTML injection
+ * };
+ *
+ * @category Master/detail
+ * @since 1.1.97
+ */
+export type DetailRenderFnType<T = any> = (container: HTMLDivElement, row: T, context: DetailRenderContextIf<T>) => (() => void) | void;
+/**
+ * Renders the content of a detail row – the object form of {@link DetailRenderFnType}, e.g. the
+ * `DetailComponentRendererWrapper` of the framework wrappers (React, Vue, Svelte …).
+ *
+ * The content is created once, when the detail row becomes visible for the first time, and lives until the row is
+ * collapsed – scrolling only hides and shows it (inputs, selections and scroll positions stay).
+ *
+ * @example
+ * class OrderNotesRenderer implements DetailRendererIf<Order> {
+ *   render(container: HTMLDivElement, order: Order): () => void {
+ *     const textarea = document.createElement("textarea");
+ *     textarea.value = order.notes ?? "";
+ *     container.appendChild(textarea);
+ *     return () => { order.notes = textarea.value; };   // cleanup: keep the text
+ *   }
+ * }
+ *
+ * @category Master/detail
+ * @since 1.1.97
+ */
+export interface DetailRendererIf<T = any> {
+    render(container: HTMLDivElement, row: T, context: DetailRenderContextIf<T>): (() => void) | void;
+}

package/lib/table/master-detail/master-detail-options.d.ts

@@ -0,0 +1,30 @@
+import { DetailHeightType, MasterDetailOptionsIf } from './master-detail-options.if.js';
+import { DetailRendererIf, DetailRenderFnType } from './detail-renderer.if.js';
+
+/**
+ * The defaults of {@link MasterDetailOptionsIf}.
+ *
+ * @example
+ * const options = MasterDetailOptions.create({ detailRenderer: (el, row) => { el.textContent = String(row.id); } });
+ * options.detailHeight;          // "auto"
+ * options.maxRenderedDetails;    // 50
+ *
+ * @category Master/detail
+ * @since 1.1.97
+ */
+export declare class MasterDetailOptions<T = any> implements MasterDetailOptionsIf<T> {
+    detailRenderer: DetailRendererIf<T> | DetailRenderFnType<T>;
+    isMaster?: (row: T, rowIndex: number) => boolean;
+    detailHeight: DetailHeightType | ((row: T, rowIndex: number) => DetailHeightType);
+    estimatedDetailHeight: number;
+    toggleColumn?: number | string;
+    maxRenderedDetails: number;
+    getRowId?: (row: T) => string | number;
+    /**
+     * The defaults, overridden by the given values (`undefined` keeps the default).
+     *
+     * @param {Partial<MasterDetailOptionsIf>} [options] - e.g. `tableOptions.masterDetail`
+     * @returns {MasterDetailOptionsIf} complete options
+     */
+    static create<T = any>(options?: Partial<MasterDetailOptionsIf<T>>): MasterDetailOptionsIf<T>;
+}