@adaptabletools/adaptable 24.0.0-canary.5 → 24.0.0-canary.7

package/src/Redux/Store/AdaptableReduxLocalStorageEngine.d.ts

@@ -1,6 +1,14 @@
 import IStorageEngine from './Interface/IStorageEngine';
 import { InitialState } from '../../AdaptableState/InitialState';
 import { AdaptableLoadStateFunction, AdaptablePersistStateFunction } from '../../AdaptableOptions/StateOptions';
+/**
+ * Default `persistState` implementation - writes the state to localStorage under `adaptableStateKey`
+ */
+export declare const persistState: AdaptablePersistStateFunction;
+/**
+ * Default `loadState` implementation - reads the state from localStorage under `adaptableStateKey`
+ */
+export declare const loadState: AdaptableLoadStateFunction;
 export declare function createEngine(config: {
     adaptableId: string;
     adaptableStateKey: string;

package/src/Redux/Store/AdaptableReduxLocalStorageEngine.js

@@ -1,6 +1,7 @@
 import { debounce } from '../../Utilities/Helpers/TimingHelper';
 import { MergeStateFunction } from './AdaptableReduxMerger';
 import { AdaptableLogger } from '../../agGrid/AdaptableLogger';
+import { runAsyncStateFunction, runSyncStateFunction } from './StateOptionsGuards';
 const checkStatus = (response) => {
     const error = new Error(response.statusText);
     if (response.status >= 200 && response.status < 300) {
@@ -8,7 +9,7 @@ const checkStatus = (response) => {
     }
     throw error;
 };
-const persistState = (state, config) => {
+export const persistState = (state, config) => {
     return new Promise((resolve, reject) => {
         try {
             localStorage.setItem(config.adaptableStateKey, JSON.stringify(state));
@@ -19,7 +20,7 @@ const persistState = (state, config) => {
         }
     });
 };
-const loadState = ({ adaptableId, adaptableStateKey }) => {
+export const loadState = ({ adaptableStateKey }) => {
     const jsonState = localStorage.getItem(adaptableStateKey);
     const parsedJsonState = JSON.parse(jsonState) || {};
     return Promise.resolve(parsedJsonState);
@@ -49,7 +50,7 @@ class AdaptableReduxLocalStorageEngine {
         this.adaptableStateKey = adaptableStateKey;
     }
     load(adaptableInstance, initialState = this.initialState) {
-        return (this.loadState || loadState)(adaptableInstance.api.stateApi.internalApi.buildAdaptableStateFunctionConfig()).then((parsedJsonState) => {
+        return runAsyncStateFunction('loadState', this.loadState || loadState, [adaptableInstance.api.stateApi.internalApi.buildAdaptableStateFunctionConfig()], adaptableInstance.logger).then((parsedJsonState) => {
             return Promise.resolve(initialState)
                 .then((parsedInitialState) => {
                 return MergeStateFunction(parsedInitialState, parsedJsonState);
@@ -67,20 +68,19 @@ class AdaptableReduxLocalStorageEngine {
         const config = adaptableInstance.api.stateApi.internalApi.buildAdaptableStateFunctionConfig();
         config.actionName = actionName;
         config.previousState = adaptableInstance.adaptableStore.getPreviousStorageState() || null;
-        let stateObject = structuredClone(state);
-        const getTransformedState = adaptableInstance.adaptableOptions.stateOptions.saveState;
-        if (getTransformedState) {
-            stateObject = getTransformedState(stateObject, config);
+        let stateObject;
+        try {
+            stateObject = runSyncStateFunction('saveState', adaptableInstance.adaptableOptions.stateOptions.saveState, structuredClone(state), config, adaptableInstance.logger);
         }
-        const promise = (this.persistState || persistState)(stateObject, config)?.catch(rejectWithMessage);
-        if (!(promise instanceof Promise)) {
-            AdaptableLogger.consoleWarnBase(`AdaptableId: ${this.adaptableId}`, 'stateOptions.persistState should return a promise, it returned', 'Error', promise);
+        catch (error) {
+            adaptableInstance.logger.consoleError('Adaptable State was NOT persisted:', error instanceof Error ? error.message : error);
+            return Promise.reject(error);
         }
-        return promise;
+        return runAsyncStateFunction('persistState', this.persistState || persistState, [stateObject, config], adaptableInstance.logger).catch(rejectWithMessage);
     }
 }
 function rejectWithMessage(error) {
-    return Promise.reject(error.message);
+    return Promise.reject(error?.message ?? error);
 }
 export function createEngine(config) {
     return new AdaptableReduxLocalStorageEngine(config);

package/src/Redux/Store/AdaptableStore.d.ts

@@ -1,11 +1,14 @@
 import * as Redux from 'redux';
 import { IAdaptable } from '../../AdaptableInterfaces/IAdaptable';
-import { AdaptableState } from '../../AdaptableState/AdaptableState';
+import { AdaptablePersistentState, AdaptableState } from '../../AdaptableState/AdaptableState';
 import { BaseState } from '../../AdaptableState/BaseState';
 import { IAdaptableStore, LoadStoreConfig } from './Interface/IAdaptableStore';
 type EmitterCallback = (data?: any) => any;
 type EmitterAnyCallback = (eventName: string, data?: any) => any;
-export declare const getPersistableState: (state: AdaptableState) => AdaptableState;
+/**
+ * Strips the transient (non-persisted) sections from the given state object - mutates and returns the same object.
+ */
+export declare const getPersistableState: (state: AdaptableState) => AdaptablePersistentState;
 export interface ResetUserDataAction extends Redux.Action {
 }
 export interface InitStateAction extends Redux.Action {
@@ -40,9 +43,9 @@ export declare class AdaptableStore implements IAdaptableStore {
      */
     constructor(adaptable: IAdaptable);
     destroy(): void;
-    getCurrentStorageState(): AdaptableState;
-    getPreviousStorageState(): AdaptableState;
-    saveStateNow(adaptable: IAdaptable, state?: AdaptableState): Promise<any>;
+    getCurrentStorageState(): AdaptablePersistentState;
+    getPreviousStorageState(): AdaptablePersistentState;
+    saveStateNow(adaptable: IAdaptable, state?: AdaptablePersistentState): Promise<any>;
     loadStore: (config: LoadStoreConfig) => Promise<any>;
 }
 export {};

package/src/Redux/Store/AdaptableStore.js

@@ -4,6 +4,7 @@ import * as PopupRedux from '../ActionsReducers/PopupRedux';
 import { PROGRESS_INDICATOR_HIDE, PROGRESS_INDICATOR_SHOW } from '../ActionsReducers/PopupRedux';
 import { createEngine as createEngineLocal } from './AdaptableReduxLocalStorageEngine';
 import { mergeReducer } from './AdaptableReduxMerger';
+import { runSyncStateFunction } from './StateOptionsGuards';
 import { isRowChangeAlertDefinition } from '../../AdaptableState/AlertState';
 import { getAlertCellDataChangedInfos, isAdaptableRowChangedAlert, } from '../../AdaptableState/Common/AdaptableAlert';
 import { closeAgChartDefinitionIfOpen, closeExternalChartDefinitionIfOpen, } from '../../Utilities/Helpers/ChartHelper';
@@ -185,13 +186,9 @@ export class AdaptableStore {
                 !init &&
                 !this.loadStorageInProgress;
             if (shouldPersist) {
-                let storageState = { ...finalState };
-                storageState = getPersistableState(storageState);
+                const storageState = getPersistableState({ ...finalState });
                 this.currentStorageState = storageState;
-                this.previousStorageState = { ...state };
-                NON_PERSISTENT_STORE_KEYS.forEach((key) => {
-                    delete this.previousStorageState[key];
-                });
+                this.previousStorageState = getPersistableState({ ...state });
                 storageEngine.save(adaptable, storageState, action.type);
             }
             return finalState;
@@ -245,7 +242,9 @@ export class AdaptableStore {
         return this.previousStorageState;
     }
     saveStateNow(adaptable, state) {
-        const newState = state ?? this.getCurrentStorageState();
+        const newState = state
+            ? getPersistableState({ ...state })
+            : this.getCurrentStorageState();
         if (newState) {
             return this.storageEngine.saveNow(adaptable, newState, 'API_CALL_SAVE_STATE');
         }
@@ -260,7 +259,8 @@ export class AdaptableStore {
             .load(adaptable, initialState ?? adaptable.adaptableOptions.initialState)
             .then((storedState) => {
             if (storedState && this.loadStateOnStartup) {
-                this.TheStore.dispatch(LoadState(postProcessState(adaptable.adaptableOptions.stateOptions.applyState(storedState, adaptable.api.stateApi.internalApi.buildAdaptableStateFunctionConfig()))));
+                const appliedState = runSyncStateFunction('applyState', adaptable.adaptableOptions.stateOptions.applyState, storedState, adaptable.api.stateApi.internalApi.buildAdaptableStateFunctionConfig(), adaptable.logger);
+                this.TheStore.dispatch(LoadState(postProcessState(appliedState)));
             }
         })
             .then(() => {
@@ -402,10 +402,26 @@ function refreshFormulaTraceCells(adaptable, formulaTraceInfo) {
     });
 }
 const LAYOUT_EXTENSION_OBJECT_ACTIONS = {
-    [AlertRedux.ALERT_DEFINITION_EDIT]: { module: 'Alert', payloadKey: 'alertDefinition', kind: 'edit' },
-    [AlertRedux.ALERT_DEFINITION_DELETE]: { module: 'Alert', payloadKey: 'alertDefinition', kind: 'delete' },
-    [CustomSortRedux.CUSTOM_SORT_EDIT]: { module: 'CustomSort', payloadKey: 'customSort', kind: 'edit' },
-    [CustomSortRedux.CUSTOM_SORT_DELETE]: { module: 'CustomSort', payloadKey: 'customSort', kind: 'delete' },
+    [AlertRedux.ALERT_DEFINITION_EDIT]: {
+        module: 'Alert',
+        payloadKey: 'alertDefinition',
+        kind: 'edit',
+    },
+    [AlertRedux.ALERT_DEFINITION_DELETE]: {
+        module: 'Alert',
+        payloadKey: 'alertDefinition',
+        kind: 'delete',
+    },
+    [CustomSortRedux.CUSTOM_SORT_EDIT]: {
+        module: 'CustomSort',
+        payloadKey: 'customSort',
+        kind: 'edit',
+    },
+    [CustomSortRedux.CUSTOM_SORT_DELETE]: {
+        module: 'CustomSort',
+        payloadKey: 'customSort',
+        kind: 'delete',
+    },
     [FlashingCellRedux.FLASHING_CELL_DEFINITION_EDIT]: {
         module: 'FlashingCell',
         payloadKey: 'flashingCellDefinition',
@@ -416,13 +432,21 @@ const LAYOUT_EXTENSION_OBJECT_ACTIONS = {
         payloadKey: 'flashingCellDefinition',
         kind: 'delete',
     },
-    [FormatColumnRedux.FORMAT_COLUMN_EDIT]: { module: 'FormatColumn', payloadKey: 'formatColumn', kind: 'edit' },
+    [FormatColumnRedux.FORMAT_COLUMN_EDIT]: {
+        module: 'FormatColumn',
+        payloadKey: 'formatColumn',
+        kind: 'edit',
+    },
     [FormatColumnRedux.FORMAT_COLUMN_DELETE]: {
         module: 'FormatColumn',
         payloadKey: 'formatColumn',
         kind: 'delete',
     },
-    [PlusMinusRedux.PLUS_MINUS_RULE_EDIT]: { module: 'PlusMinus', payloadKey: 'plusMinusNudge', kind: 'edit' },
+    [PlusMinusRedux.PLUS_MINUS_RULE_EDIT]: {
+        module: 'PlusMinus',
+        payloadKey: 'plusMinusNudge',
+        kind: 'edit',
+    },
     [PlusMinusRedux.PLUS_MINUS_RULE_DELETE]: {
         module: 'PlusMinus',
         payloadKey: 'plusMinusNudge',
@@ -430,7 +454,11 @@ const LAYOUT_EXTENSION_OBJECT_ACTIONS = {
     },
     [ShortcutRedux.SHORTCUT_EDIT]: { module: 'Shortcut', payloadKey: 'shortcut', kind: 'edit' },
     [ShortcutRedux.SHORTCUT_DELETE]: { module: 'Shortcut', payloadKey: 'shortcut', kind: 'delete' },
-    [StyledColumnRedux.STYLED_COLUMN_EDIT]: { module: 'StyledColumn', payloadKey: 'StyledColumn', kind: 'edit' },
+    [StyledColumnRedux.STYLED_COLUMN_EDIT]: {
+        module: 'StyledColumn',
+        payloadKey: 'StyledColumn',
+        kind: 'edit',
+    },
     [StyledColumnRedux.STYLED_COLUMN_DELETE]: {
         module: 'StyledColumn',
         payloadKey: 'StyledColumn',
@@ -585,8 +613,8 @@ const adaptableMiddleware = (adaptable) => (function(middlewareAPI) {
                         if (!adaptable.api.freeTextColumnApi.internalApi.validateDeletedFreeTextColumn(actionTyped.freeTextColumn)) {
                             return;
                         }
-                        if (adaptable.api.optionsApi.getLayoutOptions()
-                            ?.autoRemoveDeletedColumnsFromLayouts !== false) {
+                        if (adaptable.api.optionsApi.getLayoutOptions()?.autoRemoveDeletedColumnsFromLayouts !==
+                            false) {
                             adaptable.api.layoutApi.internalApi.removeColumnIdFromAllLayouts(actionTyped.freeTextColumn.ColumnId);
                         }
                     }
@@ -607,8 +635,8 @@ const adaptableMiddleware = (adaptable) => (function(middlewareAPI) {
                         if (!adaptable.api.calculatedColumnApi.internalApi.validateDeletedCalculatedColumn(calculatedColumn)) {
                             return;
                         }
-                        if (adaptable.api.optionsApi.getLayoutOptions()
-                            ?.autoRemoveDeletedColumnsFromLayouts !== false) {
+                        if (adaptable.api.optionsApi.getLayoutOptions()?.autoRemoveDeletedColumnsFromLayouts !==
+                            false) {
                             adaptable.api.layoutApi.internalApi.removeColumnIdFromAllLayouts(calculatedColumn.ColumnId);
                         }
                     }
@@ -692,10 +720,12 @@ const adaptableMiddleware = (adaptable) => (function(middlewareAPI) {
                     adaptable.refreshSortIfColumnsSorted();
                     return returnAction;
                 }
+                case QuickSearchRedux.QUICK_SEARCH_CLEAR:
                 case QuickSearchRedux.QUICK_SEARCH_RUN: {
                     let returnAction = next(action);
-                    const actionTyped = action;
-                    const searchText = actionTyped.quickSearchText;
+                    const searchText = action.type === QuickSearchRedux.QUICK_SEARCH_CLEAR
+                        ? ''
+                        : action.quickSearchText;
                     adaptable.setAgGridFindSearchValue(searchText);
                     adaptable.api.gridApi.refreshAllCells(true);
                     if (adaptable.adaptableOptions.quickSearchOptions.filterGridAfterQuickSearch) {

package/src/Redux/Store/Interface/IAdaptableStore.d.ts

@@ -1,20 +1,20 @@
 import * as Redux from 'redux';
-import { AdaptableState } from '../../../AdaptableState/AdaptableState';
+import { AdaptablePersistentState, AdaptableState } from '../../../AdaptableState/AdaptableState';
 import { InitialState } from '../../../types';
 import { IAdaptable } from '../../../AdaptableInterfaces/IAdaptable';
 export interface LoadStoreConfig {
     adaptable: IAdaptable;
     adaptableStateKey: string;
     initialState?: InitialState;
-    postLoadHook?: (state: AdaptableState) => AdaptableState;
+    postLoadHook?: (state: Partial<AdaptablePersistentState>) => Partial<AdaptablePersistentState>;
 }
 export interface IAdaptableStore {
     TheStore: Redux.Store<AdaptableState>;
     Load: Promise<any>;
     loadStore: (config: LoadStoreConfig) => Promise<any>;
-    getCurrentStorageState: () => AdaptableState | void;
-    getPreviousStorageState: () => AdaptableState | void;
-    saveStateNow: (adaptable: IAdaptable, state?: AdaptableState) => Promise<any>;
+    getCurrentStorageState: () => AdaptablePersistentState | void;
+    getPreviousStorageState: () => AdaptablePersistentState | void;
+    saveStateNow: (adaptable: IAdaptable, state?: AdaptablePersistentState) => Promise<any>;
     on: (eventName: string, callback: (data?: any) => any) => () => void;
     onAny: (callback: (eventName: string, data?: any) => any) => () => void;
     onBeforeAny: (callback: (eventName: string, data?: any) => any) => () => void;

package/src/Redux/Store/Interface/IStorageEngine.d.ts

@@ -1,9 +1,9 @@
-import { AdaptableState } from '../../../AdaptableState/AdaptableState';
+import { AdaptablePersistentState } from '../../../AdaptableState/AdaptableState';
 import { InitialState } from '../../../AdaptableState/InitialState';
 import { IAdaptable } from '../../../AdaptableInterfaces/IAdaptable';
 export default interface IStorageEngine {
-    load(adaptable: IAdaptable, initialState?: string | InitialState): Promise<any>;
-    save(adaptable: IAdaptable, state: AdaptableState, actionName: string): Promise<any>;
-    saveNow(adaptable: IAdaptable, state: AdaptableState, actionName: string): Promise<any>;
+    load(adaptable: IAdaptable, initialState?: string | InitialState): Promise<Partial<AdaptablePersistentState> | void>;
+    save(adaptable: IAdaptable, state: AdaptablePersistentState, actionName: string): Promise<any>;
+    saveNow(adaptable: IAdaptable, state: AdaptablePersistentState, actionName: string): Promise<any>;
     setStateKey(stateKey: string): void;
 }

package/src/Redux/Store/StateOptionsGuards.d.ts

@@ -0,0 +1,58 @@
+import { AdaptablePersistentState } from '../../AdaptableState/AdaptableState';
+import { AdaptableStateFunctionConfig, StateOptions } from '../../AdaptableOptions/StateOptions';
+/**
+ * Runtime guards for the `StateOptions` functions.
+ *
+ * The most frequent mistakes when implementing these functions are:
+ * - providing an `async` function (or otherwise returning a Promise) for `saveState` / `applyState`, which are synchronous
+ * - mutating the state in `saveState` / `applyState` but forgetting to return it
+ * - returning a plain value (not a Promise) from `loadState` / `persistState`
+ *
+ * The helpers below detect these cases - as early as possible - and either recover (when there is only one sensible
+ * interpretation) or fail with an actionable error message instead of an obscure one further down the line.
+ */
+export type StateOptionsLogger = {
+    consoleError(message: string, ...optionalParams: any[]): void;
+    consoleWarn(message: string, ...optionalParams: any[]): void;
+};
+export type SyncStateFunctionName = 'saveState' | 'applyState';
+export type AsyncStateFunctionName = 'loadState' | 'persistState' | 'clearState';
+export type StateFunctionName = SyncStateFunctionName | AsyncStateFunctionName;
+/**
+ * Error thrown when a `StateOptions` function breaks its contract
+ */
+export declare class AdaptableStateOptionsError extends Error {
+    constructor(message: string);
+}
+export declare const isThenable: (value: unknown) => value is PromiseLike<unknown>;
+/**
+ * Detects functions declared with the `async` keyword (not transpiled to generators / promises)
+ */
+export declare const isAsyncFunction: (fn: unknown) => boolean;
+/**
+ * Validates the shape of `stateOptions` once, at initialisation - before any state is loaded or persisted.
+ *
+ * Reports (does not throw):
+ * - non-function values for any state function
+ * - `async` functions for `saveState` / `applyState`
+ * - `loadState` without `persistState` (or vice versa) - the localStorage fallback is used for the missing one,
+ *   which makes the remote and local copies of the state diverge
+ */
+export declare function validateStateOptions(stateOptions: StateOptions | undefined, logger: StateOptionsLogger): void;
+/**
+ * Invokes a synchronous state transform (`saveState` / `applyState`) and validates its result.
+ *
+ * - returns the result when it is a state object
+ * - **recovers** when the function returned nothing: the input state is used (the function most likely mutated it in place
+ *   and forgot to `return` it) and an error is logged
+ * - **throws** `AdaptableStateOptionsError` when the result is a Promise (async function) or any other non-object value;
+ *   there is no safe way to continue in these cases
+ */
+export declare function runSyncStateFunction<T extends Partial<AdaptablePersistentState>>(functionName: SyncStateFunctionName, fn: ((state: T, config: AdaptableStateFunctionConfig) => T) | undefined, state: T, config: AdaptableStateFunctionConfig, logger: StateOptionsLogger): T;
+/**
+ * Invokes an asynchronous state function (`loadState` / `persistState` / `clearState`) and normalises its result to a Promise.
+ *
+ * A non-Promise result is logged (these functions are expected to be async) and wrapped in a resolved Promise, so a
+ * synchronous implementation degrades gracefully instead of failing with `.then is not a function`.
+ */
+export declare function runAsyncStateFunction<TResult, TArgs extends unknown[]>(functionName: AsyncStateFunctionName, fn: (...args: TArgs) => Promise<TResult>, args: TArgs, logger: StateOptionsLogger): Promise<TResult>;

package/src/Redux/Store/StateOptionsGuards.js

@@ -0,0 +1,112 @@
+import { StatePersistenceDocsLink } from '../../Utilities/Constants/DocumentationLinkConstants';
+const STATE_FUNCTION_NAMES = [
+    'loadState',
+    'persistState',
+    'applyState',
+    'saveState',
+    'clearState',
+];
+export class AdaptableStateOptionsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AdaptableStateOptionsError';
+    }
+}
+export const isThenable = (value) => {
+    return value != null && typeof value.then === 'function';
+};
+export const isAsyncFunction = (fn) => {
+    return typeof fn === 'function' && fn.constructor?.name === 'AsyncFunction';
+};
+const isStateObject = (value) => {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+};
+const docs = `See ${StatePersistenceDocsLink}`;
+const syncFunctionMustReturnMessage = (functionName) => `stateOptions.${functionName} must be synchronous and return the (modified) state object.`;
+const asyncFunctionMessage = (functionName, reason) => `${syncFunctionMustReturnMessage(functionName)} ${reason} ` +
+    `Asynchronous work belongs in stateOptions.${functionName === 'saveState' ? 'persistState' : 'loadState'}. ${docs}`;
+export function validateStateOptions(stateOptions, logger) {
+    if (!stateOptions) {
+        return;
+    }
+    for (const functionName of STATE_FUNCTION_NAMES) {
+        const fn = stateOptions[functionName];
+        if (fn != null && typeof fn !== 'function') {
+            logger.consoleError(`stateOptions.${functionName} must be a function, but received ${describe(fn)}. ${docs}`);
+        }
+    }
+    for (const functionName of ['saveState', 'applyState']) {
+        if (isAsyncFunction(stateOptions[functionName])) {
+            logger.consoleError(asyncFunctionMessage(functionName, 'It is declared as an async function.'));
+        }
+    }
+    const hasLoadState = typeof stateOptions.loadState === 'function';
+    const hasPersistState = typeof stateOptions.persistState === 'function';
+    if (hasLoadState !== hasPersistState) {
+        const provided = hasLoadState ? 'loadState' : 'persistState';
+        const missing = hasLoadState ? 'persistState' : 'loadState';
+        logger.consoleWarn(`stateOptions.${provided} is provided without stateOptions.${missing}; ` +
+            `the default localStorage implementation is used for ${missing}, so the loaded and the persisted state may diverge. ` +
+            `Provide both functions (or neither). ${docs}`);
+    }
+}
+export function runSyncStateFunction(functionName, fn, state, config, logger) {
+    if (fn == null) {
+        return state;
+    }
+    if (typeof fn !== 'function') {
+        throw new AdaptableStateOptionsError(`stateOptions.${functionName} must be a function, but received ${describe(fn)}. ${docs}`);
+    }
+    const result = fn(state, config);
+    if (result === undefined) {
+        logger.consoleError(`${syncFunctionMustReturnMessage(functionName)} It returned nothing - ` +
+            `the state object passed to it is used instead (add 'return state;' to fix this). ${docs}`);
+        return state;
+    }
+    if (isThenable(result)) {
+        throw new AdaptableStateOptionsError(asyncFunctionMessage(functionName, 'It returned a Promise (is it an async function?).'));
+    }
+    if (!isStateObject(result)) {
+        throw new AdaptableStateOptionsError(`${syncFunctionMustReturnMessage(functionName)} It returned ${describe(result)}. ${docs}`);
+    }
+    return result;
+}
+export function runAsyncStateFunction(functionName, fn, args, logger) {
+    if (typeof fn !== 'function') {
+        return Promise.reject(new AdaptableStateOptionsError(`stateOptions.${functionName} must be a function, but received ${describe(fn)}. ${docs}`));
+    }
+    let result;
+    try {
+        result = fn(...args);
+    }
+    catch (error) {
+        return Promise.reject(error);
+    }
+    if (!isThenable(result)) {
+        logger.consoleWarn(`stateOptions.${functionName} should be asynchronous and return a Promise, but it returned ${describe(result)}. The value is used as if it had been resolved. ${docs}`);
+        return Promise.resolve(result);
+    }
+    return Promise.resolve(result);
+}
+function describe(value) {
+    if (value === null) {
+        return 'null';
+    }
+    if (value === undefined) {
+        return 'undefined';
+    }
+    if (Array.isArray(value)) {
+        return 'an array';
+    }
+    if (isThenable(value)) {
+        return 'a Promise';
+    }
+    const type = typeof value;
+    if (type === 'object') {
+        return 'an object';
+    }
+    if (type === 'string') {
+        return `a string ('${String(value).slice(0, 40)}${String(value).length > 40 ? '…' : ''}')`;
+    }
+    return `${type} (${String(value)})`;
+}

package/src/Redux/Store/isTransientReduxAction.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Whether a Redux action only affects transient (non-persisted) Adaptable state,
+ * e.g. showing a popup, highlighting cells or setting the selected rows.
+ */
+export declare function isTransientReduxAction(actionType: string | undefined): boolean;

package/src/Redux/Store/isTransientReduxAction.js

@@ -0,0 +1,19 @@
+import * as CommentsRedux from '../ActionsReducers/CommentsRedux';
+import * as InternalRedux from '../ActionsReducers/InternalRedux';
+import * as PluginsRedux from '../ActionsReducers/PluginsRedux';
+import * as PopupRedux from '../ActionsReducers/PopupRedux';
+const collectActionTypes = (reduxModule) => {
+    return Object.values(reduxModule).filter((value) => typeof value === 'string');
+};
+const TRANSIENT_REDUX_ACTION_TYPES = new Set([
+    ...collectActionTypes(InternalRedux),
+    ...collectActionTypes(PopupRedux),
+    ...collectActionTypes(PluginsRedux),
+    ...collectActionTypes(CommentsRedux),
+]);
+export function isTransientReduxAction(actionType) {
+    if (!actionType) {
+        return false;
+    }
+    return TRANSIENT_REDUX_ACTION_TYPES.has(actionType);
+}

package/src/Utilities/Constants/DocumentationLinkConstants.d.ts

@@ -16,3 +16,4 @@ export declare const AgGridModulesDocsLink = "https://www.adaptabletools.com/doc
 export declare const AlertMessageDocsLink = "https://www.adaptabletools.com/docs/handbook-alerting-message";
 export declare const FormatColumnPlaceholderDocsLink = "https://www.adaptabletools.com/docs/handbook-column-formatting-display-format-template";
 export declare const AgGridRequiredModulesDocsLink = "https://www.adaptabletools.com/docs/getting-started-aggrid-modules#mandatory-modules";
+export declare const StatePersistenceDocsLink = "https://www.adaptabletools.com/docs/dev-guide-adaptable-state-persistence";

package/src/Utilities/Constants/DocumentationLinkConstants.js

@@ -16,3 +16,4 @@ export const AgGridModulesDocsLink = `${HOST_URL_DOCS}/getting-started-aggrid-mo
 export const AlertMessageDocsLink = `${HOST_URL_DOCS}/handbook-alerting-message`;
 export const FormatColumnPlaceholderDocsLink = `${HOST_URL_DOCS}/handbook-column-formatting-display-format-template`;
 export const AgGridRequiredModulesDocsLink = `${HOST_URL_DOCS}/getting-started-aggrid-modules#mandatory-modules`;
+export const StatePersistenceDocsLink = `${HOST_URL_DOCS}/dev-guide-adaptable-state-persistence`;

package/src/Utilities/Constants/ReduxConstants.d.ts

@@ -2,8 +2,8 @@ import { SummaryOperation } from '../../AdaptableState/Common/Enums';
 import { SystemThemeEntry } from '../../AdaptableState/ThemeState';
 export declare const CELL_SUMMARY_DEFAULT_OPERATION: SummaryOperation | string;
 export declare const QUICK_SEARCH_DEFAULT_TEXT_BACK_COLOR: string;
-export declare const QUICK_SEARCH_DEFAULT_CELL_BACK_COLOR: string;
-export declare const QUICK_SEARCH_DEFAULT_FORE_COLOR: string;
+export declare const QUICK_SEARCH_DEFAULT_TEXT_FORE_COLOR: string;
 export declare const QUICK_SEARCH_DEFAULT_CURRENT_BACK_COLOR: string;
+export declare const QUICK_SEARCH_DEFAULT_CURRENT_FORE_COLOR: string;
 export declare const SYSTEM_THEMES: SystemThemeEntry[];
 export declare const THEME_DEFAULT_CURRENT_THEME: string;

package/src/Utilities/Constants/ReduxConstants.js

@@ -1,10 +1,10 @@
 import { SummaryOperation } from '../../AdaptableState/Common/Enums';
-import { getSwatchColorVar } from '../../Utilities/Helpers/UIHelper';
+import { themeColorVar } from '../../Utilities/Helpers/UIHelper';
 import { LIGHT_THEME, DARK_THEME, OS_THEME } from './GeneralConstants';
 export const CELL_SUMMARY_DEFAULT_OPERATION = SummaryOperation.Sum;
-export const QUICK_SEARCH_DEFAULT_TEXT_BACK_COLOR = getSwatchColorVar(9);
-export const QUICK_SEARCH_DEFAULT_CELL_BACK_COLOR = getSwatchColorVar(10);
-export const QUICK_SEARCH_DEFAULT_FORE_COLOR = getSwatchColorVar(1);
-export const QUICK_SEARCH_DEFAULT_CURRENT_BACK_COLOR = getSwatchColorVar(20);
+export const QUICK_SEARCH_DEFAULT_TEXT_BACK_COLOR = themeColorVar('quick-search-match');
+export const QUICK_SEARCH_DEFAULT_TEXT_FORE_COLOR = themeColorVar('quick-search-match-foreground');
+export const QUICK_SEARCH_DEFAULT_CURRENT_BACK_COLOR = themeColorVar('quick-search-current-match');
+export const QUICK_SEARCH_DEFAULT_CURRENT_FORE_COLOR = themeColorVar('quick-search-current-match-foreground');
 export const SYSTEM_THEMES = [LIGHT_THEME, DARK_THEME, OS_THEME];
 export const THEME_DEFAULT_CURRENT_THEME = LIGHT_THEME;

package/src/Utilities/Helpers/AlertTypeHelper.d.ts

@@ -31,4 +31,4 @@ export declare const inferAlertTypeFromDefinition: (alert: AlertDefinition, kind
  * otherwise inferred from Rule / Schedule shape.
  */
 export declare const getAlertType: (alert: AlertDefinition, kind?: ExpressionKind) => AlertType | null;
-export declare const getAlertTypeText: (alertType: AlertType) => "" | "Aggregation" | "Observable" | "Scheduled" | "Data Change" | "Relative Change" | "Data Validation" | "Row Change";
+export declare const getAlertTypeText: (alertType: AlertType) => "" | "Observable" | "Aggregation" | "Scheduled" | "Data Change" | "Relative Change" | "Data Validation" | "Row Change";

package/src/Utilities/Helpers/SettingsPanelHelper.d.ts

@@ -1,6 +1,15 @@
 import { AdaptableApi } from '../../Api/AdaptableApi';
 import { SettingsPanelDisplayOptions, SettingsPanelNavigation, SettingsPanelNavigationGroup, SettingsPanelOptions } from '../../AdaptableOptions/SettingsPanelOptions';
 import { AdaptableIcon } from '../../types';
+/** One Settings Panel sidebar module (visible for the current grid / entitlements). */
+export type VisibleSettingsPanelNavigationItem = {
+    moduleName: string;
+    label: string;
+};
+export type VisibleSettingsPanelNavigationGroup = {
+    label: string;
+    items: VisibleSettingsPanelNavigationItem[];
+};
 /**
  * True when `adaptableId` is the framework placeholder (`adaptable_id` or `adaptable_id_<n>`),
  * not a developer-supplied human name.
@@ -41,3 +50,8 @@ export declare const getSettingsPanelOpenIcon: (resolvedIcon: SettingsPanelOptio
 export declare const DEFAULT_SETTINGS_PANEL_NAVIGATION_GROUPS: SettingsPanelNavigationGroup[];
 export declare const buildDefaultSettingsPanelNavigation: (customPanelNames?: string[]) => SettingsPanelNavigation;
 export declare const resolveSettingsPanelNavigation: (api: AdaptableApi, settingsPanelOptions: SettingsPanelOptions) => SettingsPanelNavigation;
+/**
+ * Settings Panel navigation groups containing only modules that appear in the
+ * panel sidebar (same rules as {@link useMenuItems} in AdaptablePopup).
+ */
+export declare function resolveVisibleSettingsPanelNavigationGroups(api: AdaptableApi): VisibleSettingsPanelNavigationGroup[];

package/src/Utilities/Helpers/SettingsPanelHelper.js

@@ -1,4 +1,4 @@
-import { ADAPTABLE_ID } from '../Constants/GeneralConstants';
+import { ADAPTABLE_ID, STANDALONE_MODULE_POPUPS } from '../Constants/GeneralConstants';
 import { SettingsPanelFriendlyName } from '../Constants/ModuleConstants';
 import StringExtensions from '../Extensions/StringExtensions';
 export const isGenericAdaptableId = (adaptableId) => {
@@ -143,3 +143,39 @@ export const resolveSettingsPanelNavigation = (api, settingsPanelOptions) => {
     warnLegacyNavigationOnce(api);
     return convertLegacyFlatNavigationToGrouped(navigation);
 };
+export function resolveVisibleSettingsPanelNavigationGroups(api) {
+    const settingsPanelOptions = api.optionsApi.getAdaptableOptions().settingsPanelOptions;
+    const navigation = resolveSettingsPanelNavigation(api, settingsPanelOptions ?? {});
+    const allMenuItems = api.internalApi.getInternalState().SettingsPanelModuleEntries ?? [];
+    const visibleItems = allMenuItems.filter((item) => item.category !== 'General' &&
+        item.category !== 'CustomSettingsPanel' &&
+        item.category !== 'Group' &&
+        !STANDALONE_MODULE_POPUPS.includes(item.category) &&
+        item.isVisible);
+    const moduleService = api.internalApi.getModuleService();
+    const groups = [];
+    for (const group of navigation.groups) {
+        const items = [];
+        for (const moduleName of group.items) {
+            const moduleId = String(moduleName);
+            const customSettingsPanel = settingsPanelOptions?.customSettingsPanels?.find((panel) => panel.name === moduleId);
+            if (customSettingsPanel) {
+                items.push({ moduleName: moduleId, label: customSettingsPanel.name });
+                continue;
+            }
+            const menuItem = visibleItems.find((item) => item.category === moduleId);
+            if (!menuItem) {
+                continue;
+            }
+            items.push({
+                moduleName: moduleId,
+                label: menuItem.label ??
+                    moduleService.getModuleFriendlyName(moduleId),
+            });
+        }
+        if (items.length) {
+            groups.push({ label: group.label ?? '', items });
+        }
+    }
+    return groups;
+}