@geoscene/map-components 4.33.20 → 4.34.9

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

@@ -1,37 +1,50 @@
 /// <reference types="@geoscene/core/interfaces.d.ts" />
-/// <reference types="../../index.d.ts" />
+/// <reference path="../../index.d.ts" />
+import { JsxNode, PublicLitElement as LitElement, TargetedEvent } from '@geoscene/lumina';
 import { Use } from '@geoscene/lumina/controllers';
-import { default as CoordinateConversion } from '@geoscene/core/widgets/CoordinateConversion.js';
-import { PublicLitElement as LitElement, TargetedEvent } from '@geoscene/lumina';
 import { GeosceneReferenceElement } from '../../utils/component-utils';
+import { HeadingLevel } from '../../support/heading';
+import { default as Point } from '@geoscene/core/geometry/Point.js';
+import { default as Conversion } from '@geoscene/core/widgets/CoordinateConversion/support/Conversion.js';
+import { default as CoordinateConversionViewModel } from '@geoscene/core/widgets/CoordinateConversion/CoordinateConversionViewModel.js';
+import { default as Format } from '@geoscene/core/widgets/CoordinateConversion/support/Format.js';
+import { View, AlertProperties, Orientation, StorageType } from './interfaces';
 
-declare const useCoordinateConversionWidget: (component: LitElement & Pick<CoordinateConversion, "icon" | "label" | "viewModel" | "orientation" | "mode" | "headingLevel" | "goToOverride" | "conversions" | "formats" | "locationSymbol" | "storageType"> & {
-    state?: unknown;
-    viewModel?: __geoscene.CoordinateConversionViewModel | undefined;
-    closed?: boolean;
-    icon: import('@arcgis/components-utils').Nil | string;
-    label: import('@arcgis/components-utils').Nil | string;
-    referenceElement?: GeosceneReferenceElement | string;
-    position: __geoscene.UIPosition;
-    geosceneReady: import('@geoscene/lumina').EventEmitter;
-    geoscenePropertyChange: import('@geoscene/lumina').EventEmitter<{
-        name: string;
-    }> | undefined;
-    el: HTMLElement & {
-        childElem?: HTMLElement & {
-            ownedBy?: HTMLElement;
-        };
-        view?: __geoscene.LinkChartView | __geoscene.MapView | __geoscene.SceneView;
-    };
-    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://doc.geoscene.cn/javascript/4.33/api-reference/geoscene-geometry-Point.html).
+ * 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://doc.geoscene.cn/javascript/4.33/api-reference/geoscene-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 GeoScene-provided basemaps.
+ *
+ * Additional formats can be created by a developer and made available
+ * through the component
  *
  * [Read more...](https://doc.geoscene.cn/javascript/4.33/references/map-components/geoscene-coordinate-conversion/)
+ *
+ * @example
+ * ```html
+ * <geoscene-map item-id="45b3b2fb35e94ab09381d0caa0da5946">
+ *   <geoscene-coordinate-conversion slot="bottom-left"></geoscene-coordinate-conversion>
+ * </geoscene-map>
+ * ```
  */
 export declare class GeosceneCoordinateConversion extends LitElement {
+    /**
+     * 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 Coordinate Conversion component will be associated with a map or scene component rather than using the `view` property.
+     */
+    view?: __geoscene.MapView | __geoscene.SceneView | nullish;
     /**
      * 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
@@ -43,90 +56,204 @@ export declare class GeosceneCoordinateConversion extends LitElement {
      */
     autoDestroyDisabled: boolean;
     /**
-     * A [Collection](https://doc.geoscene.cn/javascript/4.33/api-reference/geoscene-core-Collection.html) containing every [Conversion](https://doc.geoscene.cn/javascript/4.33/api-reference/geoscene-widgets-CoordinateConversion-support-Conversion.html)
-     * that the widget is currently displaying.
+     * A [collection](https://doc.geoscene.cn/javascript/4.33/api-reference/geoscene-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://doc.geoscene.cn/javascript/4.33/api-reference/geoscene-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.
+     * ```js
+     * coordinateConversionComponent.conversions = ["mgrs"];
+     * ```
      */
-    conversions: __geoscene.Collection<__geoscene.Conversion>;
+    conversions: __geoscene.Collection<Conversion>;
     /**
-     * Describes the location of the coordinates currently displayed by the widget as a [Point](https://doc.geoscene.cn/javascript/4.33/api-reference/geoscene-geometry-Point.html).
+     * Describes the location of the coordinates currently displayed by the component as a [Point](https://doc.geoscene.cn/javascript/4.33/api-reference/geoscene-geometry-Point.html).
+     * Setting this property will update all conversions.
      *
-     * [Read more...](https://doc.geoscene.cn/javascript/4.33/api-reference/geoscene-widgets-CoordinateConversion.html#currentLocation)
+     * @type {Point}
+     * @example
+     * Set the current location.
+     * ```js
+     * coordinateConversionComponent.currentLocation = { x: 77.0369, y: 38.9072, spatialReference: { wkid: 4326 } };
+     * ```
      */
-    readonly currentLocation: nullish | __geoscene.Point;
+    currentLocation?: nullish | Point;
     /**
-     * A [Collection](https://doc.geoscene.cn/javascript/4.33/api-reference/geoscene-core-Collection.html) containing every [Format](https://doc.geoscene.cn/javascript/4.33/api-reference/geoscene-widgets-CoordinateConversion-support-Format.html)
-     * that the widget is capable of displaying.
+     * Describes whether the component is expanded or not. If `true`, the component is expanded and all conversions are visible.
      *
-     * [Read more...](https://doc.geoscene.cn/javascript/4.33/api-reference/geoscene-widgets-CoordinateConversion.html#formats)
+     * @type {boolean}
+     * @example
+     * Expand the component.
+     * ```js
+     * coordinateConversionComponent.expanded = true;
+     * ```
+     * @default false
      */
-    formats: __geoscene.Collection<__geoscene.Format>;
+    expanded: boolean;
+    /**
+     * A [collection](https://doc.geoscene.cn/javascript/4.33/api-reference/geoscene-core-Collection.html) containing every coordinate format
+     * that the component is capable of displaying.
+     *
+     * The default formats are `basemap`, `dd`, `ddm`, `dms`, `mgrs`, `usng`, `utm`, and `xy`.
+     *
+     * @type {Collection<Format>}
+     * @example
+     * Only show the "xy" format.
+     * ```js
+     * const coordinateConversionComponent = document.getElementsByTagName("geoscene-coordinate-conversion")[0];
+     * const toRemove = coordinateConversionComponent.formats.filter(format => format.name !== "xy");
+     * coordinateConversionComponent.formats.removeMany(toRemove);
+     * ```
+     * @example
+     * Show every format except "xy".
+     * ```js
+     * const coordinateConversionComponent = document.getElementsByTagName("geoscene-coordinate-conversion")[0];
+     * const toRemove = coordinateConversionComponent.formats.filter(format => format.name === "xy");
+     * coordinateConversionComponent.formats.removeMany(toRemove);
+     * ```
+     */
+    formats: __geoscene.Collection<Format>;
     /**
      * This function provides the ability to override either the
      * [MapView goTo()](https://doc.geoscene.cn/javascript/4.33/api-reference/geoscene-views-MapView.html#goTo) or
      * [SceneView goTo()](https://doc.geoscene.cn/javascript/4.33/api-reference/geoscene-views-SceneView.html#goTo) methods.
      *
-     * [Read more...](https://doc.geoscene.cn/javascript/4.33/api-reference/geoscene-widgets-CoordinateConversion.html#goToOverride)
+     * [Read more...](https://doc.geoscene.cn/javascript/4.33/api-reference/geoscene-widgets-CoordinateConversion-CoordinateConversionViewModel.html#goToOverride)
      *
      * @since 4.33
      */
     goToOverride: nullish | __geoscene.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}
      * @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. If `true`, the capture button will be hidden.
+     *
+     * @type {boolean}
+     * @example
+     * Hide the capture button.
+     * ```html
+     * <geoscene-map item-id="45b3b2fb35e94ab09381d0caa0da5946">
+     *   <geoscene-coordinate-conversion hide-capture-button slot="bottom-left"></geoscene-coordinate-conversion>
+     * </geoscene-map>
+     * ```
+     * @default false
+     */
+    hideCaptureButton: boolean;
+    /**
+     * Determines whether the input coordinate button will be shown in the component. If `true`, the input button will be hidden.
+     *
+     * @type {boolean}
+     * @example
+     * Hide the input button.
+     * ```html
+     * <geoscene-map item-id="45b3b2fb35e94ab09381d0caa0da5946">
+     *   <geoscene-coordinate-conversion hide-input-button slot="bottom-left"></geoscene-coordinate-conversion>
+     * </geoscene-map>
+     * ```
+     * @default false
+     */
+    hideInputButton: boolean;
+    /**
+     * Determines whether the expand button will be shown in the component. If `true`, the expand button will be hidden.
+     *
+     * @type {boolean}
+     * @example
+     * Hide the expand button.
+     * ```html
+     * <geoscene-map item-id="45b3b2fb35e94ab09381d0caa0da5946">
+     *   <geoscene-coordinate-conversion hide-expand-button slot="bottom-left"></geoscene-coordinate-conversion>
+     * </geoscene-map>
+     * ```
+     * @default false
+     */
+    hideExpandButton: boolean;
+    /**
+     * Determines whether the settings button will be shown in the component. If `true`, the settings button will be hidden.
+     *
+     * @type {boolean}
+     * @example
+     * Hide the settings button.
+     * ```html
+     * <geoscene-map item-id="45b3b2fb35e94ab09381d0caa0da5946">
+     *   <geoscene-coordinate-conversion hide-settings-button slot="bottom-left"></geoscene-coordinate-conversion>
+     * </geoscene-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://doc.geoscene.cn/calcite-design-system/icons/) for possible values.
      *
-     * @see [Calcite Icons](https://doc.geoscene.cn/calcite-design-system/icons/)
      * @default "coordinate-system"
      */
     icon: string;
     /**
-     * The widget's default label.
+     * The component's default label.
      *
-     * [Read more...](https://doc.geoscene.cn/javascript/4.33/api-reference/geoscene-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://doc.geoscene.cn/javascript/4.33/api-reference/geoscene-widgets-CoordinateConversion.html#locationSymbol)
+     * This property should be set to a point symbol, typically a [Simple Marker Symbol](https://doc.geoscene.cn/javascript/4.33/api-reference/geoscene-symbols-SimpleMarkerSymbol.html).
+     *
+     * @type {SimpleMarkerSymbol}
+     * @example
+     * Set the location symbol to be an 'x'.
+     * ```js
+     * const coordinateConversionComponent = document.getElementsByTagName("geoscene-coordinate-conversion")[0];
+     * coordinateConversionComponent.locationSymbol = { type: "simple-marker", style: "x" };
+     * ```
      */
-    locationSymbol: __geoscene.SimpleMarkerSymbol | __geoscene.PictureMarkerSymbol | __geoscene.PointSymbol3D | __geoscene.CIMSymbol;
+    locationSymbol: __geoscene.PictureMarkerSymbol | __geoscene.SimpleMarkerSymbol | __geoscene.CIMSymbol | __geoscene.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.
+     * ```js
+     * const coordinateConversionComponent = document.getElementsByTagName("geoscene-coordinate-conversion")[0];
+     * coordinateConversionComponent.mode = "capture";
+     * ```
      * @default "live"
      */
     mode: "live" | "capture";
     /**
-     * If this property is set to `false`, multiple conversions cannot be displayed.
+     * If this property is set to `true`, multiple conversions will be disabled, and only a single conversion will be displayed. Otherwise, multiple conversions will be shown.
      *
+     * @type {boolean}
      * @default false
      */
-    multipleConversionsDisabled: boolean;
+    get multipleConversionsDisabled(): boolean;
+    set multipleConversionsDisabled(value: 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";
-    /** @default "bottom-left" */
-    position: __geoscene.UIPosition;
+    orientation: Orientation;
+    /** @deprecated since 4.34, use [`slot`](https://doc.geoscene.cn/javascript/4.33/building-your-ui/#slots) instead. */
+    position?: __geoscene.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.
      *
@@ -140,26 +267,45 @@ export declare class GeosceneCoordinateConversion extends LitElement {
      */
     readonly state: "ready" | "loading" | "disabled";
     /**
-     * Unless this property is set to `false`, sessionStorage or localStorage (depending on [storageType](https://doc.geoscene.cn/javascript/4.33/api-reference/geoscene-widgets-CoordinateConversion.html#storageType))
-     * will be used to hydrate and persist the Coordinate Conversion component's state.
+     * If this property is set to `true`, sessionStorage or localStorage (depending on [storageType](https://doc.geoscene.cn/javascript/4.33/api-reference/geoscene-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: __geoscene.Format): Promise<__geoscene.Point | nullish>;
+    /**
+     * Attempt to convert a string into a [point](https://doc.geoscene.cn/javascript/4.33/api-reference/geoscene-geometry-Point.html).  The format of the
+     * string must be specified.  A [collection](https://doc.geoscene.cn/javascript/4.33/api-reference/geoscene-core-Collection.html) of available formats can be
+     * obtained from the [formats](#formats) property.
+     *
+     * @param coordinate - The coordinate string.
+     * @param  ://developers.geoscene.cn/javascript/latest/api-reference/geoscene-widgets-CoordinateConversion-support-Format.html} format - Specifies the format of the input coordinate.
+     * @return ://developers.geoscene.cn/javascript/latest/api-reference/geoscene-geometry-Point.html | nil>} When resolved, returns a [point](https://doc.geoscene.cn/javascript/4.33/api-reference/geoscene-geometry-Point.html).
+     */
+    reverseConvert(coordinate: string, format: Format): Promise<__geoscene.Point | nullish>;
+    /**
+     * Emitted when a conversion is added or removed, or when the order of conversions changes.
+     *
+     * @since 4.34
+     */
+    readonly geosceneConversionChange: TargetedEvent<this, void>;
     /** Emitted when the value of a property is changed. Use this to listen to changes to properties. */
     readonly geoscenePropertyChange: TargetedEvent<this, {
-        name: "state" | "currentLocation";
+        name: "state" | "mode" | "expanded" | "currentLocation";
     }>;
-    /** Emitted when the component associated with a map or scene view is is ready to be interacted with. */
+    /** Emitted when the component associated with a map or scene view is ready to be interacted with. */
     readonly geosceneReady: TargetedEvent<this, void>;
 }
 export {};