@arcgis/map-components 4.34.0-next.8 → 4.34.0-next.80

package/dist/components/arcgis-bookmarks/customElement.d.ts

@@ -1,82 +1,131 @@
 /// <reference types="@arcgis/core/interfaces.d.ts" />
-/// <reference types="../../index.d.ts" />
-import { Use } from '@arcgis/lumina/controllers';
-import { default as Bookmarks } from '@arcgis/core/widgets/Bookmarks.js';
-import { PublicLitElement as LitElement, TargetedEvent } from '@arcgis/lumina';
+/// <reference path="../../index.d.ts" />
+import { default as BookmarksViewModel } from '@arcgis/core/widgets/Bookmarks/BookmarksViewModel.js';
 import { ArcgisReferenceElement } from '../../utils/component-utils';
+import { HeadingLevel } from '../../support/heading';
+import { Use } from '@arcgis/lumina/controllers';
+import { JsxNode, PublicLitElement as LitElement, TargetedEvent } from '@arcgis/lumina';
 
-declare const useBookmarksWidget: (component: LitElement & Pick<Bookmarks, "icon" | "label" | "viewModel" | "disabled" | "goToOverride" | "dragEnabled" | "filterPlaceholder" | "filterText" | "defaultCreateOptions" | "bookmarks" | "defaultEditOptions"> & {
-    state?: unknown;
-    viewModel?: __esri.BookmarksViewModel | undefined;
-    closed?: boolean;
-    icon: import('@arcgis/components-utils').Nil | string;
-    label: import('@arcgis/components-utils').Nil | string;
-    referenceElement?: ArcgisReferenceElement | string;
-    position: __esri.UIPosition;
-    arcgisReady: import('@arcgis/lumina').EventEmitter;
-    arcgisPropertyChange: import('@arcgis/lumina').EventEmitter<{
-        name: string;
-    }> | undefined;
-    el: HTMLElement & {
-        childElem
-        /** @copyDoc */
-        ? /** @copyDoc */: HTMLElement & {
-            ownedBy?: HTMLElement;
-        };
-        view?: __esri.LinkChartView | __esri.MapView | __esri.SceneView;
-    };
-    autoDestroyDisabled: boolean;
-    destroy: () => Promise<void>;
-}) => Bookmarks;
+declare const useBookmarksViewModel: (component: LitElement & Pick<BookmarksViewModel, never> & import('../../controllers/useViewModel').ViewModelControllerUses<BookmarksViewModel>) => BookmarksViewModel;
 /**
- * The Bookmarks component allow end users to quickly navigate to a particular area of interest. It displays a list of [bookmarks](https://developers.arcgis.com/javascript/latest/api-reference/esri-webmap-Bookmark.html), which are typically defined inside the [WebMap](https://developers.arcgis.com/javascript/latest/api-reference/esri-WebMap.html#bookmarks).
+ * The Bookmarks component allows end users to quickly navigate to a particular area of interest.
+ * It displays a list of [bookmarks](https://developers.arcgis.com/javascript/latest/api-reference/esri-webmap-Bookmark.html),
+ * which are typically defined inside the [WebMap](https://developers.arcgis.com/javascript/latest/api-reference/esri-WebMap.html#bookmarks).
+ *
+ * Each bookmark may contain the following properties: `name`, `thumbnail`, `viewpoint` (defines rotation, scale, and target geometry), and `timeExtent`.
+ * When a bookmark with a timeExtent is selected, the [arcgis-map.timeExtent](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-map/#timeExtent) of the Map will be set to the timeExtent of the selected bookmark.
+ * To disable time capability in the Bookmarks component, set [timeDisabled](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-bookmarks/#timeDisabled) to `true`.
+ *
+ * The Bookmarks component can be used to create, edit, reorder, and delete bookmarks.
+ * To enable these features, set the following properties to `true`:
+ * [showAddBookmarkButton](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-bookmarks/#showAddBookmarkButton), [showEditBookmarkButton](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-bookmarks/#showEditBookmarkButton), and [dragEnabled](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-bookmarks/#dragEnabled).
+ *
+ * **Note:** Bookmarks are supported in a 3D [Scene](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-scene/) only if they come from a [WebMap](https://developers.arcgis.com/javascript/latest/api-reference/esri-WebMap.html#bookmarks) or are [provided manually](#bookmarks). [Presentation](https://developers.arcgis.com/javascript/latest/api-reference/esri-webscene-Presentation.html) provides a similar experience for [WebScenes](https://developers.arcgis.com/javascript/latest/api-reference/esri-webscene-Presentation.html).
  *
  * [Read more...](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-bookmarks/)
+ *
+ * @since 4.28
+ * @see [Sample - Bookmarks component](https://developers.arcgis.com/javascript/latest/sample-code/bookmarks/)
  */
 export declare class ArcgisBookmarks extends LitElement {
     /**
-     * Emitted when the component's close button is clicked.
+     * 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.
      *
-     * @since 4.33
+     * @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)
      */
-    readonly arcgisClose: TargetedEvent<this>;
-    /**
-     * 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/arcgis-bookmarks/#destroy) method when you are done to
-     * prevent memory leaks.
-     *
-     * @default false
-     */
-    autoDestroyDisabled: boolean;
+    referenceElement?: ArcgisReferenceElement | string;
+    /** @default "top-left" */
+    position: __esri.UIPosition;
     /**
-     * A collection of [Bookmark](https://developers.arcgis.com/javascript/latest/api-reference/esri-webmap-Bookmark.html)s.
+     * Icon which represents the component.
+     * Typically used when the component is controlled by another component (e.g. by the Expand component).
      *
-     * [Read more...](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-Bookmarks.html#bookmarks)
+     * @see [Calcite Icons](https://developers.arcgis.com/calcite-design-system/icons/)
+     * @default "icon"
      */
-    bookmarks: __esri.Collection<__esri.Bookmark>;
+    icon?: string;
     /**
      * Indicates whether a component is closed. When `true`, the component will be hidden.
      *
-     * @since 4.33
      * @default false
      */
     closed: boolean;
     /**
-     * Specifies how new bookmarks will be created if [visibleElements.addBookmarkButton](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-Bookmarks.html#VisibleElements) is set to `true`.
+     * Specifies how new bookmarks will be created if [showAddBookmarkButton](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-bookmarks/#showAddBookmarkButton) is set to `true`.
+     * Can be used to enable or disable taking screenshots or capturing the bookmark's viewpoint based on the current
+     * view when a bookmark is created. See [BookmarkOptions](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-Bookmarks-BookmarksViewModel-BookmarkOptions.html)
+     * for the full list of options.
      *
-     * [Read more...](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-Bookmarks.html#defaultCreateOptions)
+     * @example
+     * ```js
+     * const bookmarksElement = document.querySelector("arcgis-bookmarks");
+     * bookmarksElement.showAddBookmarkButton = true;
+     * bookmarksElement.defaultCreateOptions = {
+     *   // whenever a new bookmark is created, a 100x100 px
+     *   // screenshot of the view will be taken and the rotation, scale, and extent
+     *   // of the view will not be set as the viewpoint of the new bookmark
+     *   takeScreenshot: true,
+     *   captureViewpoint: false,
+     *   captureTimeExtent: false, // the time extent will not be saved in the bookmark
+     *   screenshotSettings: {
+     *     width: 100,
+     *     height: 100
+     *   }
+     * };
+     * ```
      */
     defaultCreateOptions: __esri.BookmarkOptions;
     /**
-     * Specifies how bookmarks will be edited, if [visibleElements.editBookmarkButton](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-Bookmarks.html#VisibleElements) is set to `true`.
-     *
-     * [Read more...](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-Bookmarks.html#defaultEditOptions)
+     * Specifies how bookmarks will be edited, if [showEditBookmarkButton](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-bookmarks/#showEditBookmarkButton) is set to `true`.
+     * Can be used to enable or disable taking screenshots or capturing the bookmark's viewpoint based on the current
+     * view when a bookmark is edited. See [BookmarkOptions](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-Bookmarks-BookmarksViewModel-BookmarkOptions.html)
+     * for the full list of options.
      */
     defaultEditOptions: __esri.BookmarkOptions;
     /**
-     * When true, the widget is visually withdrawn and cannot be interacted with.
+     * A collection of [Bookmark](https://developers.arcgis.com/javascript/latest/api-reference/esri-webmap-Bookmark.html)s. These are typically defined inside of a [WebMap](https://developers.arcgis.com/javascript/latest/api-reference/esri-WebMap.html#bookmarks), but can also be defined manually, as shown in the code snippet below.
+     *
+     * @example
+     * ```js
+     * const bookmarksElement = document.querySelector("arcgis-bookmarks");
+     * // define bookmarks manually
+     * bookmarksElement.bookmarks = [
+     *   new Bookmark({
+     *     name: "Angeles National Forest",
+     *     viewpoint: {
+     *       targetGeometry: {
+     *         type: "extent",
+     *         spatialReference: {
+     *           wkid: 102100
+     *         },
+     *         xmin: -13139131.948889678,
+     *         ymin: 4047767.23531948,
+     *         xmax: -13092887.54677721,
+     *         ymax: 4090610.189673263
+     *       }
+     *     }
+     *   }),
+     *   new Bookmark({
+     *     name: "Crystal Lake",
+     *     viewpoint: {
+     *       targetGeometry: {
+     *         type: "extent",
+     *         spatialReference: {
+     *           wkid: 102100
+     *         },
+     *         xmin: -13125852.551697943,
+     *         ymin: 4066904.1101411926,
+     *         xmax: -13114291.451169826,
+     *         ymax: 4077614.8487296384
+     *       },
+     *       rotation: 90
+     *     }
+     *   })
+     * ];
+     */
+    bookmarks: __esri.Collection<__esri.Bookmark>;
+    /**
+     * When true, the component is visually withdrawn and cannot be interacted with.
      *
      * @default false
      */
@@ -84,65 +133,136 @@ export declare class ArcgisBookmarks extends LitElement {
     /**
      * Indicates if a Bookmark is able to be dragged in order to update its position in the list.
      *
+     * @since 4.29
      * @default false
      */
     dragEnabled: boolean;
     /**
-     * Defines the text used as a placeholder when visibleElements.filter is set to `true`.
+     * Defines the text used as a placeholder when [showFilter](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-bookmarks/#showFilter) is set to `true`.
      *
-     * [Read more...](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-Bookmarks.html#filterPlaceholder)
+     * @since 4.29
+     * @default ""
      */
     filterPlaceholder: string;
     /**
-     * Defines the text used to filter the bookmarks when visibleElements.filter is set to `true`.
+     * Defines the text used to filter the bookmarks when [showFilter](https://developers.arcgis.com/javascript/latest/references/map-components/arcgis-bookmarks/#showFilter) is set to `true`.
      *
-     * [Read more...](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-Bookmarks.html#filterText)
+     * @since 4.29
+     * @default ""
      */
     filterText: string;
+    /**
+     * Indicates the heading level to use for the message "No bookmarks" when no bookmarks
+     * are available. By default, this message is rendered
+     * as a level 2 heading (e.g. `<h2>No bookmarks</h2>`). Depending on the component's placement
+     * in your app, you may need to adjust this heading for proper semantics. This is
+     * important for meeting accessibility standards.
+     *
+     * @see [Heading Elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements)
+     * @example
+     * ```js
+     * // "No bookmarks" will render as an <h3>
+     * bookmarksElement.headingLevel = 3;
+     * ```
+     * @default 2
+     */
+    headingLevel: HeadingLevel;
     /**
      * 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-Bookmarks.html#goToOverride)
-     *
-     * @since 4.33
+     * [Read more...](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-Bookmarks-BookmarksViewModel.html#goToOverride)
      */
     goToOverride: nullish | __esri.GoToOverride;
-    /** @default false */
-    hideFlow: boolean;
-    /** @default false */
-    hideThumbnail: boolean;
-    /** @default false */
-    hideTime: boolean;
     /**
-     * Icon which represents the widget.
+     * Indicates whether to display the button to add a new bookmark.
      *
-     * @see [Calcite Icons](https://developers.arcgis.com/calcite-design-system/icons/)
-     * @default "bookmark"
+     * @since 4.30
+     * @default false
      */
-    icon: string;
+    showAddBookmarkButton: boolean;
     /**
-     * The widget's default label.
+     * Indicates whether to display the close button.
      *
-     * [Read more...](https://developers.arcgis.com/javascript/latest/api-reference/esri-widgets-Bookmarks.html#label)
+     * @since 4.30
+     * @default false
      */
-    label: string;
-    /** @default "bottom-left" */
-    position: __esri.UIPosition;
-    referenceElement?: ArcgisReferenceElement | string;
-    /** @default false */
-    showAddBookmarkButton: boolean;
-    /** @default false */
     showCloseButton: boolean;
-    /** @default false */
+    /**
+     * Indicates whether to display the collapse button.
+     *
+     * @since 4.30
+     * @default false
+     */
     showCollapseButton: boolean;
-    /** @default false */
+    /**
+     * Indicates whether to display the button to edit a bookmark.
+     *
+     * @since 4.30
+     * @default false
+     */
     showEditBookmarkButton: boolean;
-    /** @default false */
+    /**
+     * Indicates whether to display the bookmark filter.
+     *
+     * @since 4.30
+     * @default false
+     */
     showFilter: boolean;
-    /** @default false */
+    /**
+     * Determines whether the component should be rendered within its built-in [flow component](https://developers.arcgis.com/calcite-design-system/components/flow/).
+     *
+     * @since 4.30
+     * @default false
+     */
+    hideFlow: boolean;
+    /**
+     * Indicates whether to display the heading.
+     *
+     * @since 4.30
+     * @default false
+     */
     showHeading: boolean;
+    /**
+     * Indicates whether the thumbnail associated with the bookmark is hidden.
+     *
+     * @since 4.30
+     * @default false
+     */
+    hideThumbnail: boolean;
+    /**
+     * Indicates whether the time (`h:m:s`) displayed next to the date is hidden if the bookmark has a time extent defined.
+     *
+     * @since 4.30
+     * @default false
+     */
+    hideTime: boolean;
+    /**
+     * Indicates whether to disable the time capability of the Bookmarks component.
+     *
+     * @since 4.34
+     * @default false
+     */
+    timeDisabled: boolean | 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/arcgis-bookmarks/#destroy) method when you are done to
+     * prevent memory leaks.
+     *
+     * @default false
+     */
+    autoDestroyDisabled: boolean;
+    /**
+     * Replace localized message strings with your own strings.
+     *
+     * _**Note**: Individual message keys may change between releases._
+     */
+    messageOverrides?: typeof this.messages._overrides;
+    /** The component's default label. */
+    label?: string;
     /**
      * The view model's state.
      *
@@ -153,13 +273,50 @@ export declare class ArcgisBookmarks extends LitElement {
     readonly state: "ready" | "loading";
     /** Permanently destroy the component. */
     destroy(): Promise<void>;
-    readonly arcgisEdit: TargetedEvent<this, __esri.BookmarksBookmarkEditEvent>;
+    /** Zoom to a specific bookmark. */
+    goTo(bookmark: __esri.Bookmark): Promise<void>;
+    /**
+     *
+     * Fires when a [Bookmark](https://developers.arcgis.com/javascript/latest/api-reference/esri-webmap-Bookmark.html) is edited.
+     *
+     * @example
+     * ```js
+     * // once an edit has been made, enable the "Save Webmap" button
+     * //    to allow the user to save their changes
+     * bookmarksElement.addEventListener("arcgisBookmarkEdit", (event) => {
+     *    saveBtn.disabled = false;
+     * });
+     * ```
+     */
+    readonly arcgisBookmarkEdit: TargetedEvent<this, __esri.BookmarksBookmarkEditEvent>;
+    /**
+     * Fires when a [Bookmark](https://developers.arcgis.com/javascript/latest/api-reference/esri-webmap-Bookmark.html) is selected.
+     *
+     * @example
+     * ```html
+     * <arcgis-expand expanded>
+     *  <arcgis-bookmarks></arcgis-bookmarks>
+     * </arcgis-expand>
+     * ```
+     *
+     * ```js
+     * const bookmarksElement = document.querySelector("arcgis-bookmarks");
+     * const expandElement = document.querySelector("arcgis-expand");
+     *
+     * // collapses the associated Expand component
+     * // when a bookmark is selected
+     * bookmarksElement.addEventListener("arcgisBookmarkSelect", (event) => {
+     *   expandElement.expanded = false;
+     * });
+     * ```
+     */
+    readonly arcgisBookmarkSelect: TargetedEvent<this, __esri.BookmarksBookmarkSelectEvent>;
     /** Emitted when the value of a property is changed. Use this to listen to changes to properties. */
     readonly arcgisPropertyChange: TargetedEvent<this, {
         name: "state";
     }>;
-    /** 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 arcgisReady: TargetedEvent<this, void>;
-    readonly arcgisSelect: TargetedEvent<this, __esri.BookmarksBookmarkSelectEvent>;
+    private messages;
 }
 export {};