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

package/src/AdaptableOptions/UserInterfaceOptions.d.ts

@@ -1,4 +1,5 @@
 import { AdaptableIcon } from '../AdaptableState/Common/AdaptableIcon';
+import { AdaptableModule } from '../AdaptableState/Common/Types';
 import { DateInputOptions } from './DateInputOptions';
 import { AdaptableObjectTag } from '../AdaptableState/Common/AdaptableObject';
 import { AdaptableStyle } from '../AdaptableState/Common/AdaptableStyle';
@@ -29,6 +30,10 @@ export interface UserInterfaceOptions<TData = any> {
      *
      */
     dateInputOptions?: DateInputOptions;
+    /**
+     * Options for the Colour Picker, including which colours to display
+     */
+    colourPickerOptions?: ColourPickerOptions;
     /**
      * Style to set for editable Cells
      */
@@ -80,7 +85,6 @@ export interface UserInterfaceOptions<TData = any> {
     /**
      * Hides confirmation dialog which displays whenever an AdaptableObject is deleted
      * @defaultValue false
-     * @noCodeItem
      */
     disableDeleteConfirmation?: boolean;
     /**
@@ -109,7 +113,6 @@ export interface LoadingScreenOptions<TData = any> {
     /**
      * Display Loading Screen when AdapTable initialises
      * @defaultValue true
-     * @noCodeItem
      */
     showLoadingScreen?: boolean;
     /**
@@ -130,6 +133,88 @@ export interface LoadingScreenOptions<TData = any> {
      */
     loadingScreenText?: string;
 }
+/**
+ * Options for the Colour Picker.
+ */
+export interface ColourPickerOptions {
+    /**
+     * Colour Picker tabs to display in order provided; `Custom`, `Palette`, or both
+     *
+     * @defaultValue ['Custom', 'Palette']
+     */
+    tabs?: ColourPickerTab[];
+    /**
+     * Orders Palette swatches around the colour wheel; if `false`, each colour stays the order supplied
+     *
+     * @defaultValue true
+     */
+    orderPaletteColours?: boolean;
+    /**
+     * Leave out duplicates of swatches already displayed
+     *
+     * @defaultValue true
+     */
+    removeDuplicates?: boolean;
+    /**
+     * Chooses which of the supplied colours (theme & colour palette) the Palette tab shows
+     */
+    filterColours?: (context: ColourPickerFilterContext) => ColourPickerFilterResult | void;
+    /**
+     * Show **Theme** and **Palette** headings on the Palette tab (if both have colours)
+     *
+     * @defaultValue false
+     */
+    showGroupLabels?: boolean;
+}
+/**
+ * Colour Picker tabs: `Custom` is free colour picker, `Palette` is list of swatches
+ */
+export type ColourPickerTab = 'Custom' | 'Palette';
+/**
+ * A colour the Colour Picker can offer. `value` is what gets stored
+ */
+export interface ColourPickerColour {
+    /**
+     * The CSS value that gets stored, e.g. `var(--ab-color-success)`.
+     */
+    value: string;
+    /** The name shown for the colour, e.g. "Success" or "Palette 3". */
+    label: string;
+    /**
+     * The colour as the active theme paints it
+     */
+    hex?: string;
+}
+/**
+ * Colours available when Colour Picker opens, and module being edited.
+ */
+export interface ColourPickerFilterContext {
+    /**
+     * Available Theme colours
+     */
+    themeColours: ColourPickerColour[];
+    /**
+     * Available Palette colours
+     */
+    paletteColours: ColourPickerColour[];
+    /**
+     * Module being edited
+     */
+    module?: AdaptableModule;
+}
+/**
+ * Colours to show - must be in list provided (otherwise ignored)
+ */
+export interface ColourPickerFilterResult {
+    /**
+     * Theme colours to keep. A colour not in the supplied list is ignored.
+     */
+    themeColours: ColourPickerColour[];
+    /**
+     * Palette colours to keep. A colour not in the supplied list is ignored.
+     */
+    paletteColours: ColourPickerColour[];
+}
 /**
  * Context used when evaluating Object Tags
  */

package/src/AdaptableState/AdaptableState.d.ts

@@ -25,47 +25,141 @@ import { NamedQueryState } from './NamedQueryState';
 import { CommentState } from './CommentState';
 import { UserInterfaceState } from './UserInterfaceState';
 /**
- * The main state object of Adaptable
+ * Full AdapTable State in the store: the persisted sections plus the sections that are never saved.
+ *
+ * {@link AdaptablePersistentState} is what `loadState` / `saveState` round-trip, and what `InitialState` seeds.
+ * {@link AdaptableTransientState} exists only for the current session.
+ *
+ * Each section has its own `Revision`. When a later Initial State has a higher Revision for a section, that section is replaced (`Override`) or merged so user-created objects are kept (`KeepUserDefined`). See {@link BaseState.Revision}.
  */
 export interface AdaptableState extends AdaptablePersistentState, AdaptableTransientState {
     [s: string]: BaseState;
 }
 /**
- * The state object of Adaptable which is persisted
+ * AdapTable State that is persisted.
+ *
+ * This is the object passed to `stateOptions.loadState`, `saveState`, `persistState` and `applyState`.
+ * Supply the same section names in `InitialState`. Initial State is applied only when nothing has been persisted yet for this grid; after that, raising a section's `Revision` is how a new Initial State updates that section.
  *
- * This is the state shape handled by all `StateOptions` functions (`saveState`, `persistState`, `loadState`, `applyState`)
+ * `TeamSharing` is persisted, but it is not part of Initial State. Shares are created at run time.
  */
 export interface AdaptablePersistentState {
+    /**
+     * Developer-owned key/value entries, stored with the rest of AdapTable State.
+     *
+     * Set from Initial State. There is no UI for editing these entries.
+     */
     Application: ApplicationState;
+    /**
+     * Alert definitions. Each rule, schedule or data-change alert fires when its condition is met.
+     */
     Alert: AlertState;
+    /**
+     * Calculated Columns. Each column's `Expression` is evaluated to produce the cell value.
+     */
     CalculatedColumn: CalculatedColumnState;
+    /**
+     * Named charts. Each definition wraps an AG Chart model.
+     */
     Charting: ChartingState;
+    /**
+     * Custom Sorts. A column listed here sorts by the given value order instead of the default comparison.
+     */
     CustomSort: CustomSortState;
+    /**
+     * Dashboard: tabs, which toolbars are on each tab, and whether the Dashboard is collapsed, floating or hidden.
+     */
     Dashboard: DashboardState;
+    /**
+     * Reports and report schedules used by Export.
+     */
     Export: ExportState;
+    /**
+     * Flashing Cell rules. Matching cells or rows flash when their data changes.
+     */
     FlashingCell: FlashingCellState;
+    /**
+     * Format Columns: styles and display formats, applied to a column scope, optionally when a `Rule` is true.
+     */
     FormatColumn: FormatColumnState;
+    /**
+     * Free Text Columns. Cell values are stored here, not in the grid's data source.
+     */
     FreeTextColumn: FreeTextColumnState;
+    /**
+     * Layouts: column visibility, order, sizing, sorting, grouping, aggregations, filters and the current Layout.
+     *
+     * Initial State must include a Layout unless `layoutOptions.autoCreateLayout` creates one.
+     */
     Layout: LayoutState;
+    /**
+     * Named Queries. An expression saved here can be referred to by name from other modules.
+     */
     NamedQuery: NamedQueryState;
+    /**
+     * Cell Notes. A Note is one piece of text on a cell, separate from Comments and from Free Text Columns.
+     */
     Note: NoteState;
+    /**
+     * Plus Minus nudges. Each nudge names a column and how much `+` / `-` (or a custom shortcut) changes the cell.
+     */
     PlusMinus: PlusMinusState;
+    /**
+     * Quick Search text, and whether matches are highlighted or non-matching rows are filtered out.
+     */
     QuickSearch: QuickSearchState;
+    /**
+     * Keyboard shortcuts that write a value into the edited cell, used to speed up entry and block mistyped values.
+     */
     Shortcut: ShortcutState;
+    /**
+     * Status Bar panels and the order they appear in.
+     */
     StatusBar: StatusBarState;
+    /**
+     * Styled Columns: badges, bars, sparklines, gradients and the other cell renderers that are not a Format Column.
+     */
     StyledColumn: StyledColumnState;
+    /**
+     * Team Sharing entities. Persisted, but not supplied in Initial State.
+     *
+     * `Snapshot` is a one-time copy. `Active` stays linked and its `Revision` increases when the shared object changes.
+     */
     TeamSharing: TeamSharingState;
+    /**
+     * Current theme (`light`, `dark` or `os`) and which shipped themes are offered.
+     */
     Theme: ThemeState;
+    /**
+     * Tool Panel: which module controls are visible and their order.
+     */
     ToolPanel: ToolPanelState;
+    /**
+     * Which AdapTable UI surfaces are shown: Dashboard, Tool Panel, Status Bar, column menu, context menu and the rest.
+     */
     UserInterface: UserInterfaceState;
 }
 /**
- * The state which is available in the internal Redux store but never persisted
+ * AdapTable State that is never persisted and is not part of Initial State.
  */
 export interface AdaptableTransientState {
+    /**
+     * Session bookkeeping: current selection, in-flight module data and similar runtime fields.
+     */
     Internal: InternalState;
+    /**
+     * Which popup or form is open.
+     */
     Popup: PopupState;
+    /**
+     * Comment threads for this session.
+     *
+     * Comments are not in the persisted snapshot. Load them with `commentOptions.loadCommentThreads` and save them with `commentOptions.persistCommentThreads`.
+     */
     Comment: CommentState;
+    /**
+     * State owned by plugins, keyed by plugin id (for example ipushpull and OpenFin session data).
+     */
     Plugins: {
         [key: string]: any;
     };

package/src/AdaptableState/AlertState.d.ts

@@ -9,23 +9,24 @@ import { ButtonStyle } from './Common/ButtonStyle';
 import { Schedule } from './Common/Schedule';
 import { AlertFormContext, BaseContext, NotificationsOptions, SuspendableObject } from '../types';
 /**
- * Adaptable State section for Alert Module
+ * Alert section of Adaptable State, including Initial State.
+ *
+ * Each definition fires when its condition is met. A rule-based alert sets `Scope` and `Rule`. A row-change alert sets `RowChangeTrigger` (`'Added'` or `'Removed'`). A scheduled alert sets `Schedule` and has no rule. `MessageType` sets the colour and icon. `MessageHeader` is the title and `MessageText` is the body.
  */
 export interface AlertState extends BaseState {
     /**
-     * Alert Definitions - will trigger Alerts when rule is met
+     * Alerts to evaluate. Each one is a rule-based alert (`Scope` + `Rule`), a row-change alert (`RowChangeTrigger`), or a scheduled alert (`Schedule`).
      */
     AlertDefinitions?: AlertDefinition[];
 }
 /**
- * Wizard / evaluation category for an Alert Definition.
+ * Category of an Alert Definition, stored on {@link AlertDefinitionBase.Type}.
  *
- * Persisted on {@link AlertDefinitionBase.Type}. When absent (legacy state),
- * inferred from Rule / Schedule shape via migration and runtime fallback.
+ * When `Type` is omitted it is inferred: a `Schedule` is `Scheduled`, a `RowChangeTrigger` is `RowChange`, and a `Rule` is `DataChange`, `RelativeChange`, `Validation`, `Aggregation` or `Observable` from the expression.
  */
 export type AlertType = 'DataChange' | 'RelativeChange' | 'Validation' | 'RowChange' | 'Aggregation' | 'Observable' | 'Scheduled';
 /**
- * Runtime constants matching {@link AlertType} (replaces the previous View-layer enum).
+ * Runtime constants matching {@link AlertType}.
  */
 export declare const AlertType: {
     readonly DataChange: "DataChange";
@@ -38,7 +39,9 @@ export declare const AlertType: {
 };
 export declare const ALERT_TYPES: readonly AlertType[];
 /**
- * Fields shared by all alert definitions
+ * Fields every alert definition has.
+ *
+ * `Name` identifies the alert. `MessageType` is required and sets the colour, icon and log level (`'Info'`, `'Success'`, `'Warning'` or `'Error'`). `MessageHeader` is the notification title. `MessageText` is the body. Suspend with `IsSuspended`.
  */
 export interface AlertDefinitionBase extends SuspendableObject {
     /**
@@ -46,9 +49,7 @@ export interface AlertDefinitionBase extends SuspendableObject {
      */
     Name: string;
     /**
-     * Alert category (Data Change, Relative Change, Validation, etc.).
-     * Optional for one release so legacy InitialState migrates via VersionUpgrade24;
-     * when omitted, inferred from Rule / Schedule.
+     * Alert category. When omitted, inferred from `Rule` or `Schedule`. See {@link AlertType}.
      */
     Type?: AlertType;
     /**
@@ -60,7 +61,9 @@ export interface AlertDefinitionBase extends SuspendableObject {
      */
     MessageHeader?: string;
     /**
-     * Title of displayed Alert Message; if null, AdapTable creates dynamically using Rule & Scope
+     * Body of the displayed alert. The title is {@link AlertDefinitionBase.MessageHeader}.
+     *
+     * Tokens such as the column and the old and new values are substituted when the alert fires. When omitted, a rule-based alert uses the scope and the rule, and a row-change alert uses a count of the rows that were added or removed. `alertOptions.alertMessageText` overrides this text when it returns a string.
      */
     MessageText?: string;
 }
@@ -112,9 +115,7 @@ export interface AlertTriggerPolicy {
 /**
  * Alert that fires when a row is added to or removed from the grid.
  *
- * Replaces the legacy observable `ROW_ADDED{}` / `ROW_REMOVED{}` rules: one Alert per
- * row event, with an optional per-row {@link RowChangeAlertDefinition.Rule}
- * (`[make] = 'Toyota'`) evaluated on the added / removed row.
+ * Set `Type` to `'RowChange'` and `RowChangeTrigger` to `'Added'` or `'Removed'`. `Scope` is `{ All: true }`. `Rule` is an optional per-row boolean expression (`[make] = 'Toyota'`); when it is omitted every matching row event fires.
  */
 export interface RowChangeAlertDefinition extends AlertDefinitionBase {
     Type: 'RowChange';
@@ -167,9 +168,7 @@ export type AlertDefinition = RuleBasedAlertDefinition | RowChangeAlertDefinitio
  */
 export type GridAlertDefinition = RuleBasedAlertDefinition | RowChangeAlertDefinition;
 /**
- * Row Change Alert in its current shape (`RowChangeTrigger`). Pre-v24
- * `Type: 'RowChange'` definitions with a `ROW_ADDED{}` rule and no trigger
- * are not matched: `VersionUpgrade24` rewrites them on load.
+ * True when the alert is a Row Change alert: `Type` is `'RowChange'` and `RowChangeTrigger` is set.
  */
 export declare const isRowChangeAlertDefinition: (alertDefinition: AlertDefinition | undefined | null) => alertDefinition is RowChangeAlertDefinition;
 /**
@@ -217,11 +216,11 @@ export interface AlertPresentationProperties {
      */
     DisplayNotification?: boolean;
     /**
-     * Notifiction duration(defaults to `NotificationOptions.duration`)
+     * How long the notification stays visible. When omitted, `notificationsOptions.duration` is used.
      */
     NotificationDuration?: NotificationsOptions['duration'];
     /**
-     * Shows Alert text in the div specificed in `alertContainer` property of Container Options
+     * Shows the alert text in the element named by `containerOptions.alertContainer`
      */
     ShowInDiv?: boolean;
     /**
@@ -238,11 +237,11 @@ export interface AlertPresentationProperties {
  */
 export interface RuleAlertProperties extends AlertPresentationProperties {
     /**
-     * Colours updated Row using `MessageType` of triggering Alert Definition
+     * Colours the cell that triggered the alert. `true` uses the colour for `MessageType`. An {@link AdaptableStyle} is applied instead of that colour.
      */
     HighlightCell?: boolean | AdaptableStyle;
     /**
-     * Colours updated Row using `MessageType` of triggering Alert Definition
+     * Colours the row that triggered the alert. `true` uses the colour for `MessageType`. An {@link AdaptableStyle} is applied instead of that colour.
      */
     HighlightRow?: boolean | AdaptableStyle;
     /**

package/src/AdaptableState/ApplicationState.d.ts

@@ -1,7 +1,9 @@
 import { BaseState } from './BaseState';
 /**
- * Adaptable State Section for the Application Module
- **/
+ * Application section of Adaptable State, including Initial State.
+ *
+ * A place to store your own key/value data with the rest of AdapTable State. There is no Application UI. Each `Value` must be stringifiable, because the section is persisted.
+ */
 export interface ApplicationState extends BaseState {
     /**
      * Array of Key / Value pairs enabling custom data to be stored in Adaptable State.
@@ -17,7 +19,7 @@ export interface ApplicationDataEntry {
      */
     Key: string;
     /**
-     * Value of Key / Value pair (actual data being stored) - needs to stringifiable
+     * Value stored for `Key`. It must be stringifiable, because it is saved with the rest of AdapTable State.
      */
     Value: any;
 }

package/src/AdaptableState/BaseState.d.ts

@@ -1,9 +1,16 @@
 /**
- * Base Interface for all Adaptable State objects; contains`Revision` property, used for versioning
+ * Base of every AdapTable State section.
+ *
+ * `Revision` is how a newer Initial State updates one section without touching the others.
  */
 export interface BaseState {
     /**
-     * Version number of the Item - allows developers to update one section in Initial Adaptable State while keeping others unchanged
+     * Version of this section.
+     *
+     * A number, or `{ Key, UpdateStrategy }`. AdapTable compares `Key` (or the number) with the Revision already persisted for this section. When the Initial State key is higher, the section is updated:
+     *
+     * - `Override` (the default) replaces the persisted section with the Initial State section.
+     * - `KeepUserDefined` applies the Initial State section, then appends objects the user added (their `Source` is not `InitialState`) back onto each array.
      */
     Revision?: number | {
         Key: number;

package/src/AdaptableState/CalculatedColumnState.d.ts

@@ -4,20 +4,24 @@ import { expressionContainsAggregation, expressionContainsObservableCall, type E
 import { SpecialColumnSettings } from './Common/SpecialColumnSettings';
 export { expressionContainsAggregation, expressionContainsObservableCall };
 /**
- * Adaptable State Section for Calculated Column Module
- **/
+ * Calculated Column section of Adaptable State, including Initial State.
+ *
+ * Each entry adds a column whose cells are the result of an AdapTableQL expression. The column is not in the grid data source. `ColumnId` is the id of the column AdapTable creates. `CalculatedColumnSettings.DataType` is required. `Type` can be omitted; it is inferred from the expression.
+ */
 export interface CalculatedColumnState extends BaseState {
     /**
-     * Collection of Calculated Columns
+     * Calculated Columns to add. `ColumnId` is the id of the column AdapTable creates.
      */
     CalculatedColumns?: CalculatedColumn[];
 }
 /**
- *  Defines a Column where value is derived from other values in row, and the definition is stored in State
+ * A column whose value is an AdapTableQL expression, stored in Adaptable State.
+ *
+ * `ColumnId` is the id of the new column. `Expression` is required. `CalculatedColumnSettings.DataType` is required and is the type AdapTable uses for filters and expressions. `Type` is optional and is inferred from the expression: a per-row expression is `Standard`, an expression that reads change history is `Observable`, and an aggregation, cumulative, quantile or window expression is evaluated over rows.
  */
 export interface CalculatedColumn extends AdaptableObject {
     /**
-     * Name of Calculated Column
+     * Id of the column AdapTable creates. It is not the id of a column already in the data source.
      */
     ColumnId: string;
     /**
@@ -108,9 +112,7 @@ export declare const supportsCompactExpressionEditor: (calculatedColumn: Pick<Ca
  * evaluation follows the expression's {@link ExpressionKind} — see
  * {@link expressionKindForCalculatedColumnType}.
  *
- * Persisted on {@link CalculatedColumn.Type}. When absent (legacy state),
- * inferred from {@link CalculatedColumn.Expression} via
- * {@link inferCalculatedColumnTypeFromExpression}.
+ * Stored on {@link CalculatedColumn.Type}. When `Type` is omitted it is inferred from {@link CalculatedColumn.Expression}.
  */
 export type CalculatedColumnType = 'Standard' | 'Observable' | 'Aggregated' | 'Cumulative' | 'Quantile' | 'Window';
 export declare const CALCULATED_COLUMN_TYPES: readonly CalculatedColumnType[];

package/src/AdaptableState/ChartingState.d.ts

@@ -4,8 +4,9 @@ import { BaseState } from './BaseState';
 export declare const isExternalChartDefinition: (chartDefinition: ChartDefinition | ExternalChartDefinition) => chartDefinition is ExternalChartDefinition;
 export declare const isAgChartDefinition: (chartDefinition: ChartDefinition | ExternalChartDefinition) => chartDefinition is ChartDefinition;
 /**
- * Wraps external chart definitions
- * Can be used to store charts in Adaptable State
+ * A chart stored by the application, not an AG Grid chart.
+ *
+ * Distinguished from {@link ChartDefinition} by `Data` (an AG Grid chart has `Model` instead). `Name` must not match an AG Grid chart name. `IsPersisted` defaults to true, which keeps the chart in Adaptable State.
  */
 export interface ExternalChartDefinition<T = unknown> extends AdaptableObject {
     /**
@@ -23,7 +24,9 @@ export interface ExternalChartDefinition<T = unknown> extends AdaptableObject {
     IsPersisted?: boolean;
 }
 /**
- * Wraps an AG Grid Chart Model
+ * An AG Grid chart saved in Adaptable State.
+ *
+ * Distinguished from {@link ExternalChartDefinition} by `Model`. `Name` is unique and is how a layout opens the chart.
  */
 export interface ChartDefinition extends AdaptableObject {
     /**
@@ -36,7 +39,9 @@ export interface ChartDefinition extends AdaptableObject {
     Model: ChartModel;
 }
 /**
- * Persists AG Grid Charts in Adaptable State
+ * Charting section of Adaptable State, including Initial State.
+ *
+ * `ChartDefinitions` are AG Grid charts (`Name` + `Model`). `ExternalChartDefinitions` are application charts (`Name` + `Data`). A layout opens a saved chart by name.
  */
 export interface ChartingState extends BaseState {
     /**
@@ -49,6 +54,6 @@ export interface ChartingState extends BaseState {
     ExternalChartDefinitions?: ExternalChartDefinition<unknown>[];
 }
 /**
- * Aggregation function used in the Chart
+ * Aggregation used when a chart summarises a numeric column: `sum`, `min`, `max`, `count`, `avg`, `first` or `last`.
  */
 export type ChartingAggFunc = 'sum' | 'min' | 'max' | 'count' | 'avg' | 'first' | 'last';

package/src/AdaptableState/CommentState.d.ts

@@ -1,16 +1,20 @@
 import { CellAddress, BaseState } from '../types';
 import { TypeUuid } from './Uuid';
 /**
- * Internal State used for Comments Module
+ * Comment threads for the current session.
+ *
+ * This section is not persisted and is not part of Initial State. Load threads with `commentOptions.loadCommentThreads` and save them with `commentOptions.persistCommentThreads`.
  */
 export interface CommentState extends BaseState {
     /**
-     * Collection of AdapTable Comments
+     * Comment threads for this session. Each thread belongs to one cell (`PrimaryKeyValue` and `ColumnId`) and holds its `Comments` in order.
      */
     CommentThreads?: CommentThread[];
 }
 /**
- * Comment that can be applied to a Cell in AdapTable
+ * One comment in a cell's thread.
+ *
+ * `Value` is the text. `Timestamp` is when it was written. `Author.UserName` is who wrote it. `Uuid` identifies the comment.
  */
 export interface AdaptableComment {
     /**
@@ -37,7 +41,9 @@ export interface AdaptableComment {
     AdaptableId?: string;
 }
 /**
- * Thread of Comments for an Adaptable Cell
+ * Every comment on one cell.
+ *
+ * The cell is `PrimaryKeyValue` plus `ColumnId` (from `CellAddress`). `Comments` is the thread, in order.
  */
 export interface CommentThread extends CellAddress {
     /**

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

@@ -3,11 +3,15 @@ import { CellDataChangedInfo } from './CellDataChangedInfo';
 import { AlertDefinition } from '../AlertState';
 import { RowDataChangedInfo } from './RowDataChangedInfo';
 /**
- * Defines an Alert fired by AdapTable
+ * An alert that has fired.
+ *
+ * This is the runtime alert, not the {@link AlertDefinition} that defines the rule. `alertType` is `'cellChanged'`, `'rowChanged'` or `'generic'`. `header` is the title and `message` is the body. `alertDefinition` is the rule.
  */
 export type AdaptableAlert<TData = any> = AdaptableCellChangedAlert<TData> | AdaptableRowChangedAlert<TData> | AdaptableGenericAlert;
 /**
- * Type of AdapTable Alert: generic, cellChange or rowChange
+ * Kind of a fired alert: `'generic'`, `'cellChange'` or `'rowChange'`.
+ *
+ * The `alertType` field on a fired alert uses `'cellChanged'` and `'rowChanged'` for the last two.
  */
 export type AdaptableAlertType = 'generic' | 'cellChange' | 'rowChange';
 /**

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

@@ -3,7 +3,9 @@ import { Identifiable } from './AdaptableObject';
 import { AdaptableIcon } from './AdaptableIcon';
 import { BaseContext } from '../../types';
 /**
- * Defines a Button that appears in numerous places including Adaptable Form
+ * A button on a form, alert or toolbar.
+ *
+ * `label` is the text. `onClick` runs when it is clicked and receives the button and the form or event context. `buttonStyle` and `icon` are optional. `disabled` and `hidden` are functions that return whether the button is disabled or hidden.
  */
 export interface AdaptableButton<CONTEXT_TYPE extends BaseContext> extends Identifiable {
     /**

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

@@ -7,7 +7,9 @@ import { ColumnFilter } from './ColumnFilter';
  */
 export type AdaptableColumnDataType = 'text' | 'number' | 'boolean' | 'date' | 'object' | 'textArray' | 'numberArray' | 'tupleArray' | 'objectArray' | 'groupColumn' | 'unknown';
 /**
- * Column Types recognised by AdapTable; to be set in GridOptions
+ * Column types AdapTable assigns.
+ *
+ * `'calculatedColumn'`, `'freeTextColumn'`, `'actionColumn'` and `'fdc3Column'` mark columns AdapTable created. `'hiddenColumn'` is kept out of the grid. The `pivot*Total` names mark pivot total columns.
  */
 export type AdaptableColumnTypeName = 'hiddenColumn' | 'calculatedColumn' | 'freeTextColumn' | 'actionColumn' | 'fdc3Column' | 'pivotAnyTotal' | 'pivotGrandTotal' | 'pivotColumnTotal' | 'pivotAggregationTotal';
 export declare const HIDDEN_COLUMN_TYPE: AdaptableColumnTypeName;
@@ -212,19 +214,54 @@ export interface AdaptableColumn<TData = any> extends AdaptableColumnBase {
 /**
  * Key properties of a Column (used in Layout Editor)
  */
+/**
+ * What a column allows, as shown in the Layout editor.
+ *
+ * Each flag is read from the column. `true` means that action is available.
+ */
 export interface AdaptableColumnProperties {
+    /**
+     * Whether the column can be sorted.
+     */
     sortable: boolean;
+    /**
+     * Whether the column can be filtered.
+     */
     filterable: boolean;
+    /**
+     * Whether the column can be dragged to a new position.
+     */
     moveable: boolean;
+    /**
+     * Whether the column can be row-grouped.
+     */
     groupable: boolean;
+    /**
+     * Whether the column can be used as a pivot column.
+     */
     pivotable: boolean;
+    /**
+     * Whether the column can show an aggregation.
+     */
     aggregatable: boolean;
 }
 /**
  * Summary of a Column including filters and all unique values
  */
+/**
+ * One column as shown in Column Info: the column, its Column Filter, and the distinct values currently in the grid.
+ */
 export interface AdaptableColumnSummary {
+    /**
+     * Column this summary describes.
+     */
     column: AdaptableColumn;
+    /**
+     * Column Filter on this column in the current Layout. Absent when the column is not filtered.
+     */
     columnFilter: ColumnFilter;
+    /**
+     * Distinct cell values in this column, each with how many rows have that value.
+     */
     uniqueGridCells: UniqueGridCell[];
 }

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

@@ -1,6 +1,8 @@
 import { ColumnFilter } from '../../types';
 /**
- * Current Filters in AdapTable
+ * Filters currently applied.
+ *
+ * `gridFilter` is the Grid Filter expression, absent when there is none. `columnFilters` are the Column Filters in the current layout.
  */
 export interface AdaptableFilterState {
     /**

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

@@ -2,7 +2,9 @@ import { Identifiable } from './AdaptableObject';
 import { CellDataChangedInfo } from '../../types';
 import { FlashingCellDefinition } from '../../../types';
 /**
- * Defines an Alert fired by AdapTable
+ * A cell or row that has just flashed.
+ *
+ * `flashingCellDefinition` is the rule. `cellDataChangedInfo` is the change that triggered it, when there is one. `direction` is `up`, `down` or `neutral`. `flashTarget` is what flashed (cell or row).
  */
 export interface AdaptableFlashingCell extends Identifiable {
     /**