@arcgis/map-components 5.2.0-next.98 → 6.0.0-next.0

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

@@ -11,13 +11,14 @@ import type { SelectionToolConfig } from "@arcgis/core/widgets/support/Selection
 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 view.
+ * 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. Only one selection operation can be active at a time.
+   * 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
    */
@@ -42,15 +43,14 @@ export abstract class ArcgisSelectionToolbar extends LitElement {
    */
   accessor autoDestroyDisabled: boolean;
   /**
-   * An array of operation type names that determines what operation types appear in the associated dropdown component.
+   * 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
-   * after the completion of an active selection operation, using options from the previous operation.
-   * This only applies if the previous selection operation was completed, and not cancelled.
+   * 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
@@ -63,8 +63,8 @@ export abstract class ArcgisSelectionToolbar extends LitElement {
    */
   accessor defaultLassoToolOptions: SelectionOperationProperties;
   /**
-   * The default selection operation type to use when starting a new selection operation.
-   * This value can be changed via the selection operation type dropdown.
+   * 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
@@ -76,6 +76,12 @@ export abstract class ArcgisSelectionToolbar extends LitElement {
    * @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.
    *
@@ -83,32 +89,39 @@ export abstract class ArcgisSelectionToolbar extends LitElement {
    */
   accessor defaultRectangleToolOptions: SelectionOperationProperties;
   /**
-   * When true, the component is visually withdrawn and cannot receive user interaction.
+   * 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 currently in use by the component.
+   * 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. These sources will also include any relevant layer views
-   * that were found on the provided view if `layerViewPreferenceDisabled` is false.
+   * 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.
+   * 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.
    *
@@ -117,16 +130,17 @@ export abstract class ArcgisSelectionToolbar extends LitElement {
    */
   accessor hideLassoTool: boolean;
   /**
-   * Indicates whether the selection operation type controls should be hidden. The operation type controls
-   * allow for changing the selection operation type (e.g., replace, add, remove).
+   * 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 should be hidden. The pan tool allows for panning the view without
-   * performing a selection operation. This tool is the default when no selection operation is active.
+   * 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
@@ -134,24 +148,34 @@ export abstract class ArcgisSelectionToolbar extends LitElement {
   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 clicked point, not just the topmost feature.
+   * 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 progress indicator should be hidden. The progress indicator shows when a selection
-   * operation is processing results. The processing time can vary depending on the potential number of selected
-   * features, or whether the selection operation is querying source layers or layer views for results.
+   * 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 tool should be hidden. The rectangle tool allows for selecting features by
-   * drawing a rectangle.
+   * 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
@@ -168,15 +192,12 @@ export abstract class ArcgisSelectionToolbar extends LitElement {
   /** The component's default label. */
   accessor label: string | undefined;
   /**
-   * Indicates whether selection operations should always perform queries against source layers instead of
-   * preferring to query their associated layer views in order to determine selection results. Querying the
-   * layer may be required when up-to-date features are necessary. Changing this property while a selection
-   * operation is active will not have any effect on that operation, and will only affect subsequent operations.
+   * 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 layerViewPreferenceDisabled: boolean;
+  accessor layerPreferenceEnabled: boolean;
   /**
    * Controls the orientation of the component.
    *
@@ -198,6 +219,7 @@ export abstract class ArcgisSelectionToolbar extends LitElement {
       countTruncated: string;
       lasso: string;
       pan: string;
+      polygon: string;
       point: string;
       processing: string;
       rectangle: string;
@@ -207,8 +229,10 @@ export abstract class ArcgisSelectionToolbar extends LitElement {
       replaceSelection: string;
       selectFeatures: string;
       selectByLasso: string;
+      selectByPolygon: string;
       selectByPoint: string;
       selectByRectangle: string;
+      selectionCount: string;
   }> & T9nMeta<{
       componentLabel: string;
       add: string;
@@ -218,6 +242,7 @@ export abstract class ArcgisSelectionToolbar extends LitElement {
       countTruncated: string;
       lasso: string;
       pan: string;
+      polygon: string;
       point: string;
       processing: string;
       rectangle: string;
@@ -227,8 +252,10 @@ export abstract class ArcgisSelectionToolbar extends LitElement {
       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.
@@ -237,23 +264,42 @@ export abstract class ArcgisSelectionToolbar extends LitElement {
    */
   accessor referenceElement: ArcgisReferenceElement | string | undefined;
   /**
-   * Determines if selected features should be returned with fields necessary for displaying feature titles as
-   * defined by the WebMap.
+   * 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 selected features returned by the selection operation should include their geometries.
-   * This may be leveraged to improve performance when geometries are not needed for the selection results.
+   * 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 to use instead of the view's default selection manager.
+   * 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
    */
@@ -266,34 +312,34 @@ export abstract class ArcgisSelectionToolbar extends LitElement {
    */
   accessor showTextLabels: boolean;
   /**
-   * An array of layer or layer views that selection is derived from.
+   * 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;
   /**
-   * The state of the component.
+   * Reflects the current operational state of the selection toolbar.
    *
    * @since 5.2
    */
   get state(): "active" | "disabled" | "ready";
   /**
-   * Indicates whether new selection operation results should be synced with the associated selection
-   * manager automatically. Events emitted by the toolbar will still contain updated selection information but
-   * the changes will not be reflected by the selection manager when a selection operation completes.
+   * 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 should continuously determine the potential selection while
-   * the associated draw tool is active, which is reflected via events. Otherwise, a selection operation will
-   * only determine the selection a single time when a drawing has been completed. It is important to note that
-   * the potential selection is not saved or reflected via the associated selection manager. Set this property to true to
-   * enable constant updates to the working selection set, which can be useful in some cases e.g. highlighting potential
-   * features while drawing. This does not affect whether final selection results are stored by the selection manager, which
-   * can be controlled via the syncResultsDisabled property.
+   * 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
@@ -312,34 +358,52 @@ export abstract class ArcgisSelectionToolbar extends LitElement {
    */
   accessor view: SelectableViewUnion | null | undefined;
   /**
-   * Controls the scale of any rendered Calcite elements.
+   * 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 a tool with the provided options. Cancels any currently active selection operation.
-   * This method has no effect if the toolbar is disabled.
+   * 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, or `undefined` if activation was blocked.
+   * @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 a tool by name. Cancels any currently active selection operation.
-   * Custom tools should be pre-configured via the 'toolConfigs' property.
-   * This method has no effect if the toolbar is disabled.
+   * 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, or `undefined` if activation was blocked.
+   * @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, if applicable, triggers a 'complete' event.
-   * The 'complete' event indicates if the operation was cancelled via the 'aborted' property.
+   * 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
    */
@@ -347,49 +411,100 @@ export abstract class ArcgisSelectionToolbar extends LitElement {
   /** Permanently destroy the component. */
   destroy(): Promise<void>;
   /**
-   * Convenience method for syncing the effective selection manager with the current layers and tables on
-   * the view. This is useful when new layers or table layers have been added to the view after construction.
-   * Otherwise, newly-added layers are not included in selection results made by this component. This method will do
-   * nothing if the effective selection manager does not have a view assigned.
+   * 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>;
   /**
-   * Convenience method for toggling the active state of a specific tool. If the provided tool is already active, it will be cancelled.
-   * If the provided tool is not active, it will be activated. Any currently active selection operation will also be cancelled before
-   * activating the new tool.
+   * 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 if the associated tool was toggled on, or `undefined` if the tool was toggled off.
+   * @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 is activated.
+   * 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 selection operation is complete and results have been processed.
+   * 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 to be interacted with. */
+  /** 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' property is set to true. For the final selection set, use the 'complete' event.
+   * 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"];