@adaptabletools/adaptable 23.1.0-canary.2 → 24.0.0-canary.0

package/src/aql/formulaValueSubstitutionUtils.js

@@ -0,0 +1,100 @@
+import { CALCULATED_COLUMN_INVALID_CELL_VALUE, MISSING_COLUMN, } from '../Utilities/Constants/GeneralConstants';
+import { assignFormulaTraceColorIndexes, tokenizeExpressionForFormulaTrace, } from './formulaTraceUtils';
+export function formatValueForFormulaSubstitution(api, rowNode, columnId) {
+    const displayValue = api.gridApi.getDisplayValueFromRowNode(rowNode, columnId);
+    const rawValue = api.gridApi.getRawValueFromRowNode(rowNode, columnId);
+    if (displayValue === CALCULATED_COLUMN_INVALID_CELL_VALUE ||
+        rawValue === CALCULATED_COLUMN_INVALID_CELL_VALUE) {
+        return CALCULATED_COLUMN_INVALID_CELL_VALUE;
+    }
+    const hasDisplay = displayValue != null && String(displayValue) !== '';
+    const text = hasDisplay
+        ? String(displayValue)
+        : rawValue == null
+            ? ''
+            : String(rawValue);
+    if (text === '' && (rawValue == null || rawValue === '')) {
+        return 'blank';
+    }
+    return text;
+}
+export function buildAnnotatedExpressionSegments(formulaSegments, valueByColumnId) {
+    return formulaSegments.map((segment) => {
+        if (segment.type !== 'col' || !segment.columnId) {
+            return segment;
+        }
+        const value = valueByColumnId.get(segment.columnId) ?? 'blank';
+        return {
+            ...segment,
+            text: `${segment.text}(${value})`,
+        };
+    });
+}
+export function buildValueExpressionSegments(formulaSegments, valueByColumnId) {
+    return formulaSegments.map((segment) => {
+        if (segment.type !== 'col' || !segment.columnId) {
+            return segment;
+        }
+        return {
+            ...segment,
+            text: valueByColumnId.get(segment.columnId) ?? 'blank',
+        };
+    });
+}
+export function joinFormulaSegments(segments) {
+    return segments.map((segment) => segment.text).join('');
+}
+export function buildFormulaExplainerTooltipText(formulaText, valueText, resultText) {
+    const result = resultText || 'blank';
+    if (valueText) {
+        return `${formulaText}\n${valueText} = ${result}`;
+    }
+    return `${formulaText} = ${result}`;
+}
+function resolveFriendlyName(api, columnId) {
+    const column = api.columnApi.getColumnWithColumnId(columnId);
+    let friendlyName = column?.friendlyName;
+    if (!friendlyName || friendlyName.includes(MISSING_COLUMN)) {
+        const lookedUp = api.columnApi.getFriendlyNameForColumnId(columnId);
+        friendlyName =
+            lookedUp && !lookedUp.includes(MISSING_COLUMN) ? lookedUp : columnId;
+    }
+    return friendlyName;
+}
+export function buildStandardFormulaExplainer(api, expression, rowNode, calculatedColumnId, colorByColumnId) {
+    if (!expression?.trim() || !rowNode) {
+        return undefined;
+    }
+    const discovered = tokenizeExpressionForFormulaTrace(expression, new Map());
+    const columnIds = Array.from(new Set(discovered
+        .filter((segment) => segment.type === 'col' && segment.columnId)
+        .map((segment) => segment.columnId)));
+    const colors = colorByColumnId ?? assignFormulaTraceColorIndexes(columnIds);
+    const friendlyNameByColumnId = new Map();
+    const valueByColumnId = new Map();
+    columnIds.forEach((columnId) => {
+        friendlyNameByColumnId.set(columnId, resolveFriendlyName(api, columnId));
+        valueByColumnId.set(columnId, formatValueForFormulaSubstitution(api, rowNode, columnId));
+    });
+    const formulaSegments = tokenizeExpressionForFormulaTrace(expression, colors, friendlyNameByColumnId);
+    const valueSegments = buildValueExpressionSegments(formulaSegments, valueByColumnId);
+    const annotatedSegments = buildAnnotatedExpressionSegments(formulaSegments, valueByColumnId);
+    const annotatedText = joinFormulaSegments(annotatedSegments);
+    const formulaText = joinFormulaSegments(formulaSegments);
+    const valueText = joinFormulaSegments(valueSegments);
+    const resultDisplay = api.gridApi.getDisplayValueFromRowNode(rowNode, calculatedColumnId);
+    const resultRaw = api.gridApi.getRawValueFromRowNode(rowNode, calculatedColumnId);
+    const resultText = resultDisplay != null && String(resultDisplay) !== ''
+        ? String(resultDisplay)
+        : resultRaw == null
+            ? 'blank'
+            : String(resultRaw);
+    return {
+        annotatedText,
+        resultText,
+        tooltipText: buildFormulaExplainerTooltipText(formulaText, valueText, resultText),
+        formulaSegments,
+        valueSegments,
+        annotatedSegments,
+    };
+}

package/src/aql/getMissingColumnIssues.d.ts

@@ -0,0 +1,10 @@
+import { type ExpressionTypeIssue } from "../../vendor/aql/index.js";
+/**
+ * AdapTable-host validation: flag `COL` / `[columnId]` refs that are not in the
+ * grid catalog. Kept out of `@adaptabletools/aql` so the language package stays
+ * host-agnostic (unknown columns remain typed as `unknown` there).
+ *
+ * Skeleton-chip placeholders (`[col-here]`) get a replace-this hint instead of
+ * an unknown-column error.
+ */
+export declare function getMissingColumnIssues(ast: unknown, columnExists: (columnId: string) => boolean): ExpressionTypeIssue[];

package/src/aql/getMissingColumnIssues.js

@@ -0,0 +1,33 @@
+import { isAST_Function, walker, } from "../../vendor/aql/index.js";
+import { CHIP_COLUMN_PLACEHOLDER_MESSAGE, isChipColumnPlaceholder, } from './chipColumnPlaceholder';
+export function getMissingColumnIssues(ast, columnExists) {
+    const issues = [];
+    walker(ast, (node) => {
+        if (!isAST_Function(node) || node.type !== 'COL') {
+            return;
+        }
+        if (node.args.length !== 1 || typeof node.args[0] !== 'string') {
+            return;
+        }
+        const columnId = node.args[0];
+        if (columnExists(columnId)) {
+            return;
+        }
+        if (isChipColumnPlaceholder(columnId)) {
+            issues.push({
+                message: CHIP_COLUMN_PLACEHOLDER_MESSAGE,
+                severity: 'warning',
+                range: node.range,
+                functionName: 'COL',
+            });
+            return;
+        }
+        issues.push({
+            message: `Column name "${columnId}" is not found`,
+            severity: 'error',
+            range: node.range,
+            functionName: 'COL',
+        });
+    });
+    return issues;
+}

package/src/aql/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Adaptable-QL wrapper: the thin layer that binds `@adaptabletools/aql` to
+ * Adaptable's host (AG Grid + `AdaptableApi`).
+ *
+ * Deliberately not re-exported from the package barrel yet — the public façade
+ * lands with `QueryLanguageApi` (Phase 11).
+ */
+export { createAdaptableAqlHost, toAqlCellChange } from './createAdaptableAqlHost';
+export { applySystemFunctionEnhancements } from './expressionFunctionAvailabilityOverlay';
+export { systemAggregatedExpressionFunctions, systemScalarExpressionFunctions, } from './systemExpressionFunctions';
+export type { AdaptableCustomExpressionFunction, AdaptableCustomExpressionFunctionEntry, AdaptableCustomExpressionFunctionWithExtends, AdaptableExpressionContext, AdaptableExpressionFunction, AdaptableExpressionFunctionEnhancement, AdaptableExpressionFunctionMap, AdaptableInternalExpressionContext, ExpressionFunctionAvailabilityContext, ExpressionFunctionType, } from './types';

package/src/aql/index.js

@@ -0,0 +1,3 @@
+export { createAdaptableAqlHost, toAqlCellChange } from './createAdaptableAqlHost';
+export { applySystemFunctionEnhancements } from './expressionFunctionAvailabilityOverlay';
+export { systemAggregatedExpressionFunctions, systemScalarExpressionFunctions, } from './systemExpressionFunctions';

package/src/aql/legacyExpressionKinds.d.ts

@@ -0,0 +1,18 @@
+import type { ExpressionValidationRequest, MigrateOptions } from "../../vendor/aql/index.js";
+/**
+ * Adaptable's four expression binding kinds — the vocabulary AdaptableState,
+ * the modules and the editors speak. aql itself only knows validation
+ * requests (`ExpressionValidationRequest`) and a migrate-only
+ * `aggregatedContext` hint; this module is the one place that maps between
+ * the two.
+ */
+export type LegacyExpressionKind = 'boolean' | 'scalar' | 'aggregatedScalar' | 'aggregatedBoolean';
+export declare const isAggregatedExpressionKind: (kind: LegacyExpressionKind | undefined) => boolean;
+/** Binding kind → validation request. */
+export declare const mapLegacyKindToValidationRequest: (kind: LegacyExpressionKind) => ExpressionValidationRequest;
+/**
+ * Binding kind → migrate options. Only the aggregated kinds carry
+ * information the migrator needs (single-argument dual names such as
+ * `SUM([x])` are aggregations there, row-wise scalars elsewhere).
+ */
+export declare const toMigrateOptions: (kind: LegacyExpressionKind | undefined) => MigrateOptions;

package/src/aql/legacyExpressionKinds.js

@@ -0,0 +1,14 @@
+export const isAggregatedExpressionKind = (kind) => kind === 'aggregatedScalar' || kind === 'aggregatedBoolean';
+export const mapLegacyKindToValidationRequest = (kind) => {
+    switch (kind) {
+        case 'boolean':
+            return { returnType: 'boolean', allowsAggCalls: false };
+        case 'scalar':
+            return { allowsAggCalls: false };
+        case 'aggregatedBoolean':
+            return { returnType: 'boolean', requiresAggCalls: true };
+        case 'aggregatedScalar':
+            return { requiresAggCalls: true };
+    }
+};
+export const toMigrateOptions = (kind) => isAggregatedExpressionKind(kind) ? { aggregatedContext: true } : {};

package/src/aql/mapCustomAggregatedScalarFunctions.d.ts

@@ -0,0 +1,31 @@
+import type { AggregationOperator } from "../../vendor/aql/index.js";
+import type { AdaptableApi } from '../Api/AdaptableApi';
+import type { AdaptableAggregationFunctionDef, AggregatedExpressionFunction } from './types';
+/**
+ * Docs-only pool entry for a product-authored custom aggregation: what the
+ * editors / QueryBuilder / Row Summary wizard present. Evaluation is the
+ * operator's job (see {@link toAggregationOperator}).
+ */
+export declare function toCustomAggregationFunctionDef(definition: AggregatedExpressionFunction): AdaptableAggregationFunctionDef;
+/**
+ * Adapts one product-authored `customAggregatedFunctions` entry (IRowNode
+ * reducer callbacks) onto an aql {@link AggregationOperator}: compiled, not
+ * evaluated. `currentValue` is the computed input; `aggColumnId` is
+ * populated for bare column refs and `undefined` otherwise.
+ *
+ * Declared capabilities map 1:1 onto the operator: `weight` →
+ * `capabilities.weight` (the executor resolves the WEIGHT input and hands it
+ * over as `weightValue`), `cumulative` → `capabilities.cumulative` (a running
+ * variant over the same `reducer`), `returnType` → `resultType` /
+ * `outputType`. Validation, editor clause chips, the Cumulative editor and
+ * the Query Builder read those capabilities from the aggregation catalogue,
+ * so nothing else has to be registered.
+ *
+ * Performance notes (vs the retired descriptor mapper): the host base
+ * context is built once per aggregation run (`init`) rather than per row,
+ * and visited rows are collected only when `processAggregatedValue` or a
+ * cumulative `currentValue` will read them.
+ */
+export declare function toAggregationOperator(name: string, definition: AggregatedExpressionFunction, adaptableApi: AdaptableApi): AggregationOperator;
+/** {@link toAggregationOperator} over a name-keyed map of definitions. */
+export declare function mapCustomAggregatedFunctionsToOperators(aggregatedScalarFunctions: Record<string, AggregatedExpressionFunction>, adaptableApi: AdaptableApi): AggregationOperator[];

package/src/aql/mapCustomAggregatedScalarFunctions.js

@@ -0,0 +1,202 @@
+import { SKIP_ROW } from "../../vendor/aql/index.js";
+const RETURN_TYPE_TO_EXPRESSION_RETURN_TYPE = {
+    number: 'number',
+    text: 'string',
+    date: 'date',
+    boolean: 'boolean',
+    input: undefined,
+};
+const RETURN_TYPE_TO_VALUE_TYPE = {
+    number: 'number',
+    text: 'text',
+    date: 'date',
+    boolean: 'boolean',
+};
+export function toCustomAggregationFunctionDef(definition) {
+    const returnType = definition.returnType
+        ? RETURN_TYPE_TO_EXPRESSION_RETURN_TYPE[definition.returnType]
+        : undefined;
+    return {
+        description: definition.description,
+        signatures: definition.signatures,
+        examples: definition.examples,
+        category: definition.category ?? 'aggregation',
+        inputs: definition.inputTypes,
+        isAvailable: definition.isAvailable,
+        ...(returnType ? { returnType } : {}),
+    };
+}
+const isColParam = (value) => typeof value === 'object' &&
+    value != null &&
+    value.type === 'COL' &&
+    typeof value.args?.[0] === 'string';
+const toLegacyArg = (param) => isColParam(param) ? { name: 'COL', value: param.args[0] } : param;
+const resolveInitialValue = (initialValue) => {
+    if (typeof initialValue === 'function') {
+        return initialValue();
+    }
+    if (initialValue !== null && typeof initialValue === 'object') {
+        return structuredClone(initialValue);
+    }
+    return initialValue;
+};
+const toParameters = (definition) => ({
+    subject: 'column-or-field',
+    queryBuilder: false,
+    list: [definition.inputTypes?.length ? { types: [...definition.inputTypes] } : {}],
+});
+const toResultType = (definition) => definition.returnType ?? 'unknown';
+const toOutputType = (definition) => (inputType) => {
+    const declared = definition.returnType;
+    if (!declared) {
+        return undefined;
+    }
+    return declared === 'input' ? inputType : RETURN_TYPE_TO_VALUE_TYPE[declared];
+};
+export function toAggregationOperator(name, definition, adaptableApi) {
+    const getValueForColId = (colId, rowNode) => adaptableApi.gridApi.getRawValueFromRowNode(rowNode, colId);
+    const resolveArgsForRow = (params, rowNode) => params.map((param) => isColParam(param) ? getValueForColId(param.args[0], rowNode) : param);
+    const cumulativeOverride = typeof definition.cumulative === 'object' ? definition.cumulative.currentValue : undefined;
+    const collectsRows = !!definition.processAggregatedValue || !!cumulativeOverride;
+    let baseContext;
+    const refreshBaseContext = () => {
+        baseContext = adaptableApi.internalApi.buildBaseContext();
+        return baseContext;
+    };
+    const getBaseContext = () => baseContext ?? refreshBaseContext();
+    const buildReducerContext = (spec, state, value, rowCtx) => {
+        const rowNode = rowCtx.rowRef;
+        const context = {
+            accumulator: state.acc,
+            currentValue: value,
+            index: rowCtx.rowIndex,
+            rowNode,
+            args: resolveArgsForRow(spec.params, rowNode),
+            aggColumnId: spec.inputField,
+            groupByColumnIds: spec.groupBy,
+            getValueForColId: (colId) => getValueForColId(colId, rowNode),
+            ...getBaseContext(),
+        };
+        if (spec.hasWeight) {
+            context.weightValue = rowCtx.weightValue;
+        }
+        return context;
+    };
+    const buildProcessContext = (spec, state) => ({
+        ...getBaseContext(),
+        aggregatedValue: state.acc,
+        rowNodes: state.rows,
+        args: spec.params.map(toLegacyArg),
+        aggColumnId: spec.inputField,
+        groupByColumnIds: spec.groupBy,
+    });
+    const stepState = (spec, state, value, rowCtx) => {
+        state.acc = definition.reducer(buildReducerContext(spec, state, value, rowCtx));
+        if (collectsRows) {
+            state.rows.push(rowCtx.rowRef);
+        }
+    };
+    const finishState = (spec, state) => definition.processAggregatedValue
+        ? definition.processAggregatedValue(buildProcessContext(spec, state))
+        : state.acc;
+    const operator = {
+        name,
+        kind: 'reducer',
+        capabilities: {},
+        outputType: toOutputType(definition),
+        parameters: toParameters(definition),
+        resultType: toResultType(definition),
+        docs: {
+            description: definition.description,
+            signatures: definition.signatures,
+            examples: definition.examples,
+            category: definition.category ?? 'aggregation',
+        },
+        init: () => {
+            refreshBaseContext();
+            return { acc: resolveInitialValue(definition.initialValue), rows: [] };
+        },
+        step: (spec, acc, value, rowCtx) => {
+            const state = acc;
+            stepState(spec, state, value, rowCtx);
+            return state;
+        },
+        done: (spec, acc) => finishState(spec, acc),
+    };
+    if (definition.weight) {
+        operator.capabilities.weight = true;
+    }
+    if (definition.cumulative) {
+        operator.capabilities.cumulative = (spec) => ({
+            init: () => {
+                refreshBaseContext();
+                return {
+                    acc: resolveInitialValue(definition.initialValue),
+                    rows: [],
+                    lastIndex: -1,
+                };
+            },
+            step: (rawState, value, rowCtx) => {
+                const state = rawState;
+                stepState(spec, state, value, rowCtx);
+                state.lastRow = rowCtx.rowRef;
+                state.lastIndex = rowCtx.rowIndex;
+                state.lastWeight = rowCtx.weightValue;
+            },
+            current: (rawState) => {
+                const state = rawState;
+                if (!state.lastRow) {
+                    return SKIP_ROW;
+                }
+                if (!cumulativeOverride) {
+                    return finishState(spec, state);
+                }
+                const context = {
+                    ...buildProcessContext(spec, state),
+                    rowNode: state.lastRow,
+                    index: state.lastIndex,
+                };
+                if (spec.hasWeight) {
+                    context.weightValue = state.lastWeight;
+                }
+                return cumulativeOverride(context);
+            },
+        });
+    }
+    if (definition.prepareRowValue) {
+        operator.projectRow = (spec, aggregatedValue, rowCtx) => {
+            const rowNode = rowCtx.rowRef;
+            const prepareContext = {
+                rowNode,
+                aggregatedValue,
+                args: resolveArgsForRow(spec.params, rowNode),
+                aggColumnId: spec.inputField,
+                groupByColumnIds: spec.groupBy,
+                getValueForColId: (colId) => getValueForColId(colId, rowNode),
+                ...getBaseContext(),
+            };
+            if (spec.hasWeight) {
+                prepareContext.weightValue = rowCtx.weightValue;
+            }
+            return definition.prepareRowValue(prepareContext);
+        };
+    }
+    if (definition.filterRow) {
+        operator.rowGate = (rowRef, _rowData, spec, rowCtx) => {
+            const rowNode = rowRef;
+            return definition.filterRow({
+                rowNode,
+                args: resolveArgsForRow(spec.params, rowNode),
+                aggColumnId: spec.inputField,
+                groupByColumnIds: spec.groupBy,
+                getValueForColId: (colId) => getValueForColId(colId, rowNode),
+                ...getBaseContext(),
+                ...(spec.hasWeight ? { weightValue: rowCtx.weightValue } : {}),
+            });
+        };
+    }
+    return operator;
+}
+export function mapCustomAggregatedFunctionsToOperators(aggregatedScalarFunctions, adaptableApi) {
+    return Object.entries(aggregatedScalarFunctions).map(([name, definition]) => toAggregationOperator(name, definition, adaptableApi));
+}

package/src/aql/resolveCustomExpressionFunctions.d.ts

@@ -0,0 +1,21 @@
+import type { AdaptableCustomExpressionFunctionEntry, AdaptableExpressionFunction } from './types';
+export type ResolveCustomExpressionFunctionsLog = {
+    warn: (message: string) => void;
+    info: (message: string) => void;
+};
+/**
+ * Structural AQL primitives that must never be overridden by
+ * `customStandardFunctions` / `customAggregatedFunctions`.
+ */
+export declare const PROTECTED_CORE_EXPRESSION_FUNCTIONS: Set<string>;
+/**
+ * Resolves a custom expression-function map: applies `extends` inheritance,
+ * drops protected-core overrides, and logs system-function shadows.
+ * Pure helper used by `QueryLanguageService.resolveCustomFunctions`.
+ *
+ * Customs are flat objects carrying aql evaluation props + Adaptable
+ * enhancement props together, so the resolved entries have the same
+ * `AdaptableExpressionFunction` shape as the (already enriched) system pool
+ * they merge into.
+ */
+export declare const resolveCustomExpressionFunctions: (rawCustom: Record<string, AdaptableCustomExpressionFunctionEntry>, systemPool: Record<string, AdaptableExpressionFunction>, log: ResolveCustomExpressionFunctionsLog) => Record<string, AdaptableExpressionFunction>;

package/src/aql/resolveCustomExpressionFunctions.js

@@ -0,0 +1,82 @@
+export const PROTECTED_CORE_EXPRESSION_FUNCTIONS = new Set([
+    'COL',
+    'FIELD',
+    'QUERY',
+    'DATE',
+    '$SCOPE',
+    'NULL',
+    'VAR',
+    'TRUE',
+    'FALSE',
+    'AND',
+    'OR',
+    'NOT',
+]);
+const isPartialWithExtends = (entry) => !!entry &&
+    typeof entry === 'object' &&
+    'extends' in entry &&
+    typeof entry.extends === 'string';
+const overloadArity = (overload) => Array.isArray(overload) ? overload.length : 1;
+const isQueryBuilderEligibleFromOperands = (functionDef) => {
+    if (functionDef.returnType !== 'boolean') {
+        return false;
+    }
+    const operands = functionDef.operands;
+    if (!Array.isArray(operands) || operands.length === 0) {
+        return false;
+    }
+    return operands.every((overload) => {
+        const arity = overloadArity(overload);
+        return arity === 1 || arity === 2;
+    });
+};
+const applyQueryBuilderEligibility = (functionDef, isBrandNewCustom) => {
+    if (!isBrandNewCustom) {
+        return functionDef;
+    }
+    if (isQueryBuilderEligibleFromOperands(functionDef)) {
+        return { ...functionDef, excludeFromQueryBuilder: false };
+    }
+    return { ...functionDef, excludeFromQueryBuilder: true };
+};
+export const resolveCustomExpressionFunctions = (rawCustom, systemPool, log) => {
+    const resolved = new Map();
+    for (const [name, entry] of Object.entries(rawCustom)) {
+        if (!entry) {
+            continue;
+        }
+        let functionDef = null;
+        if (isPartialWithExtends(entry)) {
+            const target = systemPool[entry.extends] ?? resolved.get(entry.extends);
+            if (!target) {
+                log.warn(`Custom expression function '${name}' references a missing 'extends' target '${entry.extends}'. No such system or custom expression function found.`);
+                continue;
+            }
+            const { extends: _extends, ...rest } = entry;
+            functionDef = {
+                ...target,
+                ...rest,
+            };
+            if (rest.handler && !('hasEagerEvaluation' in rest)) {
+                delete functionDef.hasEagerEvaluation;
+            }
+        }
+        else {
+            functionDef = entry;
+        }
+        if (!functionDef?.handler) {
+            log.warn(`Custom expression function '${name}' is missing a handler and was ignored.`);
+            continue;
+        }
+        if (PROTECTED_CORE_EXPRESSION_FUNCTIONS.has(name)) {
+            log.warn(`Custom expression function '${name}' attempts to override a structural AQL primitive; ignored`);
+            continue;
+        }
+        if (systemPool[name]) {
+            log.info(`Custom expression function '${name}' overrides the system function`);
+        }
+        const isBrandNewCustom = !systemPool[name];
+        resolved.set(name, applyQueryBuilderEligibility(functionDef, isBrandNewCustom));
+    }
+    return Object.fromEntries(resolved);
+};

package/src/aql/resolveOperatorPresentation.d.ts

@@ -0,0 +1,28 @@
+import { type ExpressionFunctionInputType } from "../../vendor/aql/index.js";
+import type { AdaptableIcon } from '../AdaptableState/Common/AdaptableIcon';
+import type { AdaptableExpressionFunctionEnhancement } from './types';
+type OperatorPresentation = Pick<AdaptableExpressionFunctionEnhancement, 'label' | 'labelsBySubjectType' | 'icon' | 'iconsBySubjectType'>;
+export declare const isComparisonOperator: (operator: string) => boolean;
+/**
+ * Resolves the UI label for an operator, preferring a subject-type-specific
+ * label when provided (e.g. BETWEEN → "Range" for dates).
+ */
+export declare const resolveOperatorLabel: (presentation: OperatorPresentation | undefined, operator: string, subjectType?: ExpressionFunctionInputType) => string;
+/**
+ * Compact label for the *selected* operator control (Query Builder trigger).
+ * EQ / NEQ / LT / LTE / GT / GTE render as `=`, `!=`, `<`, `<=`, `>`, `>=`
+ * so rows read like AQL; everything else keeps the friendly word label.
+ * Menu items should still use {@link resolveOperatorLabel}.
+ *
+ * Multi-character symbols get a thin space between glyphs (`> =`) so the
+ * larger trigger typeface does not crush `>=` / `<=` / `!=` together.
+ */
+export declare const resolveOperatorTriggerLabel: (presentation: OperatorPresentation | undefined, operator: string, subjectType?: ExpressionFunctionInputType) => string;
+/**
+ * Resolves the UI icon for an operator, preferring a subject-type-specific
+ * icon when provided.
+ */
+export declare const resolveOperatorIcon: (presentation: OperatorPresentation | undefined, subjectType?: ExpressionFunctionInputType) => AdaptableIcon | {
+    text: string;
+} | undefined;
+export {};

package/src/aql/resolveOperatorPresentation.js

@@ -0,0 +1,22 @@
+import { getQlPredicateSymbol, } from "../../vendor/aql/index.js";
+const COMPARISON_OPERATORS = new Set(['EQ', 'NEQ', 'LT', 'LTE', 'GT', 'GTE']);
+export const isComparisonOperator = (operator) => COMPARISON_OPERATORS.has(operator);
+export const resolveOperatorLabel = (presentation, operator, subjectType) => {
+    if (subjectType && presentation?.labelsBySubjectType?.[subjectType]) {
+        return presentation.labelsBySubjectType[subjectType];
+    }
+    return presentation?.label ?? operator;
+};
+export const resolveOperatorTriggerLabel = (presentation, operator, subjectType) => {
+    if (isComparisonOperator(operator)) {
+        const symbol = getQlPredicateSymbol(operator);
+        return symbol.length > 1 ? symbol.split('').join('\u2009') : symbol;
+    }
+    return resolveOperatorLabel(presentation, operator, subjectType);
+};
+export const resolveOperatorIcon = (presentation, subjectType) => {
+    if (subjectType && presentation?.iconsBySubjectType?.[subjectType]) {
+        return presentation.iconsBySubjectType[subjectType];
+    }
+    return presentation?.icon;
+};

package/src/aql/systemExpressionFunctionEnhancements.d.ts

@@ -0,0 +1,55 @@
+import type { AggregationCallableName, AqlClauseName, ScalarFunctionName, ObservableSourceName } from "../../vendor/aql/index.js";
+import type { AdaptableExpressionFunctionEnhancement } from './types';
+/**
+ * Presentation / UX metadata for the **system** expression functions.
+ *
+ * The function definitions themselves (handler, operand matrix, docs) live in
+ * `@adaptabletools/aql`'s function packs and are host-agnostic; everything a
+ * grid application needs to *present* a function — label, icon, Quick Filter
+ * shortcuts, QueryBuilder `rhs` slots, menu visibility, Row Summary `inputs` —
+ * is Adaptable policy and lives here.
+ *
+ * The maps are exhaustively keyed by aql's exported per-pack name unions, so
+ * adding a function to an aql pack without deciding its Adaptable presentation
+ * is a compile error (an explicit `{}` entry means "no enhancement").
+ *
+ * Module *availability* is intentionally NOT declared per-function here — it
+ * comes from the aql `requires` declaration and the availability policy in
+ * `expressionFunctionAvailabilityOverlay.ts`, both applied together by
+ * `applySystemFunctionEnhancements`.
+ */
+export declare const scalarFunctionEnhancements: Record<ScalarFunctionName, AdaptableExpressionFunctionEnhancement>;
+/**
+ * Presentation for the aggregation callables (operators + compile-time
+ * sugar) the aql aggregation catalogue ships. Keyed exhaustively by
+ * `AggregationCallableName`, so a new system operator without a presentation
+ * decision is a compile error.
+ *
+ * `inputs` here is the Row Summary wizard's type-applicability hint (see the
+ * deprecation note on the enhancement type); the argument model itself comes
+ * from the operator's `parameters`.
+ */
+export declare const aggregatedFunctionEnhancements: Record<AggregationCallableName, AdaptableExpressionFunctionEnhancement>;
+/**
+ * Clause keywords accepted inside an aggregation brace call. They are not
+ * callables (nothing to evaluate — the compiler consumes them structurally),
+ * but the editors present them like functions (menu entries, chips, hover
+ * docs), so they get a presentation table of their own. Docs come from aql's
+ * `CLAUSE_DOCS`.
+ */
+export type AggregationClauseKeyword = Extract<AqlClauseName, 'GROUP_BY' | 'OVER' | 'WEIGHT' | 'CUMULATIVE' | 'WHERE'>;
+export declare const clauseEnhancements: Record<AggregationClauseKeyword, AdaptableExpressionFunctionEnhancement>;
+/**
+ * Clause keywords of an observable brace call (`ANY_COL()`, `WITHIN(5m)`,
+ * `LAST_N(20)`, `ALL_ROWS()`, `TRIGGER('edit')`).
+ */
+export type ObservableClauseKeyword = Extract<AqlClauseName, 'ANY_COL' | 'WITHIN' | 'LAST_N' | 'ALL_ROWS' | 'TRIGGER'>;
+/** Names of the observable pool: the history readers plus their clause keywords. */
+export type ObservablePoolName = ObservableSourceName | ObservableClauseKeyword;
+/**
+ * Presentation for the observable pool. Keyed exhaustively so a new observable
+ * source in aql without a presentation decision is a compile error.
+ * Icons / chips arrive with the authoring polish; labels are enough for the
+ * function menu and hover docs.
+ */
+export declare const observableFunctionEnhancements: Record<ObservablePoolName, AdaptableExpressionFunctionEnhancement>;