@arcgis/core 5.2.0-next.153 → 5.2.0-next.155

package/layers/GeospatialPDFLayer.d.ts

@@ -1,3 +1,4 @@
+import type Extent from "../geometry/Extent.js";
 import type SpatialReference from "../geometry/SpatialReference.js";
 import type Layer from "./Layer.js";
 import type TileInfo from "./support/TileInfo.js";
@@ -7,21 +8,170 @@ import type { ScaleRangeLayer, ScaleRangeLayerProperties } from "./mixins/ScaleR
 import type { GeospatialPDFDataUnion } from "./support/types.js";
 import type { LayerProperties } from "./Layer.js";
 
+/**
+ * Properties used to construct a [GeospatialPDFLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/GeospatialPDFLayer/).
+ *
+ * @since 5.2
+ */
 export interface GeospatialPDFLayerProperties extends LayerProperties, ScaleRangeLayerProperties, BlendLayerProperties, Partial<Pick<GeospatialPDFLayer, "clippedToNeatline" | "data">> {}
 
+/**
+ * Displays a geospatial PDF document as georeferenced raster imagery.
+ * A geospatial PDF contains information that relates locations on a PDF page to real-world coordinates.
+ * This allows a map distributed as a PDF, such as a topographic map, to be displayed alongside other geographic data
+ * without manually specifying its location.
+ *
+ * To create a GeospatialPDFLayer, set the [data](https://developers.arcgis.com/javascript/latest/references/core/layers/GeospatialPDFLayer/#data) property to a PDF URL, a browser [File](https://developer.mozilla.org/en-US/docs/Web/API/File), or a [PortalItemData](https://developers.arcgis.com/javascript/latest/references/core/layers/support/PortalItemData/).
+ * Remote PDF URLs must be accessible to the application and comply with the browser's [cross-origin request restrictions](https://developers.arcgis.com/javascript/latest/cors/).
+ * The document is downloaded and rendered on the client; publishing an image service is not required.
+ * The first page of the PDF is used for georeferencing and rendering.
+ * The entire document is downloaded before rendering; large or complex PDFs can increase load time and memory usage.
+ * The layer derives its [spatial reference](https://developers.arcgis.com/javascript/latest/references/core/layers/GeospatialPDFLayer/#spatialReference) and
+ * [extent](https://developers.arcgis.com/javascript/latest/references/core/layers/GeospatialPDFLayer/#fullExtent) from the embedded georeferencing information.
+ * The rendered imagery can be reprojected to the spatial reference of the view. In an scene, it is draped on the ground.
+ *
+ * Additionally the PDF defines the boundary of the georeferenced map within the page, called a *neatline*.
+ * Set [clippedToNeatline](https://developers.arcgis.com/javascript/latest/references/core/layers/GeospatialPDFLayer/#clippedToNeatline) to `true` to hide content outside this boundary, such as page margins, legends, and titles.
+ *
+ * The [arcgis-print](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-print/) component can generate geospatial PDFs.
+ * When creating PDFs in ArcGIS Pro, enable "Export georeference information".
+ * Merely exporting a map to PDF does not guarantee that the resulting document contains georeferencing.
+ * See [Export to PDF](https://pro.arcgis.com/en/pro-app/latest/help/sharing/overview/pdf-export.htm) for export settings.
+ *
+ * > [!WARNING]
+ * >
+ * > **Known Limitations**
+ * >
+ * > - Documents that require a password to open are not supported.
+ * > - Tile reprojection is limited: grid-based transformations are not supported. As a result, the layer may still display but appear shifted. See the [project operator's known limitations](https://developers.arcgis.com/javascript/latest/references/core/geometry/operators/projectOperator/).
+ * > - To decode certain image types from PDF files, GeospatialPDFLayer is using WebAssembly features not available yet in Safari. As a result it uses a slower JavaScript fallback which impact the initial load of the layer.
+ * > - Not supported by the [Legend](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-legend/).
+ *
+ * @beta
+ * @since 5.2
+ * @see [PortalItemData](https://developers.arcgis.com/javascript/latest/references/core/layers/support/PortalItemData/)
+ * @see [GeospatialPDFDataUnion](https://developers.arcgis.com/javascript/latest/references/core/layers/support/types/#GeospatialPDFDataUnion)
+ * @see [GeospatialPDFLayer with a local file](https://developers.arcgis.com/javascript/latest/sample-code/layers-geospatialpdf/) sample
+ * @example
+ * ```ts
+ * import GeospatialPDFLayer from "@arcgis/core/layers/GeospatialPDFLayer.js";
+ *
+ * // Replace this URL with a georeferenced PDF.
+ * const layer = new GeospatialPDFLayer({
+ *   data: "https://jsapi.maps.arcgis.com/sharing/rest/content/items/0d8613492b1e4598a5edb111f05be7fd/data",
+ *   clippedToNeatline: true
+ * });
+ * // viewElement is an existing arcgis-map or arcgis-scene component.
+ * await viewElement.viewOnReady();
+ * viewElement.map.add(layer);
+ * ```
+ * @example
+ * ```ts
+ * import GeospatialPDFLayer from "@arcgis/core/layers/GeospatialPDFLayer.js";
+ * import PortalItemData from "@arcgis/core/layers/support/PortalItemData.js";
+ *
+ * const layer = new GeospatialPDFLayer({
+ *   data: new PortalItemData({
+ *     portalItem: {
+ *       id: "0d8613492b1e4598a5edb111f05be7fd"
+ *     }
+ *   })
+ * });
+ * // viewElement is an existing arcgis-map or arcgis-scene component.
+ * await viewElement.viewOnReady();
+ * viewElement.map.add(layer);
+ * ```
+ */
 export default class GeospatialPDFLayer extends GeospatialPDFLayerSuperclass {
   constructor(properties?: GeospatialPDFLayerProperties);
   /**
-   * TODO doc
+   * Indicates whether to hide PDF content outside the georeferenced map's neatline.
+   * A neatline is the boundary of the map within the PDF page. When `true`, content outside that boundary
+   * is masked out. When `false`, the entire page is displayed, including margins and other layout elements.
    *
    * @default false
+   * @example
+   * ```ts
+   * layer.clippedToNeatline = true;
+   * ```
    */
   accessor clippedToNeatline: boolean;
-  /** The geospatial PDF data source. */
+  /**
+   * The data source of the `GeospatialPDFLayer`.
+   *
+   * Specify one of the following before loading the layer:
+   * - A string containing the URL of a geospatial PDF.
+   * - A browser [File](https://developer.mozilla.org/en-US/docs/Web/API/File), for example from a file input.
+   * - A [PortalItemData](https://developers.arcgis.com/javascript/latest/references/core/layers/support/PortalItemData/) instance referencing a portal item whose
+   *   [url](https://developers.arcgis.com/javascript/latest/references/core/portal/PortalItem/#url) resolves to a geospatial PDF.
+   *
+   * @see [GeospatialPDFDataUnion](https://developers.arcgis.com/javascript/latest/references/core/layers/support/types/#GeospatialPDFDataUnion)
+   * @example
+   * ```ts
+   * import GeospatialPDFLayer from "@arcgis/core/layers/GeospatialPDFLayer.js";
+   *
+   * // Replace this URL with an accessible georeferenced PDF.
+   * const layer = new GeospatialPDFLayer({
+   *   data: "https://jsapi.maps.arcgis.com/sharing/rest/content/items/0d8613492b1e4598a5edb111f05be7fd/data",
+   *   clippedToNeatline: true
+   * });
+   * // viewElement is an existing arcgis-map or arcgis-scene component.
+   * await viewElement.viewOnReady();
+   * viewElement.map.add(layer);
+   * ```
+   * @example
+   * ```ts
+   * import GeospatialPDFLayer from "@arcgis/core/layers/GeospatialPDFLayer.js";
+   * import PortalItemData from "@arcgis/core/layers/support/PortalItemData.js";
+   *
+   * const layer = new GeospatialPDFLayer({
+   *   data: new PortalItemData({
+   *     portalItem: {
+   *       id: "0d8613492b1e4598a5edb111f05be7fd"
+   *     }
+   *   }),
+   *   clippedToNeatline: true
+   * });
+   * // viewElement is an existing arcgis-map or arcgis-scene component.
+   * await viewElement.viewOnReady();
+   * viewElement.map.add(layer);
+   * ```
+   * @example
+   * ```ts
+   * import GeospatialPDFLayer from "@arcgis/core/layers/GeospatialPDFLayer.js";
+   *
+   * // file is a File obtained from a file input or drag-and-drop.
+   * const layer = new GeospatialPDFLayer({
+   *   data: file,
+   *   clippedToNeatline: true
+   * });
+   * // viewElement is an existing arcgis-map or arcgis-scene component.
+   * await viewElement.viewOnReady();
+   * viewElement.map.add(layer);
+   * ```
+   */
   accessor data: GeospatialPDFDataUnion | null | undefined;
-  /** The spatial reference of the layer. */
+  /**
+   * The full extent of the layer.
+   *
+   * @example
+   * ```ts
+   * await viewElement.viewOnReady();
+   * await layer.load();
+   * if (layer.fullExtent) {
+   *   await viewElement.goTo(layer.fullExtent);
+   * }
+   * ```
+   * @example
+   * // Once the layer loads, set the view's extent to the layer's full extent
+   * layer.when(function(){
+   *   view.extent = layer.fullExtent;
+   * });
+   */
+  get fullExtent(): Extent | null | undefined;
+  /** The spatial reference of the layer derived from the georeferencing information found in the PDF. */
   get spatialReference(): SpatialReference;
-  /** The tiling scheme information for the layer. */
+  /** Contains information about the tiling scheme for the layer used to render the PDF as raster tiles. */
   get tileInfo(): TileInfo | null | undefined;
   /** The layer type provides a convenient way to check the type of the layer without the need to import specific layer modules. */
   get type(): "geospatial-pdf";

package/layers/Layer.d.ts

@@ -142,6 +142,7 @@ export interface FromArcGISServerUrlParameters {
  * [WMTSLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/WMTSLayer/) | WMTS tile services, ArcGIS portal item | Image tiles | OGC specification | N/A
  * [WebTileLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/WebTileLayer/) | non-ArcGIS, non-OGC, and non-OSM tile services | Image tiles | N/A | No editing, client-side rendering, or popup templates.
  * [BingMapsLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/BingMapsLayer/) | Bing Spatial Data Service data | Image tiles | Displays Microsoft's Bing tiled content | Bing Maps key is required; three map styles are supported: `road`, `aerial`, and `hybrid`
+ * [GeospatialPDFLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/GeospatialPDFLayer/) | PDF File, ArcGIS portal item | PDF documents | Displays a geospatial PDF document as georeferenced raster imagery | Documents that require a password to open are not supported
  * [MediaLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/MediaLayer/) | HTMLVideoElement, HTMLImageElement, or HTMLCanvasElement | Image/video element | Displays image and video elements in the map at specified geographic locations | GIF/APNG not currently
  * [VideoLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/VideoLayer/) | ArcGIS VideoServer, ArcGIS portal item | Video | Displays a georeferenced video in the map | No 3D support
  *
@@ -263,6 +264,7 @@ export default abstract class Layer extends LayerSuperclass {
    * > **Known Limitations**
    * >
    * > - This method does not currently work with [OGCFeatureServer portal items](https://developers.arcgis.com/rest/users-groups-and-items/items-and-item-types/#layers).
+   * > - This method does not currently work with [GeospatialPDFLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/GeospatialPDFLayer/)
    *
    * @param params - The parameters for loading the portal item.
    * @returns Returns a promise which resolves to the new layer instance.

package/layers/SketchLayer.d.ts

@@ -37,8 +37,9 @@ export interface SketchLayerProperties extends LayerProperties, PortalLayerPrope
 
 /**
  * The SketchLayer lets you display and modify sketches (features sketched on a web map) from the
- * [Map Viewer](https://www.arcgis.com/apps/mapviewer/index.html). A new SketchLayer can also be created
- * using the [SketchViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/Sketch/SketchViewModel/) in a 2D [MapView](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/).
+ * [Map Viewer](https://www.arcgis.com/apps/mapviewer/index.html). A new SketchLayer can also be used with the
+ * [Sketch component](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-sketch/)
+ * or the [SketchViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/Sketch/SketchViewModel/) in a 2D [MapView](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/).
  *
  * Sketches belong to the [graphics](https://developers.arcgis.com/javascript/latest/references/core/layers/SketchLayer/#graphics) collection. Each graphic can have its own
  * popup template, geometry, and symbol.
@@ -104,6 +105,7 @@ export interface SketchLayerProperties extends LayerProperties, PortalLayerPrope
  * ```
  *
  * @since 5.2
+ * @beta
  * @see [Map](https://developers.arcgis.com/javascript/latest/references/core/Map/)
  * @see [WebMap](https://developers.arcgis.com/javascript/latest/references/core/WebMap/)
  * @see [SketchViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/Sketch/SketchViewModel/)