@adaptabletools/adaptable 24.0.0-canary.8 → 24.0.0

package/src/AdaptableState/Common/SystemStatusMessageInfo.d.ts

@@ -1,7 +1,9 @@
 import { AdaptableMessageType } from './AdaptableMessageType';
 import { Identifiable } from '../../types';
 /**
- * Wraps a System Status Message
+ * One message in the System Status panel.
+ *
+ * `statusMessage` is the text. `statusType` is `'Success'`, `'Info'`, `'Warning'` or `'Error'` and sets the colour. `statusFurtherInformation` is optional extra text. `timestamp` is when it was raised.
  */
 export interface SystemStatusMessageInfo extends Identifiable {
     /**
@@ -13,7 +15,7 @@ export interface SystemStatusMessageInfo extends Identifiable {
      */
     statusFurtherInformation?: string;
     /**
-     * Type of Message i.e. Succcess, Warning, Error, Info
+     * Message type: `Success`, `Info`, `Warning` or `Error`
      */
     statusType: AdaptableMessageType;
     /**

package/src/AdaptableState/Common/TransposeConfig.d.ts

@@ -20,7 +20,7 @@ export interface TransposeConfig {
      */
     columnsToTranspose?: string[] | ((context: AdaptableColumnsContext) => string[]);
     /**
-     * Rows to Transpose: All, Visible or via Expression
+     * Which rows are transposed. `'All'` (the default, also used when omitted) takes every row. `'VisibleOnly'` takes the rows currently visible. Any other string is a boolean AdapTableQL expression, and only matching rows are transposed.
      * @defaultValue All
      */
     rowsToTranspose?: TypeHint<string, 'VisibleOnly' | 'All'>;

package/src/AdaptableState/Common/Types.d.ts

@@ -29,7 +29,13 @@ export type AdaptableModuleButtons = AdaptableModuleButton[];
  * List of all the Module buttons Adaptable provides - each Module has a popup for which this is a shortcut button
  */
 export type AdaptableModuleButton = 'Alert' | 'BulkUpdate' | 'CalculatedColumn' | 'CellSummary' | 'Comment' | 'CustomSort' | 'Dashboard' | 'DataChangeHistory' | 'DataImport' | 'DataSet' | 'Export' | 'ColumnFilter' | 'GridFilter' | 'NamedQuery' | 'FlashingCell' | 'FormatColumn' | 'FreeTextColumn' | 'GridInfo' | 'Layout' | 'Note' | 'OpenFin' | 'PlusMinus' | 'QuickSearch' | 'SettingsPanel' | 'Shortcut' | 'SmartEdit' | 'StyledColumn' | 'StateManagement' | 'StatusBar' | 'SystemStatus' | 'TeamSharing' | 'Theme';
+/**
+ * Names of Adaptable State sections.
+ */
 export type AdaptableStateKeys = AdaptableStateKey[];
+/**
+ * One Adaptable State section name: a persisted section, or `'OpenFin'` or `'IPushPull'`.
+ */
 export type AdaptableStateKey = keyof AdaptablePersistentState | 'OpenFin' | 'IPushPull';
 /**
  * Modules provided by AdapTable, subject to Entitlements and usually have Initial Adaptable State
@@ -40,6 +46,9 @@ export declare const ALL_MODULES: AdaptableModule[];
  * Modules which can appear in the Settings Panel
  */
 export type AdaptableSettingsPanel = 'Alert' | 'BulkUpdate' | 'CalculatedColumn' | 'CellSummary' | 'Charting' | 'SmartEdit' | 'CustomSort' | 'Dashboard' | 'DataChangeHistory' | 'DataSet' | 'Export' | 'ColumnFilter' | 'FlashingCell' | 'FormatColumn' | 'FreeTextColumn' | 'GridInfo' | 'ColumnInfo' | 'Layout' | 'PlusMinus' | 'QuickSearch' | 'Shortcut' | 'StateManagement' | 'StatusBar' | 'StyledColumn' | 'SystemStatus' | 'TeamSharing' | 'Theme' | 'ToolPanel' | 'Note' | 'DataImport' | 'GridFilter' | 'NamedQuery' | 'Comment';
+/**
+ * A string (or other base type) that editors treat as one of `Literals`, while still accepting any value of the base type.
+ */
 export type TypeHint<Base, Literals> = (Base & {
     __subType?: true;
 }) | Literals;

package/src/AdaptableState/CustomSortState.d.ts

@@ -1,16 +1,20 @@
 import { BaseState } from './BaseState';
 import { SuspendableObject } from '../types';
 /**
- * Adaptable State Section for Custom Sort Module
+ * Custom Sort section of Adaptable State, including Initial State.
+ *
+ * Each entry replaces the normal sort of one column with the order in `SortedValues`. Values in that list sort in list order. Values absent from the list sort after them, using the normal comparison. A custom sort comparer registered for the column is used instead of `SortedValues`.
  */
 export interface CustomSortState extends BaseState {
     /**
-     * Collection of Custom Sort objects.
+     * Custom Sorts to apply. One column uses the first Custom Sort whose `ColumnId` matches.
      */
     CustomSorts?: CustomSort[];
 }
 /**
- * Custom Sort object used in Custom Sort function.
+ * A column sorted in a fixed order instead of the normal comparison.
+ *
+ * `ColumnId` is the column. `SortedValues` is the order: listed values come first, in that order, and any other value sorts after them. Date values are stored as ISO dates (`yyyy-MM-dd`). Suspend with `IsSuspended`.
  */
 export interface CustomSort extends SuspendableObject {
     /**
@@ -22,8 +26,7 @@ export interface CustomSort extends SuspendableObject {
      */
     ColumnId: string;
     /**
-     * Order of values by which Column will be sorted; Date values are persisted as ISO strings ('yyyy-MM-dd')
-     *
+     * Sort order. Listed values come first, in this order. Any other value sorts after them. Dates are stored as ISO strings (`yyyy-MM-dd`).
      */
     SortedValues?: (string | number)[];
 }

package/src/AdaptableState/DashboardState.d.ts

@@ -2,20 +2,22 @@ import { BaseState } from './BaseState';
 import { AdaptableDashboardToolbars, AdaptableModuleButtons } from './Common/Types';
 import { AdaptableObject } from './Common/AdaptableObject';
 /**
- * Adaptable State Section for the AdapTable Dashboard
+ * Dashboard section of Adaptable State, including Initial State.
+ *
+ * The Dashboard sits above the grid. `Tabs` are named groups of toolbars (the default is an empty list). `PinnedToolbars` sit above the grid and are not inside a tab. `ActiveTabIndex` is the zero-based index of the open tab. `IsCollapsed` leaves the header visible and hides the tab contents. `IsFloating` shows a draggable dashboard; `FloatingPosition` is its pixel position. `IsHidden` removes it until it is shown again from the Column Menu or Tool Panel.
  */
 export interface DashboardState extends BaseState {
     /**
-     * Named group of Toolbars
+     * Named groups of toolbars. Each tab has a `Name` and the `Toolbars` it shows.
      * @defaultValue Empty Array
      */
     Tabs?: DashboardTab[];
     /**
-     * Toolbars displayed above Grid (and not in Tab)
+     * Toolbars shown above the grid, outside any tab.
      */
     PinnedToolbars?: AdaptableDashboardToolbars | string[];
     /**
-     * Index of Active Tab (in Tabs collection)
+     * Zero-based index into `Tabs` of the tab that is open.
      */
     ActiveTabIndex?: number;
     /**
@@ -24,7 +26,7 @@ export interface DashboardState extends BaseState {
      */
     IsCollapsed?: boolean;
     /**
-     * Is Dashboard floating; if true, appears in draggable, minmised form (double-click to revert to default position)
+     * Is Dashboard floating; if true, it appears in a draggable form (double-click to revert to the default position)
      *  @defaultValue false
      */
     IsFloating?: boolean;
@@ -34,7 +36,7 @@ export interface DashboardState extends BaseState {
      */
     IsHidden?: boolean;
     /**
-     * Position of Dashboard when in Floating mode
+     * Pixel position of the Dashboard while `IsFloating` is true. `x` and `y` are offsets in pixels.
      */
     FloatingPosition?: AdaptableCoordinate;
     /**
@@ -53,7 +55,9 @@ export interface DashboardState extends BaseState {
     DashboardTitle?: string;
 }
 /**
- * Defines a named set of Toolbars in the AdapTable Dashboard
+ * One Dashboard tab.
+ *
+ * `Name` is the label in the header. `Toolbars` are the toolbars shown while this tab is the active one (`ActiveTabIndex`).
  */
 export interface DashboardTab extends AdaptableObject {
     /**
@@ -66,15 +70,15 @@ export interface DashboardTab extends AdaptableObject {
     Toolbars: AdaptableDashboardToolbars | string[];
 }
 /**
- * Used by AdapTable to remember position of Floating Dashboard
+ * Pixel position of the floating Dashboard.
  */
 export interface AdaptableCoordinate extends AdaptableObject {
     /**
-     * x axis number
+     * Horizontal offset, in pixels.
      */
     x: number;
     /**
-     * y axis number
+     * Vertical offset, in pixels.
      */
     y: number;
 }

package/src/AdaptableState/ExportState.d.ts

@@ -7,7 +7,9 @@ import { TypeHint } from './Common/Types';
 import { ExportDestinationType } from '../AdaptableOptions/ExportOptions';
 import { SuspendableObject } from './Common/SuspendableObject';
 /**
- * Adaptable State Section for Export Module with Schedules
+ * Export section of Adaptable State, including Initial State.
+ *
+ * `Reports` are reports you define. AdapTable also provides the system reports `'All Data'`, `'Current Layout'` and `'Selected Data'`. `CurrentReport` and `CurrentFormat` are the report and format selected in the Export toolbar. `ReportSchedules` run a report on a `Schedule`.
  */
 export interface ExportState extends BaseState {
     /**
@@ -28,7 +30,9 @@ export interface ExportState extends BaseState {
     ReportSchedules?: ReportSchedule[];
 }
 /**
- * A Report which can export data from AdapTable
+ * A report you define.
+ *
+ * `ReportColumnScope` chooses the columns. Set `Scope` only when that is `'ScopeColumns'`. `ReportRowScope` chooses the rows. Set `Expression` only when that is `'ExpressionRows'`. The system reports are separate from this list.
  */
 export interface Report extends AdaptableObject {
     /**
@@ -144,11 +148,15 @@ export type SystemReportFormat =
  */
  | 'JSON';
 /**
- * Columns to be included in a Report
+ * Which columns a report exports.
+ *
+ * `'AllColumns'` exports every column. `'VisibleColumns'` exports the columns currently on screen. `'ScopeColumns'` exports the columns in `Scope`. `'SelectedColumns'` exports the selected columns and is not offered in the report wizard.
  */
 export type ReportColumnScope = 'AllColumns' | 'VisibleColumns' | 'ScopeColumns' | 'SelectedColumns';
 /**
- * AG Grid Row Data to be included in a Report
+ * Which rows a report exports.
+ *
+ * `'AllRows'` exports every row. `'VisibleRows'` exports the rows that are currently visible. `'ExpressionRows'` exports rows matching `Expression`. `'SelectedRows'` exports the selected rows and is not offered in the report wizard.
  */
 export type ReportRowScope = 'AllRows' | 'VisibleRows' | 'ExpressionRows' | 'SelectedRows';
 /**

package/src/AdaptableState/FlashingCellState.d.ts

@@ -3,11 +3,13 @@ import { AdaptableStyle } from './Common/AdaptableStyle';
 import { ColumnScope } from '../types';
 import { AdaptableObject, SuspendableObject } from '../../types';
 /**
- * Adaptable State Section for Flashing Cell module
+ * Flashing Cell section of Adaptable State, including Initial State.
+ *
+ * Each definition watches columns in `Scope` and flashes when `Rule` is true. `FlashTarget` is `'cell'` (the default), `'row'`, `'aggFuncCell'`, or a list of those. `UpChangeStyle`, `DownChangeStyle` and `NeutralChangeStyle` colour the flash. `FlashDuration` is milliseconds or `'always'` (the default is 500).
  */
 export interface FlashingCellState extends BaseState {
     /**
-     * Flashing Cell Definitions - will flash cells/rows when rule is met
+     * Flashing Cell definitions. Each one names a column scope, a boolean rule, and what flashes.
      */
     FlashingCellDefinitions?: FlashingCellDefinition[];
 }
@@ -22,7 +24,9 @@ export type FlashTargetTypes = 'row' | 'cell' | 'aggFuncCell';
  */
 export type FlashingCellType = 'Change' | 'Observable';
 /**
- * The Flashing Cell Definition
+ * Flashes a cell, a row, or an aggregated cell when a rule matches.
+ *
+ * `Scope` and `Rule` are required. `Type` is `'Change'` (this edit against the previous value) or `'Observable'` (change history such as `CHANGE_COUNT`). When `Type` is omitted it is treated as `'Change'`. Suspend with `IsSuspended`.
  */
 export interface FlashingCellDefinition extends AdaptableObject, SuspendableObject {
     /**
@@ -30,8 +34,7 @@ export interface FlashingCellDefinition extends AdaptableObject, SuspendableObje
      */
     Name: string;
     /**
-     * Rule flavour — Change (default) or Observable.
-     * Existing definitions without a Type are stamped `Change` on upgrade.
+     * `'Change'` compares this edit with the previous value. `'Observable'` evaluates the rule against change history. When omitted, the definition is treated as `'Change'`.
      */
     Type?: FlashingCellType;
     /**

package/src/AdaptableState/FormatColumnState.d.ts

@@ -5,16 +5,20 @@ import { ColumnScope } from './Common/ColumnScope';
 import { RowScope } from './Common/RowScope';
 import { SuspendableObject } from '../types';
 /**
- * Adaptable State Section for Format Column Module
+ * Format Column section of Adaptable State, including Initial State.
+ *
+ * Each entry styles cells, changes how a value is displayed, or both. `Scope` says where it applies. `Rule` limits it to matching rows; omit `Rule` to apply it on every row. `Style` sets colours and fonts. `DisplayFormat` changes the displayed value.
  */
 export interface FormatColumnState extends BaseState {
     /**
-     * Collection of Format Columns
+     * Format Columns to apply. Several can match the same cell. Their styles are combined, and the first definition in this list wins on a property both set. A Styled Column wins over a Format Column where both set the same property.
      */
     FormatColumns?: FormatColumn[];
 }
 /**
- * Object used in Format Column function
+ * Colours a cell, changes how its value is displayed, or both.
+ *
+ * `Scope` is required. `Style` and `DisplayFormat` can be set together. Omit `Rule` to apply the format on every row in scope. `Target` defaults to `'cell'` (`'columnHeader'` formats the header). Suspend with `IsSuspended`.
  */
 export interface FormatColumn extends SuspendableObject {
     /**
@@ -36,7 +40,7 @@ export interface FormatColumn extends SuspendableObject {
      */
     Rule?: string;
     /**
-     * AdapTable Style to apply
+     * Colours, font and CSS class applied to the cell or header. Can be set together with `DisplayFormat`.
      */
     Style?: AdaptableStyle;
     /**
@@ -47,28 +51,44 @@ export interface FormatColumn extends SuspendableObject {
      */
     DisplayFormat?: DisplayFormat;
     /**
-     * Which types of Rows to apply format (data, grouped, summary, total)
+     * Row kinds to skip. Each flag excludes that kind. When omitted, data, group, summary and total rows are all included.
      */
     RowScope?: RowScope;
     /**
-     * When to format Columns in Column Groups ('Expanded', 'Collapsed', 'Both')
+     * When a format applies to a column inside a column group.
      *
+     * Omit it to apply the format whether the parent group is expanded or collapsed. `'Expanded'` applies only while the parent group is expanded. `'Collapsed'` applies only while it is collapsed. `'Both'` applies in either state. A column that is the only leaf of a top-level group ignores an explicit scope.
      */
     ColumnGroupScope?: ColumnGroupScope;
 }
 /**
- * Specifies whether Column's cells or header is formatted
+ * Where a Format Column is drawn. `'cell'` formats the cells (the default). `'columnHeader'` formats the column header. Header formats are not applied to column group headers.
  */
 export type FormatColumnTarget = 'cell' | 'columnHeader';
 /**
- * Defines Column Group Scope
+ * Whether a Format Column applies while its parent column group is expanded, collapsed, or either.
  */
 export type ColumnGroupScope = 'Expanded' | 'Collapsed' | 'Both';
 /**
  * Config for api methods that get Format Columns
  */
 export interface FormatColumnConfig {
+    /**
+     * Include Format Columns that are suspended.
+     *
+     * When omitted or `false`, suspended definitions are left out.
+     */
     includeSuspended?: boolean;
+    /**
+     * Include Format Columns that are read-only.
+     *
+     * When omitted or `false`, read-only definitions are left out.
+     */
     includeReadOnly?: boolean;
+    /**
+     * Only Format Columns whose `Target` is this value (`cell` or `columnHeader`).
+     *
+     * When omitted, both targets are returned.
+     */
     target?: FormatColumnTarget;
 }

package/src/AdaptableState/FreeTextColumnState.d.ts

@@ -2,20 +2,24 @@ import { BaseState } from './BaseState';
 import { AdaptableObject } from './Common/AdaptableObject';
 import { SpecialColumnSettings } from './Common/SpecialColumnSettings';
 /**
- * Adaptable State Section for the Free Text Column Module
+ * Free Text Column section of Adaptable State, including Initial State.
+ *
+ * Each entry adds an editable column whose values are stored in Adaptable State, not in the grid data source. A cell shows the `FreeTextStoredValues` entry for its primary key. When that row has no stored value, it shows `DefaultValue`. Group rows are empty.
  */
 export interface FreeTextColumnState extends BaseState {
     /**
-     * Collection of Free Text Columns
+     * Free Text Columns to add. `ColumnId` is the id of the column AdapTable creates.
      */
     FreeTextColumns?: FreeTextColumn[];
 }
 /**
- * The FreeTextColumn object used in the Free Text Column function
+ * An editable column whose values live in Adaptable State.
+ *
+ * `ColumnId` is the id of the new column. `FreeTextColumnSettings.DataType` is required. `TextEditor` applies to string columns: `'Inline'` (the default) edits in the cell, `'Large'` opens AG Grid's large text editor.
  */
 export interface FreeTextColumn extends AdaptableObject {
     /**
-     * Id of Column
+     * Id of the column AdapTable creates. It is not the id of a column already in the data source.
      */
     ColumnId: string;
     /**
@@ -23,15 +27,15 @@ export interface FreeTextColumn extends AdaptableObject {
      */
     FriendlyName?: string;
     /**
-     * Initial value to use for each cell in the Column
+     * Value shown for a data row that has no `FreeTextStoredValues` entry for its primary key.
      */
     DefaultValue?: any;
     /**
-     * Collection of Stored Values to aplly in the Column
+     * Values stored for this column, keyed by the row primary key. A stored value is shown instead of `DefaultValue`.
      */
     FreeTextStoredValues?: FreeTextStoredValue[];
     /**
-     * Cell editor to use when editing a string Free Text Column
+     * Editor for a string Free Text Column. `'Inline'` edits in the cell. `'Large'` opens AG Grid's large text editor.
      * @defaultValue 'Inline'
      */
     TextEditor?: 'Inline' | 'Large';
@@ -41,7 +45,9 @@ export interface FreeTextColumn extends AdaptableObject {
     FreeTextColumnSettings: FreeTextColumnSettings;
 }
 /**
- * Defines a cell value stored in a Free Text Column
+ * One stored Free Text cell.
+ *
+ * `PrimaryKey` is the row. `FreeText` is the value shown for that row. A row with no entry shows `DefaultValue`.
  */
 export interface FreeTextStoredValue {
     /**

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;
     /**