@arcgis/map-components 4.34.0-next.134 → 4.34.0-next.135

package/dist/components/arcgis-coordinate-conversion/customElement.d.ts

@@ -1,37 +1,43 @@
 /// <reference types="@arcgis/core/interfaces.d.ts" />
 /// <reference path="../../index.d.ts" />
+import { JsxNode, PublicLitElement as LitElement, TargetedEvent } from '@arcgis/lumina';
 import { Use } from '@arcgis/lumina/controllers';
-import { default as CoordinateConversion } from '@arcgis/core/widgets/CoordinateConversion.js';
-import { PublicLitElement as LitElement, TargetedEvent } from '@arcgis/lumina';
 import { ArcgisReferenceElement } from '../../utils/component-utils';
+import { HeadingLevel } from '../../support/heading';
+import { default as Point } from '@arcgis/core/geometry/Point.js';
+import { default as Conversion } from '@arcgis/core/widgets/CoordinateConversion/support/Conversion.js';
+import { default as CoordinateConversionViewModel } from '@arcgis/core/widgets/CoordinateConversion/CoordinateConversionViewModel.js';
+import { default as Format } from '@arcgis/core/widgets/CoordinateConversion/support/Format.js';
+import { View, AlertProperties, Orientation, StorageType } from './interfaces';
 
-declare const useCoordinateConversionWidget: (component: LitElement & Pick<CoordinateConversion, "icon" | "label" | "orientation" | "mode" | "viewModel" | "headingLevel" | "goToOverride" | "conversions" | "formats" | "locationSymbol" | "storageType"> & {
-    state?: unknown;
-    viewModel?: __esri.CoordinateConversionViewModel | undefined;
-    closed?: boolean;
-    icon: import('@arcgis/toolkit/type').nil | string;
-    label: import('@arcgis/toolkit/type').nil | string;
-    referenceElement?: ArcgisReferenceElement | string;
-    position?: __esri.UIPosition;
-    arcgisReady: import('@arcgis/lumina').EventEmitter;
-    arcgisPropertyChange: import('@arcgis/lumina').EventEmitter<{
-        name: string;
-    }> | undefined;
-    el: HTMLElement & {
-        childElem?: HTMLElement & {
-            ownedBy?: HTMLElement;
-        };
-        view?: __esri.LinkChartView | __esri.MapView | __esri.SceneView | nullish;
-    };
-    autoDestroyDisabled: boolean;
-    destroy: () => Promise<void>;
-}) => CoordinateConversion;
+declare const useCoordinateConversionViewModel: (component: LitElement & Pick<CoordinateConversionViewModel, never> & import('../../controllers/useViewModel').ViewModelControllerUses<CoordinateConversionViewModel>) => CoordinateConversionViewModel;
 /**
- * The Coordinate Conversion component provides a way to display user cursor position either as map coordinates or as any of several popular coordinate notations. Additionally, the component provides a way to convert user input coordinates into a [Point](https://developers.arcgis.com/javascript/latest/api-reference/esri-geometry-Point.html).
+ * The CoordinateConversion component provides a way to display user cursor position either as map coordinates or
+ * as any of several popular coordinate notations.  Additionally, the component provides a way to convert
+ * user input coordinates into a [point](https://developers.arcgis.com/javascript/latest/api-reference/esri-geometry-Point.html).
+ *
+ *
+ * Several common formats are included by default:
+ * * XY - Longitude, Latitude (WGS84)
+ * * MGRS - [Military Grid Reference System](https://earth-info.nga.mil/index.php?dir=coordsys&action=coordsys#mgrs)
+ * * UTM - [Universal Transverse Mercator](https://earth-info.nga.mil/index.php?dir=coordsys&action=coordsys#utm)
+ * * DD - Decimal Degrees
+ * * DDM - Degrees Decimal Minutes
+ * * DMS - Degrees Minutes Seconds
+ * * Basemap - X, Y in the coordinate system used by the current basemap in the units used by the basemap.
+ * Web Mercator is the standard for Esri-provided basemaps.
+ *
+ * Additional formats can be created by a developer and made available
+ * through the component
  *
  * [Read more...](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-coordinate-conversion/)
  *
- * @since 4.28
+ * @example
+ * ```tsx
+ * <arcgis-map item-id="45b3b2fb35e94ab09381d0caa0da5946">
+ *   <arcgis-coordinate-conversion position="bottom-left"></arcgis-coordinate-conversion>
+ * </arcgis-map>
+ * ```
  */
 export declare class ArcgisCoordinateConversion extends LitElement {
     /**
@@ -50,89 +56,200 @@ export declare class ArcgisCoordinateConversion extends LitElement {
      */
     autoDestroyDisabled: boolean;
     /**
-     * A [Collection](https://developers.arcgis.com/javascript/latest/api-reference/esri-core-Collection.html) containing every [Conversion](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-CoordinateConversion-support-Conversion.html)
-     * that the widget is currently displaying.
+     * A [collection](https://developers.arcgis.com/javascript/latest/api-reference/esri-core-Collection.html) of conversions
+     * that the component is currently displaying. Each row in the component displaying a coordinate is a conversion.
      *
-     * [Read more...](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-CoordinateConversion.html#conversions)
+     * @type {Collection<Conversion>}
+     * @example
+     * Conversions can be set with an array of strings where each string is a format's name
+     * ```ts
+     * coordinateConversionComponent.conversions = ["mgrs"];
+     * ```
      */
-    conversions: __esri.Collection<__esri.Conversion>;
+    conversions: __esri.Collection<Conversion>;
     /**
-     * Describes the location of the coordinates currently displayed by the widget as a [Point](https://developers.arcgis.com/javascript/latest/api-reference/esri-geometry-Point.html).
+     * Describes the location of the coordinates currently displayed by the component as a [Point](https://developers.arcgis.com/javascript/latest/api-reference/esri-geometry-Point.html).
+     * Setting this property will update all conversions.
      *
-     * [Read more...](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-CoordinateConversion.html#currentLocation)
+     * @type {Point}
+     * @example
+     * Set the current location
+     * ```ts
+     * coordinateConversionComponent.currentLocation = { x: 77.0369, y: 38.9072, spatialReference: { wkid: 4326 } };
+     * ```
+     */
+    currentLocation?: nullish | Point;
+    /**
+     * Describes whether the  component is expanded or not. Can be set manually to expand or retract the component.
+     *
+     * @type {boolean}
+     * @example
+     * Expand the component
+     * ```ts
+     * coordinateConversionComponent.expanded = true;
+     * ```
+     * @default false
      */
-    readonly currentLocation: nullish | __esri.Point;
+    expanded: boolean;
     /**
-     * A [Collection](https://developers.arcgis.com/javascript/latest/api-reference/esri-core-Collection.html) containing every [Format](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-CoordinateConversion-support-Format.html)
-     * that the widget is capable of displaying.
+     * A [collection](https://developers.arcgis.com/javascript/latest/api-reference/esri-core-Collection.html) containing every coordinate format
+     * that the component is capable of displaying.
      *
-     * [Read more...](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-CoordinateConversion.html#formats)
+     * The default formats are `basemap`, `dd`, `ddm`, `dms`, `mgrs`, `usng`, `utm`, and `xy`.
+     *
+     * @type {Collection<Format>}
+     * @example
+     * Only show the "xy" format
+     * ```ts
+     * const coordinateConversionComponent = document.getElementsByTagName("arcgis-coordinate-conversion")[0];
+     * const toRemove = coordinateConversionComponent.formats.filter(format => format.name !== "xy");
+     * coordinateConversionComponent.formats.removeMany(toRemove);
+     * ```
+     * @example
+     * Show every format except "xy"
+     * ```ts
+     * const coordinateConversionComponent = document.getElementsByTagName("arcgis-coordinate-conversion")[0];
+     * const toRemove = coordinateConversionComponent.formats.filter(format => format.name === "xy");
+     * coordinateConversionComponent.formats.removeMany(toRemove);
+     * ```
      */
-    formats: __esri.Collection<__esri.Format>;
+    formats: __esri.Collection<Format>;
     /**
      * This function provides the ability to override either the
      * [MapView goTo()](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-MapView.html#goTo) or
      * [SceneView goTo()](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-SceneView.html#goTo) methods.
      *
-     * [Read more...](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-CoordinateConversion.html#goToOverride)
+     * [Read more...](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-CoordinateConversion-CoordinateConversionViewModel.html#goToOverride)
      *
      * @since 4.33
      */
     goToOverride: nullish | __esri.GoToOverride;
     /**
-     * Indicates the heading level to use for the coordinate input and coordinate settings headings.
+     * Indicates the heading level to use for the coordinate input and coordinate settings headings. By default,
+     * these headings are rendered as level 4 headings (e.g. `<h4>Input coordinate</h4>`). Depending on the coordinate conversion component's
+     * placement in your app, you may need to adjust this heading for proper semantics. This is important for meeting
+     * accessibility standards.
      *
+     * @type {number}
+     * @example
+     * Coordinate conversion heading will render as an <h2>
+     * ```ts
+     * coordinateConversionComponent.headingLevel = 2;
+     * ```ts
      * @default 4
      */
-    headingLevel: number;
-    /** @default false */
-    hideCaptureButton: boolean | undefined;
-    /** @default false */
-    hideInputButton: boolean | undefined;
-    /** @default false */
-    hideExpandButton: boolean | undefined;
-    /** @default false */
-    hideSettingsButton: boolean | undefined;
+    headingLevel: HeadingLevel;
+    /**
+     * Determines whether the capture button will be shown in the component
+     *
+     * @type {boolean}
+     * @example
+     * Hide the capture button
+     * ```tsx
+     * <arcgis-map item-id="45b3b2fb35e94ab09381d0caa0da5946">
+     *   <arcgis-coordinate-conversion hide-capture-button position="bottom-left"></arcgis-coordinate-conversion>
+     * </arcgis-map>
+     * ```
+     * @default false
+     */
+    hideCaptureButton: boolean;
+    /**
+     * Determines whether the edit button will be shown in the component
+     *
+     * @type {boolean}
+     * @example
+     * Hide the edit button
+     * ```tsx
+     * <arcgis-map item-id="45b3b2fb35e94ab09381d0caa0da5946">
+     *   <arcgis-coordinate-conversion hide-edit-button position="bottom-left"></arcgis-coordinate-conversion>
+     * </arcgis-map>
+     * ```
+     * @default false
+     */
+    hideInputButton: boolean;
+    /**
+     * Determines whether the expand button will be shown in the component
+     *
+     * @type {boolean}
+     * @example
+     * Hide the capture button
+     * ```tsx
+     * <arcgis-map item-id="45b3b2fb35e94ab09381d0caa0da5946">
+     *   <arcgis-coordinate-conversion hide-expand-button position="bottom-left"></arcgis-coordinate-conversion>
+     * </arcgis-map>
+     * ```
+     * @default false
+     */
+    hideExpandButton: boolean;
+    /**
+     * Determines whether the settings button will be shown in the component
+     *
+     * @type {boolean}
+     * @example
+     * Hide the capture button
+     * ```tsx
+     * <arcgis-map item-id="45b3b2fb35e94ab09381d0caa0da5946">
+     *   <arcgis-coordinate-conversion hide-settings-button position="bottom-left"></arcgis-coordinate-conversion>
+     * </arcgis-map>
+     * ```
+     * @default false
+     */
+    hideSettingsButton: boolean;
     /**
      * Icon which represents the component.
      * Typically used when the component is controlled by another component (e.g. by the Expand component).
+     * Search [Calcite Icons](https://developers.arcgis.com/calcite-design-system/icons/) for possible values.
      *
-     * @see [Calcite Icons](https://developers.arcgis.com/calcite-design-system/icons/)
      * @default "coordinate-system"
      */
     icon: string;
     /**
-     * The widget's default label.
+     * The component's default label.
      *
-     * [Read more...](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-CoordinateConversion.html#label)
+     * @default "Coordinate conversion"
      */
-    label: string;
+    label: string | undefined;
     /**
-     * This symbol is used to visualize the location currently described by the widget when `capture` mode
+     * This symbol is used to visualize the location currently described by the component when `capture` mode
      * is active.
      *
-     * [Read more...](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-CoordinateConversion.html#locationSymbol)
+     * This property should be set to an Esri JS API point symbol, typically a [Simple Marker Symbol](https://developers.arcgis.com/javascript/latest/api-reference/esri-symbols-SimpleMarkerSymbol.html)
+     *
+     * @type {SimpleMarkerSymbol}
+     * @example
+     * Set the location symbol to be an 'x'
+     * ```ts
+     * const coordinateConversionComponent = document.getElementsByTagName("arcgis-coordinate-conversion")[0];
+     * coordinateConversionComponent.locationSymbol = { type: "simple-marker", style: "x" };
+     * ```
      */
     locationSymbol: __esri.PictureMarkerSymbol | __esri.SimpleMarkerSymbol | __esri.CIMSymbol | __esri.PointSymbol3D;
     /**
-     * Describes the current mode of the widget.
+     * Describes the current mode of the component.
      *
+     * * While in `live` mode, the component will update as the cursor moves.
+     * * While in `capture` mode, the component will update on mouse click and display a graphic
+     * marking the current location.
+     *
+     * @type {"live" | "capture"}
+     * @example
+     * Programmatically set the component to capture mode
+     * ```ts
+     * const coordinateConversionComponent = document.getElementsByTagName("arcgis-coordinate-conversion")[0];
+     * coordinateConversionComponent.mode = "capture";
+     * ```
      * @default "live"
      */
     mode: "live" | "capture";
     /**
-     * If this property is set to `false`, multiple conversions cannot be displayed.
-     *
-     * @default false
-     */
-    multipleConversionsDisabled: boolean;
-    /**
-     * Determines whether the widget should expand up or down.
+     * Determines whether the component should expand up or down.  If set to `auto`
+     * the component will be oriented based on its position in the view.
      *
+     * @type {"auto" | "expand-up" | "expand-down"}
      * @default "auto"
      */
-    orientation: "auto" | "expand-up" | "expand-down";
-    /** @deprecated since 4.34, use [`slot`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/slot) instead. */
+    orientation: Orientation;
+    /** @deprecated since 4.34, use `slot` instead. */
     position?: __esri.UIPosition;
     /**
      * 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.
@@ -147,24 +264,47 @@ export declare class ArcgisCoordinateConversion extends LitElement {
      */
     readonly state: "ready" | "loading" | "disabled";
     /**
-     * Unless this property is set to `false`, sessionStorage or localStorage (depending on [storageType](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-CoordinateConversion.html#storageType))
-     * will be used to hydrate and persist the Coordinate Conversion component's state.
+     * If this property is set to `true`, only a single conversion can be displated.  For a simpler experience with only
+     * one conversion at a time, this property can be set to `true`.
+     *
+     * @type {boolean}
+     * @default false
+     */
+    get singleConversion(): boolean;
+    set singleConversion(value: boolean);
+    /**
+     * If this property is set to `true`, sessionStorage or localStorage (depending on [storageType](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-CoordinateConversion.html#storageType))
+     * will not be used to hydrate and persist the component's state.
      *
+     * @type {boolean}
      * @default false
      */
     storageDisabled: boolean;
     /**
-     * This property determines whether sessionStorage or localStorage will be used to store widget state.
+     * This property determines whether sessionStorage or localStorage will be used to store component's state.
      *
+     * @type {"session" | "local"}
+     * @see [Window.sessionStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage)
+     * @see [Window.localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage)
      * @default "session"
      */
-    storageType: "local" | "session";
+    storageType: StorageType;
     /** Permanently destroy the component. */
     destroy(): Promise<void>;
-    reverseConvert(coordinate: string, format: __esri.Format): Promise<__esri.Point | nullish>;
+    /**
+     * Attempt to convert a string into a [point](https://developers.arcgis.com/javascript/latest/api-reference/esri-geometry-Point.html).  The format of the
+     * string must be specified.  A [collection](https://developers.arcgis.com/javascript/latest/api-reference/esri-core-Collection.html) of available formats can be
+     * obtained from the [formats](#formats) property.
+     *
+     * @param coordinate - The coordinate string.
+     * @param  ://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-CoordinateConversion-support-Format.html} format - Specifies the format of the input coordinate.
+     * @return ://developers.arcgis.com/javascript/latest/api-reference/esri-geometry-Point.html | nil>} When resolved, returns a [point](https://developers.arcgis.com/javascript/latest/api-reference/esri-geometry-Point.html).
+     */
+    reverseConvert(coordinate: string, format: Format): Promise<__esri.Point | nullish>;
+    readonly arcgisConversionChange: TargetedEvent<this, void>;
     /** Emitted when the value of a property is changed. Use this to listen to changes to properties. */
     readonly arcgisPropertyChange: TargetedEvent<this, {
-        name: "state" | "currentLocation";
+        name: "state" | "mode" | "expanded" | "currentLocation";
     }>;
     /** Emitted when the component associated with a map or scene view is ready to be interacted with. */
     readonly arcgisReady: TargetedEvent<this, void>;