@arcgis/core/widgets/LayerList/ListItem.d.ts

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

import type Accessor from "../../core/Accessor.js";
import type Collection from "../../core/Collection.js";
import type EsriError from "../../core/Error.js";
import type Layer from "../../layers/Layer.js";
import type SubtypeGroupLayer from "../../layers/SubtypeGroupLayer.js";
import type Sublayer from "../../layers/support/Sublayer.js";
import type SubtypeSublayer from "../../layers/support/SubtypeSublayer.js";
import type LayerView from "../../views/layers/LayerView.js";
import type ListItemPanel from "./ListItemPanel.js";
import type { IdentifiableMixin, IdentifiableMixinProperties } from "../../core/Identifiable.js";
import type { MapViewOrSceneView } from "../../views/MapViewOrSceneView.js";
import type { StreamLayerViewConnectionStatus } from "../../views/layers/StreamLayerView.js";
import type { Action } from "./types.js";
import type { ActionToggleProperties } from "../../support/actions/ActionToggle.js";
import type { ActionButtonProperties } from "../../support/actions/ActionButton.js";
import type { ReadonlyArrayOrCollection } from "../../core/Collection.js";
import type { ListItemPanelProperties } from "./ListItemPanel.js";

export interface ListItemProperties extends IdentifiableMixinProperties, Partial<Pick<ListItem, "actionsOpen" | "childrenSortable" | "hidden" | "layer" | "listModeDisabled" | "open" | "parent" | "sortable" | "view" | "visible">> {
  /**
   * A nested 2-dimensional collection of actions that could be triggered on the item.
   *
   * @see [Sample - LayerList widget with actions](https://developers.arcgis.com/javascript/latest/sample-code/widgets-layerlist-actions/)
   */
  actionsSections?: ReadonlyArrayOrCollection<ReadonlyArrayOrCollection<((ActionButtonProperties & { type: "button" }) | (ActionToggleProperties & { type: "toggle" }))>>;
  /** When a layer contains sublayers, this property is a Collection of ListItem objects belonging to the given layer. */
  children?: ReadonlyArrayOrCollection<ListItemProperties>;
  /**
   * Allows you to display custom content for each ListItem
   * in the [LayerList](https://developers.arcgis.com/javascript/latest/references/core/widgets/LayerList/) widget.
   *
   * A common scenario for using ListItemPanel is to display a [Legend](https://developers.arcgis.com/javascript/latest/references/core/widgets/Legend/) widget within
   * each list item. The `legend` keyword can be used in the [ListItemPanel.content](https://developers.arcgis.com/javascript/latest/references/core/widgets/LayerList/ListItemPanel/#content)
   * property to display a legend for each layer in the LayerList.
   *
   * @since 4.7
   * @example
   * // displays the legend for each layer list item
   * const layerList = new LayerList({
   *   view: view,
   *   listItemCreatedFunction: function(event){
   *     const item = event.item;
   *     item.panel = {
   *       content: "legend"
   *     };
   *   }
   * });
   * @example
   * // displays content from the DOM in the LayerList
   * const layerList = new LayerList({
   *   view: view,
   *   listItemCreatedFunction: function(event){
   *     const item = event.item;
   *     item.panel = {
   *       content: document.getElementById("myDiv"),
   *       icon: "pie-chart",
   *       open: item.visible
   *     };
   *   }
   * });
   */
  panel?: ListItemPanelProperties;
  /** The title of the layer. */
  title?: string | null;
}

/**
 * Represents a layer view that supports spatial referencing. Used to indicate whether the
 * associated layer view can operate with a spatial reference in the current view context.
 *
 * @since 5.0
 * @see [layerView](https://developers.arcgis.com/javascript/latest/references/core/widgets/LayerList/ListItem/#layerView)
 */
export interface SpatiallyReferencedLayerView extends LayerView {
  /**
   * Indicates if the layer view supports the current spatial reference.
   *
   * @since 5.0
   */
  spatialReferenceSupported: boolean;
}

/**
 * Represents a layer view for stream layers that provides connection status information.
 * Used to determine the current connection state of a stream layer in the view.
 *
 * @since 5.0
 * @see [connectionStatus](https://developers.arcgis.com/javascript/latest/references/core/widgets/LayerList/ListItem/#connectionStatus)
 */
export interface ConnectedLayerView extends LayerView {
  /**
   * The current connection status of the stream layer view.
   *
   * @since 5.0
   */
  connectionStatus: StreamLayerViewConnectionStatus;
}

/**
 * Defines how the visibility of child layers is managed within a list item.
 *
 * - `independent`: Each child layer's visibility is controlled separately.
 * - `inherited`: Child layers inherit the visibility from their parent layer.
 * - `exclusive`: Only one child layer can be visible at a time.
 *
 * @see [visibilityMode](https://developers.arcgis.com/javascript/latest/references/core/widgets/LayerList/ListItem/#visibilityMode)
 */
export type ListItemVisibilityMode = "independent" | "inherited" | "exclusive";

/**
 * The ListItem class represents one of the [LayerListViewModel.operationalItems](https://developers.arcgis.com/javascript/latest/references/core/widgets/LayerList/LayerListViewModel/#operationalItems).
 * In the [LayerList](https://developers.arcgis.com/javascript/latest/references/core/widgets/LayerList/) widget UI, the list item represents a layer displayed in the view.
 * It provides access to the associated 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.
 *
 * To hide list items in the LayerList widget, you must set the
 * [Layer.listMode](https://developers.arcgis.com/javascript/latest/references/core/layers/Layer/#listMode) property to `hide` on the desired layers.
 * You cannot hide list items using this class or the [LayerList](https://developers.arcgis.com/javascript/latest/references/core/widgets/LayerList/) class.
 *
 * @since 4.2
 * @see [LayerListViewModel.operationalItems](https://developers.arcgis.com/javascript/latest/references/core/widgets/LayerList/LayerListViewModel/#operationalItems)
 * @see [LayerListViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/LayerList/LayerListViewModel/)
 */
export default class ListItem extends ListItemSuperclass {
  constructor(properties?: ListItemProperties);
  /**
   * Whether the actions panel is open in the LayerList.
   *
   * @default false
   */
  accessor actionsOpen: boolean;
  /**
   * A nested 2-dimensional collection of actions that could be triggered on the item.
   *
   * @see [Sample - LayerList widget with actions](https://developers.arcgis.com/javascript/latest/sample-code/widgets-layerlist-actions/)
   */
  get actionsSections(): Collection<Collection<Action>>;
  set actionsSections(value: ReadonlyArrayOrCollection<ReadonlyArrayOrCollection<((ActionButtonProperties & { type: "button" }) | (ActionToggleProperties & { type: "toggle" }))>>);
  /** When a layer contains sublayers, this property is a Collection of ListItem objects belonging to the given layer. */
  get children(): Collection<ListItem>;
  set children(value: ReadonlyArrayOrCollection<ListItemProperties>);
  /**
   * Indicates if the children of a list item (or sublayers in a GroupLayer) can be sorted or moved/reordered.
   *
   * @default true
   * @since 4.16
   * @example
   * // disables the children of a parent list item from being sorted
   * listItem.childrenSortable = false;
   */
  accessor childrenSortable: boolean;
  /**
   * Only valid when the list item represents a [StreamLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/StreamLayer/). Indicates
   * the [StreamLayerView.connectionStatus](https://developers.arcgis.com/javascript/latest/references/core/views/layers/StreamLayerView/#connectionStatus) of the stream layer connection.
   * This overrides the [updating](https://developers.arcgis.com/javascript/latest/references/core/widgets/LayerList/ListItem/#updating) property.
   *
   * Starting at version 4.27, a green [beacon](https://developers.arcgis.com/calcite-design-system/icons/?icon=beacon&library=Calcite%20UI&query=beacon)
   * icon will appear next to the list item title when a stream layer is `connected`.
   * Prior to version 4.27, when a stream layer is `connected` a green calcite [check-circle](https://developers.arcgis.com/calcite-design-system/icons/?icon=check-circle&library=Calcite%20UI&query=check-cir)
   * icon will appear next to the list item title.
   *
   * When a stream layer is `disconnected` an orange calcite [offline](https://developers.arcgis.com/calcite-design-system/icons/?library=Calcite%20UI&query=offline)
   * icon will display next to the list item title.
   *
   * Starting at version 4.26, the [StreamLayerView.connectionStatus](https://developers.arcgis.com/javascript/latest/references/core/views/layers/StreamLayerView/#connectionStatus)
   * can be `paused`. This also results in displaying an orange offline icon next to the list item title.
   *
   * @since 4.24
   */
  get connectionStatus(): ConnectedLayerView["connectionStatus"] | null | undefined;
  /** The Error object returned if an error occurred. */
  get error(): EsriError | null | undefined;
  /**
   * When `true`, hides the layer from the LayerList instance. This is an alternative to
   * [Layer.listMode](https://developers.arcgis.com/javascript/latest/references/core/layers/Layer/#listMode), which hides
   * a layer from all instances of LayerList that include the layer.
   *
   * @default false
   * @since 4.24
   * @example
   * let layerList1 = new LayerList({
   *   view,
   *   container: layerList1Container,
   *   listItemCreatedFunction: (event) => {
   *     // hides the USA - Highway layer from the
   *     // layerList1 instance of layerlist
   *     if(event.item.title === "USA - Highways") {
   *       event.item.hidden = true;
   *     }
   *   }
   * });
   */
  accessor hidden: boolean;
  /**
   * Whether the layer is unsupported by the view.
   *
   * @default false
   * @since 4.32
   */
  get incompatible(): boolean;
  /** The layer associated with the triggered action. */
  accessor layer: Layer | Sublayer | SubtypeSublayer | SubtypeGroupLayer | null | undefined;
  /**
   * The [LayerView](https://developers.arcgis.com/javascript/latest/references/core/views/layers/LayerView/) displaying data for the
   * associated [layer](https://developers.arcgis.com/javascript/latest/references/core/widgets/LayerList/ListItem/#layer).
   */
  get layerView(): LayerView | SpatiallyReferencedLayerView | ConnectedLayerView | null | undefined;
  /**
   * Specifies whether to ignore the [Layer.listMode](https://developers.arcgis.com/javascript/latest/references/core/layers/Layer/#listMode) property of the child layers in the list item.
   * A common use case for `listModeDisabled` is when you want to use the [LayerList](https://developers.arcgis.com/javascript/latest/references/core/widgets/LayerList/)
   * or [BasemapLayerList](https://developers.arcgis.com/javascript/latest/references/core/widgets/BasemapLayerList/) to manage and configure a layer's `listMode` value.
   *
   * @default false
   * @since 4.30
   * @see [Layer.listMode](https://developers.arcgis.com/javascript/latest/references/core/layers/Layer/#listMode)
   */
  accessor listModeDisabled: boolean;
  /**
   * Whether the layer is open in the LayerList.
   *
   * @default false
   */
  accessor open: boolean;
  /**
   * Allows you to display custom content for each ListItem
   * in the [LayerList](https://developers.arcgis.com/javascript/latest/references/core/widgets/LayerList/) widget.
   *
   * A common scenario for using ListItemPanel is to display a [Legend](https://developers.arcgis.com/javascript/latest/references/core/widgets/Legend/) widget within
   * each list item. The `legend` keyword can be used in the [ListItemPanel.content](https://developers.arcgis.com/javascript/latest/references/core/widgets/LayerList/ListItemPanel/#content)
   * property to display a legend for each layer in the LayerList.
   *
   * @since 4.7
   * @example
   * // displays the legend for each layer list item
   * const layerList = new LayerList({
   *   view: view,
   *   listItemCreatedFunction: function(event){
   *     const item = event.item;
   *     item.panel = {
   *       content: "legend"
   *     };
   *   }
   * });
   * @example
   * // displays content from the DOM in the LayerList
   * const layerList = new LayerList({
   *   view: view,
   *   listItemCreatedFunction: function(event){
   *     const item = event.item;
   *     item.panel = {
   *       content: document.getElementById("myDiv"),
   *       icon: "pie-chart",
   *       open: item.visible
   *     };
   *   }
   * });
   */
  get panel(): ListItemPanel;
  set panel(value: ListItemPanelProperties);
  /**
   * The parent of this item
   *
   * @since 4.5
   */
  accessor parent: ListItem | null | undefined;
  /**
   * Value is `true` when the [layer](https://developers.arcgis.com/javascript/latest/references/core/widgets/LayerList/ListItem/#layer) is being published.
   * Value will be `false` if the [layer](https://developers.arcgis.com/javascript/latest/references/core/widgets/LayerList/ListItem/#layer) is not being published or
   * [LayerListViewModel.checkPublishStatusEnabled](https://developers.arcgis.com/javascript/latest/references/core/widgets/LayerList/LayerListViewModel/#checkPublishStatusEnabled)
   * is `false`.
   *
   * @default false
   * @since 4.25
   */
  get publishing(): boolean;
  /**
   * Indicates if the list item (or layer in the map) can be sorted or moved/reordered.
   *
   * @default true
   * @since 4.16
   * @example
   * // disables the list item from being sorted
   * listItem.sortable = false;
   */
  accessor sortable: boolean;
  /** The title of the layer. */
  get title(): string;
  set title(value: string | null | undefined);
  /**
   * Value is `true` when the layer is updating; for example, if it is in the process of fetching data.
   *
   * @default false
   */
  get updating(): boolean;
  /** The view from which the widget will operate. */
  accessor view: MapViewOrSceneView | null | undefined;
  /** Indicates how to manage the visibility of the children layers. */
  get visibilityMode(): ListItemVisibilityMode;
  /**
   * Indicates if the ListItem is visible.
   *
   * @default true
   */
  accessor visible: boolean;
  /**
   * Whether the layer is visible at the current scale or not.
   *
   * @default true
   */
  get visibleAtCurrentScale(): boolean;
  /**
   * Whether the layer is visible at the current time extent or not.
   *
   * @default true
   * @since 4.30
   */
  get visibleAtCurrentTimeExtent(): boolean;
  /**
   * Creates a deep clone of this object.
   *
   * @returns A clone of the new [ListItem](https://developers.arcgis.com/javascript/latest/references/core/widgets/LayerList/ListItem/) instance.
   */
  clone(): ListItem;
}
declare const ListItemSuperclass: typeof Accessor & typeof IdentifiableMixin