@adaptabletools/adaptable 24.0.0-canary.1 → 24.0.0-canary.10

package/src/AdaptableState/IPushPullState.d.ts

@@ -1,22 +1,56 @@
 import { AdaptableObject } from './Common/AdaptableObject';
 import { BaseState } from './BaseState';
 /**
- * Internal State used by AdapTable for managing the ipushpull plugin
+ * ipushpull session state.
+ *
+ * Held under transient `Plugins` state for the current session. It is not part of Initial State and it is not persisted. `CurrentIPushpullPassword` is the password for the signed-in session.
  */
 export interface IPushPullState extends BaseState {
+    /**
+     * Whether the ipushpull session is connected.
+     */
     IsIPushPullRunning?: boolean;
+    /**
+     * Folders (domains) available on the connected ipushpull account, and the pages in each folder.
+     */
     IPushPullDomainsPages?: IPushPullDomain[];
+    /**
+     * Message from the last failed login. Absent after a successful login.
+     */
     IPushPullLoginErrorMessage?: string;
+    /**
+     * Report currently streaming to ipushpull. Absent when live data is stopped.
+     */
     CurrentLiveIPushPullReport?: IPushPullReport;
+    /**
+     * Username of the signed-in ipushpull account.
+     */
     CurrentIPushpullUsername?: string;
+    /**
+     * Password held for the current ipushpull session.
+     */
     CurrentIPushpullPassword?: string;
+    /**
+     * Report name selected in the ipushpull UI.
+     */
     IPushPullCurrentReportName?: string;
+    /**
+     * Folder selected in the ipushpull UI.
+     */
     IPushPullCurrentFolder?: string;
+    /**
+     * Page selected in the ipushpull UI.
+     */
     IPushPullCurrentPage?: string;
+    /**
+     * Page names in the selected folder.
+     */
     IPushPullCurrentAvailablePages?: string[];
 }
 /**
- * Internal object that maps an IPushPull Domain object
+ * One ipushpull folder and the pages in it.
+ *
+ * Returned for the signed-in account. `Name` is the folder name, `FolderId` is its id, and `Pages` are the page names.
  */
 export interface IPushPullDomain {
     /**
@@ -33,7 +67,9 @@ export interface IPushPullDomain {
     Pages: string[];
 }
 /**
- * An ipushpull report
+ * A report streaming to one ipushpull page.
+ *
+ * `ReportName` is a report in Export state. `Folder` and `Page` are the ipushpull destination.
  */
 export interface IPushPullReport extends AdaptableObject {
     /**

package/src/AdaptableState/InitialState.d.ts

@@ -36,7 +36,7 @@ export interface InitialState {
      */
     CalculatedColumn?: CalculatedColumnState;
     /**
-     * Named Charts (wrapping Chart models)
+     * Saved charts. AG Grid charts are `ChartDefinitions` (`Name` and `Model`). Application charts are `ExternalChartDefinitions` (`Name` and `Data`).
      */
     Charting?: ChartingState;
     /**
@@ -52,11 +52,11 @@ export interface InitialState {
      */
     Export?: ExportState;
     /**
-     * Definitions of which cells flash in response to data changes
+     * Flashing Cell definitions. Each one names a column scope and a boolean rule, and flashes a cell, a row, or an aggregated cell.
      */
     FlashingCell?: FlashingCellState;
     /**
-     * Collection of *FormatColumn* objects that will style an entire column either fully or using a Condition
+     * Format Columns. Each one colours cells, changes how values are displayed, or both, for a column scope. Omit `Rule` to apply it on every row.
      */
     FormatColumn?: FormatColumnState;
     /**
@@ -69,11 +69,11 @@ export interface InitialState {
      */
     Layout?: LayoutState;
     /**
-     * Named Queries available for use across multiple AdapTable Modules
+     * Named Queries other expressions can call with `QUERY('Name')`. A boolean query can be a Grid Filter or an Alert rule.
      */
     NamedQuery?: NamedQueryState;
     /**
-     * Collection of personal Notes that are edited at Cell level
+     * Notes. One piece of text on one cell, located by primary key and column id.
      */
     Note?: NoteState;
     /**
@@ -83,7 +83,7 @@ export interface InitialState {
      */
     PlusMinus?: PlusMinusState;
     /**
-     * Configues how Quick Search will run i.e. how and whether to highlight matching cells and to filter out non-matching rows
+     * Quick Search text restored at startup, and the styles used to highlight matches.
      */
     QuickSearch?: QuickSearchState;
     /**
@@ -91,15 +91,15 @@ export interface InitialState {
      */
     Shortcut?: ShortcutState;
     /**
-     * Configures the Adaptable Status Bar
+     * Status bars. Each `Key` matches an AG Grid `statusPanels` entry whose component is `AdaptableStatusPanel`.
      */
     StatusBar?: StatusBarState;
     /**
-     * Collection of Special Column Styles
+     * Styled Columns. Each entry draws one column with a single visual style.
      */
     StyledColumn?: StyledColumnState;
     /**
-     * Specifies current Theme and lists User and System themes available for selection
+     * Active theme (`light`, `dark` or `os`) and which shipped themes are offered.
      */
     Theme?: ThemeState;
     /**

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;