@adaptabletools/adaptable/src/AdaptableOptions/RowFormOptions.d.ts

Powerful AG Grid extension which provides advanced, cutting-edge functionality to meet all DataGrid requirements

import { IRowNode } from 'ag-grid-enterprise';
import { RowFormSubmittedInfo, AdaptableButton, AdaptableColumn, AdaptableFormField, BaseContext, FormContext } from '../types';
/**
 * Options related to Dynamic Row Forms in AdapTable
 */
export interface RowFormOptions<TData = any> {
    /**
     * Whether AdapTable automatically updates AG Grid data model with created/edited/deleted rows
     * @defaultValue true
     */
    autoHandle?: boolean;
    /**
     * Prevents direct editing in Grid cells even for editable columns
     * @defaultValue false
     */
    disableInlineEditing?: boolean;
    /**
     * Function called when auto-handling 'create' or 'clone' Command Button; returned value should be valid for Primary Key column
     * @defaultValue undefined
     */
    setPrimaryKeyValue?: (context: SetPrimaryKeyValueContext<TData>) => any;
    /**
     * Custom form title provider
     * @defaultValue 'Create New Row'/'Edit Row'
     */
    rowFormTitle?: string | ((context: RowFormTitleContext<TData>) => string);
    /**
     * Custom form description provider
     * @defaultValue undefined
     */
    rowFormDescription?: string | ((context: RowFormTitleContext<TData>) => string);
    /**
     * Custom form field label provider.
     *
     * Superseded by {@link rowFormField} (which can return any subset of
     * {@link AdaptableFormField} properties, including `label`); kept for
     * backward compatibility.
     * @defaultValue undefined
     */
    rowFormFieldLabel?: (context: RowFormFieldContext<TData>) => string;
    /**
     * Per-column override for the auto-built {@link AdaptableFormField}.
     *
     * Return any subset of `AdaptableFormField` properties to customise the
     * field for a particular column. Anything you don't return falls back to
     * AdapTable's default - which is derived from the column's data type
     * (string → `text`, number → `number`, boolean → `checkbox`, date →
     * `date`, columns with discrete options → `select`).
     *
     * Returning `undefined` keeps the default field for that column.
     *
     * Use this to unlock the full power of {@link AdaptableFormField} in
     * Row Forms - including:
     * - presentation (`placeholder`, `helpText`, `tooltip`)
     * - validation (`required`, `min`, `max`, `pattern`, `validate`)
     * - data-driven `hidden` / `disabled`
     * - alternative field types (`textarea`, `radio`, `slider`, `time`,
     *   `datetime`, `color`)
     * - multi-select via `multi: true`
     * - bespoke widgets via `fieldType: 'custom'` + `render`
     *
     * @example
     * ```ts
     * rowFormField: ({ column }) => {
     *   if (column.columnId === 'notes') {
     *     return { fieldType: 'textarea', rows: 4, placeholder: 'optional notes' };
     *   }
     *   if (column.columnId === 'email') {
     *     return {
     *       required: true,
     *       pattern: '^\\S+@\\S+\\.\\S+$',
     *       helpText: 'we will only use this for delivery',
     *     };
     *   }
     * }
     * ```
     *
     * @defaultValue undefined
     */
    rowFormField?: (context: RowFormFieldContext<TData>) => Partial<AdaptableFormField> | undefined;
    /**
     * Custom form buttons; if provided, need to handle form submission explicitly
     */
    rowFormButtons?: AdaptableButton<RowFormContext<TData>>[];
    /**
     * Event fired when a Row Form is submitted via a standard button provided by AdapTable; this is not invoked when custom form buttons are provided
     *
     * @param rowFormSubmittedInfo the form submitted info
     * @defaultValue undefined
     */
    onRowFormSubmit?: (rowFormSubmittedInfo: RowFormSubmittedInfo<TData>) => void;
    /**
     * Is given Column displayed in Row Form
     * @defaultValue true
     */
    includeColumnInRowForm?: (rowFormColumnContext: RowFormColumnContext) => boolean;
}
/**
 * Context passed into a Row Form - can be `CreateRowFormContext` or `EditRowFormContext`
 */
export type RowFormContext<TData = any> = CreateRowFormContext<TData> | EditRowFormContext<TData>;
/**
 * Context used in a Create Row Form
 */
export interface CreateRowFormContext<TData = any> extends FormContext {
    /**
     * Type of the Context
     */
    type: Extract<RowFormType, 'rowCreated'>;
    /**
     * The RowNode being cloned
     */
    clonedRowNode?: IRowNode<TData>;
}
/**
 * Context used in an Edit Row Form
 */
export interface EditRowFormContext<TData = any> extends FormContext {
    /**
     * Type of the Context
     */
    type: Extract<RowFormType, 'rowEdited'>;
    /**
     * The RowNode being edited
     */
    rowNode: IRowNode<TData>;
}
/**
 * Context used for overriding Title and Description of Row Form
 */
export interface RowFormTitleContext<TData = any> extends BaseContext {
    type: Extract<RowFormType, 'rowEdited' | 'rowCreated'>;
    rowNode?: IRowNode<TData>;
}
/**
 * Context used for overriding Field elements in Row Form
 */
export interface RowFormFieldContext<TData = any> extends RowFormTitleContext {
    column: AdaptableColumn<TData>;
}
/**
 * Type of RowForm: 'rowCreated' | 'rowEdited' | 'rowDeleted'
 */
export type RowFormType = 'rowCreated' | 'rowEdited' | 'rowDeleted';
/**
 * Context used when decided if column should be included in a Row Form
 */
export interface RowFormColumnContext extends BaseContext {
    /**
     * Column to be displayed
     */
    adaptableColumn: AdaptableColumn;
    /**
     * Type of Row Form
     */
    rowFormType: RowFormType;
}
/**
 * Context for the setPrimaryKeyValue function
 */
export interface SetPrimaryKeyValueContext<TData = any> extends BaseContext {
    /**
     * Data in the row being created or cloned
     */
    rowData: TData;
}