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

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

import type Collection from "../core/Collection.js";
import type CatalogLayer from "../layers/CatalogLayer.js";
import type Widget from "./Widget.js";
import type CatalogLayerListViewModel from "./CatalogLayerList/CatalogLayerListViewModel.js";
import type CatalogLayerListVisibleElements from "./CatalogLayerList/CatalogLayerListVisibleElements.js";
import type ListItem from "./LayerList/ListItem.js";
import type { Icon } from "@esri/calcite-components/components/calcite-icon";
import type { IdentifiableMixin, IdentifiableMixinProperties } from "../core/Identifiable.js";
import type { MapViewOrSceneView } from "../views/MapViewOrSceneView.js";
import type { WidgetProperties } from "./Widget.js";
import type { CatalogLayerListViewModelEvents, CatalogLayerListViewModelProperties } from "./CatalogLayerList/CatalogLayerListViewModel.js";
import type { Action, FilterPredicate, ListItemModifier, VisibilityAppearance } from "./LayerList/types.js";
import type { HeadingLevel } from "./support/types.js";
import type { ListItemProperties } from "./LayerList/ListItem.js";
import type { ReadonlyArrayOrCollection } from "../core/Collection.js";
import type { CatalogLayerListVisibleElementsProperties } from "./CatalogLayerList/CatalogLayerListVisibleElements.js";

export interface CatalogLayerListProperties extends WidgetProperties, IdentifiableMixinProperties, Partial<Pick<CatalogLayerList, "catalogItems" | "catalogLayer" | "collapsed" | "filterPlaceholder" | "filterPredicate" | "filterText" | "headingLevel" | "listItemCreatedFunction" | "minFilterItems" | "selectionMode" | "view" | "visibilityAppearance">> {
  /**
   * Icon which represents the widget. It is typically used when the widget is controlled by another
   * one (e.g. in the Expand widget).
   *
   * @default "catalog-dataset"
   * @see [Calcite Icon Search](https://developers.arcgis.com/calcite-design-system/icons/)
   * @since 4.27
   * @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 [ListItems](https://developers.arcgis.com/javascript/latest/references/core/widgets/LayerList/ListItem/) representing [catalogItems](https://developers.arcgis.com/javascript/latest/references/core/widgets/CatalogLayerList/#catalogItems)
   * selected by the user.
   *
   * @see [selectionMode](https://developers.arcgis.com/javascript/latest/references/core/widgets/CatalogLayerList/#selectionMode)
   * @see [catalogItems](https://developers.arcgis.com/javascript/latest/references/core/widgets/CatalogLayerList/#catalogItems)
   */
  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
   * [CatalogLayerListViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/CatalogLayerList/CatalogLayerListViewModel/) class to access
   * all properties and methods on the widget.
   */
  viewModel?: CatalogLayerListViewModelProperties;
  /**
   * 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.
   *
   * @default null
   * @example
   * catalogLayerList.visibleElements = {
   *   closeButton: false,
   *   collapseButton: true,
   *   errors: true,
   *   filter: true,
   *   heading: true,
   *   statusIndicators: true
   * };
   */
  visibleElements?: CatalogLayerListVisibleElementsProperties;
}

export interface CatalogLayerListEvents extends CatalogLayerListViewModelEvents {}

/**
 * The CatalogLayerList widget provides a way to display and interact with [CatalogLayers](https://developers.arcgis.com/javascript/latest/references/core/layers/CatalogLayer/).
 * The widget displays a list of layers in the [CatalogLayer.dynamicGroupLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/CatalogLayer/#dynamicGroupLayer) and allows you to toggle their visibility.
 *
 * The [ListItem](https://developers.arcgis.com/javascript/latest/references/core/widgets/LayerList/ListItem/) API provides access to each layer's properties, allows
 * the developer to configure actions related to the layer, and allows the developer to add content to the item related to the layer.
 *
 * ![CatalogLayerList](https://developers.arcgis.com/javascript/latest/assets/references/core/widgets/catalog-layer-list.png)
 *
 * @deprecated since version 5.0. Use the [Catalog Layer List](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-catalog-layer-list/) component 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.30
 * @see [CatalogLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/CatalogLayer/)
 * @see [CatalogLayerListViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/CatalogLayerList/CatalogLayerListViewModel/)
 * @see [LayerList.catalogLayerList](https://developers.arcgis.com/javascript/latest/references/core/widgets/LayerList/#catalogLayerList)
 * @example
 * const catalogLayerList = new CatalogLayerList({
 *   catalogLayer,
 *   view
 * });
 *
 * view.ui.add(catalogLayerList, "top-right");
 */
export default class CatalogLayerList extends CatalogLayerListSuperclass {
  /**
   * @deprecated
   * Do not directly reference this property.
   * Use EventNames and EventTypes helpers from \@arcgis/core/Evented
   */
  "@eventTypes": CatalogLayerListEvents;
  /**
   * @example
   * // typical usage
   * const catalogLayerList = new CatalogLayerList({
   *   catalogLayer,
   *   view
   * });
   *
   * view.ui.add(catalogLayerList, "top-right");
   */
  constructor(properties?: CatalogLayerListProperties);
  /**
   * The collection of [ListItems](https://developers.arcgis.com/javascript/latest/references/core/widgets/LayerList/ListItem/) representing the [CatalogLayer.dynamicGroupLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/CatalogLayer/#dynamicGroupLayer).
   *
   * @see [selectedItems](https://developers.arcgis.com/javascript/latest/references/core/widgets/CatalogLayerList/#selectedItems)
   */
  accessor catalogItems: Collection<ListItem>;
  /**
   * The [CatalogLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/CatalogLayer/) to display in the widget.
   *
   * @example catalogLayerList.catalogLayer = new CatalogLayer({ url });
   */
  accessor catalogLayer: CatalogLayer | null | undefined;
  /**
   * Indicates whether the widget is collapsed.
   * When collapsed, only the collapse button and the heading are displayed.
   *
   * @default false
   * @see [visibleElements.collapseButton](https://developers.arcgis.com/javascript/latest/references/core/widgets/CatalogLayerList/#visibleElements)
   * @example catalogLayerList.collapsed = true;
   */
  accessor collapsed: boolean;
  /**
   * Placeholder text used in the filter input if [visibleElements.filter](https://developers.arcgis.com/javascript/latest/references/core/widgets/CatalogLayerList/#visibleElements) is true.
   *
   * @default ""
   * @see [visibleElements.filter](https://developers.arcgis.com/javascript/latest/references/core/widgets/CatalogLayerList/#visibleElements)
   * @example catalogLayerList.filterPlaceholder = "Filter layers";
   */
  accessor filterPlaceholder: string;
  /**
   * Specifies a function to handle filtering [list items](https://developers.arcgis.com/javascript/latest/references/core/widgets/LayerList/ListItem/).
   *
   * @since 4.32
   * @example layerList.filterPredicate = (item) => item.title.toLowerCase().includes("streets");
   */
  accessor filterPredicate: FilterPredicate | null | undefined;
  /**
   * The value of the filter input if [visibleElements.filter](https://developers.arcgis.com/javascript/latest/references/core/widgets/CatalogLayerList/#visibleElements) is true.
   *
   * @default ""
   * @see [visibleElements.filter](https://developers.arcgis.com/javascript/latest/references/core/widgets/CatalogLayerList/#visibleElements)
   * @example
   * reactiveUtils.watch(
   *   () => catalogLayerList.filterText,
   *   (filterText) => console.log(filterText)
   * );
   */
  accessor filterText: string;
  /**
   * Indicates the heading level to use for the heading of the widget.
   * By default, the heading is rendered as a level 2 heading (e.g., `<h2>Catalog Layer 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
   * @see [visibleElements.heading](https://developers.arcgis.com/javascript/latest/references/core/widgets/CatalogLayerList/#visibleElements)
   * @example catalogLayerList.headingLevel = 3;
   */
  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 "catalog-dataset"
   * @see [Calcite Icon Search](https://developers.arcgis.com/calcite-design-system/icons/)
   * @since 4.27
   * @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);
  /**
   * A function that executes each time a [ListItem](https://developers.arcgis.com/javascript/latest/references/core/widgets/LayerList/ListItem/) is created.
   * Use this function to add actions and panels to list items, and to override
   * the default settings of a list item. Actions can be added to list items
   * using the [ListItem.actionsSections](https://developers.arcgis.com/javascript/latest/references/core/widgets/LayerList/ListItem/#actionsSections).
   *
   * @example
   * // Create a new CatalogLayerList with a listItemCreatedFunction
   * // that adds an "add-layer" action to each catalog layer list item
   * const catalogLayerList = new CatalogLayerList({
   *  catalogLayer,
   *  listItemCreatedFunction: (event) => {
   *    const { item } = event;
   *    const { layer } = item;
   *
   *    if (isLayerFromCatalog(layer)) {
   *      item.actionsSections = [
   *        [
   *          {
   *            title: "Add layer to map",
   *            icon: "add-layer",
   *            id: "add-layer"
   *          }
   *        ]
   *      ];
   *    }
   *  },
   *  view
   * });
   *
   * // Listen for the trigger-action event on the CatalogLayerListViewModel
   * // and add layers from the catalog to the map when the "add-layer" action is triggered.
   * // To correctly add a layer to the map, you must create a footprint from the layer
   * // and then create a new layer from the footprint.
   * catalogLayerList.on("trigger-action", async (event) => {
   *   const { id } = event.action;
   *   const { layer } = event.item;
   *
   *   if (id === "add-layer") {
   *     const parentCatalogLayer = catalogUtils.getCatalogLayerForLayer(layer);
   *     const footprint = parentCatalogLayer.createFootprintFromLayer(layer);
   *     const layerFromFootprint = await parentCatalogLayer.createLayerFromFootprint(footprint);
   *     map.add(layerFromFootprint);
   *   }
   * });
   */
  accessor listItemCreatedFunction: ListItemModifier | null | undefined;
  /**
   * The minimum number of list items required to display the [visibleElements.filter](https://developers.arcgis.com/javascript/latest/references/core/widgets/CatalogLayerList/CatalogLayerListVisibleElements/) input box.
   *
   * @default 10
   * @see [visibleElements.filter](https://developers.arcgis.com/javascript/latest/references/core/widgets/CatalogLayerList/CatalogLayerListVisibleElements/)
   * @example
   * layerList.visibleElements.filter = true;
   * layerList.minFilterItems = 5;
   */
  accessor minFilterItems: number;
  /**
   * A collection of selected [ListItems](https://developers.arcgis.com/javascript/latest/references/core/widgets/LayerList/ListItem/) representing [catalogItems](https://developers.arcgis.com/javascript/latest/references/core/widgets/CatalogLayerList/#catalogItems)
   * selected by the user.
   *
   * @see [selectionMode](https://developers.arcgis.com/javascript/latest/references/core/widgets/CatalogLayerList/#selectionMode)
   * @see [catalogItems](https://developers.arcgis.com/javascript/latest/references/core/widgets/CatalogLayerList/#catalogItems)
   */
  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/CatalogLayerList/#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"
   * @see [selectedItems](https://developers.arcgis.com/javascript/latest/references/core/widgets/CatalogLayerList/#selectedItems)
   * @example catalogLayerList.selectionMode = "multiple";
   */
  accessor selectionMode: "multiple" | "none" | "single" | "single-persist";
  /** A reference to the [MapView](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/) or [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/). Set this to link the widget to a specific view. */
  accessor view: MapViewOrSceneView | null | undefined;
  /**
   * 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
   * [CatalogLayerListViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/CatalogLayerList/CatalogLayerListViewModel/) class to access
   * all properties and methods on the widget.
   */
  get viewModel(): CatalogLayerListViewModel;
  set viewModel(value: CatalogLayerListViewModelProperties);
  /**
   * Determines the icons used to indicate visibility.
   *
   * | Value | Description | Example |
   * | ----- | ----------- | ------- |
   * | default | Displays view icons on the far side. Icons are hidden except on hover or if they have keyboard focus. See [view-visible](https://developers.arcgis.com/calcite-design-system/icons/?icon=view-visible&library=Calcite%20UI&query=view) and [view-hide](https://developers.arcgis.com/calcite-design-system/icons/?icon=view-hide&library=Calcite%20UI&query=view) calcite icons. | ![visibilityAppearance-default](https://developers.arcgis.com/javascript/latest/assets/references/core/widgets/layer-list/visibilityAppearance-default.png) |
   * | checkbox | Displays checkbox icons on the near side. See [check-square-f](https://developers.arcgis.com/calcite-design-system/icons/?icon=check-square-f&library=Calcite%20UI&query=check) and [square](https://developers.arcgis.com/calcite-design-system/icons/?icon=square&library=Calcite%20UI&query=square) calcite icons. | ![visibilityAppearance-checkbox](https://developers.arcgis.com/javascript/latest/assets/references/core/widgets/layer-list/visibilityAppearance-checkbox.png) |
   *
   * @default "default"
   * @example catalogLayerList.visibilityAppearance = "checkbox";
   */
  accessor visibilityAppearance: VisibilityAppearance;
  /**
   * 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.
   *
   * @default null
   * @example
   * catalogLayerList.visibleElements = {
   *   closeButton: false,
   *   collapseButton: true,
   *   errors: true,
   *   filter: true,
   *   heading: true,
   *   statusIndicators: true
   * };
   */
  get visibleElements(): CatalogLayerListVisibleElements;
  set visibleElements(value: CatalogLayerListVisibleElementsProperties);
  /**
   * Triggers the [@trigger-action](https://developers.arcgis.com/javascript/latest/references/core/widgets/CatalogLayerList/#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 CatalogLayerListSuperclass: typeof Widget & typeof IdentifiableMixin