@adaptabletools/adaptable 24.0.0-canary.8 → 24.0.0

package/src/AdaptableState/PopupState.d.ts

@@ -1,17 +1,45 @@
 import { ScreenPopup, ConfirmationPopup, PromptPopup, WindowPopup, FormPopup } from '../Utilities/Interface/MessagePopups';
 import { BaseState } from './BaseState';
 import { ProgressIndicatorConfig } from './Common/ProgressIndicatorConfig';
+/**
+ * Progress indicator for this session, plus whether it is currently showing.
+ *
+ * Session state only. It is not part of Initial State and it is not persisted.
+ */
 export interface ProgressIndicator extends ProgressIndicatorConfig {
+    /**
+     * Whether the progress indicator is on screen.
+     */
     active: boolean;
 }
 /**
- * Internal state to manage open popups - NOT persisted by Redux
+ * Popups open in this session.
+ *
+ * Session state only. It is not part of Initial State and it is not persisted. Each property is always present. Its `ShowScreenPopup`, `ShowConfirmationPopup` or equivalent flag is false when that popup is closed.
  */
 export interface PopupState extends BaseState {
+    /**
+     * Full-screen popup, when one is open.
+     */
     ScreenPopup: ScreenPopup;
+    /**
+     * Window popup, when one is open.
+     */
     WindowPopup: WindowPopup;
+    /**
+     * Form popup, when one is open.
+     */
     FormPopup: FormPopup;
+    /**
+     * Confirmation popup, when one is open.
+     */
     ConfirmationPopup: ConfirmationPopup;
+    /**
+     * Prompt popup, when one is open.
+     */
     PromptPopup: PromptPopup;
+    /**
+     * Progress indicator and whether it is showing.
+     */
     ProgressIndicator: ProgressIndicator;
 }

package/src/AdaptableState/QuickSearchState.d.ts

@@ -1,7 +1,9 @@
 import { AdaptableStyle } from './Common/AdaptableStyle';
 import { BaseState } from './BaseState';
 /**
- * Adaptable State Section for Quick Search Module
+ * Quick Search section of Adaptable State, including Initial State.
+ *
+ * `QuickSearchText` is the search restored at startup. `CellMatchStyle` highlights matching cells. `TextMatchStyle` and `CurrentTextMatchStyle` highlight the matching text inside a cell; those two styles are not available with the Server-Side Row Model.
  */
 export interface QuickSearchState extends BaseState {
     /**
@@ -13,13 +15,13 @@ export interface QuickSearchState extends BaseState {
      */
     CellMatchStyle?: Omit<AdaptableStyle, 'ClassName'>;
     /**
-     * Style used to highlight matching text within a cell (not availale in SSRM)
+     * Style used to highlight matching text within a cell (not available with the Server-Side Row Model)
      *
      * @defaultValue `var(--ab-color-quick-search-match)` background and `var(--ab-color-quick-search-match-foreground)` text
      */
     TextMatchStyle?: Omit<AdaptableStyle, 'ClassName'>;
     /**
-     * Style used to highlight matching text within current match (not availale in SSRM)
+     * Style used to highlight the current match within a cell (not available with the Server-Side Row Model)
      *
      * @defaultValue `var(--ab-color-quick-search-current-match)` background, `var(--ab-color-quick-search-current-match-foreground)` text, bold
      */

package/src/AdaptableState/Selection/GridCell.d.ts

@@ -1,15 +1,17 @@
 import { IRowNode } from 'ag-grid-enterprise';
 import { AdaptableColumn } from '../Common/AdaptableColumn';
 /**
- * Very lightweight object to define an AdapTable Cell
+ * A cell located by its primary key and column id.
+ *
+ * Used wherever AdapTable names one cell: Notes, Comments, highlights and other cell lookups.
  */
 export type CellAddress = {
     /**
-     * Value in Primary Key Column
+     * Value in the primary key column for the row.
      */
     PrimaryKeyValue: string | number;
     /**
-     * Id of Column containing the Note
+     * Column id of the cell.
      */
     ColumnId: string;
 };

package/src/AdaptableState/Selection/GridCellRange.d.ts

@@ -1,26 +1,27 @@
 /**
- * Defines a range of Cell - used in Grid Api Selection methods
- * Typically use either PrimaryKey Values or Row Indexes
+ * A rectangular cell selection passed to `selectCellRange`.
+ *
+ * `columnIds` is required. The rows are resolved from primary keys when `primaryKeyValueEnd` is set: the start row is `primaryKeyValueStart` and the end row is `primaryKeyValueEnd`. When `primaryKeyValueEnd` is omitted, both rows are resolved from `rowIndexStart` and `rowIndexEnd`. A range with only `primaryKeyValueStart` is resolved by row index. Omit `rowIndexEnd` and the range is the single start row.
  */
 export interface GridCellRange {
     /**
-     * Columns to select
+     * Column ids in the selection. Required.
      */
     columnIds: string[];
     /**
-     * Primary Key value of row at start of range
+     * Primary key of the first row. Used when `primaryKeyValueEnd` is set.
      */
     primaryKeyValueStart?: any;
     /**
-     * Primary Key value of row at end of range
+     * Primary key of the last row. When this is set, both row ends are resolved by primary key.
      */
     primaryKeyValueEnd?: any;
     /**
-     * Index of row at start of range
+     * Index of the first row. Used when `primaryKeyValueEnd` is omitted.
      */
     rowIndexStart?: any;
     /**
-     * Index of row at end of range
+     * Index of the last row. Used when `primaryKeyValueEnd` is omitted. When this is omitted too, the range is the single start row.
      */
     rowIndexEnd?: any;
 }

package/src/AdaptableState/Selection/SelectedCellInfo.d.ts

@@ -9,7 +9,7 @@ export interface SelectedCellInfo<TData = any> {
      */
     columns: AdaptableColumn<TData>[];
     /**
-     * Array of GridCells (which provide cell value, primary kev value and other info)
+     * Selected cells. Each entry has the cell value, the Primary Key value and the column. Empty when nothing is selected.
      */
     gridCells: GridCell<TData>[];
 }

package/src/AdaptableState/ShortcutState.d.ts

@@ -2,16 +2,20 @@ import { BaseState } from './BaseState';
 import { ColumnScope, NumberScopeDataType } from './Common/ColumnScope';
 import { SuspendableObject } from '../types';
 /**
- * Adaptable State Section for Shortcut Module
+ * Shortcut section of Adaptable State, including Initial State.
+ *
+ * Each shortcut updates a numeric cell while its editor is open and `ShortcutKey` is pressed. The cell value is the first operand and `ShortcutValue` is the second. `ShortcutOperation` is `'Add'`, `'Subtract'`, `'Multiply'` or `'Divide'`. The first shortcut whose key and scope match is used. A `ShortcutValue` of `0` is ignored.
  */
 export interface ShortcutState extends BaseState {
     /**
-     * Collection of Shortcuts - designed to speed up data entry
+     * Shortcuts to apply. Each one names numeric columns, a key, an operation and the second operand.
      */
     Shortcuts?: Shortcut[];
 }
 /**
- * Used to define a Shortcut as used in Shortcut State
+ * A key that updates a numeric cell with an arithmetic operation.
+ *
+ * `Scope` is numeric columns only. Pressing `ShortcutKey` sets the cell to `cellValue` combined with `ShortcutValue` by `ShortcutOperation`. Suspend with `IsSuspended`.
  */
 export interface Shortcut extends SuspendableObject {
     /**

package/src/AdaptableState/StatusBarState.d.ts

@@ -1,12 +1,13 @@
 import { BaseState } from '../types';
 import { AdaptableStatusBarPanel } from './Common/Types';
 /**
- * Adaptable State Section for the Adaptable Status Bar
+ * Status Bar section of Adaptable State, including Initial State.
+ *
+ * Each entry is one AG Grid status panel. Its `Key` must match `gridOptions.statusBar.statusPanels[].key`, and that panel's `statusPanel` must be `'AdaptableStatusPanel'`. AG Grid places the panel with `align`: `'left'`, `'center'` or `'right'`. When `StatusBars` is omitted, no AdapTable status bars are shown.
  */
 export interface StatusBarState extends BaseState {
     /**
-     * Adaptable Status Bars to display - can be unlimited and displayed in 3 locations
-     * @defaultValue null
+     * Status bars to show. Each `Key` matches an AG Grid `statusPanels` entry whose component is `AdaptableStatusPanel`.
      */
     StatusBars?: AdaptableStatusBar[];
 }
@@ -15,15 +16,15 @@ export interface StatusBarState extends BaseState {
  */
 export declare const ADAPTABLE_STATUS_PANEL = "AdaptableStatusPanel";
 /**
- * Defines an Adaptable Status Bar
+ * One AdapTable status bar, rendered inside an AG Grid status panel.
  */
 export interface AdaptableStatusBar {
     /**
-     * Key of Status Bar Panel as defined in AG Grid GridOptions - ensure keys are the same (note: AG Grid statusPanel is lowercase 'key')
+     * Must equal the `key` of an AG Grid `statusPanels` entry (AG Grid spells the property `key`). That entry's `statusPanel` is `'AdaptableStatusPanel'`.
      */
     Key: string;
     /**
-     * Module Status Panels to render inside Adaptable Status Bar
+     * AdapTable module panels drawn inside this status bar.
      */
     StatusBarPanels?: AdaptableStatusBarPanel[];
 }

package/src/AdaptableState/StyledColumnState.d.ts

@@ -10,60 +10,92 @@ import { RangeBarStyle } from './StyledColumns/RangeBarStyle';
 import { RatingStyle } from './StyledColumns/RatingStyle';
 import { SparklineStyle } from './StyledColumns/SparklineStyle';
 /**
- * Adaptable State Section for Styled Column Module
+ * Styled Column section of Adaptable State, including Initial State.
+ *
+ * Each entry replaces the normal cell rendering of one column with a single visual style.
  */
 export interface StyledColumnState extends BaseState {
     /**
-     * Collection of Styled Columns
+     * Styled Columns to apply. Each one names a column and sets exactly one style property.
      */
     StyledColumns?: StyledColumn[];
 }
 /**
- * Core Styled Column object
+ * One column drawn with a Styled Column.
+ *
+ * Set exactly one of `GradientStyle`, `PercentBarStyle`, `BulletChartStyle`, `RangeBarStyle`, `RatingStyle`, `IconStyle`, `BadgeStyle` or `SparklineStyle`. The Settings Panel edits them as alternatives and clears the others when the type changes.
+ *
+ * If a cell-renderer style is combined with another, AdapTable uses the first match in this order: Percent Bar, Bullet Chart, Range Bar, Rating, Icon, Badge, Sparkline. `GradientStyle` is the cell background rather than a replacement renderer, so it still paints when it is set.
+ *
+ * Suspend with `IsSuspended` (inherited from {@link SuspendableObject}). A suspended Styled Column is kept in state and is not drawn.
  */
 export interface StyledColumn extends SuspendableObject {
     /**
-     * Unique Name of Styled Column - used to identify it in Adaptable UI and APIs
+     * Name shown in the Settings Panel and used by `styledColumnApi` to find this definition.
+     *
+     * Unique among Styled Columns.
      */
     Name: string;
     /**
-     * Id of Column being styled
+     * `colId` of the column this style draws.
+     *
+     * AdapTable uses the first Styled Column with this `ColumnId`.
      */
     ColumnId: string;
     /**
-     * Which rows will render the Styled Column (data / group / summary total)
+     * Which row kinds draw the style: data (leaf) rows, group rows, summary rows and grand-total rows.
+     *
+     * Each `Exclude*` flag turns that kind off. When `RowScope` is omitted, Badge draws on every row kind and every other style draws on every kind except group rows.
+     *
+     * Sparkline ignores this for non-data rows: it only draws on leaf rows, because the cell value has to be the array of points.
      */
     RowScope?: RowScope;
     /**
-     * Styles a numeric column with a Gradient
+     * Numeric column. Tints the cell background by where the value sits in a range.
+     *
+     * The cell text stays. Set `CellRanges` for bands (a traffic-light scale), or `ZeroCentred` for a diverging colour either side of 0. `ColumnComparison` measures this cell against another column. `RangeValueType` is `Number` (the default) or `Percentage` (0–100).
      */
     GradientStyle?: GradientStyle;
     /**
-     * Styles a numeric column so each cell displays a 'Bar'
+     * Numeric column. Draws a bar whose length is the cell value on the column's scale.
+     *
+     * `CellRanges` colours the bar by which band the value falls in. `Origin` is where the bar grows from: `Auto` (the default), `Zero`, `Min`, or a fixed number. `ColumnComparison` measures the cell against another column.
      */
     PercentBarStyle?: PercentBarStyle;
     /**
-     * Displays a Sparkline Chart in an array column
+     * Numeric-array column. The cell value is the series, and AG Grid's sparkline renderer draws it.
+     *
+     * `options` is an AG Charts sparkline options object (`type: 'line'`, `'bar'`, `'area'` or `'column'`). Only leaf data rows are drawn.
      */
     SparklineStyle?: SparklineStyle;
     /**
-     * Displays cell values in Column as a Badge
+     * Any column. Draws the cell value as a pill. A `numberArray` or `textArray` column draws one pill per element; other array types are drawn as a single value.
+     *
+     * `Badges` is the list of pill definitions. A `Rule` is an AdapTableQL boolean expression, evaluated per cell (and per element on a number or text array). Rules are tried in list order and the first match wins. A badge with no `Rule` is the fallback when no rule matches; if several have no rule, the first of those is used. `Density`, `Spacing` and `OverflowMode` (`Truncate`, `Wrap` or `Scroll`) apply to the whole column.
      */
     BadgeStyle?: BadgeStyle;
     /**
-     * Styles a numeric column with single-row Bullet Chart, showing value as bar, target as marker and optional bands behind bar
+     * Numeric column. Draws a bullet chart in the cell: the value as a bar, a target as a marker, and optional qualitative bands behind the bar.
+     *
+     * `CellRanges` colours those background bands (poor / ok / good). They are not a colour switch for the bar itself, which is what Percent Bar uses `CellRanges` for. `TargetProperties` supplies the target. `Orientation` is `Horizontal` (the default) or `Vertical`; a vertical chart needs a tall row.
      */
     BulletChartStyle?: BulletChartStyle;
     /**
-     * Styles a numeric column as a Rating - row of icons filled according to cell value
+     * Numeric column. Draws a row of icons (stars by default) filled in proportion to the cell value.
+     *
+     * `Max` is both the number of icons and the top of the scale, in the same units as the cell value. The default is 5, so a value of 4 fills four of five stars. The value is clamped to `[0, Max]`. `AllowHalf` (the default) fills the boundary icon by the fraction; otherwise the value rounds to a whole icon. `Icon` is `Star`, `Heart`, `Circle` or `Thumb`.
      */
     RatingStyle?: RatingStyle;
     /**
-     * Styles a numeric column as Range Bar - track showing where cell value sits between Min and Max
+     * Numeric column. Draws a track from `Min` to `Max` and a marker at the cell value.
+     *
+     * `Min` and `Max` are required. Each can be a number, another column's `colId` (that row's value), or `Col-Min`, `Col-Max`, `Col-Avg` or `Col-Median` across the visible rows. `Reference` is an optional second marker (a target or a previous close). `CellRanges` draws background bands on the track.
      */
     RangeBarStyle?: RangeBarStyle;
     /**
-     * Styles a column where each cell displays an icon looked up from a list of key → icon mappings
+     * Scalar column. Looks the cell value up in `Mappings` (and an optional `Preset`) and draws the matching icon.
+     *
+     * Array columns are not supported; use `BadgeStyle` to draw one glyph per array element. `Preset` is `Flags`, `Currencies`, `Trend` or `Status`. `MatchMode` is `Exact` (the default) or `CaseInsensitive`. When nothing matches, `FallbackProperties.Mode` is `Hide` (the default), `ShowText` or `Icon`.
      */
     IconStyle?: IconStyle;
 }

package/src/AdaptableState/TeamSharingState.d.ts

@@ -138,18 +138,35 @@ export interface CustomSharedEntity<T = any> {
     Tags?: AdaptableObjectTag[];
 }
 /**
- * Defines Objects which have been imported into Team Sharing
+ * How one module imports a shared object.
+ *
+ * Used while a Team Share is applied. It is not part of Initial State. `ModuleEntities` are the objects already in that module. `AddAction` adds an imported object. `EditAction` updates an existing one.
  */
 export interface TeamSharingImportInfo<T extends AdaptableObject> {
+    /**
+     * Objects of this module that are already in local state.
+     */
     ModuleEntities: T[];
+    /**
+     * Action creator that adds one imported object.
+     */
     AddAction: (entity: T) => any;
+    /**
+     * Action creator that updates one imported object.
+     */
     EditAction: (entity: T) => any;
 }
 /**
  * Describes an AdaptableObject which is being Team Shared
  */
 export interface AdaptableSharedEntityConfig {
+    /**
+     * Description stored on the shared object.
+     */
     description: string;
+    /**
+     * `Snapshot` shares the object once (`Revision` stays 1). `Active` keeps it linked and increases `Revision` when the object changes.
+     */
     type: SharedEntityType;
 }
 /**
@@ -174,15 +191,42 @@ export interface CustomSharedEntityConfig {
     Tags?: AdaptableObjectTag[];
 }
 /**
- * Type of Shared Entity - Snapshot or Active
+ * How a Team Share behaves.
+ *
+ * `Snapshot` is a one-time copy (`Revision` stays 1). `Active` stays linked to the original and its `Revision` increases when that object changes.
  */
 export type SharedEntityType = 'Snapshot' | 'Active';
+/**
+ * One shared object and the Redux action that imports it.
+ *
+ * Produced while an import is running. It is not part of Initial State.
+ */
 export interface TeamSharingImportStep {
+    /**
+     * Shared AdapTable object being imported.
+     */
     sharedEntity: AdaptableSharedEntity;
+    /**
+     * Redux action that applies this object to local state.
+     */
     importAction: Redux.Action;
 }
+/**
+ * Active shares whose remote revision is newer than the revision last applied locally.
+ *
+ * Keyed by the shared entity `Uuid`. Session data used to decide whether to show an update. It is not part of Initial State.
+ */
 export type SharedEntityActiveStatus = Record<TypeUuid, {
+    /**
+     * The remote shared object.
+     */
     sharedEntity: AdaptableSharedEntity;
+    /**
+     * Revision of the copy last applied locally.
+     */
     importedRevision: number;
+    /**
+     * Revision currently on the shared object.
+     */
     sharedRevision: number;
 }>;

package/src/AdaptableState/ThemeState.d.ts

@@ -6,11 +6,13 @@ import { TypeHint } from './Common/Types';
  */
 export type SystemThemeName = TypeHint<string, 'light' | 'dark' | 'os'>;
 /**
- * Theme section of Adaptable State
+ * Theme section of Adaptable State, including Initial State.
+ *
+ * `CurrentTheme` is `'light'` (the default), `'dark'`, or `'os'`. `SystemThemes` limits which shipped themes are offered. Omit it to offer all of them.
  */
 export interface ThemeState extends BaseState {
     /**
-     * Name of current Theme or theme set at startup; leave blank if using 'Light Theme', set to 'dark' for 'Dark Theme'
+     * Shipped theme that is active: `'light'`, `'dark'`, or `'os'` (follows the operating system). When omitted, the theme is `'light'`.
      */
     CurrentTheme?: SystemThemeName;
     /**
@@ -53,10 +55,30 @@ export type SystemThemeEntry = SystemThemeName | SystemThemeOptions;
  * @deprecated User-defined themes are deprecated; customise shipped themes via CSS variables and use SystemThemeOptions for AG Grid pairing
  */
 export interface AdaptableTheme extends AdaptableObject {
+    /**
+     * Theme name. For a shipped theme this is `light`, `dark` or `os`.
+     */
     Name: string;
+    /**
+     * Text shown for this theme in the theme list.
+     */
     Description: string;
+    /**
+     * CSS class of a legacy AG Grid theme.
+     *
+     * @deprecated Unused with the AG Grid Theming API. Pair a shipped theme with an AG Grid mode via {@link SystemThemeOptions.AgThemeMode}.
+     */
     AgGridClassName?: string;
+    /**
+     * CSS variables this theme sets, keyed by variable name (for example `--ab-color-primary`).
+     */
     CSSVariables?: Record<string, string>;
+    /**
+     * Whether the theme is a light or dark palette. Used when AdapTable picks contrasting UI colours.
+     */
     Variant?: 'light' | 'dark';
+    /**
+     * AG Grid theme mode applied with this theme: `light`, `dark`, `dark-blue`, or a custom mode defined in AG Grid.
+     */
     AgThemeMode?: TypeHint<string, 'light' | 'dark' | 'dark-blue'>;
 }

package/src/AdaptableState/ToolPanelState.d.ts

@@ -1,12 +1,15 @@
 import { BaseState } from './BaseState';
 import { AdaptableModuleButtons, AdaptableToolPanel } from './Common/Types';
 /**
- * Adaptable State Section for the AdapTable ToolPanel
+ * Tool Panel section of Adaptable State, including Initial State.
+ *
+ * `ToolPanels` is the list of panels and whether each is expanded or collapsed. When it is omitted, AdapTable shows a collapsed panel for every module and for every custom tool panel. `ModuleButtons` are the shortcut buttons in the tool panel; the default is an empty list.
  */
 export interface ToolPanelState extends BaseState {
     /**
-     * Adaptable Tool Panels which are viaible
-     * @defaultValue ToolPanels for all available Modules (subject to Entitlement rules)
+     * Tool panels to show, and whether each is expanded or collapsed.
+     *
+     * When omitted, every module and every custom tool panel is included, collapsed.
      */
     ToolPanels?: AdaptableToolPanelDefinition[];
     /**
@@ -16,7 +19,9 @@ export interface ToolPanelState extends BaseState {
     ModuleButtons?: AdaptableModuleButtons;
 }
 /**
- * Defines a ToolPanel - Name and VisibilityMode (Expanded / Collapsed)
+ * One tool panel.
+ *
+ * `Name` is an AdapTable module or a custom panel from Tool Panel Options. `VisibilityMode` is `'expanded'` (the panel body is open) or `'collapsed'` (only the header is shown). The default is `'collapsed'`.
  */
 export interface AdaptableToolPanelDefinition {
     /**
@@ -24,7 +29,7 @@ export interface AdaptableToolPanelDefinition {
      */
     Name: AdaptableToolPanel | string;
     /**
-     * Whether the ToolPanel is 'expanded' or 'collapsed'
+     * `'expanded'` shows the panel body. `'collapsed'` shows only the header.
      * @defaultValue 'collapsed'
      */
     VisibilityMode?: 'expanded' | 'collapsed';

package/src/AdaptableState/UserInterfaceState.d.ts

@@ -1,8 +1,8 @@
 import { BaseState } from './BaseState';
 /**
- * Adaptable State Section for the User Interface
+ * User Interface section of Adaptable State, including Initial State.
  *
- * Controls the visibility and behaviour of AdapTable UI elements
+ * `HideAdaptableUI` hides the Dashboard, Tool Panel, Status Bar, and the column and context menus. The default is false.
  */
 export interface UserInterfaceState extends BaseState {
     /**

package/src/AdaptableState/Uuid.d.ts

@@ -1,2 +1,8 @@
+/**
+ * UUID string used as the identity of an AdapTable object.
+ */
 export type TypeUuid = string;
+/**
+ * Creates a new UUID string.
+ */
 export declare const createUuid: () => TypeUuid;

package/src/Api/ActionColumnApi.d.ts

@@ -1,15 +1,17 @@
 import { ActionColumn } from '../../types';
 /**
- * Functions for accessing Action Columns
+ * The Action Columns in the grid, looked up together or by column id.
  */
 export interface ActionColumnApi {
     /**
      * Retrieves the Action Columns provided in Action Column Options
+     * @returns The Action Columns provided in Action Column Options
      */
     getActionColumns(): ActionColumn[];
     /**
      * Returns Action Column with given Id
      * @param columnId id of Action Column
+     * @returns Action Column with given Id
      */
     getActionColumnForColumnId(columnId: string): ActionColumn | undefined;
 }