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

package/src/aql/systemExpressionFunctionEnhancements.js

@@ -0,0 +1,234 @@
+export const scalarFunctionEnhancements = {
+    TRUE: { label: 'True', icon: { text: 'T' } },
+    FALSE: { label: 'False', icon: { text: 'F' } },
+    AND: { label: 'And', isHiddenFromMenu: true, inputs: ['boolean', 'boolean'], icon: { text: '&' } },
+    OR: { label: 'Or', isHiddenFromMenu: true, inputs: ['boolean', 'boolean'], icon: { text: '|' } },
+    NOT: { label: 'Not', isHiddenFromMenu: true, inputs: ['boolean'], icon: { text: '!' } },
+    EQ: { label: 'Equals', shortcuts: ['='], isHiddenFromMenu: true, icon: { name: 'equals' } },
+    NEQ: {
+        label: 'Not Equals',
+        shortcuts: ['!='],
+        isHiddenFromMenu: true,
+        icon: { name: 'not-equal' },
+    },
+    LT: {
+        label: 'Less Than',
+        labelsBySubjectType: { date: 'Before' },
+        shortcuts: ['<'],
+        isHiddenFromMenu: true,
+        icon: { name: 'less-than' },
+    },
+    LTE: {
+        label: 'Less Than or Equals',
+        labelsBySubjectType: { date: 'On Or Before' },
+        shortcuts: ['<='],
+        isHiddenFromMenu: true,
+        icon: { name: 'less-than-or-equal' },
+    },
+    GT: {
+        label: 'Greater Than',
+        labelsBySubjectType: { date: 'After' },
+        shortcuts: ['>'],
+        isHiddenFromMenu: true,
+        icon: { name: 'greater-than' },
+    },
+    GTE: {
+        label: 'Greater Than or Equals',
+        labelsBySubjectType: { date: 'On Or After' },
+        shortcuts: ['>='],
+        isHiddenFromMenu: true,
+        icon: { name: 'greater-than-or-equal' },
+    },
+    IN: { label: 'In', shortcuts: ['#', '['], icon: { name: 'in' } },
+    NOT_IN: { label: 'Not In', icon: { name: 'not-in' } },
+    CONTAINS: { label: 'Contains', icon: { name: 'contains' } },
+    NOT_CONTAINS: { label: 'Not Contains', icon: { name: 'contains' } },
+    STARTS_WITH: { label: 'Starts With', icon: { name: 'starts-with' } },
+    ENDS_WITH: { label: 'Ends With', icon: { name: 'ends-with' } },
+    ANY_CONTAINS: {
+        label: 'Any Contains',
+        rhs: [{ allowedOperands: ['value'], editor: 'free', label: 'Search Text' }],
+    },
+    IS_NUMERIC: { label: 'Is Numeric', isHiddenFromMenu: false },
+    REGEX: {
+        label: 'Regex',
+        isHiddenFromMenu: false,
+        icon: { name: 'regex' },
+        rhs: [{ allowedOperands: ['value'], editor: 'free', label: 'Pattern' }],
+    },
+    IS_TODAY: { label: 'Today', isHiddenFromMenu: false, icon: { name: 'calendar' } },
+    IS_YESTERDAY: { label: 'Yesterday', isHiddenFromMenu: false, icon: { text: '-1' } },
+    IS_TOMORROW: { label: 'Tomorrow', isHiddenFromMenu: false, icon: { text: '+1' } },
+    IS_HOLIDAY: { label: 'Holiday', isHiddenFromMenu: false, icon: { name: 'star' } },
+    IS_WORKDAY: { label: 'Working Day', isHiddenFromMenu: false, icon: { name: 'schedule' } },
+    IS_THIS_WEEK: { label: 'This Week', isHiddenFromMenu: false, icon: { text: 'W' } },
+    IS_THIS_MONTH: { label: 'This Month', isHiddenFromMenu: false, icon: { text: 'M' } },
+    IS_THIS_QUARTER: { label: 'This Quarter', isHiddenFromMenu: false, icon: { text: 'Q' } },
+    IS_THIS_YEAR: { label: 'This Year', isHiddenFromMenu: false, icon: { text: 'Y' } },
+    IS_PAST: { label: 'In Past', isHiddenFromMenu: false, icon: { name: 'history' } },
+    IS_FUTURE: { label: 'In Future', isHiddenFromMenu: false, icon: { name: 'fast-forward' } },
+    IS_BEFORE_TODAY: {
+        label: 'Before Today',
+        isHiddenFromMenu: false,
+        icon: { text: '<T' },
+    },
+    IS_AFTER_TODAY: {
+        label: 'After Today',
+        isHiddenFromMenu: false,
+        icon: { text: '>T' },
+    },
+    IS_NEXT_WORKDAY: {
+        label: 'Next Work Day',
+        isHiddenFromMenu: false,
+        icon: { name: 'arrow-right' },
+    },
+    IS_PREV_WORKDAY: {
+        label: 'Last Work Day',
+        isHiddenFromMenu: false,
+        icon: { name: 'arrow-left' },
+    },
+    IS_SAME_DAY: { label: 'Same Day', isHiddenFromMenu: false, icon: { name: 'same-day' } },
+    IS_DIFFERENT_DAY: { label: 'Different Day', isHiddenFromMenu: false, icon: { name: 'not-equal' } },
+    VAR: { label: 'Var' },
+    COL: { label: 'Col' },
+    FIELD: { label: 'Field' },
+    $SCOPE: { label: 'Scope' },
+    QUERY: { label: 'Query' },
+    TO_ARRAY: { label: 'To Array' },
+    COALESCE: { label: 'Coalesce' },
+    NULL: { label: 'Null' },
+    IS_BLANK: { label: 'Blanks', icon: { name: 'unfilled-circle' } },
+    IS_NOT_BLANK: { label: 'Non Blanks', icon: { name: 'filled-circle' } },
+    IS_POSITIVE: { label: 'Positive', icon: { text: '>0' } },
+    IS_NEGATIVE: { label: 'Negative', icon: { text: '<0' } },
+    ABS: { label: 'Abs' },
+    CEILING: { label: 'Ceiling' },
+    FLOOR: { label: 'Floor' },
+    ROUND: {
+        label: 'Round',
+        rhs: [{ label: 'Decimal Places' }],
+    },
+    SIGN: { label: 'Sign' },
+    SQRT: { label: 'Square Root', icon: { text: '√' } },
+    MIN: { label: 'Min' },
+    MAX: { label: 'Max' },
+    AVG: { label: 'Avg' },
+    SUM: { label: 'Sum' },
+    SUB: { label: 'Sub', isHiddenFromMenu: true },
+    PRODUCT: { label: 'Product' },
+    DIV: { label: 'Div', isHiddenFromMenu: true },
+    MOD: { label: 'Mod', isHiddenFromMenu: true },
+    IF: { label: 'If', isHiddenFromMenu: true },
+    CASE: { label: 'Case', isHiddenFromMenu: true },
+    IFERROR: {
+        label: 'If Error',
+        icon: { text: 'IE' },
+        rhs: [{ label: 'Value' }, { label: 'Fallback' }],
+    },
+    IFNA: {
+        label: 'If N/A',
+        icon: { text: 'NA' },
+        rhs: [{ label: 'Value' }, { label: 'Fallback' }],
+    },
+    NA: { label: 'N/A', icon: { text: '#N/A' } },
+    POW: { label: 'Pow', isHiddenFromMenu: true },
+    DATE: { label: 'Date' },
+    NOW: { label: 'Now' },
+    CURRENT_DAY: { label: 'Current Day' },
+    DAY: { label: 'Day of Month', icon: { text: 'D' } },
+    WEEK: { label: 'Week Number', icon: { text: 'W#' } },
+    WEEKDAY: { label: 'Weekday', icon: { text: '1–7' } },
+    MONTH: { label: 'Month', icon: { text: 'M#' } },
+    YEAR: { label: 'Year', icon: { text: 'Y#' } },
+    QUARTER: { label: 'Quarter', icon: { text: 'Q#' } },
+    START_OF_DAY: { label: 'Start of Day' },
+    START_OF_WEEK: { label: 'Start of Week' },
+    START_OF_MONTH: { label: 'Start of Month' },
+    START_OF_QUARTER: { label: 'Start of Quarter' },
+    START_OF_YEAR: { label: 'Start of Year' },
+    END_OF_MONTH: { label: 'End of Month' },
+    EDATE: { label: 'EDate', icon: { text: 'ED' } },
+    EOMONTH: { label: 'EOMonth', icon: { text: 'EM' } },
+    ADD_DAYS: { label: 'Add Days' },
+    ADD_WEEKS: { label: 'Add Weeks' },
+    ADD_MONTHS: { label: 'Add Months' },
+    ADD_YEARS: { label: 'Add Years' },
+    WORKDAY: { label: 'Workday', icon: { text: 'WD' } },
+    NETWORKDAYS: { label: 'Network Days', icon: { text: 'ND' } },
+    DIFF_DAYS: { label: 'Diff Days' },
+    DIFF_WEEKS: { label: 'Diff Weeks' },
+    DIFF_MONTHS: { label: 'Diff Months' },
+    DIFF_YEARS: { label: 'Diff Years' },
+    LEN: { label: 'Len' },
+    SUB_STRING: { label: 'Sub String' },
+    LEFT: { label: 'Left', icon: { text: 'L' } },
+    MID: { label: 'Mid', icon: { text: 'M' } },
+    RIGHT: { label: 'Right', icon: { text: 'R' } },
+    TEXTJOIN: {
+        label: 'Text Join',
+        icon: { text: 'TJ' },
+        rhs: [{ label: 'Delimiter' }, { label: 'Ignore Empty' }],
+    },
+    UPPER: { label: 'Upper' },
+    LOWER: { label: 'Lower' },
+    REPLACE: { label: 'Replace' },
+    TRIM: { label: 'Trim' },
+    CONCAT: { label: 'Concat' },
+    PERCENT_CHANGE: { label: 'Percent Change', inputs: ['number'] },
+    ABSOLUTE_CHANGE: { label: 'Absolute Change', inputs: ['number'] },
+    ANY_CHANGE: { label: 'Any Change' },
+};
+export const aggregatedFunctionEnhancements = {
+    SUM: { inputs: ['number'], label: 'Sum' },
+    PRODUCT: { inputs: ['number'], label: 'Product' },
+    PERCENTAGE: { label: 'Percentage' },
+    AVG: { inputs: ['number'], label: 'Avg' },
+    MEDIAN: { inputs: ['number'], label: 'Median' },
+    MODE: { inputs: [['number'], ['text'], ['date']], label: 'Mode' },
+    DISTINCT: { inputs: [['number'], ['text'], ['date']], label: 'Distinct' },
+    ONLY: { inputs: [['number'], ['text']], label: 'Only' },
+    STD_DEVIATION: { inputs: ['number'], label: 'Std Deviation' },
+    MIN: { inputs: [['number'], ['date']], label: 'Min' },
+    MAX: { inputs: [['number'], ['date']], label: 'Max' },
+    QUANT: { label: 'Quant' },
+    QUARTILE: { label: 'Quartile' },
+    PERCENTILE: { label: 'Percentile' },
+    COUNT: { inputs: [['number'], ['text'], ['date']], label: 'Count' },
+    LAG: { label: 'Lag (Previous)' },
+    LEAD: { label: 'Lead (Next)' },
+    FIRST: { label: 'First' },
+    LAST: { label: 'Last' },
+    RANK: { label: 'Rank' },
+    ABSOLUTE_DIFF: { label: 'Absolute Diff' },
+    PERCENT_DIFF: { label: 'Percent Diff' },
+    SUMIF: { label: 'Sum If' },
+    COUNTIF: { label: 'Count If' },
+    AVGIF: { label: 'Average If' },
+};
+export const clauseEnhancements = {
+    GROUP_BY: { label: 'Group By' },
+    OVER: { label: 'Over' },
+    WEIGHT: { label: 'Weight' },
+    CUMULATIVE: { label: 'Cumulative' },
+    WHERE: { label: 'Where', isHiddenFromMenu: true },
+};
+export const observableFunctionEnhancements = {
+    CHANGE_COUNT: { label: 'Change Count' },
+    NO_CHANGES: { label: 'No Changes' },
+    SINCE_CHANGE: { label: 'Since Change' },
+    CHANGED_AT: { label: 'Changed At' },
+    NET_CHANGE: { label: 'Net Change' },
+    PERCENT_CHANGE: { label: 'Percent Change' },
+    HIGHEST: { label: 'Highest' },
+    LOWEST: { label: 'Lowest' },
+    PREVIOUS: { label: 'Previous' },
+    ROW_AGE: { label: 'Row Age' },
+    ADDED_AT: { label: 'Added At' },
+    ROWS_ADDED: { label: 'Rows Added' },
+    ROWS_REMOVED: { label: 'Rows Removed' },
+    ANY_COL: { label: 'Any Column' },
+    WITHIN: { label: 'Within' },
+    LAST_N: { label: 'Last N' },
+    ALL_ROWS: { label: 'All Rows' },
+    TRIGGER: { label: 'Trigger' },
+};

package/src/aql/systemExpressionFunctions.d.ts

@@ -0,0 +1,66 @@
+import { type AggregationCallable, type AggregationCallableName, type ScalarFunctionName } from "../../vendor/aql/index.js";
+import { type AggregationClauseKeyword, type ObservableClauseKeyword, type ObservablePoolName } from './systemExpressionFunctionEnhancements';
+import type { AdaptableAggregationFunctionDef, AdaptableExpressionFunction } from './types';
+/**
+ * The enriched system pools: aql's lean function packs (handlers + argument
+ * model + docs) merged with Adaptable's enhancements (icons, labels,
+ * shortcuts, `rhs`, menu visibility, module availability).
+ *
+ * These are the definitions every Adaptable consumer sees — the
+ * `QueryLanguageService` pools start from them, and standalone consumers
+ * (predicate migration, ColumnFilter QL helpers) read them directly.
+ *
+ * Note on contexts: the pack handlers are written against aql's
+ * `HostExpressionContext`; Adaptable's evaluation context
+ * (`AdaptableInternalExpressionContext`) extends it, so the handlers are
+ * assignable (see the bivariance note on aql's `ExpressionFunction.handler`).
+ */
+export declare const systemScalarExpressionFunctions: Record<ScalarFunctionName, AdaptableExpressionFunction>;
+/** Clause keywords of the observable pool (chips / completion, never free-standing functions). */
+export declare const OBSERVABLE_CLAUSE_KEYWORDS: readonly ObservableClauseKeyword[];
+/**
+ * The observable pool: the history readers (`CHANGE_COUNT`, `NO_CHANGES`,
+ * `NET_CHANGE`, `HIGHEST`, `PREVIOUS`, `ROW_AGE`, …) and their clause keywords
+ * (`ANY_COL`, `WITHIN`, `LAST_N`, `ALL_ROWS`, `TRIGGER`), presented like functions (menus, hover docs,
+ * completion) with aql's `OBSERVABLE_DOCS` / `CLAUSE_DOCS` and Adaptable's
+ * `observableFunctionEnhancements`. Nothing here is evaluated: observable calls
+ * are compiled from `OBSERVABLE_CALL_SPECS` and read the history store.
+ *
+ * `PERCENT_CHANGE` is dual-named: when this pool is merged into a module's
+ * scalar pool, the scalar entry (with the real paren handler and the brace
+ * signature above) takes precedence wherever it is available.
+ */
+export declare const systemObservableExpressionFunctions: Record<ObservablePoolName, AdaptableExpressionFunction>;
+/**
+ * Docs-only pool entry for an aggregation callable (system operator, sugar
+ * or host-registered custom operator). Nothing here is evaluated: the entry
+ * exists so editors, hover docs, QueryBuilder and the Row Summary wizard
+ * can present the callable; the aql catalogue owns its semantics.
+ */
+export declare const toAggregationFunctionDef: (callable: AggregationCallable) => AdaptableAggregationFunctionDef;
+/**
+ * The aggregation callables Adaptable presents: every callable the aql
+ * aggregation catalogue ships (operators + compile-time sugar), as docs-only
+ * definitions merged with Adaptable's enhancements and availability policy.
+ *
+ * Clause keywords are not callables — see
+ * {@link systemAggregationClauseFunctions}.
+ */
+export declare const systemAggregatedExpressionFunctions: Record<AggregationCallableName, AdaptableAggregationFunctionDef>;
+export type AggregationLookupName = 'COL' | 'FIELD' | 'VAR';
+/**
+ * Lookups usable inside an aggregation brace call (`SUM{[col]}`,
+ * `FIELD('x')`, `VAR('threshold')`), as docs-only copies of the scalar
+ * definitions. Aggregation editors gate their Columns / Lookups panels on
+ * these names being in the pool they are handed.
+ */
+export declare const aggregationLookupFunctions: Record<AggregationLookupName, AdaptableAggregationFunctionDef>;
+/**
+ * The clause keywords of an aggregation brace call (`GROUP_BY([c])`,
+ * `OVER([c])`, `WEIGHT([c])`, `CUMULATIVE([c])`, `WHERE <predicate>`),
+ * presented like functions (menus, chips, hover docs) with aql's
+ * `CLAUSE_DOCS` and Adaptable's `clauseEnhancements`. Which callables accept
+ * which clause is decided per call by the catalogue's derived spec — this
+ * table only says how a clause is *shown*.
+ */
+export declare const systemAggregationClauseFunctions: Record<AggregationClauseKeyword, AdaptableAggregationFunctionDef>;

package/src/aql/systemExpressionFunctions.js

@@ -0,0 +1,95 @@
+import { CLAUSE_DOCS, ExpressionEvaluationError, SYSTEM_AGGREGATION_CATALOGUE, OBSERVABLE_CALL_SPECS, OBSERVABLE_DOCS, scalarFunctions, } from "../../vendor/aql/index.js";
+import { applySystemFunctionEnhancements } from './expressionFunctionAvailabilityOverlay';
+import { aggregatedFunctionEnhancements, clauseEnhancements, scalarFunctionEnhancements, observableFunctionEnhancements, } from './systemExpressionFunctionEnhancements';
+export const systemScalarExpressionFunctions = applySystemFunctionEnhancements(scalarFunctions, 'scalar', scalarFunctionEnhancements);
+systemScalarExpressionFunctions.PERCENT_CHANGE = {
+    ...systemScalarExpressionFunctions.PERCENT_CHANGE,
+    signatures: [
+        ...(systemScalarExpressionFunctions.PERCENT_CHANGE.signatures ?? []),
+        ...OBSERVABLE_DOCS.PERCENT_CHANGE.signatures,
+    ],
+    examples: [
+        ...(systemScalarExpressionFunctions.PERCENT_CHANGE.examples ?? []),
+        ...OBSERVABLE_DOCS.PERCENT_CHANGE.examples,
+    ],
+};
+const OBSERVABLE_RESULT_TYPE_TO_RETURN_TYPE = {
+    number: 'number',
+    date: 'date',
+    boolean: 'boolean',
+    duration: 'number',
+    input: undefined,
+};
+const toObservableFunctionDef = (name, docs, returnType) => ({
+    handler: () => {
+        throw new ExpressionEvaluationError(name, `is a brace call — write ${name}{...}, e.g. ${docs.examples[0] ?? `${name}{}`}`);
+    },
+    description: docs.description,
+    signatures: docs.signatures,
+    examples: docs.examples,
+    category: docs.category,
+    ...(returnType ? { returnType } : {}),
+});
+export const OBSERVABLE_CLAUSE_KEYWORDS = [
+    'ANY_COL',
+    'WITHIN',
+    'LAST_N',
+    'ALL_ROWS',
+    'TRIGGER',
+];
+export const systemObservableExpressionFunctions = applySystemFunctionEnhancements({
+    ...Object.fromEntries(Object.keys(OBSERVABLE_CALL_SPECS).map((name) => [
+        name,
+        toObservableFunctionDef(name, OBSERVABLE_DOCS[name], OBSERVABLE_RESULT_TYPE_TO_RETURN_TYPE[OBSERVABLE_CALL_SPECS[name].resultType]),
+    ])),
+    ...Object.fromEntries(OBSERVABLE_CLAUSE_KEYWORDS.map((clause) => [
+        clause,
+        toObservableFunctionDef(clause, CLAUSE_DOCS[clause], undefined),
+    ])),
+}, 'observable', observableFunctionEnhancements);
+const RESULT_TYPE_TO_RETURN_TYPE = {
+    number: 'number',
+    text: 'string',
+    date: 'date',
+    boolean: 'boolean',
+    duration: 'number',
+    input: undefined,
+    unknown: undefined,
+};
+export const toAggregationFunctionDef = (callable) => {
+    const returnType = RESULT_TYPE_TO_RETURN_TYPE[callable.spec.resultType];
+    return {
+        description: callable.docs.description,
+        signatures: callable.docs.signatures,
+        examples: callable.docs.examples,
+        category: callable.docs.category ?? 'aggregation',
+        ...(returnType ? { returnType } : {}),
+    };
+};
+const systemAggregationCallableDefs = Object.fromEntries(SYSTEM_AGGREGATION_CATALOGUE.callables().map((callable) => [
+    callable.name,
+    toAggregationFunctionDef(callable),
+]));
+export const systemAggregatedExpressionFunctions = applySystemFunctionEnhancements(systemAggregationCallableDefs, 'aggregated', aggregatedFunctionEnhancements);
+const AGGREGATION_LOOKUP_NAMES = ['COL', 'FIELD', 'VAR'];
+export const aggregationLookupFunctions = Object.fromEntries(AGGREGATION_LOOKUP_NAMES.map((name) => {
+    const { handler: _handler, hasEagerEvaluation: _eager, ...docs } = systemScalarExpressionFunctions[name];
+    return [name, docs];
+}));
+const AGGREGATION_CLAUSE_KEYWORDS = [
+    'GROUP_BY',
+    'OVER',
+    'WEIGHT',
+    'CUMULATIVE',
+    'WHERE',
+];
+export const systemAggregationClauseFunctions = applySystemFunctionEnhancements(Object.fromEntries(AGGREGATION_CLAUSE_KEYWORDS.map((clause) => {
+    const docs = CLAUSE_DOCS[clause];
+    const def = {
+        description: docs.description,
+        signatures: docs.signatures,
+        examples: docs.examples,
+        category: docs.category,
+    };
+    return [clause, def];
+})), 'aggregated', clauseEnhancements);