@vertigis/viewer-spec 56.34.1 → 56.35.0

package/app-config/web/PortalModelProperties.d.ts

@@ -1,4 +1,8 @@
 import type { ModelProperties } from "../common/ModelProperties.js";
+/**
+ * Represent sources of portal items.
+ */
+export type Source = "my-content" | "my-groups" | "my-favorites" | "organization" | "public";
 /**
  * Properties that are used for the Portal service.
  */
@@ -8,4 +12,14 @@ export interface PortalModelProperties extends ModelProperties {
      * layers.
      */
     layerFilterTags?: string[];
+    /**
+     * Optionally specify the source that will be initially selected in the
+     * Choose Layer modal. If not specified we default to "organization".
+     */
+    initialSource?: Source;
+    /**
+     * The sources that we want to expose by default in the Choose Layer modal.
+     * If not specified we include all sources.
+     */
+    sources?: Source[];
 }

package/messaging/registry/arcade.d.ts

@@ -68,12 +68,27 @@ export interface ItemPropertyPath {
 export declare class ArcadeOperations extends OperationRegistry {
     protected readonly _prefix = "arcade";
     /**
-     * Runs a stringified Arcade script. If only a string is passed in as an
-     * argument, it is interpreted as an executeScript. If an executeScript is
-     * provided, the operation will return its result. If only a canExecute
-     * script is provided and it returns a truthy result, the operation will
-     * return its input arguments. If a canExecuteScript returns a falsy value,
-     * the operation will throw a {@link Cancellation}. Web only.
+     * Runs a stringified Arcade script.
+     *
+     * - If only a string is passed in as an argument, it is interpreted as an
+     *   executeScript.
+     * - If an executeScript is provided, the operation will return its result.
+     * - If only a canExecute script is provided and it returns a truthy result,
+     *   the operation will return its input arguments.
+     * - If a canExecuteScript returns a falsy value, the operation will throw a
+     *   `Cancellation`.
+     *
+     * **Example:** Use an Arcade script to query a portal for a featureset, and
+     * return the area in square kilometers of the first feature. The output
+     * type of this operation is determined by the Arcade script, see
+     * https://developers.arcgis.com/arcade/function-reference/ for more
+     * information.
+     *
+     * ```
+     * {
+     *     "executeScript": "Area(First(FeatureSetByPortalItem(Portal(\"https://www.arcgis.com\"),\"6200db0b80de4341ae8ee2b62d606e67\",0,[\"*\"],true)),\"square-kilometers\");"
+     * }
+     * ```
      *
      * @webOnly
      */

package/messaging/registry/drawing.d.ts

@@ -100,6 +100,23 @@ export declare class DrawingCommands extends CommandRegistry {
      * can be configured with an instance of the Esri symbol or with the Esri
      * WebMap JSON. Web only.
      *
+     * **Example:** Set the default point symbol to a square.
+     *
+     * ```
+     * {
+     *     "type": "esriSMS",
+     *     "color": [251, 43, 17, 85],
+     *     "size": 12,
+     *     "style": "esriSMSSquare",
+     *     "outline": {
+     *         "type": "esriSLS",
+     *         "color": [251, 43, 17, 255],
+     *         "width": 1.5,
+     *         "style": "esriSLSSolid"
+     *     }
+     * }
+     * ```
+     *
      * @webOnly
      */
     get setDefaultSymbol(): Command<SymbolLike | HasSymbol>;

package/messaging/registry/edit.d.ts

@@ -191,7 +191,7 @@ export interface DisplayAddFeatureArgs extends CreateFeatureArgs, HasMaps, EditO
      * A collection of configuration overrides for the editable fields. Web
      * only.
      */
-    fieldElements?: Partial<FieldElement>[];
+    fieldElements?: FieldElementOverride[];
 }
 /**
  * Arguments for the "edit.display-add-related-feature" command. A feature and a
@@ -207,6 +207,10 @@ export interface DisplayAddRelatedFeatureArgs extends Omit<DisplayAddFeatureArgs
      */
     relatedFeatureSource: FeatureSource;
 }
+/**
+ * Override settings for a field element.
+ */
+export type FieldElementOverride = Partial<FieldElement>;
 /**
  * Arguments for the "edit.display-update-features" operation. Web only.
  */
@@ -218,7 +222,7 @@ export interface DisplayUpdateFeatureArgs extends EditCommandArgs, HasGeometry,
     /**
      * A collection of configuration overrides for the editable fields.
      */
-    fieldElements?: Partial<FieldElement>[];
+    fieldElements?: FieldElementOverride[];
 }
 /**
  * Arguments for the "edit.add-features", "edit.update-features" and
@@ -270,12 +274,63 @@ export declare class EditCommands extends CommandRegistry {
     /**
      * Begin an interactive feature editing session with a new feature.
      * `DisplayAddFeatureArgs` is not supported on Mobile.
+     *
+     * **Example:** Create and allow the user to edit a new feature with an
+     * initial attributes collection. If no geometry is provided in context they
+     * will be asked to select one.
+     *
+     * _Note:_ $map1.map.extension is the output of a 'Get Map' activity run in
+     * Web by Workflow. When the map and/or layer are provided in the context of
+     * a command chain these parameters can be omitted.
+     *
+     * ```
+     * {
+     *     "editAttributes": true,
+     *     "editGeometry": true,
+     *     "featureAttributes": {
+     *         "ASSET_ID": "WFH001234"
+     *     },
+     *     "layers": "Victoria_Fire_Hydrants_8780",
+     *     "maps": $map1.map.extension
+     * }
+     * ```
      */
     get displayAddFeature(): Command<FeatureSource | DisplayAddFeatureArgs>;
     /**
      * Begin an interactive feature editing session for a new related feature.
      * The specified feature will be the original feature that the new related
      * feature will be added to in the relationship.
+     *
+     * **Example:** Create and edit a new record on a related table, with the
+     * option to add attachments. Make sure the 'COMMENTS' field is included in
+     * the editable attributes and make it required.
+     *
+     * _Notes:_.
+     *
+     * 1. The feature used here must come from the running viewer, and cannot be an
+     *    ad-hoc feature created from a JSON object. For example, you can use
+     *    the output of `results.get-active-features`, or the feature provided
+     *    in a command chain context.
+     * 2. `editableExpression` and `requiredExpression` both take an arcade
+     *    expression, and here the string "true" is just a simple arcade
+     *    expression that always returns true. You can also use a more complex
+     *    expression, or reference one from your webmap.
+     *
+     * ```
+     * {
+     *     "editAttributes": true,
+     *     "editAttachments": true,
+     *     "features": $runOperation1.result,
+     *     "relationshipId": "1",
+     *     "fieldElements": [
+     *         {
+     *             "fieldName": "COMMENTS",
+     *             "editableExpression": "true",
+     *             "requiredExpression": "true"
+     *         }
+     *     ]
+     * }
+     * ```
      */
     get displayAddRelatedFeature(): Command<DisplayAddRelatedFeatureArgs>;
     /**

package/messaging/registry/layers.d.ts

@@ -116,6 +116,15 @@ export declare class LayersCommands extends CommandRegistry {
     /**
      * Updates the visibility of the provided layer(s). Web only.
      *
+     * **Example:** Toggle a layer's visibility off by id.
+     *
+     * ```
+     * {
+     *     "layers": "Victoria_Fire_Hydrants_8780",
+     *     "visible": false
+     * }
+     * ```
+     *
      * @webOnly
      */
     get setVisibility(): Command<SetVisibilityArgs>;

package/messaging/registry/location-marker.d.ts

@@ -153,6 +153,25 @@ export declare class LocationMarkerCommands extends CommandRegistry {
     /**
      * Create a new Marker. Web only.
      *
+     * **Example:** Create a user draggable location marker with a heading and
+     * fov.
+     *
+     * _Note:_ The geometry here must be a Geometry object rather than a JSON
+     * representation. You can use the Workflow task 'Get Geometry From JSON' or
+     * be passed one from another step in the command chain.
+     *
+     * ```
+     * {
+     *     "color": [24, 128, 255, 255],
+     *     "fov": 120,
+     *     "geometry": $geometry1.geometry,
+     *     "heading": 60,
+     *     "id": "custom-marker-1",
+     *     "symbol": "dot",
+     *     "userDraggable": true
+     * }
+     * ```
+     *
      * @webOnly
      */
     get create(): Command<CreateLocationMarkerArgs>;

package/messaging/registry/map.d.ts

@@ -154,40 +154,24 @@ export interface MarkupArgs extends HasMaps {
      * default markup collection will be used. Some markup collection names are
      * used internally by Web:
      *
-     * "default": The default markup layer.
-     *
-     * "vgs-active-snapping-guides": The active snap point when snapping.
-     *
-     * "vgs-buffer": Buffer graphics from out of the box buffer tools.
-     *
-     * "vgs-context-marker": Right click context marker on map.
-     *
-     * "vgs-dirty-indicator": Invalid geometry indicators used when editing.
-     *
-     * "vgs-editing-control": Edit frame and vertices while editing geometries.
-     *
-     * "vgs-location-accuracy": Location accuracy circle when geolocating.
-     *
-     * "vgs-location-marker-*": Location markers have this prefix followed by
-     * the marker id.
-     *
-     * "vgs-map-notes": Map Notes.
-     *
-     * "vgs-measurement-labels": Labels on measured graphics.
-     *
-     * "vgs-other-snapping-guides": Additional snapping point visualizations.
-     *
-     * "vgs-query": Graphics representing the custom spatial filter for the
-     * query builder tool.
-     *
-     * "vgs-self-snaps": Used internally by snapping.
-     *
-     * "vgs-sketching": Temporary graphics used while drawing geometries.
-     *
-     * "vgs-snapping-radius": Snapping radius when snapping is active.
-     *
-     * "vgs-transient-measurement-labels": Measurement labels used while
-     * drawing.
+     * | Collection Name                    | Usage                                                                       |
+     * | ---------------------------------- | --------------------------------------------------------------------------- |
+     * | "default"                          | The default markup layer.                                                   |
+     * | "vgs-active-snapping-guides"       | The active snap point when snapping.                                        |
+     * | "vgs-buffer"                       | Buffer graphics from out of the box buffer tools.                           |
+     * | "vgs-context-marker"               | Right click context marker on map.                                          |
+     * | "vgs-dirty-indicator"              | Invalid geometry indicators used when editing.                              |
+     * | "vgs-editing-control"              | Edit frame and vertices while editing geometries.                           |
+     * | "vgs-location-accuracy"            | Location accuracy circle when geolocating.                                  |
+     * | "vgs-location-marker-\*"           | Location markers have this prefix followed by the marker id.                |
+     * | "vgs-map-notes"                    | Map Notes.                                                                  |
+     * | "vgs-measurement-labels"           | Labels on measured graphics.                                                |
+     * | "vgs-other-snapping-guides"        | Additional snapping point visualizations.                                   |
+     * | "vgs-query"                        | Graphics representing the custom spatial filter for the query builder tool. |
+     * | "vgs-self-snaps"                   | Used internally by snapping.                                                |
+     * | "vgs-sketching"                    | Temporary graphics used while drawing geometries.                           |
+     * | "vgs-snapping-radius"              | Snapping radius when snapping is active.                                    |
+     * | "vgs-transient-measurement-labels" | Measurement labels used while drawing.                                      |
      *
      * Web only.
      *
@@ -765,13 +749,75 @@ export declare class MapCommands extends CommandRegistry {
     protected readonly _prefix = "map";
     /**
      * Adds markup to the map(s).
+     *
+     * **Example:** Adding markup to a custom collection using `AddMarkupArgs`.
+     *
+     * ```
+     * {
+     *     "collection": "my-custom-markup",
+     *     "graphics": [
+     *         {
+     *             "geometry": {
+     *                 "x": -13733416.69,
+     *                 "y": 6177670.86,
+     *                 "spatialReference": {
+     *                     "wkid": 3857
+     *                 },
+     *                 "type": "point"
+     *             },
+     *             "symbol": {
+     *                 "color": [76, 115, 0, 255],
+     *                 "size": 16,
+     *                 "style": "esriSMSCircle",
+     *                 "type": "simple-marker"
+     *             }
+     *         }
+     *     ]
+     * }
+     * ```
      */
     get addMarkup(): Command<AddMarkupArgs | GraphicsLike>;
     /**
      * Add the specified layer(s) to the maps(s). Layers will be inserted in the
      * order specified and will be added above existing layers in the drawing
-     * order. Note that an Esri {@link Layer} object can only be added to one
-     * map. Web only.
+     * order. Note that an Esri `Layer` object can only be added to one map.
+     *
+     * Web only.
+     *
+     * **Example:** Adding a CSV layer to the main map using `AddLayersArgs`.
+     *
+     * ```
+     * {
+     *     "layers": [
+     *         {
+     *             "id": "csv_123",
+     *             "layerType": "CSV",
+     *             "title": "Earthquakes",
+     *             "url": "http://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/2.5_month.csv",
+     *             "columnDelimiter": ",",
+     *             "layerDefinition": {
+     *                 "geometryType": "esriGeometryPoint",
+     *                 "objectIdField": "__OBJECTID",
+     *                 "capabilities": "Query",
+     *                 "extent": {
+     *                     "xmin": -20034970.25849882,
+     *                     "ymin": -9494815.985282788,
+     *                     "xmax": 20026086.963133518,
+     *                     "ymax": 14269743.874052156,
+     *                     "spatialReference": {
+     *                         "wkid": 102100
+     *                     }
+     *                 }
+     *             },
+     *             "locationInfo": {
+     *                 "locationType": "coordinates",
+     *                 "latitudeFieldName": "latitude",
+     *                 "longitudeFieldName": "longitude"
+     *             }
+     *         }
+     *     ]
+     * }
+     * ```
      *
      * @webOnly
      */

package/messaging/registry/portal.d.ts

@@ -1,4 +1,5 @@
 import type PortalItem from "@arcgis/core/portal/PortalItem";
+import type { Source } from "../../app-config/web/PortalModelProperties.js";
 import type { Event } from "../Event.js";
 import { EventRegistry } from "../EventRegistry.js";
 import type { Operation } from "../Operation.js";
@@ -19,6 +20,23 @@ export interface ChooseLayersOptions extends HasMaps, HasUITarget {
      * `false`.
      */
     allowMultiple?: boolean;
+    /**
+     * Optionally specify the tags by which the Choose Layer modal will filter
+     * out the displayed layers. If specified this will overwrite the configured
+     * default in the Portal Model.
+     */
+    layerFilterTags?: string[];
+    /**
+     * Optionally specify the source that will be initially selected. If
+     * specified this will overwrite the configured default in the Portal
+     * Model.
+     */
+    initialSource?: Source;
+    /**
+     * Optionally specify the sources that we want to expose. If specified this
+     * will overwrite the configured default in the Portal Model.
+     */
+    sources?: Source[];
 }
 /**
  * Result of the "portal.choose-layers" operation.

package/messaging/registry/project.d.ts

@@ -56,6 +56,62 @@ export declare class ProjectCommands extends CommandRegistry {
      * accordingly. If more than one file is provided, only the first will be
      * loaded. Web only.
      *
+     * **Example:** Add some default markup to the map and set the viewpoint by
+     * applying `AppConfig` JSON.
+     *
+     * ```
+     * {
+     *     "schemaVersion": "1.0",
+     *     "items": [
+     *         {
+     *             "id": "default",
+     *             "markupGraphics": [
+     *                 {
+     *                     "geometry": {
+     *                         "spatialReference": {
+     *                             "latestWkid": 3857,
+     *                             "wkid": 102100
+     *                         },
+     *                         "x": -13733817.770910433,
+     *                         "y": 6177913.346701053
+     *                     },
+     *                     "symbol": {
+     *                         "type": "esriSMS",
+     *                         "color": [251, 43, 17, 85],
+     *                         "size": 12,
+     *                         "style": "esriSMSCircle",
+     *                         "outline": {
+     *                             "type": "esriSLS",
+     *                             "color": [251, 43, 17, 255],
+     *                             "width": 1.5,
+     *                             "style": "esriSLSSolid"
+     *                         }
+     *                     },
+     *                     "attributes": {
+     *                         "markupLevel": 36,
+     *                         "isContrastGraphic": true,
+     *                         "collection": "default",
+     *                         "graphic-visible": true
+     *                     }
+     *                 }
+     *             ],
+     *             "viewpoint": {
+     *                 "rotation": 45,
+     *                 "scale": 10000,
+     *                 "targetGeometry": {
+     *                     "spatialReference": {
+     *                         "wkid": 102100
+     *                     },
+     *                     "x": -13733546.804885864,
+     *                     "y": 6177341.583529942
+     *                 }
+     *             },
+     *             "$type": "map-extension"
+     *         }
+     *     ]
+     * }
+     * ```
+     *
      * @webOnly
      */
     get load(): Command<AppConfig | HasAppConfig | SharedProject | Blob | Blob[]>;

package/messaging/registry/query-builder.d.ts

@@ -56,6 +56,28 @@ export declare class QueryBuilderCommands extends CommandRegistry {
      * Sets the current query criteria in the query builder and also activates
      * the component. Web only.
      *
+     * **Example:** Query within an extent, selecting the layer to query by
+     * title.
+     *
+     * ```
+     * {
+     *     "geometry": {
+     *         "xmin": 13871520.850500003,
+     *         "ymin": 3910293.086000003,
+     *         "xmax": 14574034.873400003,
+     *         "ymax": 4686306.161399998,
+     *         "spatialReference": {
+     *             "wkid": 102100,
+     *             "latestWkid": 3857
+     *         }
+     *     },
+     *     "layers": {
+     *         "title": "Buildings"
+     *     },
+     *     "where": "FULL_ADDR = '900 GOVERNMENT ST'"
+     * }
+     * ```
+     *
      * @webOnly
      */
     get displayQuery(): Command<SetQueryArgs>;