devextreme/ui/card_view.d.ts

HTML5 JavaScript Component Suite for Responsive Web Development

/**
* DevExtreme (ui/card_view.d.ts)
* Version: 25.1.3
* Build date: Wed Jun 25 2025
*
* Copyright (c) 2012 - 2025 Developer Express Inc. ALL RIGHTS RESERVED
* Read about DevExtreme licensing here: https://js.devexpress.com/Licensing/
*/
import { DeepPartial } from '../core';
import {
    DataType,
    DragHighlight,
    HorizontalAlignment,
 Mode, ScrollbarMode, SelectAllMode, SingleMultipleOrNone, SortOrder, template, ValidationRule,
} from '../common';
import { Format } from '../common/core/localization';
import { UserDefinedElement, DxElement } from '../core/element';
import {
 ColumnChooser, ColumnCustomizeTextArg, ColumnHeaderFilter, DataChange, DataErrorOccurredInfo, FilterPanel, FilterType, HeaderFilter, Pager, SearchPanel, SelectionColumnDisplayMode, Sorting,
} from '../common/grids';
import DataSource, { DataSourceLike } from '../data/data_source';
import Widget, { WidgetOptions } from './widget/ui.widget';
import { Cancelable, EventInfo, NativeEventInfo } from '../events';
import { dxToolbarItem, ToolbarItemLocation } from './toolbar';
import { dxLoadPanelOptions } from './load_panel';
import dxScrollable from './scroll_view/ui.scrollable';
import {
    Properties as PopupProperties,
  } from './popup';
import {
    Properties as FormProperties, SimpleItem,
  } from './form';
import { dxFilterBuilderOptions } from './filter_builder';

/**
 * Configures paging.
 */
export type Paging = {
    /**
     * Enables paging.
     */
    enabled?: boolean;
    /**
     * Specifies the page to be displayed using a zero-based index.
     */
    pageIndex?: number;
    /**
     * Specifies the page size.
     */
    pageSize?: number;
};

/**
 * Notifies CardView of the server's data processing operations.
 */
export type RemoteOperations = {
    /**
     * Specifies whether filtering must be performed on the server.
     */
    filtering?: boolean;
    /**
     * Specifies whether paging must be performed on the server.
     */
    paging?: boolean;
    /**
     * Specifies whether sorting must be performed on the server.
     */
    sorting?: boolean;
    /**
     * Specifies whether grouping must be performed on the server.
     */
    grouping?: boolean;
};

// #region Toolbar

export type PredefinedToolbarItem = 'columnChooserButton' | 'searchPanel' | 'addCardButton' | 'selectAllButton' | 'clearSelectionButton';

/**
 * @deprecated Use ToolbarItem instead
 * @deprecated Attention! This type is for internal purposes only. If you used it previously, please submit a ticket to our {@link https://supportcenter.devexpress.com/ticket/create Support Center}. We will check if there is an alternative solution.
 */
export type dxCardViewToolbarItem = ToolbarItem;

/**
 * 
 */
export type ToolbarItem = dxToolbarItem & {
    /**
     * 
     */
    name?: PredefinedToolbarItem | string;
    /**
     * 
     */
    location?: ToolbarItemLocation;
};

/**
 * @deprecated Use Toolbar instead
 * @deprecated Attention! This type is for internal purposes only. If you used it previously, please submit a ticket to our {@link https://supportcenter.devexpress.com/ticket/create Support Center}. We will check if there is an alternative solution.
 */
export type dxCardViewToolbar = Toolbar;

/**
 * 
 */
export type Toolbar = {
    /**
     * 
     */
    items?: Array<PredefinedToolbarItem | ToolbarItem>;
    /**
     * 
     */
    visible?: boolean | undefined;
    /**
     * 
     */
    disabled?: boolean;
    /**
     * 
     */
    multiline?: boolean;
};

// #endregion

// #region ColumnsController

/**
 * @deprecated Use FieldInfo instead
 * @deprecated Attention! This type is for internal purposes only. If you used it previously, please submit a ticket to our {@link https://supportcenter.devexpress.com/ticket/create Support Center}. We will check if there is an alternative solution.
 */
export type dxCardViewFieldInfo = FieldInfo;

/**
 * Information about the field.
 */
export type FieldInfo = {
    /**
     * The field value.
     */
    value: any;
    /**
     * Specifies the display value.
     */
    displayValue: any;
    /**
     * The field text.
     */
    text: string;
    /**
     * The column associated with the field.
     */
    column: Column;
    /**
     * The field index.
     */
    index: number;
    /**
     * Specifies which card the field belongs to.
     */
    card: CardInfo;
};

/**
 * The information about the card.
 */
export type CardInfo<TCardData = unknown, TKey = unknown> = {
    /**
     * The card&apos;s index.
     */
    index: number;
    /**
     * Specifies columns associated with the card.
     */
    columns: Column[];
    /**
     * The card fields.
     */
    fields: FieldInfo[];
    /**
     * The card&apos;s key.
     */
    key: TKey;
    /**
     * The card&apos;s data.
     */
    data: TCardData;
    /**
     * Specifies whether the card is selected.
     */
    isSelected?: boolean;
    /**
     * Values of the card as they exist in the data source.
     */
    values: any[];
};

/**
 * Configures column properties.
 */
export type ColumnProperties<TCardData = unknown, TKey = unknown> = {
    /**
     * Aligns the content of the entire column.
     */
    alignment?: HorizontalAlignment | undefined;
    /**
     * Specifies whether a user can edit cards in this column at runtime. Inherits the value of the editing.allowUpdating property.
     */
    allowEditing?: boolean;
    /**
     * Specifies whether data can be filtered by this column.
     */
    allowFiltering?: boolean;
    /**
     * Specifies whether data of this column can be filtered in header filter. Inherits the value of the allowFiltering property.
     */
    allowHeaderFiltering?: boolean;
    /**
     * Specifies whether a user can hide the column using the column chooser at runtime. Applies only if columnChooser.enabled is `true`.
     */
    allowHiding?: boolean;
    /**
     * Specifies whether users can reorder this column. Overrides the allowColumnReordering property value.
     */
    allowReordering?: boolean;
    /**
     * Specifies whether this column can be searched. Applies only if searchPanel.visible is `true`. Inherits the value of the allowFiltering property.
     */
    allowSearch?: boolean;
    /**
     * Specifies whether a user can sort rows by this column at runtime. Applies only if sorting.mode differs from &apos;none&apos;.
     */
    allowSorting?: boolean;
    /**
     * Calculates custom field values.
     */
    calculateFieldValue?: ((this: Column, cardData: TCardData) => any);
    /**
     * Calculates custom display values for column fields. Requires specifying the dataField or calculateFieldValue property.
     */
    calculateDisplayValue?: ((this: Column, cardData: TCardData) => any);
    /**
     * Specifies the column&apos;s custom rules to filter data.
     */
    calculateFilterExpression?: ((this: Column, filterValue: any, selectedFilterOperation: string | null, target: string) => string | Array<any> | Function);
    /**
     * Calculates custom values used to sort this column.
     */
    calculateSortValue?: string | ((this: Column, cardData: TCardData) => any);
    /**
     * Specifies a caption for the column.
     */
    caption?: string | undefined;
    /**
     * Customizes text displayed in field values.
     */
    customizeText?: ((this: Column, fieldInfo: ColumnCustomizeTextArg) => string);
    /**
     * Binds the column to a field of the dataSource.
     */
    dataField?: string | undefined;
    /**
     * Converts column values to a different data type.
     */
    dataType?: DataType | undefined;
    /**
     * Configures the default UI component used for editing.
     */
    editorOptions?: any;
    /**
     * In a boolean column, replaces all false items with a specified text.
     */
    falseText?: string;
    /**
     * Specifies whether a user changes the current filter by including (selecting) or excluding (clearing the selection of) values. Applies only if headerFilter.visible and allowHeaderFiltering are `true`.
     */
    filterType?: FilterType;
    /**
     * Specifies the filter value.
     */
    filterValue?: any | undefined;
    /**
     * Specifies the values in the header filter.
     */
    filterValues?: Array<any>;
    /**
     * Configures the form item that the field produces in the editing state.
     */
    formItem?: SimpleItem;
    /**
     * Formats a value before it is displayed in a field.
     */
    format?: Format;
    /**
     * Specifies data settings for the header filter.
     */
    headerFilter?: ColumnHeaderFilter | undefined;
    /**
     * Specifies the column&apos;s unique identifier. If not set in code, this value is inherited from the dataField.
     */
    name?: string | undefined;
    /**
     * Specifies a function to be invoked after the user has edited a field value, but before it is saved in the data source.
     */
    setFieldValue?: ((this: Column, newData: DeepPartial<TCardData>, value: any, currentCardData: TCardData) => void | PromiseLike<void>);
    /**
     * Specifies whether the column chooser can contain the column header.
     */
    showInColumnChooser?: boolean;
    /**
     * Specifies the index according to which columns participate in sorting.
     */
    sortIndex?: number | undefined;
    /**
     * Specifies the sort order of column values.
     */
    sortOrder?: SortOrder | undefined;
    /**
     * Specifies a custom comparison function for sorting. Applies only when sorting is performed on the client.
     */
    sortingMethod?: ((this: Column, value1: any, value2: any) => number) | undefined;
    /**
     * In a boolean column, replaces all true items with the specified text.
     */
    trueText?: string;
    /**
     * Specifies validation rules to be checked when field values are updated.
     */
    validationRules?: Array<ValidationRule>;
    /**
     * Specifies whether the column is visible.
     */
    visible?: boolean;
    /**
     * Specifies the position of the column among other columns in the resulting UI component.
     */
    visibleIndex?: number | undefined;
    /**
     * Specifies a custom template for the field.
     */
    fieldTemplate?: template | ((data: FieldTemplateData, container: DxElement) => string | UserDefinedElement);
    /**
     * Specifies a custom template for the field caption.
     */
    fieldCaptionTemplate?: template | ((data: FieldTemplateData, container: DxElement) => string | UserDefinedElement);
    /**
     * Specifies a custom template for the field value.
     */
    fieldValueTemplate?: template | ((data: FieldTemplateData, container: DxElement) => string | UserDefinedElement);
    /**
     * Specifies a custom template for the header item.
     */
    headerItemTemplate?: template | ((data: ColumnTemplateData<TCardData, TKey>, container: DxElement) => string | UserDefinedElement);
    /**
     * CSS class name applied to header item elements.
     */
    headerItemCssClass?: string;
};

/**
 * Configures the column.
 */
export type Column<TCardData = unknown, TKey = unknown> = ColumnProperties<TCardData, TKey> & {
    defaultCalculateFilterExpression: NonNullable<ColumnProperties['calculateFilterExpression']>;
    defaultSetFieldValue: NonNullable<ColumnProperties['setFieldValue']>;
    defaultCalculateFieldValue: NonNullable<ColumnProperties['calculateFieldValue']>;
};

// #endregion

// #region HeaderPanel

/**
 * Configures the header panel.
 */
export type HeaderPanel<TCardData = unknown, TKey = unknown> = {
    /**
     * Configures item dragging.
     */
    dragging?: {
        /**
         * Specifies how to highlight the header item&apos;s drop position.
         */
        dropFeedbackMode?: DragHighlight;
        /**
         * Specifies the scrolling speed when dragging an item beyond the viewport.
         */
        scrollSpeed?: number;
        /**
         * Specifies the distance in pixels from the edge of viewport at which scrolling should start.
         */
        scrollSensitivity?: number;
        /**
         * A function that is called when the dragged item&apos;s position changes.
         */
        onDragChange?: ((e: any) => void);
        /**
         * A function that is called when the drag gesture is finished.
         */
        onDragEnd?: ((e: any) => void);
        /**
         * A function that is called every time a draggable item is moved.
         */
        onDragMove?: ((e: any) => void);
        /**
         * A function that is called when a drag gesture is initialized.
         */
        onDragStart?: ((e: any) => void);
        /**
         * A function that is called when a draggable item is removed.
         */
        onRemove?: ((e: any) => void);
        /**
         * A function that is called when the draggable items are reordered.
         */
        onReorder?: ((e: any) => void);
    };
    /**
     * Specifies whether the header panel is visible.
     */
    visible?: boolean;
    /**
     * Specifies a custom template for header panel items.
     */
    itemTemplate?: template | ((data: ColumnTemplateData<TCardData, TKey>, container: DxElement) => string | UserDefinedElement);
    /**
     * CSS class name applied to item root elements.
     */
    itemCssClass?: string;
};

// #endregion

// #region ContentView

/**
 * @docid
 * @hidden
 */
type WithCardInfo = {
    /**
     * 
     */
    readonly card: CardInfo;
    /**
     * 
     */
    readonly cardElement: DxElement;
};

/**
 * @docid
 * @hidden
 */
type WithFieldCaptionInfo = {
    /**
     * 
     */
    readonly field: FieldInfo;
    /**
     * 
     */
    readonly fieldCaptionElement: DxElement;
};

/**
 * @docid
 * @hidden
 */
type WithFieldValueInfo = {
    /**
     * 
     */
    readonly field: FieldInfo;
    /**
     * 
     */
    readonly fieldValueElement: DxElement;
};

/**
 * The argument type in the cardClick event.
 */
export type CardClickEvent = NativeEventInfo<dxCardView, PointerEvent | MouseEvent | TouchEvent> & WithCardInfo;

/**
 * The argument type in the cardDblClick event.
 */
export type CardDblClickEvent = NativeEventInfo<dxCardView, PointerEvent | MouseEvent | TouchEvent> & WithCardInfo;

/**
 * The argument type in the cardPrepared event.
 */
export type CardPreparedEvent = EventInfo<dxCardView> & WithCardInfo;

/**
 * The argument type in the fieldCaptionClick event.
 */
export type FieldCaptionClickEvent = NativeEventInfo<dxCardView, PointerEvent | MouseEvent | TouchEvent> & WithFieldCaptionInfo;

/**
 * The argument type in the fieldCaptionDblClick event.
 */
export type FieldCaptionDblClickEvent = NativeEventInfo<dxCardView, PointerEvent | MouseEvent | TouchEvent> & WithFieldCaptionInfo;

/**
 * The argument type in the fieldValuePrepared event.
 */
export type FieldValuePreparedEvent = EventInfo<dxCardView> & WithFieldValueInfo;

/**
 * The argument type in the fieldValueClick event.
 */
export type FieldValueClickEvent = NativeEventInfo<dxCardView, PointerEvent | MouseEvent | TouchEvent> & WithFieldValueInfo;

/**
 * The argument type in the fieldValueDblClick event.
 */
export type FieldValueDblClickEvent = NativeEventInfo<dxCardView, PointerEvent | MouseEvent | TouchEvent> & WithFieldValueInfo;

/**
 * The argument type in the fieldCaptionPrepared event.
 */
export type FieldCaptionPreparedEvent = EventInfo<dxCardView> & WithFieldCaptionInfo;

/**
 * The argument type in the cardHoverChanged event.
 */
export type CardHoverChangedEvent = EventInfo<dxCardView> & WithCardInfo & {
    /**
     * Indicates whether the pointer entered or left the card. Can be either &apos;mouseover&apos; or &apos;mouseout&apos;.
     */
    eventType: string;
};

/**
 * Specifies a custom template for the field.
 */
export type FieldTemplateData = {
    /**
     * Information about the field.
     */
    field: FieldInfo;
};

/**
 * Specifies card template data.
 */
export type CardTemplateData = {
    card: CardInfo;
};

/**
 * The data of column template.
 */
export type ColumnTemplateData<TCardData = unknown, TKey = unknown> = {
    column: Column<TCardData, TKey>;
};

/**
 * Configures the card cover.
 */
export type CardCover<TCardData = unknown> = {
    /**
     * Specifies which data field to use as the `src` argument of the cover image.
     */
    imageExpr: string | ((data: TCardData) => string);
    /**
     * Specifies which data field to use as the `alt` argument of the cover image.
     */
    altExpr: string | ((data: TCardData) => string);
    /**
     * Specifies the maximum height for the card cover.
     */
    maxHeight?: number;
    /**
     * Specifies the aspect ratio of the image container.
     */
    aspectRatio?: string;
    /**
     * Specifies a custom template for the card cover.
     */
    template?: template | ((data: CardTemplateData, container: DxElement) => string | UserDefinedElement);
};

export type CardHeaderPredefinedItem = 'selectionCheckBox' | 'updateButton' | 'deleteButton';

/**
 * Configures card header items.
 */
export type CardHeaderItem = dxToolbarItem & {
    /**
     * A name used to identify the card header item.
     */
    name?: CardHeaderPredefinedItem | string;
    /**
     * Specifies the item&apos;s location in the card header.
     */
    location?: ToolbarItemLocation;
};

/**
 * Configures the card header.
 */
export type CardHeader = {
    /**
     * Specifies whether to display the card header.
     */
    visible?: boolean;
    /**
     * Configures card header items.
     */
    items?: Array<CardHeaderPredefinedItem | CardHeaderItem>;
    /**
     * Specifies a custom template for the card header.
     */
    template?: template | ((data: CardTemplateData) => string | UserDefinedElement);
};

// #endregion

// #region Editing

// Conflicts with recently introduced chat.d.ts Editing after merge
// Use a computed / parent-based docids until agreement
// Specified docid similar to other grids

/**
 * The texts displayed when editing a card.
 */
export type EditingTexts = {
  /**
   * Specifies the text of the button that adds a card.
   */
  addCard?: string;
  /**
   * Specifies the text of the deletion confirmation message.
   */
  confirmDeleteMessage?: string;
  /**
   * Specifies the title text of the pop-up deletion confirmation.
   */
  confirmDeleteTitle?: string;
  /**
   * Specifies the text of the button that invokes card deletion.
   */
  deleteCard?: string;
  /**
   * Specifies the text of the button that invokes card editing.
   */
  editCard?: string;
  /**
   * Specifies the text of the button that saves the edited card.
   */
  saveCard?: string;
};

/**
 * @deprecated Use Editing instead
 * @deprecated Attention! This type is for internal purposes only. If you used it previously, please submit a ticket to our {@link https://supportcenter.devexpress.com/ticket/create Support Center}. We will check if there is an alternative solution.
 */
export type dxCardViewEditing<TCardData=unknown, TKey=unknown> = Editing<TCardData, TKey>;

/**
 * Configures editing.
 */
export type Editing<TCardData=unknown, TKey=unknown> = {
    /**
     * Specifies whether a user can add new cards.
     */
    allowAdding?: boolean;
    /**
     * Specifies whether a user can delete cards.
     */
    allowDeleting?: boolean;
    /**
     * Specifies whether a user can update cards.
     */
    allowUpdating?: boolean;
    /**
     * An array of pending row changes.
     */
    changes?: DataChange<TCardData, TKey>[];
    /**
     * Specifies if confirmation is required when a user deletes a row.
     */
    confirmDelete?: boolean;
    /**
     * The key(s) of a card being edited.
     */
    editCardKey?: TKey | null;
    /**
     * Configures the form inside the editing popup.
     */
    form?: FormProperties;
    /**
     * Configures the editing popup.
     */
    popup?: PopupProperties;
    /**
     * 
     */
    texts?: EditingTexts;
};

/**
 * The argument type in the editCanceled event.
 */
export type EditCanceledEvent = EventInfo<dxCardView> & {
    /**
     * Discarded card changes.
     */
    changes: DataChange[];
};

/**
 * The argument type in the editCanceling event.
 */
export type EditCancelingEvent = EventInfo<dxCardView> & Cancelable & {
    /**
     * Card changes to be discarded.
     */
    changes: DataChange[];
};

/**
 * The argument type in the editingStart event.
 */
export type EditingStartEvent<TCardData = unknown, TKey = unknown> = EventInfo<dxCardView> & Cancelable & {
    /**
     * The data of a card to be edited.
     */
    data: TCardData;
    /**
     * The card&apos;s key.
     */
    key: TKey;
};

/**
 * The argument type in the initNewCard event.
 */
export type InitNewCardEvent<TCardData = unknown> = EventInfo<dxCardView> & {
    /**
     * The data of the inserted card; initially empty.
     */
    data: DeepPartial<TCardData>;
    /**
     * Assign a Promise to this field to perform an asynchronous operation, such as a request to the server.
     */
    promise?: PromiseLike<void>;
};

/**
 * The argument type in the cardInserted event.
 */
export type CardInsertedEvent<TCardData = unknown> = EventInfo<dxCardView> & {
    /**
     * The data of the card.
     */
    data: DeepPartial<TCardData>;
};

/**
 * The argument type in the cardInserting event.
 */
export type CardInsertingEvent<TCardData = unknown> = EventInfo<dxCardView> & Cancelable & {
    /**
     * The data of the card.
     */
    data: DeepPartial<TCardData>;
};

/**
 * The argument type in the cardRemoved event.
 */
export type CardRemovedEvent<TCardData = unknown, TKey = unknown> = EventInfo<dxCardView> & {
    /**
     * The data of the card.
     */
    data: TCardData;
    /**
     * The card&apos;s key.
     */
    key: TKey;
};

/**
 * The argument type in the cardRemoving event.
 */
export type CardRemovingEvent<TCardData = unknown, TKey = unknown> = EventInfo<dxCardView> & Cancelable & {
    /**
     * The data of the card.
     */
    data: TCardData;
    /**
     * The card&apos;s key.
     */
    key: TKey;
};

/**
 * The argument type in the cardUpdated event.
 */
export type CardUpdatedEvent<TCardData = unknown, TKey = unknown> = EventInfo<dxCardView> & {
    /**
     * The updated data of the card.
     */
    data: TCardData;
    /**
     * The card&apos;s key.
     */
    key: TKey;
};

/**
 * The argument type in the cardUpdating event.
 */
export type CardUpdatingEvent<TCardData = unknown, TKey = unknown> = EventInfo<dxCardView> & Cancelable & {
    /**
     * The card&apos;s key.
     */
    key: TKey;
    /**
     * The card&apos;s old data.
     */
    oldData: TCardData;
    /**
     * The card&apos;s updated data.
     */
    newData: DeepPartial<TCardData>;
};

/**
 * The argument type in the cardSaved event.
 */
export type CardSavedEvent = EventInfo<dxCardView> & {
    /**
     * All card data (including changes). Differs from onCardSaving, which only consists of pending changes.
     */
    changes: DataChange[];
};

/**
 * The argument type in the cardSaving event.
 */
export type CardSavingEvent = EventInfo<dxCardView> & Cancelable & {
    /**
     * Assign a Promise to this field to perform an asynchronous operation, such as a request to a server.
     */
    promise?: PromiseLike<void>;
    /**
     * Pending row changes; a copy of the editing.changes array. Includes only card changes, unlike onCardSaved, which contains all card data (including changes).
     */
    changes: DataChange[];
};

// #endregion

// #region Selection

/**
 * Configures runtime selection.
 */
export type SelectionConfiguration = {
    /**
     * Allows users to simultaneously select all or current page cards (depending on selectAllMode).
     */
    allowSelectAll?: boolean;
    /**
     * Specifies the selection mode.
     */
    mode?: SingleMultipleOrNone;
    /**
     * Specifies the mode for selecting cards. Applies only if selection.allowSelectAll is `true`.
     */
    selectAllMode?: SelectAllMode;
    /**
     * Specifies when to display card selection checkboxes.
     */
    showCheckBoxesMode?: SelectionColumnDisplayMode;
};

/**
 * The argument type in the selectionChanged event.
 */
export type SelectionChangedEvent<TCardData = unknown, TKey = unknown> = EventInfo<dxCardView> & {
    /**
     * The data of all selected cards.
     */
    selectedCardsData: Array<TCardData>;
    /**
     * The keys of all selected cards.
     */
    selectedCardKeys: Array<TKey>;
    /**
     * The keys of the cards that were selected.
     */
    currentSelectedCardKeys: Array<TKey>;
    /**
     * The keys of the cards whose selection was cleared.
     */
    currentDeselectedCardKeys: Array<TKey>;
};

// #endregion

// #region ContextMenu

export type ContextMenuTarget = 'toolbar' | 'headerPanel' | 'content';

/**
 * The argument type in the contextMenuPreparing event.
 */
export type ContextMenuPreparingEvent<TCardData = unknown> = EventInfo<dxCardView> & {
  /**
   * Items to be displayed in the context menu.
   */
  items?: any[];
  /**
   * The name of the element on which the context menu is invoked: &apos;headerPanel&apos;, &apos;content&apos;, or &apos;toolbar&apos;.
   */
  readonly target: ContextMenuTarget;
  /**
   * The target element&apos;s container.
   */
  readonly targetElement: DxElement;
  /**
   * The index of the column on which the context menu is invoked.
   */
  readonly columnIndex?: number;
  /**
   * The column&apos;s configuration.
   */
  readonly column?: Column;
  /**
   * The index of the card on which the context menu is invoked.
   */
  readonly cardIndex?: number;
  /**
   * The card properties.
   */
  readonly card?: TCardData;
};

// #endregion

// #region KBN

/**
 * The argument type in the focusedCardChanged event.
 */
export type FocusedCardChanged = EventInfo<dxCardView> & WithCardInfo;

// #endregion

/**
 * 
 * @deprecated 
 */
export interface dxCardViewOptions<TCardData = unknown, TKey = unknown> extends WidgetOptions<dxCardView> {

    // #region DataController

    /**
     * Binds the UI component to data.
     */
    dataSource?: DataSourceLike<TCardData, TKey>;
    /**
     * Configures paging.
     */
    paging?: Paging;
    /**
     * Specifies the key property (or properties) that supply key values to access data items. Each key value must be unique. This property applies only if data is a simple array.
     */
    keyExpr?: string | string[]; // can be undefined because of default?
    /**
     * Notifies CardView of the server&apos;s data processing operations.
     */
    remoteOperations?: RemoteOperations | boolean | Mode;
    /**
     * A function that is executed when an error occurs in the data source.
     */
    onDataErrorOccurred?: (e: EventInfo<dxCardView> & DataErrorOccurredInfo) => void;

    // #endregion

    // #region Pager

    /**
     * Configures the pager.
     */
    pager?: Pager;

    // #endregion

    // #region ColumnsController

    /**
     * An array of CardView columns.
     */
    columns?: (ColumnProperties<TCardData, TKey> | string)[];

    /**
     * Specifies whether a user can reorder columns.
     */
    allowColumnReordering?: boolean;

    // #endregion

    // #region HeaderPanel

    /**
     * Configures the header panel.
     */
    headerPanel?: HeaderPanel<TCardData, TKey>;

    // #endregion

    // #region ContentView

    /**
     * Configures scrolling.
     */
    scrolling?: {
        /**
         * Specifies whether a user can scroll the content with a swipe gesture. Applies only if useNative is `false`.
         */
        scrollByContent?: boolean;
        /**
         * Specifies whether a user can scroll the content with the scrollbar. Applies only if useNative is `false`.
         */
        scrollByThumb?: boolean;
        /**
         * Specifies when to display scroll bars. Applies only if useNative is `false`.
         */
        showScrollbar?: ScrollbarMode;
        /**
         * Specifies whether CardView should use native or simulated scrolling.
         */
        useNative?: boolean | Mode;
    };
    /**
     * Indicates whether to show the error row.
     */
    errorRowEnabled?: boolean;
    /**
     * Configures the load panel.
     */
    loadPanel?: dxLoadPanelOptions;
    /**
     * Specifies a text string to display when no data appears in CardView.
     */
    noDataText?: string;
    /**
     * Specifies a custom template to be displayed when no data appears in CardView.
     */
    noDataTemplate?: template | ((e: { text: string }, container: DxElement) => string | UserDefinedElement);
    /**
     * Specifies the number of cards per row.
     */
    cardsPerRow?: number | Mode;
    /**
     * Specifies the minimum width of the card.
     */
    cardMinWidth?: number;
    /**
     * Specifies the maximum width of the card.
     */
    cardMaxWidth?: number;
    /**
     * Specifies whether text that does not fit into a field should be wrapped.
     */
    wordWrapEnabled?: boolean;
    /**
     * Configures the card cover.
     */
    cardCover?: CardCover<TCardData>;
    /**
     * Specifies a custom template for the card.
     */
    cardTemplate?: template | ((data: CardTemplateData, container: DxElement) => string | UserDefinedElement);
    /**
     * Specifies a custom template for card content.
     */
    cardContentTemplate?: template | ((data: CardTemplateData, container: DxElement) => string | UserDefinedElement);
    /**
     * Displays a hint when the mouse hovers over truncated field content.
     */
    fieldHintEnabled?: boolean;
    /**
     * A function that is executed when a card is clicked or tapped.
     */
    onCardClick?: (e: CardClickEvent) => void;
    /**
     * A function that is executed when a card is double-clicked or double-tapped.
     */
    onCardDblClick?: (e: CardDblClickEvent) => void;
    /**
     * A function that is executed after a card is created.
     */
    onCardPrepared?: (e: CardPreparedEvent) => void;
    /**
     * A function that is executed when a field caption is clicked or tapped.
     */
    onFieldCaptionClick?: (e: FieldCaptionClickEvent) => void;
    /**
     * A function that is executed when a field caption is double-clicked or double-tapped.
     */
    onFieldCaptionDblClick?: (e: FieldCaptionDblClickEvent) => void;
    /**
     * A function that is executed after a field caption is created.
     */
    onFieldCaptionPrepared?: (e: FieldCaptionPreparedEvent) => void;
    /**
     * A function that is executed when a field value is clicked or tapped.
     */
    onFieldValueClick?: (e: FieldValueClickEvent) => void;
    /**
     * A function that is executed when a field value is double-clicked or double-tapped.
     */
    onFieldValueDblClick?: (e: FieldValueDblClickEvent) => void;
    /**
     * A function that is executed after a field value is created.
     */
    onFieldValuePrepared?: (e: FieldValuePreparedEvent) => void;
    /**
     * A function that is executed after the pointer enters or leaves a card.
     */
    onCardHoverChanged?: (e: CardHoverChangedEvent) => void;
    /**
     * Specifies a custom template for a card footer.
     */
    cardFooterTemplate?: template | ((data: CardTemplateData, container: DxElement) => string | UserDefinedElement);
    /**
     * Configures the card header.
     */
    cardHeader?: CardHeader;

    /**
     * Specifies whether the UI component changes its appearance when a user hovers over it.
     */
    hoverStateEnabled?: boolean;

    // #endregion

    // #region Toolbar

    /**
     * Configures the toolbar.
     */
    toolbar?: Toolbar;

    // #endregion

    /**
     * Configures sorting.
     */
    sorting?: Sorting;

    /**
     * Specifies a filter expression.
     */
    filterValue?: string | Array<any> | Function;
    /**
     * Configures the integrated filter builder popup.
     */
    filterBuilderPopup?: PopupProperties;
    /**
     * Configures the filter builder.
     */
    filterBuilder?: dxFilterBuilderOptions;
    /**
     * Configures the filter panel.
     */
    filterPanel?: FilterPanel<dxCardView>;
    /**
     * Configures the column chooser.
     */
    columnChooser?: ColumnChooser;
    /**
     * Configures the search panel.
     */
    searchPanel?: SearchPanel;
    /**
     * Configures the header filter.
     */
    headerFilter?: HeaderFilter;

    // #region Editing

    /**
     * Configures editing.
     */
    editing?: Editing<TCardData, TKey>;
    /**
     * A function that is executed after card changes are discarded.
     */
    onEditCanceled?: (e: EditCanceledEvent) => void;
    /**
     * A function that is executed when the edit operation is canceled, but card changes are not yet discarded.
     */
    onEditCanceling?: (e: EditCancelingEvent) => void;
    /**
     * A function that is executed before a card switches to the editing state.
     */
    onEditingStart?: (e: EditingStartEvent) => void;
    /**
     * A function that is executed before a new card is added to the UI component.
     */
    onInitNewCard?: (e: InitNewCardEvent<TCardData>) => void;
    /**
     * A function that is executed after a new card is inserted into the data source.
     */
    onCardInserted?: (e: CardInsertedEvent) => void;
    /**
     * A function that is executed before a new card is inserted into the data source.
     */
    onCardInserting?: (e: CardInsertingEvent) => void;
    /**
     * A function that is executed after a card was removed from the data source.
     */
    onCardRemoved?: (e: CardRemovedEvent) => void;
    /**
     * A function that is executed before a card is removed from the data source.
     */
    onCardRemoving?: (e: CardRemovingEvent) => void;
    /**
     * A function that is executed after a card is updated in the data source.
     */
    onCardUpdated?: (e: CardUpdatedEvent) => void;
    /**
     * A function that is executed before a card is updated in the data source.
     */
    onCardUpdating?: (e: CardUpdatingEvent) => void;
    /**
     * A function that is executed after card changes are saved.
     */
    onCardSaved?: (e: CardSavedEvent) => void;
    /**
     * A function that is executed before pending card changes are saved.
     */
    onCardSaving?: (e: CardSavingEvent) => void;

    // #endregion

    // #region Selection

    /**
     * Allows you to select cards or determine which cards are selected.
     */
    selectedCardKeys?: Array<TKey>;
    /**
     * Configures runtime selection.
     */
    selection?: SelectionConfiguration;
    /**
     * A function that is executed when a card is selected or its selection is cleared.
     */
    onSelectionChanged?: (e: SelectionChangedEvent) => void;

    // #endregion

    // #region KBN

    /**
     * A function that is executed after the focused card changes.
     */
    onFocusedCardChanged?: (e: FocusedCardChanged) => void;

    // #endregion

    /**
     * A function that is executed before the context menu is rendered.
     */
    onContextMenuPreparing?: ((e: ContextMenuPreparingEvent<TCardData>) => void);
}

/**
 * CardView is a UI component that uses a &apos;card&apos; layout to present information.
 */
export default class dxCardView<TCardData = unknown, TKey = unknown> extends Widget<Properties> {
    /**
     * Gets the container of a card with a specific index.
     */
    getCardElement(cardIndex: number): DxElement;
    /**
     * Gets currently rendered cards.
     */
    getVisibleCards(): CardInfo[];
    /**
     * Gets the index of a card with a specific key.
     */
    getCardIndexByKey(key: TKey): number;
    /**
     * Gets the key of a card with a specific index.
     */
    getKeyByCardIndex(cardIndex: number): TKey;
    /**
     * Gets the instance of the UI component&apos;s scrollable part.
     */
    getScrollable(): dxScrollable;
    /**
     * Displays the load panel.
     */
    beginCustomLoading(text?: string): void;
    /**
     * Hides the load panel.
     */
    endCustomLoading(): void;
    /**
     * Clears sorting settings of all columns.
     */
    clearSorting(): void;
    /**
     * Gets the total filter that combines all the filters applied.
     */
    getCombinedFilter(): any;
    /**
     * Clears all filters applied to UI component cards.
     */
    clearFilter(): void;
    /**
     * Hides the column chooser.
     */
    hideColumnChooser(): void;
    /**
     * Shows the column chooser.
     */
    showColumnChooser(): void;
    /**
     * Searches for a string in columns whose allowSearch property is `true`.
     */
    searchByText(text: string): void;

    // #region Editing

    /**
     * Adds an empty card and switches it to the editing state.
     */
    addCard(): void;
    /**
     * Discards changes that a user made to data.
     */
    cancelEditData(): void;
    /**
     * Removes a card with a specific index.
     */
    deleteCard(cardIndex: number): void;
    /**
     * Switches a card with a specific index to the editing state.
     */
    editCard(cardIndex: number): void;
    /**
     * Checks whether the UI component has unsaved changes.
     */
    hasEditData(): void; // boolean?
    /**
     * Saves changes that a user made to data.
     */
    saveEditData(): void;

    // #endregion

    // #region DataController

    /**
      * Gets a data object with a specific key.
      */
     byKey(key: TKey): TCardData;
    /**
     * Gets the DataSource instance.
     */
    getDataSource(): DataSource<TCardData, TKey>;
    /**
     * Gets a data item&apos;s key value.
     */
    keyOf(obj: TCardData): TKey;
    /**
     * Gets the total page count.
     */
    pageCount(): number;
    /**
     * Gets the current page index.
     */
    pageIndex(): number;
    /**
     * Switches the UI component to a specific page using a zero-based index.
     */
    pageIndex(value: number): void;
    /**
     * Gets the current page size.
     */
    pageSize(): number;
    /**
     * Sets the page size.
     */
    pageSize(value: number): void;
    /**
     * Gets the total card count.
     */
    totalCount(): number;

    // #endregion

    // #region Selection

    /**
     * Selects cards with specific keys.
     */
    selectCards(keys: Array<TKey>, preserve: boolean): void;
    /**
     * Cancels the selection of cards with specific keys.
     */
    deselectCards(keys: Array<TKey>): void;
    /**
     * Selects all cards.
     */
    selectAll(): void;
    /**
     * Clears the selection of all cards on all pages or the currently rendered page only.
     */
    deselectAll(): void;
    /**
     * Clears selection of all cards on all pages.
     */
    clearSelection(): void;
    /**
     * Gets the selected cards&apos; data objects.
     */
    getSelectedCardsData(): Array<TCardData>;
    /**
     * Gets the selected card keys.
     */
    getSelectedCardKeys(): Array<TKey>;
    /**
     * Checks whether a card with a specific key is selected.
     */
    isCardSelected(key: TKey): boolean;

    // #endregion
}

// usually imported / re-exports are right after heading imports,
// plus, some of these types are already exported with direct declarations

export {
    ScrollbarMode,
    DragHighlight,
    Sorting,
    Pager,
    DataErrorOccurredInfo,
    PopupProperties,
    FormProperties,
    ColumnChooser,
    SearchPanel,
    HeaderFilter,
};

export type ExplicitTypes<TCardData = unknown, TKey = unknown> = {
    Properties: Properties<TCardData, TKey>;
};

export type Properties<TCardData = unknown, TKey = unknown> = dxCardViewOptions<TCardData, TKey>;