@adaptabletools/adaptable 23.0.0-canary.0 → 23.0.0-canary.10

package/src/AdaptableState/StyledColumns/IconStyle.d.ts

@@ -0,0 +1,158 @@
+import { AdaptableIcon } from '../Common/AdaptableIcon';
+import { CellBoxStyle, CellFontStyle } from '../Common/AdaptableStyle';
+/**
+ * Built-in mapping presets for Icons (Flags, Currencies, Trend, Status)
+ */
+export type IconStyleBuiltInPreset = 'Flags' | 'Currencies' | 'Trend' | 'Status';
+/**
+ * How the cell value should be matched against {@link IconStyleMapping.Key}.
+ *
+ * - `'Exact'` (default) — strict `===` equality. Numbers, booleans and
+ *   strings are matched as-is; useful when keys are tightly controlled.
+ * - `'CaseInsensitive'` — string keys are matched case-insensitively
+ *   (cell value and key are both lowercased before comparison). Useful
+ *   for free-typed columns where the same logical value can appear as
+ *   `'GBP'` or `'gbp'`.
+ */
+export type IconStyleMatchMode = 'Exact' | 'CaseInsensitive';
+/**
+ * Behaviour when the cell value does not match any mapping key.
+ *
+ * - `'Hide'` (default) — render nothing.
+ * - `'ShowText'` — render the raw cell value (so the cell still shows
+ *   *something* meaningful instead of an empty cell).
+ * - `'Icon'` — render a fallback icon defined by
+ *   {@link IconFallbackProperties.Icon}.
+ */
+export type IconStyleFallback = 'Hide' | 'ShowText' | 'Icon';
+/**
+ * What the renderer draws for a single matched mapping.
+ *
+ * - An {@link AdaptableIcon} — a system icon (`{ name: 'flag' }`), a URL
+ *   (`{ src: '/img/us.svg' }`) or an HTML element / fragment.
+ * - A plain `string` — rendered verbatim, intended for emoji glyphs
+ *   (e.g. `'🇺🇸'`, `'$'`, `'⬆'`). Strings are *not* HTML-parsed so they
+ *   are safe to author from data sources.
+ */
+export type IconStyleSpec = AdaptableIcon | string;
+/**
+ * Fallback settings for {@link IconStyle} — what the renderer draws when
+ * no mapping matches the cell value (`Mode`), and the icon used when
+ * `Mode === 'Icon'` (`Icon`).
+ */
+export interface IconFallbackProperties {
+    /**
+     * Behaviour when no mapping matches the cell value (Hide, ShowText, Icon).
+     *
+     * @defaultValue `'Hide'`
+     */
+    Mode?: IconStyleFallback;
+    /**
+     * Icon used when `Mode: 'Icon'` (ignored otherwise).
+     */
+    Icon?: IconStyleSpec;
+}
+/**
+ * Companion text settings for {@link IconStyle} — what to render alongside
+ * a matched icon (`CellText`) and where it sits relative to the icon
+ * (`CellTextPosition`).
+ */
+export interface IconCellTextProperties {
+    /**
+     * Text to render alongside a matched icon (CellValue and/or the matched
+     * mapping's Description).
+     */
+    CellText?: ('CellValue' | 'IconDescription')[];
+    /**
+     * Where the cell text sits relative to the icon (Before, After, Above, Below).
+     *
+     * @defaultValue `'After'`
+     */
+    CellTextPosition?: 'Before' | 'After' | 'Above' | 'Below';
+}
+/**
+ * One mapping in an {@link IconStyle} — `Key` is matched against the
+ * cell's raw value, `Icon` is what gets drawn when it matches.
+ */
+export interface IconStyleMapping {
+    /**
+     * Cell value that triggers this mapping. Compared using the parent
+     * {@link IconStyle.MatchMode} (defaults to strict equality).
+     *
+     * Booleans and numbers are accepted to support typed columns (e.g.
+     * `Key: true` for an `isLive` flag, `Key: 0` for a status code).
+     */
+    Key: string | number | boolean;
+    /**
+     * Icon to render when `Key` matches the cell value.
+     *
+     * See {@link IconStyleSpec} — accepts an `AdaptableIcon` (system /
+     * URL / element) or a plain string for emoji.
+     */
+    Icon: IconStyleSpec;
+    /**
+     * Optional human-readable description of this mapping (e.g. the full
+     * country name when `Key` is an ISO code). Surfaced in the tooltip and
+     * by the wizard's mappings list.
+     */
+    Description?: string;
+}
+/**
+ * Renders cell values as icons by looking up the cell value in a list of key → icon mappings; designed for one-glyph-per-cell visual recognition
+ */
+export interface IconStyle {
+    /**
+     * Custom mappings for style (layered on top of a preset); leave undefined to use preset as-is
+     */
+    Mappings?: IconStyleMapping[];
+    /**
+     * Built-in mappings to use for the Icon Style
+     */
+    Preset?: IconStyleBuiltInPreset;
+    /**
+     * How `Key` is compared with the cell value (Exact or Case Insensitive)
+     *
+     * @defaultValue `'Exact'`
+     */
+    MatchMode?: IconStyleMatchMode;
+    /**
+     * Behaviour when no mapping matches the cell value, plus the icon used
+     * by `Mode: 'Icon'`.
+     *
+     * Defaults to `{ Mode: 'Hide' }` when omitted.
+     */
+    FallbackProperties?: IconFallbackProperties;
+    /**
+     * Companion text to render alongside a matched icon (Cell Value and/or
+     * the matched mapping's Description) and where it sits relative to the
+     * icon (Before / After / Above / Below).
+     *
+     * Mirrors the `CellTextProperties` grouping used by `PercentBarStyle`,
+     * `BulletChartStyle` and `RangeBarStyle` for consistency.
+     */
+    CellTextProperties?: IconCellTextProperties;
+    /**
+     * Pixel size of icon glyph (square)
+     *
+     * @defaultValue `18`
+     */
+    Size?: number;
+    /**
+     * Pixel gap between the icon and the cell text (when shown).
+     *
+     * @defaultValue `4`
+     */
+    Gap?: number;
+    /**
+     * Tooltip content: `CellValue` (raw cell value) or `IconDescription` (matched mapping's `Description`)
+     */
+    ToolTipText?: ('CellValue' | 'IconDescription')[];
+    /**
+     * Optional cell-text styling applied to the companion text
+     */
+    Font?: CellFontStyle;
+    /**
+     * Optional stying (background / border / radius) for Cell behind the Icon
+     */
+    Cell?: CellBoxStyle;
+}

package/src/AdaptableState/StyledColumns/IconStyle.js

@@ -0,0 +1 @@
+export {};

package/src/AdaptableState/StyledColumns/PercentBarStyle.d.ts

@@ -0,0 +1,32 @@
+import { CellFontStyle } from '../Common/AdaptableStyle';
+import { BarStyleCellTextProperties } from './Common/BarStyleProperties';
+import { CellTextOptions } from './Common/CellTextOptions';
+import { NumericStyledColumn } from './Common/NumericStyledColumn';
+/**
+ * Style used to display Percent Bars in Special Column Style
+ */
+export interface PercentBarStyle extends NumericStyledColumn {
+    /**
+     * Optional cell-text overlay configuration (display tokens, position, layout, alignment).
+     */
+    CellTextProperties?: BarStyleCellTextProperties;
+    /**
+     * Whether Tooltip shows Cell Value, Percent Value, both or none
+     */
+    ToolTipText?: CellTextOptions;
+    /**
+     * Background colour for 'Percent Bar'; leave unset if none required
+     * @defaultValue undefined
+     */
+    BackColor?: string;
+    /**
+     * Origin of the bar - i.e. the value the bar grows from Auto, Zero, Min or fixed number
+     *
+     * @defaultValue 'Auto'
+     */
+    Origin?: 'Auto' | 'Zero' | 'Min' | number;
+    /**
+     * Optional cell-text styling applied to `CellText` overlay
+     */
+    Font?: CellFontStyle;
+}

package/src/AdaptableState/StyledColumns/PercentBarStyle.js

@@ -0,0 +1 @@
+export {};

package/src/AdaptableState/StyledColumns/RangeBarStyle.d.ts

@@ -0,0 +1,155 @@
+import { BarStyleCellTextProperties } from './Common/BarStyleProperties';
+import { BarStyleMarker } from './Common/BarStyleProperties';
+import { CellTextOptions } from './Common/CellTextOptions';
+import { DynamicRangeEndpoint, NumericStyledColumn } from './Common/NumericStyledColumn';
+/**
+ * Resolvable value used by a Range Bar's `Min`, `Max` or `Reference.Value`.
+ *
+ * - `number` — a hard-coded value
+ * - `string` — a column id; the row's value in that column is used
+ * - `'Col-Min' | 'Col-Max' | 'Col-Avg' | 'Col-Median'` — a column-wide
+ *   aggregate computed across visible rows
+ */
+export type RangeBarBound = number | string | DynamicRangeEndpoint;
+/**
+ * Configures a Range Bar Styled Column.
+ *
+ * A Range Bar shows where a row's value sits inside a per-row (or
+ * column-wide) numeric range. The range endpoints (`Min` / `Max`) are
+ * resolved per row — they can be hard-coded numbers, the value of another
+ * column on the same row, or a column-wide aggregate (`Col-Min`, `Col-Max`,
+ * `Col-Avg`, `Col-Median`).
+ *
+ * Common scenarios:
+ *  - Stock price relative to its 52-week low / 52-week high
+ *  - Today's value relative to bid / ask quotes
+ *  - Forecast within an upper / lower confidence interval
+ *  - Measured value within an SLA `[lowerBound, upperBound]`
+ *
+ * Visually the cell renders as a thin track between `Min` and `Max`, with
+ * a marker at the cell value. An optional `Reference` value renders as a
+ * second marker (e.g. previous close, target, midpoint).
+ *
+ * Background bands (`CellRanges`) are drawn behind the track using the same
+ * conventions as Bullet Chart, and are useful for qualitative scales such
+ * as poor / acceptable / good (or red / amber / green SLA bands).
+ */
+export interface RangeBarStyle extends NumericStyledColumn {
+    /**
+     * Lower bound of the track for each row.
+     *
+     * Can be:
+     *  - `number` — a fixed lower bound shared by every row
+     *  - `string` — a column id; the row's value in that column is used
+     *  - `'Col-Min' | 'Col-Max' | 'Col-Avg' | 'Col-Median'` — a column-wide
+     *    aggregate computed across the visible rows
+     */
+    Min: RangeBarBound;
+    /**
+     * Upper bound of the track for each row.
+     *
+     * See `Min` for the supported value forms.
+     */
+    Max: RangeBarBound;
+    /**
+     * Optional reference value (e.g. previous close, target, midpoint) drawn
+     * as a *second* marker on the track, together with its marker styling.
+     * Leave unset to draw only the cell-value marker.
+     */
+    Reference?: RangeBarReferenceProperties;
+    /**
+     * Visual style of the cell-value marker.
+     *
+     * @defaultValue `{ Shape: 'Diamond', Color: 'var(--ab-color-accent)', Size: 8 }`
+     */
+    Marker?: BarStyleMarker;
+    /**
+     * Behaviour when the cell value falls outside `[Min, Max]`, plus the
+     * optional marker colour override used by `Mode: 'Clamp'`.
+     *
+     * Defaults to `{ Mode: 'Clamp' }` when omitted.
+     */
+    OutOfRange?: RangeBarOutOfRangeProperties;
+    /**
+     * Visual properties of the track (the line representing the `[Min, Max]`
+     * interval).
+     */
+    Track?: RangeBarTrackProperties;
+    /**
+     * Background colour for the chart area when no `CellRanges` are supplied.
+     */
+    BackColor?: string;
+    /**
+     * Orientation of the range bar.
+     *
+     * @defaultValue `'Horizontal'`
+     */
+    Orientation?: 'Horizontal' | 'Vertical';
+    /**
+     * Optional cell-text overlay configuration.
+     */
+    CellTextProperties?: BarStyleCellTextProperties;
+    /**
+     * Tooltip content — same tokens (`'CellValue'`, `'PercentageValue'`)
+     * as Percent Bar / Bullet Chart.
+     */
+    ToolTipText?: CellTextOptions;
+}
+/**
+ * Optional reference value drawn as a *second* marker on a Range Bar track,
+ * together with its marker styling.
+ */
+export interface RangeBarReferenceProperties {
+    /**
+     * Resolvable reference value (number / column id / `'Col-Min' | 'Col-Max'
+     * | 'Col-Avg' | 'Col-Median'`). Same forms as `RangeBarStyle.Min` / `Max`.
+     */
+    Value: RangeBarBound;
+    /**
+     * Visual style of the reference marker.
+     *
+     * @defaultValue `{ Shape: 'Line', Color: 'var(--ab-color-foreground)', Size: 2 }`
+     */
+    Marker?: BarStyleMarker;
+}
+/**
+ * Out-of-range behaviour for a Range Bar.
+ */
+export interface RangeBarOutOfRangeProperties {
+    /**
+     * Behaviour when the cell value falls outside `[Min, Max]`.
+     *
+     * - `'Clamp'` (default) — clamp the marker to the nearest end of the
+     *   track and (optionally) re-colour it via `Color`
+     * - `'Overflow'` — draw the marker outside the track at its true position
+     * - `'Hide'` — omit the cell-value marker entirely
+     *
+     * @defaultValue `'Clamp'`
+     */
+    Mode?: 'Clamp' | 'Overflow' | 'Hide';
+    /**
+     * Marker colour override applied when the cell value is out of range
+     * (only used with `Mode: 'Clamp'`). Useful to draw attention to
+     * "off-scale" rows.
+     */
+    Color?: string;
+}
+/**
+ * Visual properties of the Range Bar track (the line representing the
+ * `[Min, Max]` interval).
+ */
+export interface RangeBarTrackProperties {
+    /**
+     * Track colour.
+     *
+     * @defaultValue 'var(--ab-color-foreground, #999)' at low alpha
+     */
+    Color?: string;
+    /**
+     * Track thickness in px (the *short* axis — height in horizontal,
+     * width in vertical).
+     *
+     * @defaultValue 4
+     */
+    Height?: number;
+}

package/src/AdaptableState/StyledColumns/RangeBarStyle.js

@@ -0,0 +1 @@
+export {};

package/src/AdaptableState/StyledColumns/RatingStyle.d.ts

@@ -0,0 +1,111 @@
+import { CellBoxStyle } from '../Common/AdaptableStyle';
+import { CellTextOptions } from './Common/CellTextOptions';
+/**
+ * Icon used by a Rating Style
+ */
+export type RatingIconShape = 'Star' | 'Heart' | 'Circle' | 'Thumb';
+/**
+ * Styles a numeric column as a row of icons whose fill represents the
+ * cell value on a 0..`Max` scale.
+ *
+ * Conceptually similar to a Percent Bar but with a discrete, instantly
+ * legible visual idiom (★★★☆☆) commonly used for ratings, satisfaction
+ * scores and review-style cells.
+ *
+ * The cell value is clamped to `[0, Max]`. When `AllowHalf` is true (the
+ * default) the icon at the boundary is rendered with a partial fill that
+ * matches the fractional part of the value; otherwise the value is
+ * rounded to the nearest whole icon.
+ */
+export interface RatingStyle {
+    /**
+     * Number of icons per cell **and** the upper bound of the rating scale,
+     * in the **same numeric units as the cell value**.
+     *
+     * The renderer clamps the cell value to `[0, Max]` and maps that number
+     * directly to filled icons (e.g. `Max: 5` and value `4` → four units of
+     * fill across five icons — roughly four stars, not “4 out of 10 scaled
+     * to five stars”). Values above `Max` show as fully filled; values below
+     * `0` show as empty.
+     *
+     * To show a 1–10 score as five stars, use a calculated column (e.g.
+     * `value / 2`) or set `Max` to match your data range (e.g. `Max: 10`
+     * for ten icons), unless a future `ScaleMin` / `ScaleMax` option is added.
+     *
+     * @defaultValue 5
+     */
+    Max?: number;
+    /**
+     * Icon used for each rating mark.
+     *
+     * @defaultValue 'Star'
+     */
+    Icon?: RatingIconShape;
+    /**
+     * Fill colour for the active (filled) portion of the rating.
+     *
+     * @defaultValue 'var(--ab-color-warn, #f5a623)' — a warm amber that
+     * reads well on both light and dark themes.
+     */
+    FilledColor?: string;
+    /**
+     * Outline / fill colour for the inactive portion of the rating.
+     *
+     * Drawn as a subtle background icon so the user can see the maximum
+     * possible rating at a glance even when the cell value is low.
+     *
+     * @defaultValue a low-opacity tint of the current text colour.
+     */
+    EmptyColor?: string;
+    /**
+     * Icon size in pixels (each icon is square). The renderer keeps the
+     * row of icons vertically centred regardless of cell height.
+     *
+     * @defaultValue 14
+     */
+    Size?: number;
+    /**
+     * Pixel gap between adjacent icons.
+     *
+     * @defaultValue 2
+     */
+    Gap?: number;
+    /**
+     * Controls **partial icons** for fractional values after clamping to
+     * `[0, Max]` — not scaling between different ranges (e.g. 10-point vs
+     * 5-star).
+     *
+     * When `true`, the decimal part fills part of the next icon (e.g. `3.5`
+     * with `Max: 5` → three full icons + one half-filled + one empty).
+     * When `false`, the clamped value is rounded with `Math.round` before
+     * drawing, so only whole icons appear.
+     *
+     * @defaultValue true
+     */
+    AllowHalf?: boolean;
+    /**
+     * When `true`, the numeric cell value is also displayed alongside the
+     * icons (e.g. `★★★★☆ 4.2`). Useful when precise scores matter beyond
+     * the visual approximation.
+     *
+     * @defaultValue false
+     */
+    ShowValue?: boolean;
+    /**
+     * Optional AG Grid tooltip content — `CellValue` and/or `PercentageValue`.
+     * `PercentageValue` is the clamped cell value as a percent of `Max`
+     * (`clamp(value, 0, Max) / Max`, same scale as the icon fill).
+     */
+    ToolTipText?: CellTextOptions;
+    /**
+     * Optional cell box styling (background colour, border, border radius)
+     * applied to the cell behind the rating icons.
+     *
+     * When set, this property "claims" the Cell slice for the column: any
+     * Format Column matching this column has its Cell-box properties stripped
+     * (so a Format Column `BackColor` cannot tint the cell behind a Rating).
+     * When unset, Format Column Cell properties inherit through normally —
+     * useful for tinting a row of stars to match a Format Column theme.
+     */
+    Cell?: CellBoxStyle;
+}

package/src/AdaptableState/StyledColumns/RatingStyle.js

@@ -0,0 +1 @@
+export {};

package/src/AdaptableState/StyledColumns/SparklineStyle.d.ts

@@ -0,0 +1,21 @@
+import { AgSparklineOptions } from 'ag-charts-types';
+import { CellBoxStyle } from '../Common/AdaptableStyle';
+/**
+ * Style to show for a Sparkline Column
+ */
+export interface SparklineStyle {
+    /**
+     * AG Grid Sparkline Options
+     */
+    options?: AgSparklineOptions;
+    /**
+     * Optional cell box styling applied to the cell behind the sparkline chart.
+     *
+     * When set, this property "claims" the Cell slice for the column: any
+     * Format Column matching this column has its Cell-box properties stripped.
+     * When unset, Format Column Cell properties inherit through normally —
+     * useful for letting a row's themed background show through behind the
+     * sparkline.
+     */
+    Cell?: CellBoxStyle;
+}

package/src/AdaptableState/StyledColumns/SparklineStyle.js

@@ -0,0 +1 @@
+export {};

package/src/AdaptableState/ThemeState.d.ts

@@ -1,57 +1,62 @@
 import { BaseState } from './BaseState';
 import { AdaptableObject } from './Common/AdaptableObject';
 import { TypeHint } from './Common/Types';
+/**
+ * Shipped AdapTable theme names.
+ */
+export type SystemThemeName = TypeHint<string, 'light' | 'dark' | 'os'>;
 /**
  * Theme section of Adaptable State
  */
 export interface ThemeState extends BaseState {
     /**
-     * Name of current theme (or theme to set at startup); leave blank if using 'Light Theme', set to 'dark' for 'Dark Theme' or provide name of Custom Theme
+     * Name of current Theme or theme set at startup; leave blank if using 'Light Theme', set to 'dark' for 'Dark Theme'
      */
-    CurrentTheme?: TypeHint<string, 'light' | 'dark' | 'os'>;
+    CurrentTheme?: SystemThemeName;
     /**
-     * Which, if any, of the 2 themes shipped by Adaptable should be available; leave unset to provide both, or an empty array to provide neither.
+     * Which shipped themes are available; pass theme name string, or `{ Name, AgThemeMode? }` to pair a custom AG Grid theme mode; leave unset for all shipped themes
      */
-    SystemThemes?: (AdaptableTheme | string)[];
+    SystemThemes?: (SystemThemeEntry | AdaptableTheme)[];
     /**
-     * Custom themes (of type AdaptableTheme) provided by developers
+     * Custom themes provided by developers (deprecated)
+     *
+     * @deprecated Will be removed in next major version. Customise shipped `light` / `dark` themes via CSS variable overrides instead.
      */
     UserThemes?: AdaptableTheme[];
 }
 /**
- * Used for creating User (i.e. Custom) Themes
+ * Pairing options between AG Grid and AdapTable themes
  */
-export interface AdaptableTheme extends AdaptableObject {
+export interface SystemThemeOptions {
     /**
-     * Name of the Theme as it appears in the Theme toolbar and tool panel
+     * Shipped theme this entry configures: `light`, `dark`, or `os`
      */
-    Name: string;
+    Name: SystemThemeName;
     /**
-     * Description of Theme - will appear in Theme Toolbar and Toolpanel
+     * AG Grid theme mode to apply when this theme is selected; valid values are `light`, `dark`, `dark-blue` or any custom theme mode defined in AG Grid
      */
-    Description: string;
+    AgThemeMode?: TypeHint<string, 'light' | 'dark' | 'dark-blue'>;
     /**
-     * Ag Grid theme to apply when loading theme; relevant only when using the legacy AG Grid themes
+     * Ag Grid theme to apply when loading theme; relevant only when using legacy AG Grid themes
      *
-     * @deprecated no longer used with the new AG Grid Theming API
+     * @deprecated no longer used with new AG Grid Theming API
      */
     AgGridClassName?: string;
-    /**
-     * Variables to be applied at runtime
-     */
+}
+/**
+ * Configures a shipped system theme: a theme name, or an object with AG Grid pairing options
+ */
+export type SystemThemeEntry = SystemThemeName | SystemThemeOptions;
+/**
+ * Used for creating Custom Themes (deprecated)
+ *
+ * @deprecated User-defined themes are deprecated; customise shipped themes via CSS variables and use SystemThemeOptions for AG Grid pairing
+ */
+export interface AdaptableTheme extends AdaptableObject {
+    Name: string;
+    Description: string;
+    AgGridClassName?: string;
     CSSVariables?: Record<string, string>;
-    /**
-     * Base theme variant to derive custom theme from.
-     * Use `light` to inherit from Adaptable Light Theme or `dark` for Adaptable Dark Theme.
-     * When creating custom themes, specifying a variant ensures proper inheritance of base theme styles.
-     */
     Variant?: 'light' | 'dark';
-    /**
-     * AG Grid theme mode to apply when this theme is selected.
-     * Valid values are `light`, `dark`, `dark-blue` or any custom theme mode defined in AG Grid.
-     * When set, adds a data-ag-theme-mode attribute to the document body.
-     *
-     * @see https://www.ag-grid.com/javascript-data-grid/theming-colors/#theme-modes
-     */
     AgThemeMode?: TypeHint<string, 'light' | 'dark' | 'dark-blue'>;
 }

package/src/Api/ColumnScopeApi.d.ts

@@ -1,6 +1,6 @@
 import { AdaptableColumn } from '../AdaptableState/Common/AdaptableColumn';
 import { ColumnScope, ScopeDataType } from '../AdaptableState/Common/ColumnScope';
-import { CellColorRange } from '../AdaptableState/StyledColumnState';
+import { CellColorRange } from '../AdaptableState/StyledColumns/Common/NumericStyledColumn';
 /**
  * Provides access to a suite of functions related to the `Column Scope` object
  */

package/src/Api/EventApi.d.ts

@@ -1,4 +1,4 @@
-import { AdaptableReadyInfo, AdaptableStateChangedInfo, AdaptableStateReloadedInfo, BeforeAdaptableStateChangeInfo, AlertFiredInfo, CalculatedColumnChangedInfo, CellChangedInfo, CellSelectionChangedInfo, ChartChangedInfo, ColumnFilterAppliedInfo, CommentChangedInfo, CustomToolbarConfiguredInfo, DashboardChangedInfo, DataImportedInfo, DataSetSelectedInfo, Fdc3MessageInfo, FlashingCellDisplayedInfo, GridFilterAppliedInfo, GridSortedInfo, LayoutChangedInfo, LiveDataChangedInfo, RowChangedInfo, RowFormSubmittedInfo, RowSelectionChangedInfo, ReportScheduleRanInfo, SystemStatusMessageDisplayedInfo, TeamSharingEntityChangedInfo, ThemeChangedInfo } from '../types';
+import { AdaptableReadyInfo, AdaptableStateChangedInfo, AdaptableStateReloadedInfo, BeforeAdaptableStateChangeInfo, AlertFiredInfo, CalculatedColumnChangedInfo, CellChangedInfo, CellSelectionChangedInfo, ChartChangedInfo, ColumnFilterAppliedInfo, CommentChangedInfo, CustomToolbarConfiguredInfo, DashboardChangedInfo, DataImportedInfo, DataSetSelectedInfo, Fdc3MessageInfo, FlashingCellDisplayedInfo, GridFilterAppliedInfo, GridSortedInfo, LayoutChangedInfo, LiveDataChangedInfo, RowChangedInfo, RowFormSubmittedInfo, RowSelectionChangedInfo, ReportScheduleRanInfo, SystemStatusMessageDisplayedInfo, TeamSharingEntityChangedInfo, ThemeChangedInfo, ThemeSelectedInfo } from '../types';
 /**
  * Responsible for publishing the many Events that AdapTable fires
  */
@@ -32,7 +32,7 @@ export interface EventApi {
     /**
      * Event fired whenever a Schedule is triggered in AdapTable
      * @param eventName ReportScheduleRan
-     * @param callback ReportScheduleRan which provides details of the Report Schedule that was triggered
+     * @param callback provides the report schedule and `RanAt` (when this run started)
      */
     on(eventName: 'ReportScheduleRan', callback: (reportScheduleRanInfo: ReportScheduleRanInfo) => void): VoidFunction;
     /**
@@ -115,15 +115,28 @@ export interface EventApi {
      * Unsubscribe from RowSelectionChanged
      */
     off(eventName: 'RowSelectionChanged', callback: (rowSelectionChangedInfo: RowSelectionChangedInfo) => void): void;
+    /**
+     * Event fired whenever a shipped theme (`light`, `dark`, or `os`) is selected or re-applied
+     * @param eventName ThemeSelected
+     * @param callback ThemeSelectedInfo containing the active system theme name
+     * @returns the unsubscribe function
+     */
+    on(eventName: 'ThemeSelected', callback: (themeSelectedInfo: ThemeSelectedInfo) => void): VoidFunction;
+    /**
+     * Unsubscribe from ThemeSelected
+     */
+    off(eventName: 'ThemeSelected', callback: (themeSelectedInfo: ThemeSelectedInfo) => void): void;
     /**
      * Event fired whenever the selected theme of AdapTable is changed
      * @param eventName ThemeChanged
      * @param callback ThemeChangedInfo which just contains the name of the current Theme
      * @returns the unsubscribe function
+     * @deprecated Use `ThemeSelected` instead. Will be removed in the next major version.
      */
     on(eventName: 'ThemeChanged', callback: (themeChangedInfo: ThemeChangedInfo) => void): VoidFunction;
     /**
      * Unsubscribe from ThemeChanged
+     * @deprecated Use `ThemeSelected` instead.
      */
     off(eventName: 'ThemeChanged', callback: (themeChangedInfo: ThemeChangedInfo) => void): void;
     /**

package/src/Api/Events/ReportScheduleRan.d.ts

@@ -8,4 +8,8 @@ export interface ReportScheduleRanInfo extends BaseContext {
      * Report schedule that was triggered (if applicable)
      */
     reportSchedule?: ReportSchedule;
+    /**
+     * ISO datetime when Schedule ran (useful for logging)
+     */
+    RanAt: string;
 }

package/src/Api/Events/ThemeChanged.d.ts

@@ -2,14 +2,20 @@ import { AdaptableTheme } from '../../AdaptableState/ThemeState';
 import { BaseContext } from '../../types';
 /**
  * Object returned by the `ThemeChanged` event
+ *
+ * @deprecated Use {@link ThemeSelectedInfo} and the `ThemeSelected` event instead. Will be removed in the next major version.
  */
 export interface ThemeChangedInfo extends BaseContext {
     /**
      * Current Theme: either name of a System Theme or a Custom Theme object
+     *
+     * @deprecated Use `ThemeSelectedInfo.theme` instead.
      */
     theme: AdaptableTheme | string;
     /**
      * What caused Event to fire: "ThemeSelected" or "ThemeEdited"
+     *
+     * @deprecated No longer required — use the `ThemeSelected` event for theme selection.
      */
     trigger: 'ThemeSelected' | 'ThemeEdited';
 }