accept simple print names to identify layers

sandbox.html

@@ -187,7 +187,7 @@
       mapExtent,
       minScale,
       parts,
-      layer,
+      layers,
       simplifiedOperationMode,
       useMapSrs
     }) {
@@ -207,7 +207,7 @@
         minScale: minScale && Number(minScale),
         parts: parts && parts.split(','),
         ...(simplifiedOperationMode === 'on' && { operationMode: 'simplified' }),
-        layers: layer && [ JSON.parse(layer) ],
+        layers: layers ? JSON.parse(layers) : undefined,
         useMapSrs: useMapSrs === 'on'
       };
     }
@@ -468,17 +468,27 @@
     <input name="embeddingTargetId" id="embeddingTargetId" required>
   </div>
   <div>
-    <label for="layer">Layer</label>
-    <input name="layer" id="layer">
-    <small>A JSON array with the print names of the layer and its ancestors, e.g. ["layerGroupName","layerName"]</small>
+    <label for="layers">Layers</label>
+    <input name="layers" id="layers">
+    <small>
+      <p>
+        A JSON value like <code>["layerPrintName",...]</code> or
+        <code>[["layerGroupPrintName","layerPrintName"],...]</code>
+      </p>
+    </small>
   </div>
 </template>
 
 <template data-action="setLayerVisibility">
   <div>
     <label for="layer">Layer *</label>
     <input name="layer" id="layer" required>
-    <small>A JSON array with the print names of the layer and its ancestors, e.g. ["layerGroupName","layerName"]</small>
+    <small>
+      <p>
+        A JSON value like <code>"layerPrintName"</code> or
+        <code>["layerGroupPrintName","layerPrintName"]</code>
+      </p>
+    </small>
   </div>
   <div>
     <label>

src/cadenza.js

@@ -54,7 +54,7 @@ globalThis.cadenza = Object.assign(
  * @property {string} externalLinkId - The ID of the external link
  */
 /**
- * @typedef {string[]} WorkbookLayerPath - Identifies a workbook layer within a view
+ * @typedef {string[]} WorkbookLayerPath - Identifies a layer within a workbook map view
  *   using the print names of the layer and - if the layer is grouped - its ancestors
  */
 
@@ -405,7 +405,8 @@ export class CadenzaClient {
    *
    * @param {EmbeddingTargetId} backgroundMapView - The workbook map view
    * @param {object} [options] - Options
-   * @param {WorkbookLayerPath[]} [options.layers] - Layers to restrict the selection to
+   * @param {(WorkbookLayerPath | string)[]} [options.layers] - Layers to restrict the selection to
+   *  (identified using layer paths or print names)
    * @param {string} [options.locationFinder] - A search query for the location finder
    * @param {Extent} [options.mapExtent] - A map extent to set
    * @param {boolean} [options.useMapSrs] - Whether the geometry is in the map's SRS (otherwise EPSG:4326 is assumed)
@@ -425,7 +426,7 @@ export class CadenzaClient {
     this.#log('CadenzaClient#selectObjects', ...arguments);
     const params = createParams({
       action: 'selectObjects',
-      layers,
+      layers: layers?.map(array),
       locationFinder,
       mapExtent,
       useMapSrs,
@@ -439,13 +440,17 @@ export class CadenzaClient {
    * When making a layer visible, its ancestors will be made visible, too.
    * When hiding a layer, the ancestors are not affected.
    *
-   * @param {WorkbookLayerPath} layer - The layer to show or hide
+   * @param {WorkbookLayerPath | string} layer - The layer to show or hide
+   *   (identified using a layer path or a print name)
    * @param {boolean} visible - The visibility state of the layer
    * @return {Promise<void>} A `Promise` for when the layer visibility is set.
    */
   setLayerVisibility(layer, visible) {
     this.#log('CadenzaClient#setLayerVisibility', ...arguments);
-    return this.#postRequest('setLayerVisibility', { layer, visible });
+    return this.#postRequest('setLayerVisibility', {
+      layer: array(layer),
+      visible,
+    });
   }
 
   #show(
@@ -904,6 +909,10 @@ function createParams({
   });
 }
 
+function array(/** @type unknown */ value) {
+  return Array.isArray(value) ? value : [value];
+}
+
 // Please do not add internal event types like 'ready' here.
 /**
  * @typedef {'change:extent'

src/docs.md

@@ -234,10 +234,10 @@ cadenzaClient.on('selectObjects:ok', (event) => {
 
 <small>API: [CadenzaClient#setLayerVisibility](./classes/CadenzaClient.html#setLayerVisibility)</small>
 
-To set the visibility of a layer in the currently shown map, pass the layer path and the desired visibility.
+To set the visibility of a layer in the currently shown map, pass the layer path or print name and the desired visibility.
 
 ```javascript
-cadenzaClient.setLayerVisibility([ '{layerGroupPrintName}', '{layerPrintName}' ], false);
+cadenzaClient.setLayerVisibility('{layerPrintName}', false);
 ```
 
 ### Highlight an Item in the Navigator