@adaptabletools/adaptable 23.1.0 → 24.0.0-canary.0

package/src/aql/createExternalDataAqlHost.js

@@ -0,0 +1,73 @@
+import { createObjectDataHost, } from "../../vendor/aql/index.js";
+import { createCalendarHost, toValueDataType } from './createAdaptableAqlHost';
+const asRow = (rowRef) => rowRef;
+export const createExternalDataAqlHost = (api, config) => {
+    const rows = config.rows ?? [];
+    const columnOverrides = new Map((config.columns ?? []).map((column) => [column.columnId, column]));
+    const getFieldPath = (columnId) => {
+        const gridColumn = api.columnApi.getColumnWithColumnId(columnId, false);
+        return gridColumn?.field ?? columnId;
+    };
+    const getObjectValue = (rowRef, columnId) => api.internalApi.getValueUsingField(asRow(rowRef), getFieldPath(columnId));
+    const objectHost = createObjectDataHost({
+        rows,
+        getFieldValue: (row, field) => api.internalApi.getValueUsingField(row, field),
+        primaryKeyField: api.optionsApi.getPrimaryKey(),
+        isTextComparisonCaseSensitive: () => api.expressionApi.useCaseSensitivity(),
+        calendar: createCalendarHost(api),
+        namedQueries: {
+            getNamedQueryExpression: (name) => api.namedQueryApi.getNamedQueryByName(name)?.Expression,
+            getNamedQueryReturnType: (name) => {
+                const namedQuery = api.namedQueryApi.getNamedQueryByName(name);
+                if (!namedQuery) {
+                    return undefined;
+                }
+                return namedQuery.ReturnType ?? 'boolean';
+            },
+        },
+        variables: {
+            getQueryVariable: (name, args) => api.internalApi.getQueryLanguageService().evaluateQueryVariable(name, args),
+        },
+    });
+    return {
+        ...objectHost,
+        getColumnValue: getObjectValue,
+        getFieldValue: (rowRef, field) => api.internalApi.getValueUsingField(asRow(rowRef), field),
+        values: {
+            getRawColumnValue: getObjectValue,
+        },
+        getColumn: (columnId) => {
+            const override = columnOverrides.get(columnId);
+            if (override) {
+                return {
+                    columnId,
+                    dataType: override.dataType,
+                    queryable: true,
+                };
+            }
+            const column = api.columnApi.getColumnWithColumnId(columnId, false);
+            if (!column) {
+                return undefined;
+            }
+            return {
+                columnId: column.columnId,
+                dataType: toValueDataType(column.dataType),
+                queryable: column.queryable,
+            };
+        },
+        comparison: {
+            getColumnIds: () => {
+                const gridColumnIds = api.columnApi.getColumns().map((column) => column.columnId);
+                const overrideIds = [...columnOverrides.keys()].filter((columnId) => !gridColumnIds.includes(columnId));
+                return [...gridColumnIds, ...overrideIds];
+            },
+            getFieldDataType: (field) => {
+                const fieldDef = api.expressionApi.internalApi
+                    .getAvailableFields()
+                    ?.find((availableField) => availableField.name === field);
+                return fieldDef ? toValueDataType(fieldDef.dataType) ?? null : null;
+            },
+            shouldEvaluateDatesUsingTime: (columnId) => api.expressionApi.shouldEvaluateDatesUsingTime(columnId),
+        },
+    };
+};

package/src/aql/durationHelper.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Human-readable rendering of a duration held as milliseconds — the value
+ * shape of AQL's `duration` type (`ROW_AGE{}`, `5m`, `NOW() - [tradedAt]`).
+ *
+ * Two units at most, coarsest first, so a column of ages stays scannable:
+ *
+ * - `null` / non-finite → `—`
+ * - `< 1s`  → `250ms`
+ * - `< 1m`  → `12.3s`
+ * - `< 1h`  → `4m 05s`
+ * - `< 1d`  → `1h 05m`
+ * - else    → `2d 03h`
+ *
+ * Negative durations keep the same shape with a leading `-`.
+ */
+export declare function formatDuration(ms: number | null | undefined): string;
+/** AG Grid `cellDataType` key for duration (milliseconds) columns. */
+export declare const DURATION_CELL_DATA_TYPE = "duration";

package/src/aql/durationHelper.js

@@ -0,0 +1,37 @@
+const MS_PER_SECOND = 1_000;
+const MS_PER_MINUTE = 60 * MS_PER_SECOND;
+const MS_PER_HOUR = 60 * MS_PER_MINUTE;
+const MS_PER_DAY = 24 * MS_PER_HOUR;
+const EMPTY_DURATION = '—';
+const pad2 = (value) => String(value).padStart(2, '0');
+export function formatDuration(ms) {
+    if (ms == null || typeof ms !== 'number' || !Number.isFinite(ms)) {
+        return EMPTY_DURATION;
+    }
+    const sign = ms < 0 ? '-' : '';
+    const abs = Math.abs(ms);
+    if (abs < MS_PER_SECOND) {
+        return `${sign}${Math.round(abs)}ms`;
+    }
+    if (abs < MS_PER_MINUTE) {
+        const seconds = Math.round(abs / 100) / 10;
+        if (seconds >= 60) {
+            return `${sign}1m 00s`;
+        }
+        return `${sign}${seconds.toFixed(1)}s`;
+    }
+    if (abs < MS_PER_HOUR) {
+        const minutes = Math.floor(abs / MS_PER_MINUTE);
+        const seconds = Math.floor((abs % MS_PER_MINUTE) / MS_PER_SECOND);
+        return `${sign}${minutes}m ${pad2(seconds)}s`;
+    }
+    if (abs < MS_PER_DAY) {
+        const hours = Math.floor(abs / MS_PER_HOUR);
+        const minutes = Math.floor((abs % MS_PER_HOUR) / MS_PER_MINUTE);
+        return `${sign}${hours}h ${pad2(minutes)}m`;
+    }
+    const days = Math.floor(abs / MS_PER_DAY);
+    const hours = Math.floor((abs % MS_PER_DAY) / MS_PER_HOUR);
+    return `${sign}${days}d ${pad2(hours)}h`;
+}
+export const DURATION_CELL_DATA_TYPE = 'duration';

package/src/aql/expressionFunctionAvailability.d.ts

@@ -0,0 +1,80 @@
+import { AdaptableAggregatedExpressionModule, AdaptableModule, AdaptableStandardExpressionModule, AggregatedExpressionHostModule } from '../AdaptableState/Common/Types';
+/**
+ * Module sets consumed by the availability overlay
+ * (`expressionFunctionAvailabilityOverlay.ts`), which attaches
+ * `isAvailable` to the system pools when `QueryLanguageService` builds them —
+ * system registries no longer declare `isAvailable` inline. Each set
+ * documents either a *context requirement* of its functions (mapped from a
+ * `requires` declaration on the definition) or a product-policy restriction;
+ * functions covered by neither are available everywhere.
+ */
+/**
+ * Modules that supply `context.dataChangedEvent` when evaluating boolean
+ * expressions — required by the "change" functions (`ANY_CHANGE`,
+ * `PERCENT_CHANGE`, `ABSOLUTE_CHANGE`), which throw without it.
+ */
+export declare const DATA_CHANGE_MODULES: AdaptableStandardExpressionModule[];
+/**
+ * Modules whose expressions may contain observable brace calls
+ * (`CHANGE_COUNT{[c], WITHIN(1h)}`, `PREVIOUS{[c]}`, `ROW_AGE{}`, …): the
+ * modules that evaluate against the live grid and re-evaluate on data
+ * changes / on the clock. `Expression` (the public evaluation API) is not
+ * listed here because it receives the unfiltered super-pool
+ * ({@link SUPER_POOL_MODULES}); see {@link moduleAllowsObservableCalls}.
+ */
+export declare const OBSERVABLE_MODULES: AdaptableStandardExpressionModule[];
+/**
+ * Whether structural validation accepts observable brace calls for the module:
+ * the {@link OBSERVABLE_MODULES} plus the super-pool modules (the public
+ * evaluation API, which evaluates against grid rows and rejects external data
+ * for observable expressions at call time).
+ */
+export declare const moduleAllowsObservableCalls: (module: AdaptableModule | undefined) => boolean;
+/**
+ * Modules that evaluate aggregated boolean expressions.
+ */
+export declare const AGGREGATED_BOOLEAN_MODULES: AdaptableAggregatedExpressionModule[];
+/**
+ * Modules where the aggregated `WHERE` clause is usable: aggregated boolean
+ * expressions (Alerts) and aggregated scalar Calculated Columns, where it
+ * acts as a filtered aggregate (SUMIF-style). Layout / CellSummary don't
+ * offer a WHERE clause editor, so they are deliberately excluded.
+ */
+export declare const AGGREGATED_WHERE_MODULES: AdaptableAggregatedExpressionModule[];
+/**
+ * Modules that consume aggregated scalar expressions: user-authored
+ * aggregated Calculated Columns, Layout row summaries and system-built
+ * Cell Summary aggregations.
+ *
+ * Uses {@link AggregatedExpressionHostModule} so Layout and Cell Summary stay
+ * in system policy without being custom `isAvailable` authoring targets.
+ */
+export declare const AGGREGATION_MODULES: AggregatedExpressionHostModule[];
+/**
+ * For aggregated functions usable both as scalar aggregations and as the
+ * lhs of boolean aggregation comparators (`SUM`, `MIN`, `MAX`, `AVG`,
+ * `WEIGHT`, `COUNT`, `GROUP_BY`): the aggregation modules plus the
+ * aggregated-boolean modules.
+ */
+export declare const SHARED_AGGREGATION_MODULES: AggregatedExpressionHostModule[];
+/**
+ * Aggregated functions with per-row/series semantics (running totals,
+ * row-relative transformations, ordered-series references): only meaningful
+ * where each row gets its own value — i.e. aggregated Calculated Columns.
+ * As a single summary value (Layout row summary, Cell Summary) they are
+ * meaningless.
+ */
+export declare const PER_ROW_AGGREGATION_MODULES: AdaptableAggregatedExpressionModule[];
+/**
+ * Modules that supply `context.columnScope` when evaluating expressions —
+ * required by `$SCOPE`, which throws without it. NamedQuery is included so
+ * scope-aware named queries remain authorable.
+ */
+export declare const SCOPE_MODULES: AdaptableStandardExpressionModule[];
+/**
+ * Modules that receive the unfiltered super-pool: per-function `isAvailable`
+ * arrays (product policy / context-requirement lists) do not apply. Functions
+ * that need a precondition (`$SCOPE`, data-change) still fail at evaluation
+ * time when their context is missing.
+ */
+export declare const SUPER_POOL_MODULES: AdaptableModule[];

package/src/aql/expressionFunctionAvailability.js

@@ -0,0 +1,36 @@
+export const DATA_CHANGE_MODULES = ['Alert', 'FlashingCell'];
+export const OBSERVABLE_MODULES = [
+    'Alert',
+    'CalculatedColumn',
+    'FormatColumn',
+    'FlashingCell',
+];
+export const moduleAllowsObservableCalls = (module) => module !== undefined &&
+    (OBSERVABLE_MODULES.includes(module) ||
+        SUPER_POOL_MODULES.includes(module));
+export const AGGREGATED_BOOLEAN_MODULES = ['Alert'];
+export const AGGREGATED_WHERE_MODULES = [
+    ...AGGREGATED_BOOLEAN_MODULES,
+    'CalculatedColumn',
+];
+export const AGGREGATION_MODULES = [
+    'CalculatedColumn',
+    'Layout',
+    'CellSummary',
+];
+export const SHARED_AGGREGATION_MODULES = [
+    ...AGGREGATED_BOOLEAN_MODULES,
+    ...AGGREGATION_MODULES,
+];
+export const PER_ROW_AGGREGATION_MODULES = [
+    'CalculatedColumn',
+];
+export const SCOPE_MODULES = [
+    'Alert',
+    'FlashingCell',
+    'FormatColumn',
+    'ColumnFilter',
+    'PlusMinus',
+    'NamedQuery',
+];
+export const SUPER_POOL_MODULES = ['Expression'];

package/src/aql/expressionFunctionAvailabilityOverlay.d.ts

@@ -0,0 +1,49 @@
+import { type ExpressionFunction as AqlExpressionFunction } from "../../vendor/aql/index.js";
+import type { AdaptableAggregatedExpressionModule, AdaptableStandardExpressionModule, AggregatedExpressionHostModule } from '../AdaptableState/Common/Types';
+import type { AdaptableExpressionFunction, AdaptableExpressionFunctionEnhancement, AdaptableExpressionFunctionMetadata, AdaptableInternalExpressionContext, ExpressionFunctionType } from './types';
+/**
+ * Enhancement overlay for the system expression-function pools.
+ *
+ * aql's function packs carry only evaluation behaviour, the argument/type
+ * model and documentation. Adaptable layers two things on top when a pool is
+ * built (see `QueryLanguageService.resolveExpressionFunctionsMap`):
+ *
+ * 1. **Presentation** — label / icon / shortcuts / `rhs` / menu visibility,
+ *    from the per-pack maps in `systemExpressionFunctionEnhancements.ts`.
+ * 2. **Availability** — which modules see the function, from two sources:
+ *    - *Handler preconditions*: `requires` on the aql definition (declared
+ *      next to the handler that throws without the capability), mapped to
+ *      the providing modules via {@link REQUIREMENT_MODULES};
+ *    - *Product policy*: availability that is a product decision rather
+ *      than a technical precondition (e.g. per-row aggregations are
+ *      meaningless as a single summary value), listed by function name in
+ *      {@link AVAILABILITY_POLICY}.
+ *
+ * Names collide across categories (`MIN` / `MAX` / `PERCENT_CHANGE` exist in
+ * more than one pool with different availability), so policy is keyed per
+ * {@link ExpressionFunctionType}.
+ *
+ * IMPORTANT: the enhancement must be applied to the system pool **before**
+ * custom-function resolution — `extends` inheritance copies the target
+ * definition wholesale and `GlobalExpressionFunctionsContext` hands the
+ * system pool to user callbacks, so both must observe the fully-enriched
+ * definitions.
+ */
+type AvailabilityModules = AdaptableStandardExpressionModule[] | AdaptableAggregatedExpressionModule[] | AggregatedExpressionHostModule[];
+/**
+ * Product-policy availability, per pool. Functions absent from every list
+ * (and without `requires`) are available in all modules.
+ */
+export declare const AVAILABILITY_POLICY: Record<ExpressionFunctionType, ReadonlyArray<{
+    modules: AvailabilityModules;
+    functions: readonly string[];
+}>>;
+/**
+ * Builds the enriched system pool: each lean aql definition merged with its
+ * Adaptable enhancement, plus `isAvailable` derived from the `requires`
+ * declaration and the product policy (unless the enhancement already
+ * declares an explicit `isAvailable`).
+ */
+export declare function applySystemFunctionEnhancements<T extends string>(pool: Record<T, AqlExpressionFunction<AdaptableInternalExpressionContext>>, functionType: ExpressionFunctionType, enhancements: Record<T, AdaptableExpressionFunctionEnhancement>): Record<T, AdaptableExpressionFunction>;
+export declare function applySystemFunctionEnhancements<T extends string>(pool: Record<T, AdaptableExpressionFunctionMetadata>, functionType: ExpressionFunctionType, enhancements: Record<T, AdaptableExpressionFunctionEnhancement>): Record<T, AdaptableExpressionFunctionMetadata>;
+export {};

package/src/aql/expressionFunctionAvailabilityOverlay.js

@@ -0,0 +1,77 @@
+import { OBSERVABLE_SOURCE_NAMES, } from "../../vendor/aql/index.js";
+import { AGGREGATED_WHERE_MODULES, AGGREGATION_MODULES, DATA_CHANGE_MODULES, PER_ROW_AGGREGATION_MODULES, SCOPE_MODULES, SHARED_AGGREGATION_MODULES, OBSERVABLE_MODULES, } from './expressionFunctionAvailability';
+const REQUIREMENT_MODULES = {
+    columnScope: SCOPE_MODULES,
+    dataChange: DATA_CHANGE_MODULES,
+};
+export const AVAILABILITY_POLICY = {
+    scalar: [],
+    aggregated: [
+        {
+            modules: SHARED_AGGREGATION_MODULES,
+            functions: ['SUM', 'PRODUCT', 'AVG', 'MIN', 'MAX', 'COUNT', 'WEIGHT', 'GROUP_BY'],
+        },
+        {
+            modules: AGGREGATION_MODULES,
+            functions: [
+                'MEDIAN',
+                'MODE',
+                'DISTINCT',
+                'ONLY',
+                'STD_DEVIATION',
+                'QUANT',
+                'QUARTILE',
+                'PERCENTILE',
+            ],
+        },
+        {
+            modules: AGGREGATED_WHERE_MODULES,
+            functions: ['WHERE', 'SUMIF', 'COUNTIF', 'AVGIF'],
+        },
+        {
+            modules: PER_ROW_AGGREGATION_MODULES,
+            functions: [
+                'CUMULATIVE',
+                'PERCENTAGE',
+                'OVER',
+                'LAG',
+                'LEAD',
+                'FIRST',
+                'LAST',
+                'RANK',
+                'ABSOLUTE_DIFF',
+                'PERCENT_DIFF',
+            ],
+        },
+    ],
+    observable: [
+        {
+            modules: OBSERVABLE_MODULES,
+            functions: [...OBSERVABLE_SOURCE_NAMES, 'ANY_COL', 'WITHIN', 'LAST_N', 'ALL_ROWS', 'TRIGGER'],
+        },
+    ],
+};
+export function applySystemFunctionEnhancements(pool, functionType, enhancements) {
+    const policyByName = new Map();
+    for (const { modules, functions } of AVAILABILITY_POLICY[functionType]) {
+        for (const functionName of functions) {
+            policyByName.set(functionName, modules);
+        }
+    }
+    const result = {};
+    for (const functionName of Object.keys(pool)) {
+        const definition = pool[functionName];
+        const enhancement = enhancements[functionName] ?? {};
+        const enriched = { ...definition, ...enhancement };
+        if (enriched.isAvailable === undefined) {
+            const fromRequires = (definition.requires ?? []).flatMap((requirement) => REQUIREMENT_MODULES[requirement]);
+            const fromPolicy = policyByName.get(functionName) ?? [];
+            const modules = [...new Set([...fromRequires, ...fromPolicy])];
+            if (modules.length > 0) {
+                enriched.isAvailable = modules;
+            }
+        }
+        result[functionName] = enriched;
+    }
+    return result;
+}

package/src/aql/formulaTraceUtils.d.ts

@@ -0,0 +1,49 @@
+export interface FormulaTraceTokenSegment {
+    type: 'text' | 'col';
+    text: string;
+    columnId?: string;
+    colorIndex?: number;
+}
+/**
+ * Assigns palette color indexes by order of first appearance.
+ */
+export declare function assignFormulaTraceColorIndexes(columnIds: string[]): Map<string, number>;
+export type ColumnRefRange = {
+    start: number;
+    end: number;
+    columnId: string;
+};
+/** Bracket / quote delimiters + name span for hybrid editor colouring. */
+export type ColumnRefHighlightParts = {
+    columnId: string;
+    /** Opening `[` or quote around COL("id"). */
+    openStart: number;
+    openEnd: number;
+    nameStart: number;
+    nameEnd: number;
+    /** Closing `]` or quote. */
+    closeStart: number;
+    closeEnd: number;
+};
+/**
+ * COL / `[col]` ranges in **original** expression coordinates (accounts for
+ * leading whitespace — AQL parses `trim()` so AST ranges are on the trimmed
+ * string). Used by the Expression Editor highlight layer.
+ */
+export declare function collectColumnRefRanges(expression: string): ColumnRefRange[];
+/**
+ * Splits each column ref into delimiter + name ranges for hybrid colouring:
+ * identity palette on brackets/quotes, shared syntax colour on the name.
+ */
+export declare function collectColumnRefHighlightParts(expression: string): ColumnRefHighlightParts[];
+/**
+ * Splits an expression into plain-text and COL(...) / [col] segments using AST
+ * ranges, so each COL token can be colored to match its cell highlight.
+ *
+ * Display text always uses the column friendly name (as `[Friendly Name]`) when
+ * a mapping is provided; coloring still keys off the original columnId.
+ *
+ * Note: AQL parses `expression.trim()`, so ranges are applied to the trimmed
+ * string — we must slice from the same trimmed input.
+ */
+export declare function tokenizeExpressionForFormulaTrace(expression: string, colorByColumnId: Map<string, number>, friendlyNameByColumnId?: Map<string, string>): FormulaTraceTokenSegment[];

package/src/aql/formulaTraceUtils.js

@@ -0,0 +1,143 @@
+import { getAbstractSyntaxTree, walker } from "../../vendor/aql/index.js";
+import { FORMULA_TRACE_PALETTE_SIZE } from '../AdaptableState/Common/FormulaTraceInfo';
+export function assignFormulaTraceColorIndexes(columnIds) {
+    const colorByColumnId = new Map();
+    columnIds.forEach((columnId) => {
+        if (!colorByColumnId.has(columnId)) {
+            colorByColumnId.set(columnId, colorByColumnId.size % FORMULA_TRACE_PALETTE_SIZE);
+        }
+    });
+    return colorByColumnId;
+}
+export function collectColumnRefRanges(expression) {
+    return collectColumnRefHighlightParts(expression).map((parts) => ({
+        start: parts.openStart,
+        end: parts.closeEnd,
+        columnId: parts.columnId,
+    }));
+}
+export function collectColumnRefHighlightParts(expression) {
+    if (!expression) {
+        return [];
+    }
+    const leadingWs = expression.length - expression.trimStart().length;
+    const trimmedExpression = expression.trim();
+    if (!trimmedExpression) {
+        return [];
+    }
+    try {
+        const ast = getAbstractSyntaxTree(trimmedExpression);
+        const parts = [];
+        walker(ast, (node) => {
+            if (node?.type !== 'COL' || !node.range || !node.args?.length) {
+                return;
+            }
+            const columnIdArg = node.args[0];
+            if (typeof columnIdArg !== 'string' || !columnIdArg) {
+                return;
+            }
+            const start = node.range[0] + leadingWs;
+            const end = node.range[1] + leadingWs;
+            const split = splitColumnRefSource(expression, start, end);
+            if (!split) {
+                return;
+            }
+            parts.push({ columnId: columnIdArg, ...split });
+        });
+        parts.sort((a, b) => a.openStart - b.openStart);
+        return parts;
+    }
+    catch {
+        return [];
+    }
+}
+function splitColumnRefSource(expression, start, end) {
+    if (start < 0 || end > expression.length || start >= end) {
+        return null;
+    }
+    const text = expression.slice(start, end);
+    if (text.startsWith('[') && text.endsWith(']') && text.length >= 2) {
+        return {
+            openStart: start,
+            openEnd: start + 1,
+            nameStart: start + 1,
+            nameEnd: end - 1,
+            closeStart: end - 1,
+            closeEnd: end,
+        };
+    }
+    const colFn = /^(COL)\s*\(\s*(['"])([\s\S]*?)\2\s*\)$/i.exec(text);
+    if (colFn) {
+        const quote = colFn[2];
+        const openQuoteRel = text.indexOf(quote);
+        const closeQuoteRel = text.lastIndexOf(quote);
+        if (openQuoteRel < 0 || closeQuoteRel <= openQuoteRel) {
+            return null;
+        }
+        return {
+            openStart: start + openQuoteRel,
+            openEnd: start + openQuoteRel + 1,
+            nameStart: start + openQuoteRel + 1,
+            nameEnd: start + closeQuoteRel,
+            closeStart: start + closeQuoteRel,
+            closeEnd: start + closeQuoteRel + 1,
+        };
+    }
+    return null;
+}
+export function tokenizeExpressionForFormulaTrace(expression, colorByColumnId, friendlyNameByColumnId) {
+    if (!expression) {
+        return [];
+    }
+    const trimmedExpression = expression.trim();
+    try {
+        const ast = getAbstractSyntaxTree(trimmedExpression);
+        const colRanges = [];
+        walker(ast, (node) => {
+            if (node?.type === 'COL' && node.range && node.args?.length) {
+                const columnIdArg = node.args[0];
+                if (typeof columnIdArg !== 'string' || !columnIdArg) {
+                    return;
+                }
+                colRanges.push({
+                    start: node.range[0],
+                    end: node.range[1],
+                    columnId: columnIdArg,
+                });
+            }
+        });
+        colRanges.sort((a, b) => a.start - b.start);
+        const segments = [];
+        let cursor = 0;
+        for (const range of colRanges) {
+            if (range.start < cursor) {
+                continue;
+            }
+            if (range.start > cursor) {
+                segments.push({
+                    type: 'text',
+                    text: trimmedExpression.slice(cursor, range.start),
+                });
+            }
+            const friendlyName = friendlyNameByColumnId?.get(range.columnId) ?? range.columnId;
+            const displayText = `[${friendlyName}]`;
+            segments.push({
+                type: 'col',
+                text: displayText,
+                columnId: range.columnId,
+                colorIndex: colorByColumnId.get(range.columnId) ?? 0,
+            });
+            cursor = range.end;
+        }
+        if (cursor < trimmedExpression.length) {
+            segments.push({
+                type: 'text',
+                text: trimmedExpression.slice(cursor),
+            });
+        }
+        return segments.length ? segments : [{ type: 'text', text: trimmedExpression }];
+    }
+    catch {
+        return [{ type: 'text', text: trimmedExpression }];
+    }
+}

package/src/aql/formulaValueSubstitutionUtils.d.ts

@@ -0,0 +1,52 @@
+import type { IRowNode } from 'ag-grid-enterprise';
+import type { AdaptableApi } from '../Api/AdaptableApi';
+import { type FormulaTraceTokenSegment } from './formulaTraceUtils';
+export interface StandardFormulaExplainer {
+    /** Single-line annotated formula, e.g. `[Notional](1000000) + [Trade Id](42) * 2` */
+    annotatedText: string;
+    /** Calculated cell result for this row (display value when available) */
+    resultText: string;
+    /** Two-line tooltip: formula over substituted values (= result) */
+    tooltipText: string;
+    /**
+     * Formula row segments (`[Friendly]` COL tokens + text).
+     * Pair with {@link valueSegments} for the stacked Formula Trace popup.
+     */
+    formulaSegments: FormulaTraceTokenSegment[];
+    /**
+     * Value row segments (same structure as {@link formulaSegments}; COL tokens
+     * show this row's cell values). Same colour indexes as the formula row.
+     */
+    valueSegments: FormulaTraceTokenSegment[];
+    /**
+     * Segments for single-line `[Friendly](value)` annotation (tooltips).
+     * Does not include the trailing ` = result`.
+     */
+    annotatedSegments: FormulaTraceTokenSegment[];
+}
+/**
+ * Formats a cell value for inline formula annotation.
+ * Prefers AdapTable display values (no extra quotes — parentheses delimit the value).
+ */
+export declare function formatValueForFormulaSubstitution(api: AdaptableApi, rowNode: IRowNode, columnId: string): string;
+/**
+ * Turns `[Notional]` COL segments into `[Notional](1000000)` using this row's values.
+ */
+export declare function buildAnnotatedExpressionSegments(formulaSegments: FormulaTraceTokenSegment[], valueByColumnId: Map<string, string>): FormulaTraceTokenSegment[];
+/**
+ * Same structure as the formula row, but COL tokens show the row's cell value
+ * (for the stacked Formula Trace popup).
+ */
+export declare function buildValueExpressionSegments(formulaSegments: FormulaTraceTokenSegment[], valueByColumnId: Map<string, string>): FormulaTraceTokenSegment[];
+export declare function joinFormulaSegments(segments: FormulaTraceTokenSegment[]): string;
+export declare function buildFormulaExplainerTooltipText(formulaText: string, valueText: string, resultText: string): string;
+/**
+ * Builds a Standard Calculated Column formula explainer for one row:
+ * formula + value rows for Formula Trace, plus a matching two-line tooltip.
+ *
+ * Uses AdapTable grid APIs so nested calc columns resolve to their evaluated
+ * value for this row (Excel-style direct refs — not transitive expansion).
+ */
+export declare function buildStandardFormulaExplainer(api: AdaptableApi, expression: string, rowNode: IRowNode, calculatedColumnId: string, 
+/** Optional pre-assigned colour indexes (e.g. from Formula Trace state). */
+colorByColumnId?: Map<string, number>): StandardFormulaExplainer | undefined;