@arcgis/core/widgets/TableList.d.ts

ArcGIS Maps SDK for JavaScript: A complete 2D and 3D mapping and data visualization API

import type WebMap from "../WebMap.js";
import type WebScene from "../WebScene.js";
import type Collection from "../core/Collection.js";
import type Widget from "./Widget.js";
import type ListItem from "./TableList/ListItem.js";
import type TableListViewModel from "./TableList/TableListViewModel.js";
import type TableListVisibleElements from "./TableList/TableListVisibleElements.js";
import type { Icon } from "@esri/calcite-components/components/calcite-icon";
import type { IdentifiableMixin, IdentifiableMixinProperties } from "../core/Identifiable.js";
import type { WidgetProperties } from "./Widget.js";
import type { Action } from "./LayerList/types.js";
import type { HeadingLevel } from "./support/types.js";
import type { TableListViewModelEvents, TableListViewModelProperties } from "./TableList/TableListViewModel.js";
import type { ListItemProperties } from "./TableList/ListItem.js";
import type { ReadonlyArrayOrCollection } from "../core/Collection.js";
import type { TableListVisibleElementsProperties } from "./TableList/TableListVisibleElements.js";

export interface TableListProperties extends WidgetProperties, IdentifiableMixinProperties, Partial<Pick<TableList, "collapsed" | "dragEnabled" | "filterPlaceholder" | "filterPredicate" | "filterText" | "headingLevel" | "listItemCreatedFunction" | "map" | "minDragEnabledItems" | "minFilterItems" | "selectionMode">> {
  /**
   * Icon which represents the widget. It is typically used when the widget is controlled by another
   * one (e.g. in the Expand widget).
   *
   * @default "table"
   * @since 4.27
   * @see [Calcite Icon Search](https://developers.arcgis.com/calcite-design-system/icons/)
   * @see [Calcite Icon Search](https://developers.arcgis.com/calcite-design-system/icons/)
   */
  icon?: Icon["icon"] | null;
  /**
   * The widget's default label.
   *
   * @since 4.11
   */
  label?: string | null;
  /**
   * A collection of selected [ListItem](https://developers.arcgis.com/javascript/latest/references/core/widgets/TableList/ListItem/)s representing table list items
   * selected by the user.
   *
   * @see [selectionMode](https://developers.arcgis.com/javascript/latest/references/core/widgets/TableList/#selectionMode)
   */
  selectedItems?: ReadonlyArrayOrCollection<ListItemProperties>;
  /**
   * The view model for this widget. This is a class that contains all the logic
   * (properties and methods) that controls this widget's behavior. See the
   * [TableListViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/TableList/TableListViewModel/) class to access
   * all properties and methods on the widget.
   */
  viewModel?: TableListViewModelProperties;
  /**
   * The visible elements that are displayed within the widget.
   * This property provides the ability to turn individual elements of the widget's display on/off.
   *
   * @since 4.25
   * @example
   * tableList.visibleElements = {
   *   closeButton: false,
   *   collapseButton: true,
   *   errors: true,
   *   filter: true,
   *   heading: true,
   *   statusIndicators: true
   * };
   */
  visibleElements?: TableListVisibleElementsProperties;
}

export interface TableListEvents extends TableListViewModelEvents {}

/**
 * The TableList widget provides a way to display a list of tables associated with a [Map](https://developers.arcgis.com/javascript/latest/references/core/Map/).
 * It is meant to be used with [feature layer](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/) tables.
 *
 * If a map contains feature layer tables, they will display within the widget. Tables can also be added to the
 * [Map.tables](https://developers.arcgis.com/javascript/latest/references/core/Map/#tables) collection. Any tables referenced in the [map](https://developers.arcgis.com/javascript/latest/references/core/widgets/TableList/#map)
 * property will display in the widget. If unsure of whether the
 * layer is a table, check the feature layer's [FeatureLayer.isTable](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/#isTable) property.
 *
 * The [ListItem](https://developers.arcgis.com/javascript/latest/references/core/widgets/TableList/ListItem/) API provides access to each table, allows
 * the developer to configure actions related to the table, and allows the developer to add content to the item related to the table.
 *
 * > [!WARNING]
 * >
 * > **Known Limitations**
 * >
 * > The TableList widget is not supported with [web scenes](https://developers.arcgis.com/javascript/latest/references/core/WebScene/).
 *
 * ![tablelist widget](https://developers.arcgis.com/javascript/latest/assets/references/core/widgets/tablelist-widget.png)
 *
 * @deprecated since version 5.0. Use the [Table List component](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-table-list/) instead. For information on widget deprecation, read about [Esri's move to web components](https://developers.arcgis.com/javascript/latest/components-transition-plan/).
 * @since 4.17
 * @see [TableListViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/TableList/TableListViewModel/)
 * @see [Map.tables](https://developers.arcgis.com/javascript/latest/references/core/Map/#tables)
 * @see [WebMap.tables](https://developers.arcgis.com/javascript/latest/references/core/WebMap/#tables)
 * @see [Sample - TableList Widget](https://developers.arcgis.com/javascript/latest/sample-code/widgets-tablelist/)
 * @example
 * const tableList = new TableList({
 *   map: map, // takes any tables associated with the map and displays in widget
 *   listItemCreatedFunction: function(event) {
 *     let item = event.item;
 *     item.actionsSections = [
 *       {
 *         title: "Show table",
 *         className: "esri-icon-table",
 *         id: "table",
 *         type: "toggle"
 *       },
 *       {
 *        title: "Layer information",
 *        className: "esri-icon-description",
 *        id: "information"
 *       }
 *     ]
 * });
 */
export default class TableList extends TableListSuperclass {
  /**
   * @deprecated
   * Do not directly reference this property.
   * Use EventNames and EventTypes helpers from \@arcgis/core/Evented
   */
  "@eventTypes": TableListEvents;
  /**
   * @example
   * // Typical usage
   * const tableList = new TableList({
   *   map: map
   * });
   */
  constructor(properties?: TableListProperties);
  /**
   * Indicates whether the widget is collapsed.
   * When collapsed, only the collapse button and heading are displayed.
   *
   * @default false
   * @since 4.29
   * @see [visibleElements.collapseButton](https://developers.arcgis.com/javascript/latest/references/core/widgets/TableList/#visibleElements)
   * @example tableList.collapsed = true;
   */
  accessor collapsed: boolean;
  /**
   * Indicates whether [list items](https://developers.arcgis.com/javascript/latest/references/core/widgets/TableList/ListItem/) may be reordered within the list by dragging and dropping.
   * Drag won't be enabled until the number of list items is equal to or greater than than the value set set in [minDragEnabledItems](https://developers.arcgis.com/javascript/latest/references/core/widgets/TableList/#minDragEnabledItems).
   *
   * @default false
   * @since 4.29
   * @see [minDragEnabledItems](https://developers.arcgis.com/javascript/latest/references/core/widgets/TableList/#minDragEnabledItems)
   * @example tableList.dragEnabled = true;
   */
  accessor dragEnabled: boolean;
  /**
   * Placeholder text used in the filter input if [visibleElements.filter](https://developers.arcgis.com/javascript/latest/references/core/widgets/TableList/#visibleElements) is true.
   *
   * @default ""
   * @since 4.29
   * @see [visibleElements.filter](https://developers.arcgis.com/javascript/latest/references/core/widgets/TableList/#visibleElements)
   * @example tableList.filterPlaceholder = "Filter layers";
   */
  accessor filterPlaceholder: string;
  /**
   * Specifies a function to handle filtering [list items](https://developers.arcgis.com/javascript/latest/references/core/widgets/TableList/ListItem/).
   *
   * @since 4.32
   * @example layerList.filterPredicate = (item) => item.title.toLowerCase().includes("streets");
   */
  accessor filterPredicate: FilterPredicate | null | undefined;
  /**
   * The value of the filter input text string if [visibleElements.filter](https://developers.arcgis.com/javascript/latest/references/core/widgets/TableList/#visibleElements) is true.
   *
   * @default ""
   * @since 4.29
   * @see [visibleElements.filter](https://developers.arcgis.com/javascript/latest/references/core/widgets/TableList/#visibleElements)
   * @example
   * reactiveUtils.watch(
   *   () => tableList.filterText,
   *   (filterText) => console.log(filterText)
   * );
   */
  accessor filterText: string;
  /**
   * Indicates the heading level to use for the [TableListVisibleElements.heading](https://developers.arcgis.com/javascript/latest/references/core/widgets/TableList/TableListVisibleElements/#heading).
   * By default, the title is rendered
   * as a level 2 heading (e.g. `<h2>Table List</h2>`). Depending on the widget's placement
   * in your app, you may need to adjust this heading for proper semantics. This is
   * important for meeting accessibility standards.
   *
   * @default 2
   */
  accessor headingLevel: HeadingLevel;
  /**
   * Icon which represents the widget. It is typically used when the widget is controlled by another
   * one (e.g. in the Expand widget).
   *
   * @default "table"
   * @since 4.27
   * @see [Calcite Icon Search](https://developers.arcgis.com/calcite-design-system/icons/)
   * @see [Calcite Icon Search](https://developers.arcgis.com/calcite-design-system/icons/)
   */
  get icon(): Icon["icon"];
  set icon(value: Icon["icon"] | null | undefined);
  /**
   * The widget's default label.
   *
   * @since 4.11
   */
  get label(): string;
  set label(value: string | null | undefined);
  /**
   * Specifies a function that accesses each [ListItem](https://developers.arcgis.com/javascript/latest/references/core/widgets/TableList/ListItem/).
   * Each list item can be modified according to its modifiable properties. Actions can be added
   * to list items using the [ListItem.actionsSections](https://developers.arcgis.com/javascript/latest/references/core/widgets/TableList/ListItem/#actionsSections)
   * property of the ListItem.
   *
   * @example
   * const tableList = new TableList({
   *   map: map,
   *   listItemCreatedFunction: (event) => {
   *     const { item } = event;
   *     item.actionsSections = [
   *       [
   *         {
   *           title: "Go to full extent",
   *           icon: "layer-zoom-to",
   *           id: "full-extent"
   *         }
   *       ]
   *     ];
   *    }
   * });
   */
  accessor listItemCreatedFunction: TableListViewModel["listItemCreatedFunction"];
  /**
   * A reference to a [Map](https://developers.arcgis.com/javascript/latest/references/core/Map/) containing the tables. Set this property
   * to access the underlying tables within the map.
   *
   * @see [Map.tables](https://developers.arcgis.com/javascript/latest/references/core/Map/#tables)
   * @see [WebMap.tables](https://developers.arcgis.com/javascript/latest/references/core/WebMap/#tables)
   * @example
   * Layer.fromPortalItem({
   *   // Loads a layer (table) from a portal item
   *   portalItem: { // autocasts new PortalItem()
   *     id: "add portal item id"
   *   }
   * }).then(function(layer) {
   *   // Load the layer
   *   layer.load().then(function() {
   *     // Check if the layer is a table
   *     if (layer.isTable) {
   *       map.tables.add(layer);
   *       console.log(map.tables);
   *     }
   *   });
   * });
   *
   * const tableList = new TableList({
   *   map: map //  map contains tables collection
   * });
   */
  accessor map: WebMap | WebScene | null | undefined;
  /**
   * The minimum number of list items required to enable drag and drop reordering with [dragEnabled](https://developers.arcgis.com/javascript/latest/references/core/widgets/TableList/#dragEnabled).
   *
   * @default 2
   * @since 4.29
   * @see [dragEnabled](https://developers.arcgis.com/javascript/latest/references/core/widgets/TableList/#dragEnabled)
   * @example
   * tableList.dragEnabled = true;
   * tableList.minDragEnabledItems = 5;
   */
  accessor minDragEnabledItems: number;
  /**
   * The minimum number of list items required to display the [visibleElements.filter](https://developers.arcgis.com/javascript/latest/references/core/widgets/TableList/TableListVisibleElements/) input box.
   *
   * @default 10
   * @since 4.29
   * @see [visibleElements.filter](https://developers.arcgis.com/javascript/latest/references/core/widgets/TableList/TableListVisibleElements/)
   * @example
   * tableList.visibleElements.filter = true;
   * tableList.minFilterItems = 5;
   */
  accessor minFilterItems: number;
  /**
   * A collection of selected [ListItem](https://developers.arcgis.com/javascript/latest/references/core/widgets/TableList/ListItem/)s representing table list items
   * selected by the user.
   *
   * @see [selectionMode](https://developers.arcgis.com/javascript/latest/references/core/widgets/TableList/#selectionMode)
   */
  get selectedItems(): Collection<ListItem>;
  set selectedItems(value: ReadonlyArrayOrCollection<ListItemProperties>);
  /**
   * Specifies the selection mode.
   * Selected items are available in the [selectedItems](https://developers.arcgis.com/javascript/latest/references/core/widgets/TableList/#selectedItems) property.
   *
   * | Value | Description |
   * | ----- | ----------- |
   * | multiple | Allows any number of items to be selected at once. This is useful when you want to apply an operation to multiple items at the same time. |
   * | none | Disables selection. Use this when you want to prevent selecting items. |
   * | single | Allows only one item to be selected at a time. If another item is selected, the previous selection is cleared. This is useful when you want to ensure that a maximum of one item is selected at a time. |
   * | single-persist | Allows only one item to be selected at a time and prevents de-selection. Once an item is selected, it remains selected until another item is selected. This is useful when you want to ensure that there is always exactly one selected item. |
   *
   * @default "none"
   * @since 4.29
   * @see [selectedItems](https://developers.arcgis.com/javascript/latest/references/core/widgets/TableList/#selectedItems)
   * @example tableList.selectionMode = "multiple";
   */
  accessor selectionMode: "multiple" | "none" | "single" | "single-persist";
  /** The collection of table [ListItem](https://developers.arcgis.com/javascript/latest/references/core/widgets/TableList/ListItem/)s displayed within the widget. */
  get tableItems(): Collection<ListItem>;
  /**
   * The view model for this widget. This is a class that contains all the logic
   * (properties and methods) that controls this widget's behavior. See the
   * [TableListViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/TableList/TableListViewModel/) class to access
   * all properties and methods on the widget.
   */
  get viewModel(): TableListViewModel;
  set viewModel(value: TableListViewModelProperties);
  /**
   * The visible elements that are displayed within the widget.
   * This property provides the ability to turn individual elements of the widget's display on/off.
   *
   * @since 4.25
   * @example
   * tableList.visibleElements = {
   *   closeButton: false,
   *   collapseButton: true,
   *   errors: true,
   *   filter: true,
   *   heading: true,
   *   statusIndicators: true
   * };
   */
  get visibleElements(): TableListVisibleElements;
  set visibleElements(value: TableListVisibleElementsProperties);
  /**
   * Triggers the [@trigger-action](https://developers.arcgis.com/javascript/latest/references/core/widgets/TableList/#event-trigger-action) event and executes
   * the given [action](https://developers.arcgis.com/javascript/latest/references/core/support/actions/ActionButton/) or
   * [action toggle](https://developers.arcgis.com/javascript/latest/references/core/support/actions/ActionToggle/).
   *
   * @param action - The action to execute.
   * @param item - An item associated with the action.
   */
  triggerAction(action: Action, item: ListItem): void;
}
declare const TableListSuperclass: typeof Widget & typeof IdentifiableMixin

/**
 * Specifies a function to handle filtering [list items](https://developers.arcgis.com/javascript/latest/references/core/widgets/TableList/ListItem/).
 *
 * @param item - A list item
 *   created by the TableList.
 */
export type FilterPredicate = (item: ListItem) => boolean;