@adaptabletools/adaptable 24.0.0-canary.4 → 24.0.0-canary.6

package/aql.d.ts

@@ -0,0 +1,104 @@
+import type { AdaptableColumnDataType } from './src/AdaptableState/Common/AdaptableColumn';
+import type { AdaptableStandardExpressionModule } from './src/AdaptableState/Common/Types';
+import { type LegacyExpressionKind } from './src/aql/legacyExpressionKinds';
+/**
+ * What an Expression returns, and whether it is evaluated per row or across rows:
+ * - `boolean` - Standard boolean Expressions: Grid Filter, Column Filter, Format Column,
+ *   Alert and Flashing Cell rules, Named Queries, Reports; also Relative Change
+ *   (`ANY_CHANGE()`) and boolean Observable rules (`CHANGE_COUNT{[price], WITHIN(5m)} >= 2`)
+ * - `scalar` - Standard Expressions returning a value: Calculated Columns, scalar Named
+ *   Queries; also Observable values (`MAX{[price], WITHIN(1d)}`)
+ * - `aggregatedScalar` - Aggregation Expressions in Calculated Columns (`SUM{[price]}`),
+ *   including Cumulative, Quantile and Window Expressions (`LAG{[price], 1, OVER([date])}`)
+ * - `aggregatedBoolean` - Aggregation rules in Alerts (`SUM{[price]} > 100`)
+ *
+ * Which of these a Module accepts, and which Functions it offers, is checked
+ * when `module` is passed to {@link validateExpression}.
+ */
+export type AdaptableQLExpressionKind = LegacyExpressionKind;
+export interface ValidateExpressionOptions {
+    kind: AdaptableQLExpressionKind;
+    /**
+     * Module the Expression belongs to. Applies that Module's rules: Observable
+     * Functions only in Alert, Calculated Column, Format Column and Flashing
+     * Cell; Relative Change Functions only in Alert and Flashing Cell;
+     * Cumulative and Window Functions only in Calculated Columns; aggregated
+     * kinds only in the Modules that evaluate them. When omitted, every
+     * system Function is accepted.
+     */
+    module?: AdaptableStandardExpressionModule;
+    /**
+     * Column Id to AdapTable data type. When provided, references to other
+     * Columns are errors and Column types are checked against Function inputs.
+     */
+    columns?: Record<string, AdaptableColumnDataType | undefined>;
+}
+export interface ExpressionValidationIssue {
+    /** Stable identifier, e.g. `AQL_LEGACY_SPELLING`; absent for generic type errors */
+    code?: string;
+    message: string;
+    severity: 'error' | 'warning' | 'info';
+    /** Character range in the Expression `[start, end)` */
+    range?: [number, number];
+    /** Suggested rewrite, when one exists */
+    quickFix?: {
+        label: string;
+        replacement: string;
+        range?: [number, number];
+    };
+}
+export interface ExpressionValidationResult {
+    isValid: boolean;
+    issues: ExpressionValidationIssue[];
+}
+export interface MigrateExpressionResult {
+    /** Current-syntax Expression, or the input unchanged when it does not parse */
+    expression: string;
+    changed: boolean;
+    /** Set when the input does not parse */
+    error?: string;
+    /** How a rewritten legacy observable rule differs in meaning from the original */
+    notes?: string[];
+}
+export interface ExpressionFunctionDescription {
+    name: string;
+    /** `paren` is `NAME(...)`, `brace` is `NAME{...}` */
+    callForm: 'paren' | 'brace';
+    group: 'scalar' | 'aggregation' | 'observable' | 'clause';
+    returnType?: string;
+    description?: string;
+    signatures: string[];
+    examples: string[];
+    category?: string;
+}
+/**
+ * Validates an AdapTableQL Expression without a grid. Mirrors
+ * `ExpressionApi.isValidBooleanExpression` / `isValidScalarExpression` /
+ * `isValidAggregatedScalarExpression` / `isValidAggregatedBooleanExpression`,
+ * but reports every issue (with ranges and quick fixes) instead of the first.
+ *
+ * Pre-v24 spellings (`CUMUL(...)`, `TIMEFRAME(...)`, paren aggregations) are
+ * errors; convert them with {@link migrateExpression} first.
+ */
+export declare function validateExpression(expressionInput: string, options: ValidateExpressionOptions): ExpressionValidationResult;
+/**
+ * Converts a pre-v24 AdapTableQL Expression to the current syntax: brace
+ * aggregations (`SUM{[price]}`), named operands (`CUMULATIVE(...)`,
+ * `WITHIN(5m)`), no `CUMUL(...)` / `TIMEFRAME(...)` wrappers. Same logic as
+ * `ExpressionApi.migratePreV24Expression`.
+ *
+ * Pass `kind` for single-argument dual names: `SUM([x])` is an aggregation
+ * in the aggregated kinds and a row-wise scalar elsewhere.
+ *
+ * Legacy observable rules (`ROW_CHANGE(COUNT([price], 3), TIMEFRAME('5m'))`)
+ * are rewritten to observable calls (`CHANGE_COUNT{[price], WITHIN(5m)} >= 3`),
+ * as the State upgrade does for Alerts.
+ */
+export declare function migrateExpression(expression: string, options?: {
+    kind?: AdaptableQLExpressionKind;
+}): MigrateExpressionResult;
+/**
+ * Every system Expression Function, aggregation, observable function and
+ * clause, with its signatures and examples.
+ */
+export declare function getExpressionFunctionCatalogue(): ExpressionFunctionDescription[];

package/aql.js

@@ -0,0 +1,212 @@
+import { CLAUSE_DOCS, SYSTEM_AGGREGATION_CATALOGUE, compileValueExpression, isAST_Function, mapDataTypeToStaticType, migrateExpression as migrateAqlExpression, normalizeAst, parse, validateAqlExpression, validateExpressionTypes, } from "./vendor/aql/index.js";
+import { AGGREGATED_BOOLEAN_MODULES, moduleAllowsObservableCalls, } from './src/aql/expressionFunctionAvailability';
+import { getMissingColumnIssues } from './src/aql/getMissingColumnIssues';
+import { mapLegacyKindToValidationRequest, toMigrateOptions, } from './src/aql/legacyExpressionKinds';
+import { systemAggregatedExpressionFunctions, systemAggregationClauseFunctions, systemObservableExpressionFunctions, systemScalarExpressionFunctions, } from './src/aql/systemExpressionFunctions';
+const scalarFunctions = {
+    ...systemObservableExpressionFunctions,
+    ...systemScalarExpressionFunctions,
+};
+const isAggregatedKind = (kind) => kind === 'aggregatedScalar' || kind === 'aggregatedBoolean';
+const AGGREGATED_KIND_MODULES = {
+    aggregatedScalar: ['CalculatedColumn'],
+    aggregatedBoolean: AGGREGATED_BOOLEAN_MODULES,
+};
+const scalarPool = systemScalarExpressionFunctions;
+const aggregationPool = {
+    ...systemAggregatedExpressionFunctions,
+    ...systemAggregationClauseFunctions,
+};
+function getModuleAvailabilityIssues(ast, module, aggregated) {
+    const issues = [];
+    const reported = new Set();
+    const visit = (node) => {
+        if (node == null || typeof node !== 'object') {
+            return;
+        }
+        if (Array.isArray(node)) {
+            node.forEach(visit);
+            return;
+        }
+        if (!isAST_Function(node)) {
+            Object.values(node).forEach(visit);
+            return;
+        }
+        const fn = node;
+        const kind = fn.kind ?? fn.metaInfo;
+        if (kind === 'OBSERVABLE_CALL') {
+            return;
+        }
+        const scalar = kind === 'FUNCTION' ? scalarPool[fn.type] : undefined;
+        const modules = (scalar ?? (aggregated ? aggregationPool[fn.type] : undefined))?.isAvailable;
+        if (Array.isArray(modules) && !modules.includes(module)) {
+            if (!reported.has(fn.type)) {
+                reported.add(fn.type);
+                issues.push({
+                    code: 'AQL_NOT_AVAILABLE_IN_MODULE',
+                    message: `${fn.type} is not available in ${module} Expressions (only in ${modules.join(', ')})`,
+                    severity: scalar ? 'error' : 'warning',
+                    range: fn.range,
+                });
+            }
+            return;
+        }
+        fn.args.forEach(visit);
+    };
+    visit(ast);
+    return issues;
+}
+const error = (message, code) => ({
+    code,
+    message,
+    severity: 'error',
+});
+const toResult = (issues) => {
+    const byKey = new Map();
+    for (const issue of issues) {
+        const key = `${issue.message}::${issue.range?.join(',') ?? ''}`;
+        if (!byKey.get(key)?.code) {
+            byKey.set(key, issue);
+        }
+    }
+    const unique = [...byKey.values()];
+    return {
+        isValid: !unique.some((issue) => issue.severity === 'error'),
+        issues: unique,
+    };
+};
+export function validateExpression(expressionInput, options) {
+    const expression = (expressionInput ?? '').trim();
+    if (expression === '') {
+        return toResult([error(`empty ${options.kind} expression`, 'AQL_EMPTY')]);
+    }
+    let ast;
+    try {
+        ast = parse(expression).ast;
+    }
+    catch (e) {
+        return toResult([error(e instanceof Error ? e.message : String(e), 'AQL_PARSE_ERROR')]);
+    }
+    const columns = options.columns;
+    const getColumnType = columns
+        ? (columnId) => mapDataTypeToStaticType(columns[columnId])
+        : undefined;
+    const issues = [];
+    if (!isAggregatedKind(options.kind)) {
+        const rootFn = ast[ast.length - 1];
+        if (rootFn?.type === undefined || scalarFunctions[rootFn.type] === undefined) {
+            return toResult([
+                error(`provided function ${rootFn?.type} cannot be handled`, 'AQL_UNKNOWN_FUNCTION'),
+            ]);
+        }
+        const typeCheck = validateExpressionTypes(ast, scalarFunctions, {
+            getBraceCallSpec: SYSTEM_AGGREGATION_CATALOGUE.getBraceCallSpec,
+            getColumnType,
+        });
+        issues.push(...typeCheck.issues);
+    }
+    const { module } = options;
+    let kindInModule = true;
+    if (module && isAggregatedKind(options.kind)) {
+        const modules = AGGREGATED_KIND_MODULES[options.kind];
+        kindInModule = modules.includes(module);
+        if (!kindInModule) {
+            issues.push(error(`${module} does not evaluate ${options.kind} Expressions (only ${modules.join(', ')} does)`, 'AQL_KIND_NOT_IN_MODULE'));
+        }
+    }
+    const structure = validateAqlExpression(ast, {
+        request: {
+            ...mapLegacyKindToValidationRequest(options.kind),
+            requiresAggCalls: false,
+            allowsObservableCalls: module ? moduleAllowsObservableCalls(module) : true,
+        },
+        scalarFunctions,
+        catalogue: SYSTEM_AGGREGATION_CATALOGUE,
+        getColumnType,
+    });
+    issues.push(...structure.issues);
+    if (module && kindInModule) {
+        issues.push(...getModuleAvailabilityIssues(structure.normalizedAst, module, isAggregatedKind(options.kind)));
+    }
+    if (columns) {
+        issues.push(...getMissingColumnIssues(ast, (columnId) => columnId in columns).map((issue) => ({
+            ...issue,
+            code: 'AQL_UNKNOWN_COLUMN',
+        })));
+    }
+    if (isAggregatedKind(options.kind) && !issues.some((issue) => issue.severity === 'error')) {
+        const mismatch = error(`provided ${options.kind} expression does not evaluate to a supported aggregation`, 'AQL_AGG_REQUIRED');
+        try {
+            const compiled = compileValueExpression(normalizeAst(ast), {
+                registry: SYSTEM_AGGREGATION_CATALOGUE,
+                getColumnType,
+                scalarFunctions: systemScalarExpressionFunctions,
+            });
+            const isBoolean = compiled.outputType === 'boolean';
+            if (compiled.aggregations.length === 0 ||
+                (options.kind === 'aggregatedBoolean' && !isBoolean) ||
+                (options.kind === 'aggregatedScalar' && isBoolean)) {
+                issues.push(mismatch);
+            }
+        }
+        catch (e) {
+            issues.push(error(e instanceof Error ? e.message : String(e)));
+        }
+    }
+    return toResult(issues);
+}
+export function migrateExpression(expression, options) {
+    const result = migrateAqlExpression((expression ?? '').trim(), {
+        ...toMigrateOptions(options?.kind),
+        rewriteLegacyObservables: true,
+    });
+    return {
+        expression: result.expression,
+        changed: result.changed,
+        ...(result.error !== undefined ? { error: result.error } : {}),
+        ...(result.notes?.length ? { notes: result.notes.map((note) => note.message) } : {}),
+    };
+}
+export function getExpressionFunctionCatalogue() {
+    const scalar = Object.entries(systemScalarExpressionFunctions).map(([name, fn]) => ({
+        name,
+        callForm: 'paren',
+        group: 'scalar',
+        returnType: fn.returnType,
+        description: fn.description,
+        signatures: fn.signatures ?? [],
+        examples: fn.examples ?? [],
+        category: fn.category,
+    }));
+    const aggregations = SYSTEM_AGGREGATION_CATALOGUE.callables()
+        .filter((callable) => callable.system)
+        .map((callable) => ({
+        name: callable.name,
+        callForm: callable.callForm,
+        group: 'aggregation',
+        description: callable.docs.description,
+        signatures: callable.docs.signatures ?? [],
+        examples: callable.docs.examples ?? [],
+        category: callable.docs.category,
+    }));
+    const observables = Object.entries(systemObservableExpressionFunctions).map(([name, fn]) => ({
+        name,
+        callForm: 'brace',
+        group: 'observable',
+        returnType: fn.returnType,
+        description: fn.description,
+        signatures: fn.signatures ?? [],
+        examples: fn.examples ?? [],
+        category: fn.category,
+    }));
+    const clauses = Object.entries(CLAUSE_DOCS).map(([name, docs]) => ({
+        name,
+        callForm: 'paren',
+        group: 'clause',
+        description: docs.description,
+        signatures: docs.signatures,
+        examples: docs.examples,
+        category: docs.category,
+    }));
+    return [...scalar, ...aggregations, ...observables, ...clauses];
+}

package/devtools.d.ts

@@ -1,4 +1,175 @@
-import { AdaptableApi } from './types';
+import type { VisibleSettingsPanelNavigationGroup, VisibleSettingsPanelNavigationItem } from './src/Utilities/Helpers/SettingsPanelHelper';
+import type { AdaptableApi, AdaptableColumnDataType, AdaptableModule, AdaptablePersistentState, AdaptableState } from './types';
+/**
+ * One AdapTable instance as reported by `window.__ADAPTABLE_DEVTOOLS__.listInstances()`.
+ */
+export type DevToolsInstanceInfo = {
+    adaptableId: string;
+    adaptableVersion: string;
+    agGridVersion: string;
+    adaptableStateKey: string;
+    primaryKey?: string;
+    userName?: string;
+    gridRuntime: DevToolsGridRuntime;
+};
+/**
+ * Column description returned by `window.__ADAPTABLE_DEVTOOLS__.getColumns()`.
+ *
+ * `id` and `dataType` match the `columns` input of the AdapTable MCP server's
+ * `check_state` and `check_expression` tools.
+ */
+export type DevToolsColumnInfo = {
+    /** AdapTable column id (AG Grid `colId`) */
+    id: string;
+    friendlyName: string;
+    dataType: AdaptableColumnDataType;
+    field?: string;
+    columnTypes?: string[];
+    visible: boolean;
+    readOnly: boolean;
+    isPrimaryKey: boolean;
+    isGrouped: boolean;
+    pinned: 'left' | 'right' | false;
+    isGeneratedRowGroupColumn: boolean;
+    isGeneratedPivotResultColumn: boolean;
+    isCalculatedColumn: boolean;
+    isFreeTextColumn: boolean;
+    isActionColumn: boolean;
+};
+/**
+ * Snapshot of the facts shown in the Settings Panel `Grid Info` section,
+ * returned by `window.__ADAPTABLE_DEVTOOLS__.getGridInfo()`.
+ */
+export type DevToolsGridInfo = {
+    adaptableId: string;
+    adaptableVersion: string;
+    agGridVersion: string;
+    adaptableStateKey: string;
+    userName?: string;
+    primaryKey?: string;
+    isAutogeneratedPrimaryKey: boolean;
+    licenseKey?: string;
+    layout: {
+        name: string;
+        type: 'Table' | 'Pivot';
+        rowGroups: string[];
+        pivotColumns: string[];
+        sorts: {
+            columnId: string;
+            sortOrder: string;
+        }[];
+    };
+    columnFilters: string;
+    gridFilter?: string;
+    rows: {
+        all: number;
+        visible: number;
+        selected: number;
+    };
+    columns: {
+        all: number;
+        visible: number;
+        calculated: string[];
+        freeText: string[];
+        action: string[];
+    };
+    modules: {
+        available: AdaptableModule[];
+        unavailable: AdaptableModule[];
+    };
+};
+export type DevToolsLogLevel = 'info' | 'success' | 'warn' | 'error' | 'perf';
+/**
+ * A log message AdapTable wrote, kept in the in-page buffer regardless of
+ * `localStorage.debug`.
+ */
+export type DevToolsLogEntry = {
+    timestamp: number;
+    adaptableId: string;
+    channel: string;
+    level: DevToolsLogLevel;
+    /** Message arguments, each formatted as a string (objects as JSON) */
+    args: string[];
+};
+/**
+ * A state-changing Redux action AdapTable dispatched (transient UI actions are skipped).
+ */
+export type DevToolsActionEntry = {
+    timestamp: number;
+    actionName: string;
+};
+/**
+ * In-page API exposed as `window.__ADAPTABLE_DEVTOOLS__` as soon as AdapTable
+ * loads in a browser.
+ *
+ * Built for tools that evaluate JavaScript in the page (coding agents using
+ * Chrome DevTools MCP, Playwright `page.evaluate`, the browser console): every
+ * method returns plain JSON unless noted, so the result survives serialization.
+ *
+ * `adaptableId` can be omitted whenever exactly one AdapTable instance is
+ * mounted; with several instances, pass the id (see `listInstances()`).
+ * Unknown ids throw an `Error` naming the mounted instances.
+ *
+ * ```ts
+ * window.__ADAPTABLE_DEVTOOLS__.listInstances();
+ * window.__ADAPTABLE_DEVTOOLS__.getState('Trades', 'Layout');
+ * window.__ADAPTABLE_DEVTOOLS__.getLogs('Trades', { level: 'error' });
+ * ```
+ *
+ * The AdapTable DevTools Chrome extension uses the same functions.
+ */
+export interface AdaptableDevToolsGlobal {
+    /** Short usage text for anyone who only has the global */
+    help(): string;
+    /** Every mounted AdapTable instance with versions, identity and row counts */
+    listInstances(): DevToolsInstanceInfo[];
+    /**
+     * Full AdapTable State (including the transient `Internal`, `Popup`, `Comment` and
+     * `Plugins` sections), serialized. Pass `section` (e.g. `'Layout'`, `'FormatColumn'`)
+     * for one section only.
+     */
+    getState(adaptableId?: string, section?: keyof AdaptableState | string): any;
+    /**
+     * Persistent (user) state: what AdapTable saves to storage. Use it as the `state`
+     * argument of the MCP `check_state` and `migrate_state` tools.
+     */
+    getPersistentState(adaptableId?: string): AdaptablePersistentState;
+    /** Columns AdapTable knows about, with data types and visibility */
+    getColumns(adaptableId?: string): DevToolsColumnInfo[];
+    /** The facts shown in the Settings Panel Grid Info section */
+    getGridInfo(adaptableId?: string): DevToolsGridInfo;
+    /**
+     * Most recent AdapTable log messages (default 100, newest last), optionally
+     * filtered by level or channel substring. Messages are buffered whether or not
+     * `localStorage.debug` is set.
+     */
+    getLogs(adaptableId?: string, options?: {
+        level?: DevToolsLogLevel | DevToolsLogLevel[];
+        channel?: string;
+        limit?: number;
+    }): DevToolsLogEntry[];
+    /** Most recent state-changing actions (default 50, newest last) */
+    getRecentActions(adaptableId?: string, limit?: number): DevToolsActionEntry[];
+    /** Restores a state snapshot (as returned by `getState` or `getPersistentState`) */
+    restoreState(adaptableId: string | undefined, state: AdaptablePersistentState): Promise<void>;
+    /** Opens the Settings Panel, at a Module section when given */
+    openSettingsPanel(adaptableId?: string, moduleName?: AdaptableModule): void;
+    /**
+     * Sets `localStorage.debug` (e.g. `'Adaptable:Trades:*'`, `'Adaptable:*:error'`),
+     * `null` removes it. Returns the previous value. Channels created after the call
+     * pick it up at once; reload the page to apply it to every channel.
+     */
+    setLogging(pattern: string | null): string | null;
+    /** Toggles `localStorage.adaptableProfileTracks` (Chrome Performance panel tracks) */
+    enableProfiling(enabled?: boolean): void;
+    /** The live `AdaptableApi` of an instance (not serializable; for in-page use) */
+    getApi(adaptableId?: string): AdaptableApi;
+}
+declare global {
+    interface Window {
+        __ADAPTABLE_DEVTOOLS__?: AdaptableDevToolsGlobal;
+    }
+}
 export type DevToolsMessageAddress = 'adaptable-devtools-contentscript' | 'adaptable-devtools-contentscript-panel' | 'adaptable-devtools-background' | 'adaptable-page';
 export type DevToolsGenericMessage = {
     source: DevToolsMessageAddress;
@@ -25,11 +196,17 @@ export type DevToolsGridRuntime = {
     visibleRowsCount: number;
     selectedRowsCount: number;
 };
+export type DevToolsSettingsPanelNavigationItem = VisibleSettingsPanelNavigationItem;
+export type DevToolsSettingsPanelNavigationGroup = VisibleSettingsPanelNavigationGroup;
 export type DevToolsMountPayload = {
     adaptableId: string;
     adaptableVersion: string;
     agGridVersion: string;
     licenseKey?: string;
+    userName?: string;
+    primaryKey?: string;
+    /** Grouped modules visible in the Settings Panel sidebar for this instance. */
+    settingsPanelNavigation?: DevToolsSettingsPanelNavigationGroup[];
 };
 export type DevToolsHostPageLogMessage = {
     type: Extract<DevToolsHostPageMessageType, 'log'>;
@@ -65,6 +242,10 @@ export type DevToolsHostPageMessage = {
         state: any;
         actionName?: string;
         gridRuntime?: DevToolsGridRuntime;
+        licenseKey?: string;
+        userName?: string;
+        primaryKey?: string;
+        settingsPanelNavigation?: DevToolsSettingsPanelNavigationGroup[];
     };
 } | DevToolsHostPageLogMessage);
 export type DevToolsHookFn = (adaptableId: string, options: null | DevToolsFnOptions) => void;