@arcgis/map-components/dist/components/arcgis-catalog-layer-list/customElement.d.ts

ArcGIS Map Components

/// <reference path="../../index.d.ts" />
import type Collection from "@arcgis/core/core/Collection.js";
import type ListItem from "@arcgis/core/widgets/LayerList/ListItem.js";
import type CatalogLayer from "@arcgis/core/layers/CatalogLayer.js";
import type { PublicLitElement as LitElement } from "@arcgis/lumina";
import type { ArcgisReferenceElement, IconName } from "../types.js";
import type { TableSupportedLayers } from "../../utils/layer-list-utils.js";
import type { LayerListViewModelTriggerActionEvent } from "@arcgis/core/widgets/LayerList/LayerListViewModel.js";
import type { MapViewOrSceneView } from "@arcgis/core/views/MapViewOrSceneView.js";
import type { FilterPredicate, ListItemModifier, VisibilityAppearance } from "@arcgis/core/widgets/LayerList/types.js";
import type { HeadingLevel } from "@arcgis/core/widgets/support/types.js";
import type { Icon } from "@esri/calcite-components/components/calcite-icon";
import type { CatalogLayerListState } from "@arcgis/core/widgets/CatalogLayerList/types.js";

/**
 * The Catalog Layer List provides a way to display and interact with [CatalogLayers](https://developers.arcgis.com/javascript/latest/references/core/layers/CatalogLayer/).
 * The component displays a list of layers in the [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.
 *
 * @since 4.31
 * @example
 * ```js
 * const catalogLayerListElement = document.createElement("arcgis-catalog-layer-list");
 * catalogLayerListElement.referenceElement = viewElement;
 * catalogLayerListElement.slot = "top-right";
 * viewElement.appendChild(catalogLayerListElement);
 *
 * catalogLayerListElement.listItemCreatedFunction = (event) => {
 *   const { item } = event;
 *   const { layer } = item;
 *
 *   if (isLayerFromCatalog(layer)) {
 *     item.actionsSections = [
 *       [
 *         {
 *           title: "Add layer to map",
 *           icon: "add-layer",
 *           id: "add-layer"
 *         }
 *       ]
 *     ];
 *   }
 * }
 *
 * // Listen for the arcgisTriggerAction event on the CatalogLayerList
 * // 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.addEventListener("arcgisTriggerAction", 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);
 *     viewElement.map.add(layerFromFootprint);
 *   }
 * });
 * ```
 */
export abstract class ArcgisCatalogLayerList extends LitElement {
  /**
   * If true, the component will not be destroyed automatically when it is
   * disconnected from the document. This is useful when you want to move the
   * component to a different place on the page, or temporarily hide it. If this
   * is set, make sure to call the [destroy()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-catalog-layer-list/#destroy) method when you are done to
   * prevent memory leaks.
   *
   * @default false
   */
  accessor autoDestroyDisabled: boolean;
  /** A collection of ListItems representing the CatalogLayer's [dynamicGroupLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/CatalogLayer/#dynamicGroupLayer). */
  get catalogItems(): Collection<ListItem>;
  /**
   * The [CatalogLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/CatalogLayer/) to display in the component.
   *
   * @example
   * ```js
   * catalogLayerListElement.catalogLayer = new CatalogLayer({ url });
   * ```
   */
  accessor catalogLayer: CatalogLayer | null | undefined;
  /**
   * Indicates whether a component is closed. When `true`, the component will be hidden.
   *
   * @default false
   * @since 4.33
   */
  accessor closed: boolean;
  /**
   * Indicates whether the component is collapsed.
   * When collapsed, only the collapse button and the heading are displayed.
   *
   * @default false
   * @see [showCollapseButton](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-catalog-layer-list/#showCollapseButton)
   * @example
   * ```js
   * catalogLayerListElement.collapsed = true;
   * ```
   */
  accessor collapsed: boolean;
  /**
   * Placeholder text used in the filter input if [showFilter](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-catalog-layer-list/#showFilter) is true.
   *
   * @default ""
   * @see [showFilter](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-catalog-layer-list/#showFilter)
   * @example
   * ```js
   * catalogLayerListElement.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
   * ```js
   * catalogLayerListElement.filterPredicate = (item) => item.title.toLowerCase().includes("streets");
   * ```
   */
  accessor filterPredicate: FilterPredicate | null | undefined;
  /**
   * The value of the filter input if [showFilter](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-catalog-layer-list/#showFilter) is true.
   *
   * @default ""
   * @see [showFilter](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-catalog-layer-list/#showFilter)
   * @example
   * ```js
   * reactiveUtils.watch(
   *   () => catalogLayerListElement.filterText,
   *   (filterText) => console.log(filterText)
   * );
   * ```
   */
  accessor filterText: string;
  /**
   * Indicates the heading level to use for the heading of the component.
   * By default, the heading is rendered as a level 2 heading (e.g., `<h2>Catalog Layer List</h2>`).
   * Depending on the component'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 [showHeading](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-catalog-layer-list/#showHeading)
   * @example
   * ```js
   * catalogLayerListElement.headingLevel = 3;
   * ```
   */
  accessor headingLevel: HeadingLevel;
  /**
   * Indicates whether the status indicators will be displayed.
   *
   * @default false
   * @since 5.0
   */
  accessor hideStatusIndicators: boolean;
  /**
   * Icon which represents the component.
   * Typically used when the component is controlled by another component (e.g. by the Expand component).
   *
   * @default "catalog-dataset"
   * @since 4.27
   * @see [Calcite Icons](https://developers.arcgis.com/calcite-design-system/icons/)
   */
  get icon(): Icon["icon"];
  set icon(value: IconName);
  /**
   * The component's default label.
   *
   * @since 4.11
   */
  accessor label: string;
  /** @internal */
  accessor layerTablesEnabled: Collection<TableSupportedLayers>;
  /**
   * 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
   * ```js
   * catalogLayerListElement.listItemCreatedFunction = (event) => {
   *   const { item } = event;
   *   const { layer } = item;
   *
   *   if (isLayerFromCatalog(layer)) {
   *     item.actionsSections = [
   *       [
   *         {
   *           title: "Add layer to map",
   *           icon: "add-layer",
   *           id: "add-layer"
   *         }
   *       ]
   *     ];
   *   }
   * }
   * ```
   */
  accessor listItemCreatedFunction: ListItemModifier | null | undefined;
  /**
   * The minimum number of list items required to display the [showFilter](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-catalog-layer-list/#showFilter) input box.
   *
   * @default 10
   * @see [showFilter](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-catalog-layer-list/#showFilter)
   * @example
   * ```js
   * catalogLayerListElement.showFilter = true;
   * catalogLayerListElement.minFilterItems = 5;
   * ```
   */
  accessor minFilterItems: number;
  /** @internal */
  accessor onCatalogOpen: (item: ListItem) => void;
  /** @internal */
  accessor onTablesOpen: (item: ListItem) => void;
  /**
   * By assigning the `id` attribute of the Map or Scene component to this property, you can position a child component anywhere in the DOM while still maintaining a connection to the Map or Scene.
   *
   * @see [Associate components with a Map or Scene component](https://developers.arcgis.com/javascript/latest/programming-patterns/#associate-components-with-a-map-or-scene-component)
   */
  accessor referenceElement: ArcgisReferenceElement | string | undefined;
  /**
   * 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)
   */
  accessor selectedItems: Collection<ListItem>;
  /**
   * 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
   * ```js
   * catalogLayerListElement.selectionMode = "multiple";
   * ```
   */
  accessor selectionMode: "multiple" | "single" | "none" | "single-persist";
  /**
   * Indicates whether to display a close button in the header.
   *
   * @default false
   * @since 5.0
   */
  accessor showCloseButton: boolean;
  /**
   * Indicates whether to display a collapse button in the header.
   *
   * @default false
   * @since 5.0
   */
  accessor showCollapseButton: boolean;
  /**
   * Indicates whether to display layers with load errors.
   *
   * @default false
   * @since 5.0
   */
  accessor showErrors: boolean;
  /**
   * Indicates whether to display a filter input box when then number of list items is equal to or greater than the value set in [CatalogLayerList#minFilterItems](https://developers.arcgis.com/javascript/latest/references/core/widgets/CatalogLayerList/#minFilterItems), allowing users to filter layers by their title.
   *
   * @default false
   * @since 5.0
   */
  accessor showFilter: boolean;
  /**
   * Indicates whether to display the component's heading. The heading text is "Layer List". The heading level can be set with the [CatalogLayerList#headingLevel](https://developers.arcgis.com/javascript/latest/references/core/widgets/CatalogLayerList/#headingLevel).
   *
   * @default false
   * @since 5.0
   */
  accessor showHeading: boolean;
  /**
   * Indicates whether temporary layer indicators will be displayed for layers with [Layer#persistenceEnabled](https://developers.arcgis.com/javascript/latest/references/core/layers/Layer/#persistenceEnabled) set to `false`. A [temporary icon](https://developers.arcgis.com/calcite-design-system/icons/?icon=temporary&library=Calcite%20UI&query=temporary) will be displayed on the near side of the layer title.
   *
   * @default false
   * @since 5.0
   */
  accessor showTemporaryLayerIndicators: boolean;
  /**
   * The current state of the component.
   *
   * @default "disabled"
   */
  get state(): CatalogLayerListState;
  /**
   * The view associated with the component. 
   *   > **Note:** The recommended approach is to fully migrate applications to use map and scene components and avoid using MapView and SceneView directly. However, if you are migrating a large application from widgets to components, you might prefer a more gradual transition. To support this use case, the SDK includes this `view` property which connects a component to a MapView or SceneView. Ultimately, once migration is complete, the arcgis-catalog-layer-list component will be associated with a map or scene component rather than using the `view` property.
   */
  accessor view: MapViewOrSceneView | null | undefined;
  /**
   * 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.avif) |
   * | 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.avif) |
   *
   * @default "default"
   * @example
   * ```js
   * catalogLayerListElement.visibilityAppearance = "checkbox";
   * ```
   */
  accessor visibilityAppearance: VisibilityAppearance;
  /** Permanently destroy the component. */
  destroy(): Promise<void>;
  "@setterTypes": {
    icon?: IconName;
  };
  /**
   * Emitted when the component's close button is clicked.
   *
   * @since 4.33
   */
  readonly arcgisClose: import("@arcgis/lumina").TargetedEvent<this, void>;
  /** Emitted when the value of a property is changed. Use this to listen to changes to properties. */
  readonly arcgisPropertyChange: import("@arcgis/lumina").TargetedEvent<this, { name: "state"; }>;
  /** Emitted when the component associated with a map or scene view is ready to be interacted with. */
  readonly arcgisReady: import("@arcgis/lumina").TargetedEvent<this, void>;
  /** Emitted when an action is triggered on the component. */
  readonly arcgisTriggerAction: import("@arcgis/lumina").TargetedEvent<this, LayerListViewModelTriggerActionEvent>;
  readonly "@eventTypes": {
    arcgisClose: ArcgisCatalogLayerList["arcgisClose"]["detail"];
    arcgisPropertyChange: ArcgisCatalogLayerList["arcgisPropertyChange"]["detail"];
    arcgisReady: ArcgisCatalogLayerList["arcgisReady"]["detail"];
    arcgisTriggerAction: ArcgisCatalogLayerList["arcgisTriggerAction"]["detail"];
  };
}