@adaptabletools/adaptable 24.0.0-canary.8 → 24.0.0

package/src/AdaptableState/InternalState.d.ts

@@ -22,20 +22,56 @@ import { CompactCalculatedColumnEditorInfo } from './Common/CompactCalculatedCol
 import type { QlGroup } from "../../vendor/aql/index.js";
 export type { IPushPullReport, IPushPullDomain };
 export type { OpenFinReport };
+/**
+ * Whether Data Change History is recording.
+ *
+ * `'ACTIVE'` records edits. `'SUSPENDED'` pauses recording and keeps the log. `'INACTIVE'` is off.
+ */
 export type DataChangeHistoryMode = 'ACTIVE' | 'INACTIVE' | 'SUSPENDED';
+/**
+ * A pinned summary row AdapTable is showing this session.
+ *
+ * `Position` is the edge. `RowData` is the cell values, keyed by column id.
+ */
 export type SystemRowSummary = {
+    /**
+     * Which edge the summary row is pinned to.
+     */
     Position: 'Top' | 'Bottom';
+    /**
+     * Cell values, keyed by column id.
+     */
     RowData: Record<string, any>;
 };
 /**
- * Internal state, used by Adaptable during a session; none of it is provided through Initial Adaptable State, nor is it persisted
+ * Session state AdapTable keeps while the grid is open.
+ *
+ * Nothing here is part of Initial State, and none of it is persisted. It records the current selection, open editors, highlights, the export in progress, and similar runtime data.
  */
 export interface InternalState extends IPushPullState, OpenFinState {
+    /**
+     * AdapTable's column model for this session.
+     */
     Columns: AdaptableColumn[];
+    /**
+     * Cells selected in the grid.
+     */
     SelectedCellInfo: SelectedCellInfo;
+    /**
+     * Rows selected in the grid.
+     */
     SelectedRowInfo: SelectedRowInfo;
+    /**
+     * Cells currently highlighted.
+     */
     CellHighlightInfo: CellHighlightInfo[];
+    /**
+     * Columns currently highlighted.
+     */
     ColumnHighlightInfo: ColumnHighlightInfo[];
+    /**
+     * Rows currently highlighted.
+     */
     RowHighlightInfo: RowHighlightInfo[];
     /**
      * Active Excel-style formula trace for a calculated column cell (session-only)
@@ -45,56 +81,149 @@ export interface InternalState extends IPushPullState, OpenFinState {
      * Compact live expression editor for a Standard Calculated Column (session-only)
      */
     CompactCalculatedColumnEditorInfo?: CompactCalculatedColumnEditorInfo;
+    /**
+     * Modules listed in the Settings Panel.
+     */
     SettingsPanelModuleEntries: AdaptableMenuItem[];
+    /**
+     * Alerts currently held in the alert store.
+     */
     AdaptableAlerts: AdaptableAlert[];
+    /**
+     * System status messages currently shown.
+     */
     SystemStatusMessages: SystemStatusMessageInfo[];
+    /**
+     * Dashboard buttons for this session, and a counter that increments when the Dashboard is refreshed.
+     */
     Dashboard: {
+        /**
+         * Module buttons currently rendered in the Dashboard.
+         */
         DashboardModuleButtons: AdaptableMenuItem[];
+        /**
+         * Increments when the Dashboard is refreshed, so the UI rebuilds.
+         */
         DashboardRevision: number;
     };
+    /**
+     * Smart Edit form for this session: whether the selection can be edited, the operation, and a preview of the result.
+     */
     SmartEdit: {
+        /**
+         * Whether the current selection can be smart-edited.
+         */
         IsValidSmartEditSelection: boolean;
         /** Warning shown inline in the Smart Edit panel when the current selection is not valid. */
         Alert?: AdaptableAlert | null;
+        /**
+         * Preview of the edit that will be applied.
+         */
         SmartEditPreviewInfo: PreviewInfo;
+        /**
+         * Number used as the second operand.
+         */
         SmartEditValue?: number;
+        /**
+         * Operation applied to each selected cell.
+         */
         SmartEditOperation?: SmartEditOperation;
     };
+    /**
+     * Bulk Update form for this session: the value, whether it is valid, and a preview of the result.
+     */
     BulkUpdate: {
+        /**
+         * Whether the selection can be bulk-updated. `IsValid` is the result. `Alert` is the warning when it cannot, and `Column` is the column that was checked.
+         */
         BulkUpdateValidationResult: BulkUpdateValidationResult;
+        /**
+         * Preview of the update that will be applied.
+         */
         BulkUpdatePreviewInfo: PreviewInfo;
+        /**
+         * Value typed into the Bulk Update form.
+         */
         BulkUpdateValue?: string;
     };
+    /**
+     * Grid Filter expressions applied this session, so the editor can offer them again.
+     */
     CachedQueries: CachedQuery[];
+    /**
+     * Cell summary currently shown for the selection.
+     */
     CellSummary: {
+        /**
+         * Operation being calculated, such as sum or average.
+         */
         CellSummaryOperation?: SummaryOperation | string;
+        /**
+         * Result of that operation.
+         */
         CellSummaryInfo: CellSummmaryInfo;
     };
+    /**
+     * Licence result for this session.
+     */
     License: {
+        /**
+         * Whether a watermark is shown, and its text.
+         */
         watermark: {
             show: boolean;
             text: string;
         };
+        /**
+         * When true, AdapTable does not persist state for this session.
+         */
         disablePersistence: boolean;
     };
+    /**
+     * Data Change History log and whether recording is on, paused or off.
+     */
     DataChangeHistory: {
+        /**
+         * Recorded cell changes, keyed by an id AdapTable assigns.
+         */
         logs: Record<string, CellDataChangedInfo>;
+        /**
+         * `'ACTIVE'` records, `'SUSPENDED'` pauses and keeps the log, `'INACTIVE'` is off and clears the log.
+         */
         currentMode: DataChangeHistoryMode;
+        /**
+         * When recording was last turned on. Null while history is inactive.
+         */
         enableTime: Date;
+        /**
+         * When recording was last paused. Null while history is active or inactive.
+         */
         suspendTime: Date;
     };
+    /**
+     * Position and size of Settings Panel windows, keyed by window kind (settings, edit).
+     */
     SettingsPanel: {
         [key: string]: {
+            /**
+             * Pixel position of the window.
+             */
             position: {
                 x: number;
                 y: number;
             };
+            /**
+             * Pixel size of the window.
+             */
             size: {
                 width: number;
                 height: number;
             };
         };
     };
+    /**
+     * Whether the column quick-filter bar is visible.
+     */
     IsQuickFilterVisible: boolean;
     /**
      * Transient per-column drafts of the ColumnFilter editors, keyed by
@@ -107,18 +236,30 @@ export interface InternalState extends IPushPullState, OpenFinState {
      * (see the `LAYOUT_COLUMN_FILTER_*` cases in `InternalRedux`).
      */
     ColumnFilterDrafts: Record<string, QlGroup>;
+    /**
+     * Name of the data set currently selected. Empty when none is selected.
+     */
     CurrentDataSet: string;
     /**
-     * Chart Models are saved here for every chart event, so we can listen to chart-model changes without directly listening to AG Grid events
+     * Charts open this session. Updated on chart events so AdapTable can follow model changes.
      */
     Charting: {
+        /**
+         * Latest AG Grid chart models.
+         */
         currentChartModels: ChartModel[];
+        /**
+         * External charts open this session.
+         */
         externalChartingDefinitions: ExternalChartDefinition<unknown>[];
     };
     /**
-     * Keeps session-relevant information for Layout
+     * Layout UI flags for this session.
      */
     Layout: {
+        /**
+         * When true, module lists include objects that are not extended into the current layout.
+         */
         showLayoutNonExtendedObjects: boolean;
     };
     /**
@@ -126,22 +267,61 @@ export interface InternalState extends IPushPullState, OpenFinState {
      * It will suppress the deletion confirmation dialog in the current session.
      */
     DisableDeleteConfirmation: boolean;
+    /**
+     * Export that has started and not yet finished. Absent when no export is running.
+     */
     Export: {
+        /**
+         * Report, format and destination of the export that is running.
+         */
         inProgress?: {
+            /**
+             * Report being exported.
+             */
             reportName: ReportNameType;
+            /**
+             * Format being written.
+             */
             reportFormat: ReportFormatType;
+            /**
+             * Where the export is being sent.
+             */
             exportDestination: ExportDestinationType;
         };
     };
+    /**
+     * Floating Quick Search for this session.
+     */
     QuickSearch?: {
+        /**
+         * Whether the floating Quick Search is open.
+         */
         floatingVisible?: boolean;
     };
+    /**
+     * In-cell comment editor, when it is open.
+     */
     CommentPopup?: {
+        /**
+         * When true, the popup is editing the thread. When false, it is showing the thread.
+         */
         editMode?: boolean;
+        /**
+         * Entity the popup is editing. The only value is `'Comment'`.
+         */
         focusedEntity?: 'Comment';
+        /**
+         * Cell the popup is anchored to. Null when it is not anchored.
+         */
         popupPosition?: CellAddress | null;
     };
+    /**
+     * Summary rows AdapTable is showing this session.
+     */
     RowSummary?: {
+        /**
+         * Pinned summary rows and the edge each one uses.
+         */
         rowSummaries?: SystemRowSummary[];
     };
 }

package/src/AdaptableState/LayoutState.d.ts

@@ -9,7 +9,9 @@ import { NonEmptyArray } from '../Utilities/Extensions/ArrayExtensions';
 import { XOR } from '../Utilities/Extensions/TypeExtensions';
 import { GroupSelectionMode, SelectAllMode } from 'ag-grid-enterprise';
 /**
- * Base Layout Type - Pivot or Table
+ * One named view of the grid: a {@link TableLayout} or a {@link PivotLayout}.
+ *
+ * A table layout lists its columns in `TableColumns`. A pivot layout lists its pivot columns in `PivotColumns` (an empty array when it only shows aggregations). The other layout's fields are typed `never` and must be left unset. `Layouts` must contain at least one layout. `CurrentLayout` selects one by `Name`; when it is omitted the first layout is used.
  */
 export type Layout = TableLayout | PivotLayout;
 /**
@@ -17,7 +19,9 @@ export type Layout = TableLayout | PivotLayout;
  */
 export type LayoutArray = NonEmptyArray<Layout>;
 /**
- * Adaptable State Section for Layout Module, containing collection of Layouts and name of Current Layout
+ * Layout section of Adaptable State, including Initial State.
+ *
+ * `Layouts` is a non-empty list of table and pivot layouts. `CurrentLayout` is the `Name` loaded at startup; when omitted, the first layout is used. `LayoutExtensions` is how objects from other modules (Format Columns, Styled Columns, and so on) apply only in named layouts.
  */
 export interface LayoutState extends BaseState {
     /**
@@ -38,7 +42,9 @@ export interface LayoutState extends BaseState {
  */
 export type RowGroupDisplayType = 'single' | 'multi' | 'groupRows';
 /**
- * Base object for both Table and Pivot Layouts
+ * Fields shared by a table layout and a pivot layout.
+ *
+ * `Name` is required and is how `CurrentLayout` selects the layout. Sorts, filters, pinning, sizing, charts to open and row selection live here. The column list lives on {@link TableLayout} or {@link PivotLayout}.
  */
 export interface LayoutBase extends AdaptableObject {
     /**
@@ -78,7 +84,7 @@ export interface LayoutBase extends AdaptableObject {
      */
     GridFilter?: GridFilter;
     /**
-     * Details of which Columns are pinned
+     * Columns pinned to an edge. Each entry is a column id set to `'left'` or `'right'`. Columns absent from the map are not pinned.
      */
     ColumnPinning?: ColumnDirectionMap;
     /**
@@ -94,7 +100,9 @@ export interface LayoutBase extends AdaptableObject {
      */
     RowSelection?: LayoutRowSelection | false;
     /**
-     * Position of the Grand Total Row in the Layout
+     * Where the grand total row is shown.
+     *
+     * `'top'`, `'bottom'`, `'pinnedTop'` or `'pinnedBottom'`. `true` is the same as `'top'`. `false`, or omitting the property, turns the grand total row off.
      */
     GrandTotalRow?: 'top' | 'bottom' | 'pinnedTop' | 'pinnedBottom' | boolean;
     /**
@@ -103,15 +111,17 @@ export interface LayoutBase extends AdaptableObject {
     RowGroupDisplayType?: RowGroupDisplayType;
 }
 /**
- * Defines a Table-based Layout
+ * A table layout.
+ *
+ * `TableColumns` is required and is the column order. Row groups use `RowGroupedColumns`. Aggregations in grouped rows use `TableAggregationColumns`. Leave `PivotColumns`, `PivotGroupedColumns`, `PivotExpandLevel` and `PivotAggregationColumns` unset.
  */
 export interface TableLayout extends LayoutBase {
     /**
-     * List of Column Ids to include in Table Layout
+     * Column ids in this layout, in display order. Required.
      */
     TableColumns: string[];
     /**
-     * Map of Table Column Visibility
+     * Columns to hide. Each entry is a column id set to `false`. Columns absent from the map stay visible.
      */
     ColumnVisibility?: ColumnBooleanFalseMap;
     /**
@@ -144,7 +154,9 @@ export interface TableLayout extends LayoutBase {
     PivotAggregationColumns?: never;
 }
 /**
- * Defines a Pivot-based Layout
+ * A pivot layout.
+ *
+ * `PivotColumns` is required. Pass an empty array when the layout only shows aggregations. Row groups use `PivotGroupedColumns`. Aggregations use `PivotAggregationColumns`. Leave `TableColumns`, `TableAggregationColumns` and `RowGroupedColumns` unset.
  */
 export interface PivotLayout extends LayoutBase {
     /**
@@ -189,11 +201,15 @@ export interface PivotLayout extends LayoutBase {
     PivotResultColumnsOrder?: string[] | boolean;
 }
 /**
- * Defines the position of Pivot Total position - 'before' or 'after' the Value Column(s)
+ * Where a pivot total is drawn relative to the value columns.
+ *
+ * `'before'` and `true` place it before the value columns. `'after'` places it after them. `false`, or omitting the property on {@link PivotLayout.PivotGrandTotal} or {@link PivotLayout.PivotColumnTotal}, turns that total off.
  */
 export type PivotTotalPosition = 'before' | 'after' | boolean;
 /**
- * Manages Row Group expand / collapse behaviour, including exceptions
+ * Which row groups are expanded when the layout is applied.
+ *
+ * `'always-expanded'` and `'always-collapsed'` apply to every group and take no exception list. `'expanded'` and `'collapsed'` do the same except for the group-key paths listed in {@link GroupKeys}.
  */
 export type RowGroupValues = {
     RowGroupDefaultBehavior: 'always-expanded' | 'always-collapsed';
@@ -218,15 +234,17 @@ export type RowGroupValuesWithExceptionKeys = {
     GroupKeys?: GroupKeys[];
 }>;
 /**
- * Enables setting Row Group behaviour with exceptions
+ * Expand and collapse exceptions for one set of row-grouped columns.
+ *
+ * AdapTable uses the entry whose `RowGroupedColumns` match the layout's current row-grouped columns. `ExceptionGroupKeys` are the group-key paths that do the opposite of `RowGroupDefaultBehavior`: collapsed when the default is `'expanded'`, expanded when the default is `'collapsed'`.
  */
 export interface GroupKeys {
     /**
-     * Columns that are Row Grouped
+     * Row-grouped column ids this exception list applies to. Matched against the layout's current row-grouped columns.
      */
     RowGroupedColumns: string[];
     /**
-     * Exceptions to default behaviour, provided as array or arrays
+     * Group-key paths that do the opposite of `RowGroupDefaultBehavior`. Each inner array is one path from the top group down.
      */
     ExceptionGroupKeys?: any[][];
 }
@@ -250,31 +268,31 @@ export type ColumnGroupValuesWithExceptionKeys = {
     ExceptionGroupKeys?: any[];
 };
 /**
- * Defines a map of Columns with Sizing information
+ * Column ids mapped to a width or a flex factor. Set `Width` or `Flex` on each entry, not both.
  */
 export type ColumnSizingMap = {
     [columnId: string]: ColumnSizingDefinition;
 };
 /**
- * Defines a map of Columns with a String value
+ * Column ids mapped to a string. Used by `ColumnHeaders` for a custom header. A column absent from the map keeps its own header.
  */
 export type ColumnStringMap = {
     [columnId: string]: string;
 };
 /**
- * Defines a map of Columns with a Number value
+ * Column ids mapped to a number.
  */
 export type ColumnNumberMap = {
     [columnId: string]: number;
 };
 /**
- * Defines a map of Columns with a Boolean value
+ * Column ids mapped to `false`. Used by {@link TableLayout.ColumnVisibility} to list hidden columns. A column id cannot be mapped to `true`.
  */
 export type ColumnBooleanFalseMap = {
     [columnId: string]: false;
 };
 /**
- * Defines a map of Columns with a Left / Right direction value
+ * Column ids mapped to a pin edge. `'left'` pins to the left, `'right'` to the right.
  */
 export type ColumnDirectionMap = {
     [columnId: string]: 'left' | 'right';
@@ -283,18 +301,41 @@ export type ColumnDirectionMap = {
  * State & behaviour for column sizing (must set `width` or `flex` but not both); all other props optional
  */
 export type ColumnSizingDefinition = ({
+    /**
+     * Column width in pixels. Do not set `Flex` on the same column.
+     */
     Width?: number;
+    /**
+     * Not set when `Width` is set. A column is either fixed-width or flex.
+     */
     Flex?: never;
 } | {
+    /**
+     * Flex grow factor, as in AG Grid `flex`. Do not set `Width` on the same column.
+     */
     Flex?: number;
+    /**
+     * Not set when `Flex` is set. A column is either fixed-width or flex.
+     */
     Width?: never;
 }) & {
+    /**
+     * Whether the user can drag the column edge to resize it.
+     */
     Resizable?: boolean;
+    /**
+     * Smallest width in pixels the column can be resized to.
+     */
     MinWidth?: number;
+    /**
+     * Largest width in pixels the column can be resized to.
+     */
     MaxWidth?: number;
 };
 /**
- * Defines Row Selection behaviour in a Layout
+ * Row selection for one layout, set on {@link LayoutBase.RowSelection}.
+ *
+ * `Mode` is `'singleRow'` or `'multiRow'`. Omit `RowSelection` to keep `gridOptions.rowSelection`. Set `RowSelection` to `false` to turn selection off for that layout.
  */
 export interface LayoutRowSelection {
     /**
@@ -335,7 +376,9 @@ export interface LayoutRowSelection {
     EnableClickSelection?: boolean | 'enableDeselection' | 'enableSelection';
 }
 /**
- * The OLD Layout - kept temporarily so we can check what we previously had
+ * Stored layout shape that current layouts do not use.
+ *
+ * Author `TableLayout` or `PivotLayout`. This interface is not part of Initial State.
  */
 export interface LayoutOld extends AdaptableObject {
     Name: string;

package/src/AdaptableState/NamedQueryState.d.ts

@@ -1,11 +1,13 @@
 import { BaseState } from './BaseState';
 import { AdaptableObject } from './Common/AdaptableObject';
 /**
- * Adaptable State Section for Named Query Module
+ * Named Query section of Adaptable State, including Initial State.
+ *
+ * Each query is a scalar AdapTableQL expression other expressions can call with `QUERY('Name')`. Aggregations are not allowed. `ReturnType` defaults to `'boolean'`, which can be used as a Grid Filter or Alert rule.
  */
 export interface NamedQueryState extends BaseState {
     /**
-     * Named Queries which can be referenced in other Expressions
+     * Named Queries other expressions can reference with `QUERY('Name')`.
      */
     NamedQueries?: NamedQuery[];
 }
@@ -32,13 +34,23 @@ export interface NamedQuery extends AdaptableObject {
      */
     Description?: string;
     /**
-     * Declared return type of the Expression.
-     * Defaults to `'boolean'` when omitted (preserves legacy InitialState).
+     * Return type of the expression. When omitted, the query is treated as `'boolean'` and can be used as a Grid Filter or Alert rule.
      */
     ReturnType?: NamedQueryReturnType;
 }
+/**
+ * A Grid Filter expression kept for this session so it can be offered again in the editor.
+ *
+ * Session state only. It is not part of Initial State and it is not persisted.
+ */
 export interface CachedQuery {
+    /**
+     * Expression text that was applied.
+     */
     expression: string;
+    /**
+     * When the expression was applied.
+     */
     time: Date;
 }
 /**

package/src/AdaptableState/NoteState.d.ts

@@ -2,16 +2,20 @@ import { AdaptableObject } from '../types';
 import { BaseState } from './BaseState';
 import { AdaptableMessageType } from './Common/AdaptableMessageType';
 /**
- * Adaptable State Section for Note Module
+ * Note section of Adaptable State, including Initial State.
+ *
+ * A Note is one piece of text on one cell, located by `PrimaryKeyValue` and `ColumnId`. It is separate from a Comment thread and from a Free Text Column. `NoteType` defaults to `'Info'` and colours the cell indicator.
  */
 export interface NoteState extends BaseState {
     /**
-     * Collection of AdapTable Notes
+     * Notes to show. One note occupies one cell.
      */
     Notes?: AdaptableNotes;
 }
 /**
- * Note that can be applied to a Cell in AdapTable
+ * One piece of text attached to one cell.
+ *
+ * `PrimaryKeyValue` and `ColumnId` locate the cell. `Text` is the note. `NoteType` colours the indicator and defaults to `'Info'`.
  */
 export interface AdaptableNote extends AdaptableObject {
     /**

package/src/AdaptableState/OpenFinState.d.ts

@@ -1,14 +1,24 @@
 import { BaseState } from './BaseState';
 import { AdaptableObject } from './Common/AdaptableObject';
 /**
- * Internal State used by AdapTable for managing the OpenFin plugin
+ * OpenFin session state.
+ *
+ * Held under transient `Plugins` state for the current session. It is not part of Initial State and it is not persisted.
  */
 export interface OpenFinState extends BaseState {
+    /**
+     * Report currently streaming to OpenFin. Absent when live data is stopped.
+     */
     CurrentLiveOpenFinReport?: OpenFinReport;
+    /**
+     * Report name selected in the OpenFin UI.
+     */
     OpenFinCurrentReportName?: string;
 }
 /**
- * An OpenFin report
+ * A report streaming to OpenFin.
+ *
+ * `ReportName` is a report in Export state.
  */
 export interface OpenFinReport extends AdaptableObject {
     /**

package/src/AdaptableState/PlusMinusState.d.ts

@@ -2,16 +2,20 @@ import { BaseState } from './BaseState';
 import { ColumnScope, NumberScopeDataType } from './Common/ColumnScope';
 import { SuspendableObject } from '../types';
 /**
- * Adaptable State Section for Plus Minus Module
+ * Plus Minus section of Adaptable State, including Initial State.
+ *
+ * Each nudge adds or subtracts `NudgeValue` from numeric cells in `Scope`. The increment key adds `NudgeValue`; the decrement key subtracts it. A nudge's own keys override `plusMinusOptions`, which override the default `+` and `-` keys.
  */
 export interface PlusMinusState extends BaseState {
     /**
-     * Array of Plus Minus Nudges
+     * Nudges to apply. Each one names numeric columns, the amount, and optional keys.
      */
     PlusMinusNudges?: PlusMinusNudge[];
 }
 /**
- * Defines a Plus Minus Rule - used in the Plus Minus Module
+ * Adds or subtracts a fixed amount from numeric cells.
+ *
+ * `Scope` is numeric columns only. The increment key sets the cell to its current value plus `NudgeValue`; the decrement key subtracts `NudgeValue`. Omit `Rule` to apply the nudge on every row in scope. Suspend with `IsSuspended`.
  */
 export interface PlusMinusNudge extends SuspendableObject {
     /**
@@ -23,7 +27,7 @@ export interface PlusMinusNudge extends SuspendableObject {
      */
     Scope: ColumnScope<NumberScopeDataType>;
     /**
-     * Amount by which to update cell when Rule is applied
+     * Amount added by the increment key and subtracted by the decrement key.
      */
     NudgeValue: number;
     /**