@adaptabletools/adaptable 22.1.1 → 23.0.0-canary.1

package/src/AdaptableState/AlertState.d.ts

@@ -9,6 +9,7 @@ import { AdaptableStyle } from './Common/AdaptableStyle';
 import { XOR } from '../Utilities/Extensions/TypeExtensions';
 import { AdaptableAggregatedBooleanQuery, AdaptableBooleanQuery, AdaptableObservableQuery } from './Common/AdaptableQuery';
 import { ButtonStyle } from './Common/ButtonStyle';
+import { Schedule } from './Common/Schedule';
 import { AlertFormContext, BaseContext, NotificationsOptions, SuspendableObject } from '../types';
 /**
  * Adaptable State section for Alert Module
@@ -20,21 +21,13 @@ export interface AlertState extends BaseState {
     AlertDefinitions?: AlertDefinition[];
 }
 /**
- * The Alert Definition object used in the Alert function
+ * Fields shared by all alert definitions
  */
-export interface AlertDefinition extends SuspendableObject {
+export interface AlertDefinitionBase extends SuspendableObject {
     /**
      * Name of the Alert Definition
      */
     Name: string;
-    /**
-     * Where Alert can be triggered: one, some or all columns or DataTypes
-     */
-    Scope: ColumnScope;
-    /**
-     * When Alert should be triggered
-     */
-    Rule: AlertRule;
     /**
      * Type of Alert: 'Info', 'Success', 'Warning', 'Error'; influences Alert colour, icon and logging
      */
@@ -47,15 +40,46 @@ export interface AlertDefinition extends SuspendableObject {
      * Title of displayed Alert Message; if null, AdapTable creates dynamically using Rule & Scope
      */
     MessageText?: string;
+}
+/**
+ * Alert that fires when data matches a rule in the given column scope
+ */
+export interface RuleBasedAlertDefinition extends AlertDefinitionBase {
     /**
-     * Series of properties which set what happens when Alert is triggered
+     * Where Alert can be triggered: one, some or all columns or DataTypes
      */
-    AlertProperties?: AlertProperties;
+    Scope: ColumnScope;
+    /**
+     * When Alert should be triggered
+     */
+    Rule: AlertRule;
+    /**
+     * Properties which set what happens when the Alert is triggered (notification and grid behaviours)
+     */
+    AlertProperties?: RuleAlertProperties;
     /**
      * Form to display in Alert with buttons and inputs
      */
     AlertForm?: string | AlertButtonForm;
 }
+/**
+ * Alert that fires on a schedule (no rule or column scope)
+ */
+export interface ScheduledAlertDefinition extends AlertDefinitionBase {
+    /**
+     * When the alert should run
+     */
+    Schedule: Schedule;
+    /**
+     * Notification properties for scheduled alerts (no grid behaviours)
+     */
+    AlertProperties?: ScheduledAlertProperties;
+}
+/**
+ * The Alert Definition object used in the Alert function.
+ * Provide either a {@link Rule} (with {@link Scope}) or a {@link Schedule}, not both.
+ */
+export type AlertDefinition = RuleBasedAlertDefinition | ScheduledAlertDefinition;
 /**
  * Form triggered by an Alert which contains only Buttons
  */
@@ -99,15 +123,14 @@ export interface AlertButton<AlertFormContext> extends Omit<AdaptableButton<Base
      */
     ButtonStyle?: ButtonStyle;
     /**
-     * ToolTip to display
+     * Tooltip to display
      */
     Tooltip?: string;
 }
 /**
- *
- * Additional properties that specify how a particular Alert will ALWAYS behave
+ * Notification properties shared by rule-based and scheduled alerts
  */
-export interface AlertProperties {
+export interface AlertPresentationProperties {
     /**
      * Displays a notification when Alert is triggered
      */
@@ -116,6 +139,23 @@ export interface AlertProperties {
      * Notifiction duration(defaults to `NotificationOptions.duration`)
      */
     NotificationDuration?: NotificationsOptions['duration'];
+    /**
+     * Shows Alert text in the div specificed in `alertContainer` property of Container Options
+     */
+    ShowInDiv?: boolean;
+    /**
+     * Logs the Alert message to the console
+     */
+    LogToConsole?: boolean;
+    /**
+     * Shows the alert message in the System Status panel
+     */
+    DisplaySystemStatusMessage?: boolean;
+}
+/**
+ * Properties for rule-based alerts (presentation plus grid behaviours)
+ */
+export interface RuleAlertProperties extends AlertPresentationProperties {
     /**
      * Colours updated Row using `MessageType` of triggering Alert Definition
      */
@@ -132,20 +172,21 @@ export interface AlertProperties {
      * Grid will 'jump' to the newly added row which triggered the Alert
      */
     JumpToRow?: boolean;
-    /**
-     * Shows Alert text in the div specificed in `alertContainer` property of Container Options
-     */
-    ShowInDiv?: boolean;
-    /**
-     * Logs the Alert message to the console
-     */
-    LogToConsole?: boolean;
     /**
      * Automatically prevent any cell edit which triggered the Alert (i.e. validation)
      * @defaultValue false
      */
     PreventEdit?: boolean;
 }
+/**
+ * Properties for scheduled alerts (notification only)
+ */
+export interface ScheduledAlertProperties extends AlertPresentationProperties {
+    /**
+     * When true, the scheduled notification includes a Suspend button
+     */
+    IncludeSuspendButton?: boolean;
+}
 /**
  * Array containing all System Alert Predicates
  */

package/src/AdaptableState/CalculatedColumnState.d.ts

@@ -38,7 +38,7 @@ export interface CalculatedColumn extends AdaptableObject {
  */
 export interface CalculatedColumnSettings extends SpecialColumnSettings {
     /**
-     * Show underlying Expression as ToolTip when hovering over a cell
+     * Show underlying Expression as Tooltip when hovering over a cell
      * @defaultValue false
      */
     ShowToolTip?: boolean;

package/src/AdaptableState/ChartingState.d.ts

@@ -9,7 +9,7 @@ export declare const isAgChartDefinition: (chartDefinition: ChartDefinition | Ex
  */
 export interface ExternalChartDefinition<T = unknown> extends AdaptableObject {
     /**
-     * Name of the external chart
+     * Unique name of the external chart (used in UI references; must not clash with AG Grid chart names)
      */
     Name: string;
     /**
@@ -27,7 +27,7 @@ export interface ExternalChartDefinition<T = unknown> extends AdaptableObject {
  */
 export interface ChartDefinition extends AdaptableObject {
     /**
-     * Name of the chart definition
+     * Unique name of the chart (used in UI and layout references, like Layout names)
      */
     Name: string;
     /**

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

@@ -18,6 +18,11 @@ export interface AdaptableButton<CONTEXT_TYPE extends BaseContext> extends Ident
      * Icon for Button - can be object or function that provides a `AdaptableIcon` object
      */
     icon?: AdaptableIcon | ((button: AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => AdaptableIcon);
+    /**
+     * Where the icon appears relative to the label
+     * @defaultValue 'start'
+     */
+    iconPosition?: 'start' | 'end';
     /**
      * Tooltip for Button - can be string or function that provides string
      */

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

@@ -151,6 +151,11 @@ export interface AdaptableColumn<TData = any> extends AdaptableColumnBase {
      * Available Aggregations for the Column
      */
     availableAggregationFunctions?: string[];
+    /**
+     * `allowedAggFuncs` from the column `colDef` or `defaultColDef` as supplied in Grid Options
+     * (before Adaptable rewrites `allowedAggFuncs` for the standard Value Aggregation menu).
+     */
+    userAllowedAggFuncs?: string[];
     /**
      * Custom Aggregation function for the Column
      */

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

@@ -1,13 +1,26 @@
+import * as React from 'react';
 import { AdaptableButton } from './AdaptableButton';
 import { BaseContext } from '../../types';
 /**
- * Data which appears in an AdapTable Form
+ * Data which appears in an AdapTable Form.
+ *
+ * The default shape is a loosely-typed `Record<string, any>`, but consumers
+ * who care about strong typing can declare their own shape and pass it as
+ * the second generic parameter to {@link AdaptableForm}.
  */
 export type AdaptableFormData = Record<string, any>;
 /**
- * Defines a form which appears dynamically; used by Alerts & Export Custom Destinations
+ * Defines a form which appears dynamically; used by Alerts, Export Custom
+ * Destinations and Dashboard Custom Toolbars.
+ *
+ * @typeParam T     - The host's button/handler context (e.g.
+ *                    `CustomToolbarFormContext`).
+ * @typeParam TData - Optional shape of the form data. Defaults to the
+ *                    loosely-typed {@link AdaptableFormData}; declare your
+ *                    own shape (e.g. `{ name: string; age: number }`) for
+ *                    strongly-typed `formData` in `onSubmit` callbacks.
  */
-export interface AdaptableForm<T extends BaseContext> {
+export interface AdaptableForm<T extends BaseContext, TData extends AdaptableFormData = AdaptableFormData> {
     /**
      * Title to appear in the Form
      */
@@ -17,13 +30,89 @@ export interface AdaptableForm<T extends BaseContext> {
      */
     description?: string;
     /**
-     * Collection of Dynamic Fields to display
+     * Collection of Dynamic Fields and Field Groups to display.
+     *
+     * Items can be:
+     * - a single {@link AdaptableFormField} (rendered on its own row in the
+     *   default `rows` layout, or as one cell in the `inline` layout),
+     * - an array of {@link AdaptableFormField} (rendered side-by-side on the
+     *   same row in the `rows` layout), or
+     * - an {@link AdaptableFormFieldGroup} (a labelled section that
+     *   visually groups related fields).
      */
-    fields?: (AdaptableFormField | AdaptableFormField[])[];
+    fields?: (AdaptableFormField | AdaptableFormField[] | AdaptableFormFieldGroup)[];
     /**
      * Buttons to include in the Form
      */
     buttons?: AdaptableButton<T>[];
+    /**
+     * How the form's fields are arranged on screen.
+     *
+     * - `rows` (default): each field on its own row, label on the left and
+     *   input on the right. Suitable for popups / wizards.
+     * - `inline`: fields are placed side-by-side on a single horizontal line,
+     *   with the label rendered immediately before its input. Designed for
+     *   compact contexts such as Dashboard Custom Toolbars where vertical
+     *   real-estate is scarce.
+     *
+     * @defaultValue 'rows'
+     */
+    layout?: AdaptableFormLayout;
+    /**
+     * Optional form-level submit hook.
+     *
+     * Fired when the user presses `Enter` while focus is inside any field
+     * input AND the form is currently valid. The full `formData` is passed
+     * through, typed as `TData` if you've supplied a custom shape.
+     *
+     * Use this as an ergonomic shortcut to avoid wiring an explicit "Submit"
+     * button - or in addition to one, so power users can press Enter to
+     * commit. If the form is invalid the hook is not invoked.
+     */
+    onSubmit?: (formData: TData, context: T) => void;
+}
+/**
+ * How an AdaptableForm's fields are visually arranged
+ */
+export type AdaptableFormLayout = 'rows' | 'inline';
+/**
+ * Logical grouping of related fields, with an optional title and
+ * description. Use to break long forms into visually distinct sections.
+ *
+ * Groups behave like fields when it comes to `hidden`: a hidden group is
+ * not rendered and its child fields are excluded from validation. They
+ * are otherwise transparent - each child field continues to drive its
+ * own value, validation, and `onValueChange` lifecycle.
+ *
+ * In the `inline` layout the group's title/description are not rendered
+ * (the layout is too compact for sectioning). The child fields are
+ * laid out inline alongside the rest.
+ */
+export interface AdaptableFormFieldGroup {
+    /**
+     * Discriminator - identifies the item as a group rather than a field.
+     */
+    kind: 'group';
+    /**
+     * Optional title rendered as the section header.
+     */
+    title?: string;
+    /**
+     * Optional description rendered immediately below the title.
+     */
+    description?: string;
+    /**
+     * Fields contained in the group. Inner items may be a single field or
+     * an array of fields (rendered side-by-side on the same row, exactly
+     * like the top-level shorthand).
+     */
+    fields: (AdaptableFormField | AdaptableFormField[])[];
+    /**
+     * Hide the entire group. Either a boolean or a function evaluated
+     * against the current form data. Hidden groups skip rendering and
+     * exclude their children from validation.
+     */
+    hidden?: boolean | ((formData: AdaptableFormData, context: BaseContext) => boolean);
 }
 /**
  * Defines a Field that appears in an Adaptable Form
@@ -38,23 +127,222 @@ export interface AdaptableFormField {
      */
     label: string;
     /**
-     * Field Type: text, date, number, checkbox, select, textOutput
+     * Field Type - dictates which UI control is rendered
      */
     fieldType: AdaptableFormFieldType;
     /**
-     * Field Default Value - can be of type string, boolean, number
+     * Field Default Value - can be of type string, boolean, number, or for
+     * `select` fields with `multi: true` an array of those.
+     */
+    defaultValue?: string | boolean | number | Array<string | number | boolean>;
+    /**
+     * Items to populate the `select` and `radio` fieldTypes.
+     *
+     * Either a static array, or a function that derives the options from the
+     * current form data and Adaptable context. The function form may return
+     * a Promise for asynchronously-loaded options - the form will render the
+     * field with no items until the promise resolves.
+     */
+    options?: AdaptableFormFieldOption[] | ((formData: AdaptableFormData, context: BaseContext) => AdaptableFormFieldOption[] | Promise<AdaptableFormFieldOption[]>);
+    /**
+     * For `select` fields only. When `true` the field renders as a
+     * multi-select combobox; the field's value is an array of selected
+     * `option.value`s rather than a single value.
+     *
+     * @defaultValue false
+     */
+    multi?: boolean;
+    /**
+     * For `custom` fields only. Renders an arbitrary React node as the
+     * field's input. Receives the current value, a `setValue` setter
+     * (controlled), the current form data, the Adaptable context and the
+     * resolved `disabled` state.
+     *
+     * Use this as an escape hatch when none of the built-in `fieldType`s
+     * fit - e.g. to render a star-rating widget, a tag editor or any
+     * bespoke control.
+     */
+    render?: (params: AdaptableFormFieldRenderParams) => React.ReactNode;
+    /**
+     * Placeholder text shown inside `text`, `textarea`, `number`, `date`,
+     * `time` and `datetime` inputs when empty. For `select` fields it is
+     * rendered as the empty-state label.
+     */
+    placeholder?: string;
+    /**
+     * Inline help text rendered immediately below the field's input. Useful
+     * for short explanations such as "format: YYYY-MM-DD" or "min 3 chars".
+     */
+    helpText?: string;
+    /**
+     * Tooltip shown when hovering the field's label.
+     */
+    tooltip?: string;
+    /**
+     * Hide the field. Either a boolean or a function evaluated against the
+     * current form data. Hidden fields are not rendered and are excluded from
+     * validation.
+     */
+    hidden?: boolean | ((formData: AdaptableFormData, context: BaseContext) => boolean);
+    /**
+     * Disable the field's input. Either a boolean or a function evaluated
+     * against the current form data. Disabled fields render but the user
+     * cannot edit them.
+     */
+    disabled?: boolean | ((formData: AdaptableFormData, context: BaseContext) => boolean);
+    /**
+     * If `true` the field is treated as required. An empty value (`''`,
+     * `null`, `undefined`, or unchecked checkbox) will produce a validation
+     * error.
+     */
+    required?: boolean;
+    /**
+     * Custom field-level validation. Return an error message string to mark
+     * the field invalid, or `null`/`undefined` if the value is valid.
+     *
+     * Custom validation runs *after* built-in checks (`required`, `min`,
+     * `max`, `pattern`, etc.) - the first failing check wins.
+     */
+    validate?: (value: any, formData: AdaptableFormData, context: BaseContext) => string | null | undefined;
+    /**
+     * Minimum allowed value. For `number` and `slider`: the lowest accepted
+     * number. For `date`, `time` and `datetime`: the earliest allowed value
+     * in ISO format (`YYYY-MM-DD` / `HH:mm` / `YYYY-MM-DDTHH:mm`).
+     */
+    min?: number | string;
+    /**
+     * Maximum allowed value. For `number` and `slider`: the highest accepted
+     * number. For `date`, `time` and `datetime`: the latest allowed value in
+     * ISO format.
+     */
+    max?: number | string;
+    /**
+     * Stepping interval for `number`, `slider`, `time` and `datetime`
+     * fields.
+     */
+    step?: number;
+    /**
+     * Minimum length for `text` and `textarea` fields.
+     */
+    minLength?: number;
+    /**
+     * Maximum length for `text` and `textarea` fields.
+     */
+    maxLength?: number;
+    /**
+     * Regular expression that the value of a `text` field must match.
+     */
+    pattern?: string;
+    /**
+     * For `textarea` fields: the visible number of text rows.
+     *
+     * @defaultValue 3
+     */
+    rows?: number;
+    /**
+     * Optional callback invoked whenever value of this field changes
+     */
+    onValueChange?: (value: any, context: BaseContext) => void;
+}
+/**
+ * Map of validation errors produced by {@link validateAdaptableForm},
+ * keyed by field `name`. A field is valid when its key is not present.
+ */
+export type AdaptableFormErrors = Record<string, string>;
+/**
+ * Types of Controls used in an AdapTable Form (standard form set)
+ */
+export type AdaptableFormFieldType = 'text' | 'textarea' | 'select' | 'radio' | 'date' | 'time' | 'datetime' | 'number' | 'slider' | 'color' | 'checkbox' | 'textOutput' | 'custom';
+/**
+ * A single option used by a `select` or `radio` field.
+ */
+export interface AdaptableFormFieldOption {
+    value: any;
+    label: string;
+}
+/**
+ * Parameters provided to {@link AdaptableFormField.render} when rendering
+ * a `custom` field type.
+ */
+export interface AdaptableFormFieldRenderParams {
+    /**
+     * The field's current value
+     */
+    value: any;
+    /**
+     * Setter to update the field's value. Triggers form-level `onChange`,
+     * per-field `onValueChange` and re-validation.
+     */
+    setValue: (newValue: any) => void;
+    /**
+     * The field definition itself - useful when sharing one render function
+     * across several `custom` fields.
+     */
+    field: AdaptableFormField;
+    /**
+     * The current values of all fields in the form, keyed by field `name`.
+     */
+    formData: AdaptableFormData;
+    /**
+     * Adaptable context (carries `adaptableApi`, etc.). When the form is
+     * hosted by a Custom Toolbar this is in fact a
+     * `CustomToolbarFormContext`.
      */
-    defaultValue?: string | boolean | number;
+    context: BaseContext;
     /**
-     * Items to populate the 'select' fieldType
+     * Resolved disabled state of the field (after evaluating `field.disabled`
+     * if it's a function).
      */
-    options?: {
-        value: any;
-        label: string;
-    }[];
+    disabled: boolean;
+    /**
+     * Current validation error for this field, if any.
+     */
+    error?: string;
 }
 /**
- * Types of Controls used in an AdapTable Form
+ * Returns true if the supplied entry from a form's `fields` array is a
+ * group rather than a single field or an inline-row array of fields.
+ */
+export declare function isAdaptableFormFieldGroup(entry: AdaptableFormField | AdaptableFormField[] | AdaptableFormFieldGroup): entry is AdaptableFormFieldGroup;
+/**
+ * Flattens a form's `fields` array (which may contain field groups and
+ * inline-row arrays) into a single flat list of fields. Useful when
+ * computing defaults, validation or per-field lookups.
+ */
+export declare function flattenAdaptableFormFields<T extends BaseContext>(formDef?: AdaptableForm<T, any>): AdaptableFormField[];
+export declare function getDefaultAdaptableFormData<T extends BaseContext = BaseContext>(formDef?: AdaptableForm<T, any>): AdaptableFormData;
+/**
+ * Resolves a field's `options` to the current array of options.
+ *
+ * - When `options` is already an array, it's returned as-is.
+ * - When it's a synchronous function, the function is invoked.
+ * - When the function returns a Promise this helper returns `undefined` -
+ *   asynchronous resolution is the caller's responsibility (the
+ *   `AdaptableFormComponent` resolves promises via internal state).
+ */
+export declare function resolveAdaptableFormFieldOptionsSync(field: AdaptableFormField, formData: AdaptableFormData, context: BaseContext): AdaptableFormFieldOption[] | undefined;
+/**
+ * Returns true if the given field should be hidden given the current form
+ * data and context. Resolves both boolean and function forms of `hidden`.
+ */
+export declare function isAdaptableFormFieldHidden(field: AdaptableFormField, formData: AdaptableFormData, context: BaseContext): boolean;
+/**
+ * Returns true if the given group should be hidden given the current
+ * form data and context.
+ */
+export declare function isAdaptableFormFieldGroupHidden(group: AdaptableFormFieldGroup, formData: AdaptableFormData, context: BaseContext): boolean;
+/**
+ * Returns true if the given field should be disabled given the current
+ * form data and context. Resolves both boolean and function forms of
+ * `disabled`.
+ */
+export declare function isAdaptableFormFieldDisabled(field: AdaptableFormField, formData: AdaptableFormData, context: BaseContext): boolean;
+/**
+ * Validates an entire AdaptableForm. Hidden fields and fields inside
+ * hidden groups are skipped. Returns a map of field-name to error
+ * message; fields without entries are valid.
+ *
+ * Validation order per field: `required` -> built-in (min/max/length/
+ * pattern) -> custom `validate`. The first failing check wins.
  */
-export type AdaptableFormFieldType = 'text' | 'select' | 'date' | 'number' | 'checkbox' | 'textOutput';
-export declare function getDefaultAdaptableFormData<T extends BaseContext = BaseContext>(formDef?: AdaptableForm<T>): AdaptableFormData;
+export declare function validateAdaptableForm<T extends BaseContext = BaseContext>(formDef: AdaptableForm<T, any>, formData: AdaptableFormData, context: BaseContext): AdaptableFormErrors;