@arcgis/map-components 5.2.0-next.15 → 5.2.0-next.150

package/dist/components/arcgis-selection-toolbar/customElement.d.ts

@@ -0,0 +1,513 @@
+/// <reference path="../../index.d.ts" />
+import type SelectionOperation from "@arcgis/core/views/selection/SelectionOperation.js";
+import type SelectionManager from "@arcgis/core/views/SelectionManager.js";
+import type { SelectionToolbarViewModelEvents } from "@arcgis/core/widgets/support/SelectionToolbar/SelectionToolbarViewModel.js";
+import type { SelectionOperationProperties } from "@arcgis/core/views/selection/SelectionOperation.js";
+import type { SelectionOperationType, SelectionToolName, SelectableViewUnion, SelectionSource } from "@arcgis/core/views/selection/types.js";
+import type { PublicLitElement as LitElement } from "@arcgis/lumina";
+import type { ArcgisReferenceElement, IconName } from "../types.js";
+import type { T9nMeta } from "@arcgis/lumina/controllers";
+import type { SelectionToolConfig } from "@arcgis/core/widgets/support/SelectionToolbar/types.js";
+import type { Action as Action } from "@esri/calcite-components/components/calcite-action";
+
+/**
+ * The selection toolbar component can be used to modify selected features on a provided [MapView](/references/core/views/MapView/) or [SceneView](/references/core/views/SceneView/). It provides an interface for performing [selection operations](/references/core/views/selection/SelectionOperation/) such as adding, removing, or replacing selected features.
+ * This component can be used in conjunction with other components. Examples such as [arcgis-selection-list](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-selection-list/) and [arcgis-feature-table](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-feature-table/).
+ *
+ * @since 5.2
+ */
+export abstract class ArcgisSelectionToolbar extends LitElement {
+  /**
+   * A reference to the active [selection operation](/references/core/views/selection/SelectionOperation/). Only one selection operation can be active at a time.
+   *
+   * @since 5.2
+   */
+  get activeOperation(): SelectionOperation | null | undefined;
+  /**
+   * 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-selection-toolbar/#destroy) method when you are done to
+   * prevent memory leaks.
+   *
+   * @default false
+   * @example
+   * ```html
+   * <arcgis-selection-toolbar auto-destroy-disabled></arcgis-selection-toolbar>
+   * ```
+   *
+   * ```js
+   * selectionToolbarElement.autoDestroyDisabled = true;
+   * ```
+   * 
+   */
+  accessor autoDestroyDisabled: boolean;
+  /**
+   * An array of [selection operation type](/references/core/views/selection/types/#SelectionOperationType) names that determines what operation types appear in the associated dropdown component.
+   *
+   * @since 5.2
+   */
+  accessor availableOperationTypes: SelectionOperationType[];
+  /**
+   * Determines if the selection toolbar should automatically reactivate a new [selection operation](/references/core/views/selection/SelectionOperation/) after the completion of an active [selection operation](/references/core/views/selection/SelectionOperation/), using options from the previous operation.
+   * This only applies if the previous [selection operation](/references/core/views/selection/SelectionOperation/) was completed, and not canceled.
+   *
+   * @default false
+   * @since 5.2
+   */
+  accessor continuousSelectionEnabled: boolean;
+  /**
+   * The default configuration for the lasso tool.
+   *
+   * @since 5.2
+   */
+  accessor defaultLassoToolOptions: SelectionOperationProperties;
+  /**
+   * The default [selection operation type](/references/core/views/selection/types/#SelectionOperationType) to use when starting a new [selection operation](/references/core/views/selection/SelectionOperation/).
+   * This value can be changed via the [selection operation type](/references/core/views/selection/types/#SelectionOperationType) dropdown.
+   *
+   * @default "add"
+   * @since 5.2
+   */
+  accessor defaultOperationType: SelectionOperationType;
+  /**
+   * The default configuration for the point tool.
+   *
+   * @since 5.2
+   */
+  accessor defaultPointToolOptions: SelectionOperationProperties;
+  /**
+   * The default configuration for the polygon tool.
+   *
+   * @since 5.2
+   */
+  accessor defaultPolygonToolOptions: SelectionOperationProperties;
+  /**
+   * The default configuration for the rectangle tool.
+   *
+   * @since 5.2
+   */
+  accessor defaultRectangleToolOptions: SelectionOperationProperties;
+  /**
+   * When true, the component is visually de-emphasized and does not accept user interaction.
+   *
+   * @default false
+   */
+  accessor disabled: boolean;
+  /**
+   * A reference to the [selection manager](/references/core/views/SelectionManager/)  currently in use by the component.
+   *
+   * @since 5.2
+   */
+  get effectiveSelectionManager(): SelectionManager | null | undefined;
+  /**
+   * An array of validated [selection sources](/references/core/views/selection/types/#SelectionSource/). These sources will also include any relevant [layer views](/references/core/views/layers/LayerView/) that were found on the provided view if [layerPreferenceEnabled](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-selection-toolbar/#layerPreferenceEnabled) is `false`.
+   *
+   * @since 5.2
+   */
+  get effectiveSources(): Array<SelectionSource>;
+  /**
+   * Indicates whether the selection count chip should be hidden. The chip shows the total
+   * count of selected features and a `close` button for clearing the selection.
+   *
+   * @default false
+   * @since 5.2
+   */
+  accessor hideChip: boolean;
+  /**
+   * Indicates whether the 'close' button on the selection count chip should be hidden.
+   * The 'close' button allows users to clear the current selection.
+   *
+   * @default false
+   * @since 5.2
+   */
+  accessor hideChipCloseButton: boolean;
+  /**
+   * Indicates whether the lasso tool should be hidden. The lasso tool allows for freehand selection of features.
+   *
+   * @default false
+   * @since 5.2
+   */
+  accessor hideLassoTool: boolean;
+  /**
+   * Indicates whether the [selection operation type](/references/core/views/selection/types/#SelectionOperationType) controls should be hidden. The operation type controls
+   * allow for changing the selection operation type (e.g., `replace`, `add`, `remove`).
+   *
+   * @default false
+   * @since 5.2
+   */
+  accessor hideOperationTypeControls: boolean;
+  /**
+   * Indicates whether the pan tool is hidden. The pan tool allows users
+   * to navigate the view without initiating a [selection operation](/references/core/views/selection/SelectionOperation/) and
+   * is active by default when no [selection operation](/references/core/views/selection/SelectionOperation/) is in progress.
+   *
+   * @default false
+   * @since 5.2
+   */
+  accessor hidePanTool: boolean;
+  /**
+   * Indicates whether the point tool should be hidden. The point tool allows for selecting features by clicking on them.
+   * The point tool will include all features that intersect the selected point, rather than only the top-most feature.
+   *
+   * @default false
+   * @since 5.2
+   */
+  accessor hidePointTool: boolean;
+  /**
+   * Indicates whether the polygon tool should be hidden. The polygon tool allows for selecting features
+   * by drawing a polygon.
+   *
+   * @default false
+   * @since 5.2
+   */
+  accessor hidePolygonTool: boolean;
+  /**
+   * Indicates whether the progress indicator should be hidden.
+   *
+   * The progress indicator shows when a [selection operation](/references/core/views/selection/SelectionOperation/) is processing results. The processing time can vary depending on the potential number of selected
+   * features, or whether the [selection operation](/references/core/views/selection/SelectionOperation/) is querying source layers or [layer views](/references/core/views/layers/LayerView/) for results.
+   *
+   * @default false
+   * @since 5.2
+   */
+  accessor hideProgress: boolean;
+  /**
+   * Indicates whether the rectangle selection tool is hidden. The
+   * rectangle tool allows users to select features by drawing a
+   * rectangular area.
+   *
+   * @default false
+   * @since 5.2
+   */
+  accessor hideRectangleTool: boolean;
+  /**
+   * Icon which represents the component.
+   * Typically used when the component is controlled by another component (e.g. by the Expand component).
+   *
+   * @default "selection-set"
+   * @see [Calcite Icons](https://developers.arcgis.com/calcite-design-system/icons/)
+   */
+  accessor icon: IconName | undefined;
+  /** The component's default label. */
+  accessor label: string | undefined;
+  /**
+   * Indicates whether [selection operations](/references/core/views/selection/SelectionOperation/) should always query source layers rather than their associated [layer views](/references/core/views/layers/LayerView/) when determining selection results. Querying the source layer may be necessary when the most up-to-date feature data is required. Changing this property while a [selection operation](/references/core/views/selection/SelectionOperation/) is in progress will not affect the active operation. The change will apply only to subsequent operations.
+   *
+   * @default false
+   * @since 5.2
+   */
+  accessor layerPreferenceEnabled: boolean;
+  /**
+   * Controls the orientation of the component.
+   *
+   * @default "horizontal"
+   * @internal
+   */
+  accessor layout: "horizontal" | "vertical";
+  /**
+   * Localized strings.
+   *
+   * @internal
+   */
+  protected messages: Partial<{
+      componentLabel: string;
+      add: string;
+      addToSelection: string;
+      clearSelection: string;
+      clearSelectionCount: string;
+      countTruncated: string;
+      lasso: string;
+      pan: string;
+      polygon: string;
+      point: string;
+      processing: string;
+      rectangle: string;
+      remove: string;
+      removeFromSelection: string;
+      replace: string;
+      replaceSelection: string;
+      selectFeatures: string;
+      selectByLasso: string;
+      selectByPolygon: string;
+      selectByPoint: string;
+      selectByRectangle: string;
+      selectionCount: string;
+  }> & T9nMeta<{
+      componentLabel: string;
+      add: string;
+      addToSelection: string;
+      clearSelection: string;
+      clearSelectionCount: string;
+      countTruncated: string;
+      lasso: string;
+      pan: string;
+      polygon: string;
+      point: string;
+      processing: string;
+      rectangle: string;
+      remove: string;
+      removeFromSelection: string;
+      replace: string;
+      replaceSelection: string;
+      selectFeatures: string;
+      selectByLasso: string;
+      selectByPolygon: string;
+      selectByPoint: string;
+      selectByRectangle: string;
+      selectionCount: string;
+  }>;
+  /**
+   * 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;
+  /**
+   * Determines whether selected features include the fields required to
+   * display feature titles as defined by the [web map](/references/core/WebMap/).
+   *
+   * When enabled, these fields are available on features returned by selection
+   * events. They are not stored in the [selection manager](/references/core/views/SelectionManager/),
+   * which stores only selected feature Object IDs.
+   *
+   * Enabling this property may require additional queries and can affect
+   * selection performance.
+   *
+   * @default false
+   * @since 5.2
+   */
+  accessor returnFeatureTitleFields: boolean;
+  /**
+   * Indicates whether to omit feature geometries from features returned by
+   * selection events. Disable this property when selected feature geometries
+   * are needed by an application.
+   *
+   * Geometries are not stored in the [selection manager](/references/core/views/SelectionManager/), which stores only selected feature Object IDs.
+   *
+   * Disabling geometry results may improve selection performance when geometries are not needed.
+   *
+   * @default false
+   * @since 5.2
+   */
+  accessor returnGeometryDisabled: boolean;
+  /**
+   * A reference to a custom [selection manager](/references/core/views/SelectionManager/) to use instead of the [view's default selection manager](/references/core/views/View/#selectionManager).
+   *
+   * > [!NOTE]
+   * > When using a custom selection manager, ensure its
+   * > [sources](/references/core/views/SelectionManager/#sources) include the
+   * > layers and tables that should participate in a selection. Call
+   * > [syncSources()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-selection-toolbar/#syncSources) after adding or removing layers
+   * > from the view.
+   *
+   * @since 5.2
+   */
+  accessor selectionManager: SelectionManager | null | undefined;
+  /**
+   * Indicates text labels should be displayed next to each tool.
+   *
+   * @default false
+   * @internal
+   */
+  accessor showTextLabels: boolean;
+  /**
+   * An array of layers or [layer views](/references/core/views/layers/LayerView/) used to determine the selection.
+   *
+   * @since 5.2
+   */
+  accessor sources: Array<SelectionSource> | null | undefined;
+  /**
+   * Reflects the current operational state of the selection toolbar.
+   *
+   * @since 5.2
+   */
+  get state(): "active" | "disabled" | "ready";
+  /**
+   * Indicates whether results from new [selection operations](/references/core/views/selection/SelectionOperation/) are automatically synchronized with the associated [selection manager](/references/core/views/SelectionManager/). When set to `false`, events emitted by the selection-toolbar will still include the updated selection results, but the associated [selection manager](/references/core/views/SelectionManager/) will not be updated when the [selection operation](/references/core/views/selection/SelectionOperation/) completes.
+   *
+   * @default false
+   * @since 5.2
+   */
+  accessor syncResultsDisabled: boolean;
+  /**
+   * Indicates whether the [selection operation](/references/core/views/selection/SelectionOperation/) continuously evaluates the potential
+   * selection while the associated draw tool is active and emits updates through events.
+   * When set to `false`, the selection is evaluated only once after drawing is complete.
+   *
+   * Potential selection results are not stored or reflected by the associated [selection manager](/references/core/views/SelectionManager/). Set this property to `true` to receive continuous updates to the working
+   * selection set, such as for highlighting potential features while drawing. This
+   * property does not control whether the final selection results are stored by the
+   * [selection manager](/references/core/views/SelectionManager/); use [syncResultsDisabled](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-selection-toolbar/#syncResultsDisabled) for that
+   * behavior.
+   *
+   * @default false
+   * @since 5.2
+   */
+  accessor syncWhileDrawing: boolean;
+  /**
+   * An array of configurations for custom selection tools to display in the component UI.
+   *
+   * @since 5.2
+   * @internal
+   */
+  accessor toolConfigs: Array<SelectionToolConfig>;
+  /**
+   * 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-selection-toolbar component will be associated with a map or scene component rather than using the `view` property.
+   */
+  accessor view: SelectableViewUnion | null | undefined;
+  /**
+   * Controls the scale of any rendered [Calcite](https://developers.arcgis.com/calcite-design-system/components) elements.
+   *
+   * @default "m"
+   * @since 5.2
+   */
+  accessor visualScale: Action["scale"];
+  /**
+   * Activates the specified tool using the provided options and cancels any active [selection operation](/references/core/views/selection/SelectionOperation/). This method has no effect when the toolbar is disabled.
+   *
+   * @param options - Optional tool and operation configuration.
+   * @returns A promise that resolves to the active [selection operation](/references/core/views/selection/SelectionOperation/), or `undefined` if activation was blocked.
+   * @since 5.2
+   * @example
+   * // Once the selection-toolbar is ready, activate the lasso tool and "replace" operation type
+   *
+   * ```js
+   * const viewElement = document.querySelector("arcgis-map");
+   * const selectionToolbar = document.querySelector("arcgis-selection-toolbar");
+   * await viewElement.viewOnReady();
+   * await selectionToolbar.componentOnReady();
+   * await selectionToolbar.activate({
+   *   toolName: "lasso",
+   *   type: "replace"
+   * });
+   * ```
+   */
+  activate(options?: SelectionOperationProperties): Promise<SelectionOperation | undefined>;
+  /**
+   * Activates the specified tool by name and cancels any [selection operation](/references/core/views/selection/SelectionOperation/). This method has no effect when the toolbar is disabled.
+   *
+   * @param toolName - The name of the tool to activate.
+   * @returns A promise that resolves to the active [selection operation](/references/core/views/selection/SelectionOperation/), or `undefined` if activation was blocked.
+   * @since 5.2
+   * @example
+   * // Once the selection-toolbar is ready, activate the rectangle tool
+   * ```js
+   * const viewElement = document.querySelector("arcgis-map");
+   * const selectionToolbar = document.querySelector("arcgis-selection-toolbar");
+   * await viewElement.viewOnReady();
+   * await selectionToolbar.componentOnReady();
+   * await selectionToolbar.activateTool("rectangle");
+   * ```
+   */
+  activateTool(toolName: SelectionToolName): Promise<SelectionOperation | undefined>;
+  /**
+   * Cancels any active operation and, when applicable, emits a [complete](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-selection-toolbar/#event-arcgisComplete) event. The event includes an [aborted](/references/core/views/selection/types/#SelectionCompleteEventInfo-aborted) property that indicates whether the operation was canceled.
+   *
+   * @since 5.2
+   */
+  cancel(): Promise<void>;
+  /** Permanently destroy the component. */
+  destroy(): Promise<void>;
+  /**
+   * Synchronizes the effective [selection manager](/references/core/views/SelectionManager/)
+   * with the current layers and tables in the view.
+   *
+   * Call this method after adding or removing layers or tables from the view,
+   * especially when using a custom [selection manager](/references/core/views/SelectionManager/). Newly added [sources](/references/core/views/SelectionManager/#sources)
+   * are otherwise excluded from selection results.
+   *
+   * This method has no effect if the effective [selection manager](/references/core/views/SelectionManager/)
+   * does not have an assigned view.
+   *
+   * @since 5.2
+   */
+  syncSources(): Promise<void>;
+  /**
+   * Toggles the active state of the specified tool. If
+   * the tool is currently active, it is canceled.
+   * Otherwise, the tool is activated after canceling
+   * any active [selection operation](/references/core/views/selection/SelectionOperation/).
+   *
+   * @param toolName - The name of the tool to toggle.
+   * @returns A promise that resolves to the active [selection operation](/references/core/views/selection/SelectionOperation/) if the associated tool was toggled on, or `undefined` if the tool was toggled off.
+   * @since 5.2
+   */
+  toggleTool(toolName: SelectionToolName): Promise<SelectionOperation | undefined>;
+  /**
+   * Fires before any [selection operation](/references/core/views/selection/SelectionOperation/) is activated.
+   *
+   * @since 5.2
+   * @example
+   * ```js
+   * const toolbar = document.querySelector("my-selection-toolbar");
+   * toolbar.addEventListener("arcgisBeforeActivate", (event) => {
+   *   const { toolName } = event.detail;
+   *   console.log("Starting selection tool:", toolName);
+   * });
+   * ```
+   */
+  readonly arcgisBeforeActivate: import("@arcgis/lumina").TargetedEvent<this, SelectionToolbarViewModelEvents["before-activate"]>;
+  /**
+   * Fires when the active selection is cleared via the close button on the selection count chip.
+   * This event does not fire when the selection is cleared programmatically, or when the selection is
+   * cleared by a different component. For more information about selection changes, use the
+   * 'selection-change' event emitted by the associated [selection manager](/references/core/views/SelectionManager/).
+   *
+   * @since 5.2
+   */
+  readonly arcgisClear: import("@arcgis/lumina").TargetedEvent<this, void>;
+  /**
+   * Fires when the [selection operation](/references/core/views/selection/SelectionOperation/) is complete
+   * or canceled and results have been processed.
+   *
+   * @since 5.2
+   * @example
+   * ```js
+   * const toolbar = document.querySelector("my-selection-toolbar");
+   * toolbar.addEventListener("arcgisComplete", (event) => {
+   *   const { aborted, selection, operationType, toolName } = event.detail;
+   *   console.log("Selection complete:", {
+   *     aborted,
+   *     selection,
+   *     operationType,
+   *     toolName
+   *   });
+   * });
+   * ```
+   */
+  readonly arcgisComplete: import("@arcgis/lumina").TargetedEvent<this, SelectionToolbarViewModelEvents["complete"]>;
+  /** 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: "activeOperation" | "state"; }>;
+  /** Emitted when the component associated with a map or scene view is ready for user interaction. */
+  readonly arcgisReady: import("@arcgis/lumina").TargetedEvent<this, void>;
+  /**
+   * Fires when the potential selection set changes while drawing. This event will not fire unless
+   * the [syncWhileDrawing](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-selection-toolbar/#syncWhileDrawing) property is set to `true`. For the final selection set, use the [complete ](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-selection-toolbar/#event-arcgisComplete) event
+   * or refer to the associated [selection manager](/references/core/views/SelectionManager/).
+   *
+   * @since 5.2
+   * @example
+   * ```js
+   * const toolbar = document.querySelector("my-selection-toolbar");
+   * toolbar.addEventListener("arcgisSelectionChange", (event) => {
+   *   const { added, removed, operationType } = event.detail;
+   *   console.log("Selection changed:", {
+   *     added,
+   *     removed,
+   *     operationType,
+   *   });
+   * });
+   * ```
+   */
+  readonly arcgisSelectionChange: import("@arcgis/lumina").TargetedEvent<this, SelectionToolbarViewModelEvents["selection-change"]>;
+  readonly "@eventTypes": {
+    arcgisBeforeActivate: ArcgisSelectionToolbar["arcgisBeforeActivate"]["detail"];
+    arcgisClear: ArcgisSelectionToolbar["arcgisClear"]["detail"];
+    arcgisComplete: ArcgisSelectionToolbar["arcgisComplete"]["detail"];
+    arcgisPropertyChange: ArcgisSelectionToolbar["arcgisPropertyChange"]["detail"];
+    arcgisReady: ArcgisSelectionToolbar["arcgisReady"]["detail"];
+    arcgisSelectionChange: ArcgisSelectionToolbar["arcgisSelectionChange"]["detail"];
+  };
+}