@fusion.dev/helix-headless 0.114.0 → 0.116.0

package/custom-elements.json

@@ -62448,9 +62448,28 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "`connectMap` fills the shape as a layer of the map, under its place names.\nThe frame lists each area by its `label` and `description` for screen\nreaders.",
+          "description": "`connectMap` fills the shape as a layer of the map, under its place names.\nThe frame lists each area by its `label` and `description` for screen\nreaders.\n\nSet `caption` to draw words on the map with the area, such as a letter for a\nsearch sector, in a color that reads on the map. It is drawn rather than\nfocusable, so it adds nothing to the tab order, and a screen reader reads\nthe area's `label` in the frame's list.",
           "name": "HelixHeadlessMapArea",
           "members": [
+            {
+              "kind": "field",
+              "name": "caption",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "Words drawn on the map with the area, such as `A` for a search sector.\nUnset, nothing is drawn. Keep it short: it is a caption on a map, and the\narea's `label` is what a screen reader hears.",
+              "attribute": "caption"
+            },
+            {
+              "kind": "field",
+              "name": "captionPlacement",
+              "type": {
+                "text": "'inside' | 'outside'"
+              },
+              "default": "'inside'",
+              "description": "Where the caption stands. `inside`, the default, at the point of the area\nfurthest from its edges. `outside`, just above the area's northernmost\npoint, clear of the shape, for an area whose caption would cover what is\nin it.",
+              "attribute": "caption-placement"
+            },
             {
               "kind": "field",
               "name": "description",
@@ -62834,6 +62853,23 @@
             }
           ],
           "attributes": [
+            {
+              "name": "caption",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "Words drawn on the map with the area, such as `A` for a search sector.\nUnset, nothing is drawn. Keep it short: it is a caption on a map, and the\narea's `label` is what a screen reader hears.",
+              "fieldName": "caption"
+            },
+            {
+              "name": "caption-placement",
+              "type": {
+                "text": "'inside' | 'outside'"
+              },
+              "default": "'inside'",
+              "description": "Where the caption stands. `inside`, the default, at the point of the area\nfurthest from its edges. `outside`, just above the area's northernmost\npoint, clear of the shape, for an area whose caption would cover what is\nin it.",
+              "fieldName": "captionPlacement"
+            },
             {
               "name": "description",
               "type": {
@@ -67177,6 +67213,14 @@
               "description": "The button that makes the map fill the screen.",
               "name": "fullscreen"
             },
+            {
+              "description": "Words over the map for a moment when it lets a gesture pass to the page, such as how to zoom it.",
+              "name": "gesture-hint"
+            },
+            {
+              "description": "The line shown while a map with `gestures=\"activate\"` has the gestures.",
+              "name": "gesture-status"
+            },
             {
               "description": "The strip above the map.",
               "name": "header"
@@ -67301,6 +67345,16 @@
             }
           ],
           "members": [
+            {
+              "kind": "field",
+              "name": "activateHintLabel",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Press the map to use it'",
+              "description": "The hint shown when a map waiting to be pressed is scrolled or swiped\nover, with `gestures=\"activate\"`.",
+              "attribute": "activate-hint-label"
+            },
             {
               "kind": "field",
               "name": "bearing",
@@ -67341,6 +67395,15 @@
               "description": "What screen readers hear when the map is tilted back to looking straight down.",
               "attribute": "flat-label"
             },
+            {
+              "kind": "field",
+              "name": "gestures",
+              "type": {
+                "text": "'activate' | 'always' | 'cooperative' | undefined"
+              },
+              "description": "Which gestures the map takes from the page.\n\n- `always`, which unset is: the wheel zooms the map and one finger pans\n  it, for a map that is the page, such as a full-screen view.\n- `cooperative`: the wheel and one finger scroll the page, and the map\n  takes Ctrl or ⌘ with the wheel, and two fingers. The frame says so\n  when a gesture passes to the page. Best for a map embedded in a page.\n- `activate`: the map takes nothing until it is pressed, and gives it\n  back on Escape, when the pointer leaves it, or on a press elsewhere.\n\nThe keyboard and the frame's buttons work in every mode. The renderer is\ntold through the connector, so MapLibre and Leaflet behave alike.",
+              "attribute": "gestures"
+            },
             {
               "kind": "field",
               "name": "hybridLabel",
@@ -67521,6 +67584,36 @@
               "description": "What screen readers hear when the map is turned. `{degrees}` is the way the\ntop of the map faces, clockwise from north.",
               "attribute": "turned-label"
             },
+            {
+              "kind": "field",
+              "name": "twoFingerHintLabel",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Use two fingers to move the map'",
+              "description": "The hint shown when one finger swipes over a map with `gestures=\"cooperative\"`.",
+              "attribute": "two-finger-hint-label"
+            },
+            {
+              "kind": "field",
+              "name": "usingLabel",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Using the map. Press Escape to scroll the page again.'",
+              "description": "The line shown while a map with `gestures=\"activate\"` has the gestures.",
+              "attribute": "using-label"
+            },
+            {
+              "kind": "field",
+              "name": "wheelHintLabel",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Use {key} and scroll to zoom the map'",
+              "description": "The hint shown when the wheel scrolls past a map with\n`gestures=\"cooperative\"`, with `{key}`, which is ⌘ on a Mac and Ctrl\nelsewhere, as the renderer reads it.",
+              "attribute": "wheel-hint-label"
+            },
             {
               "kind": "field",
               "name": "zoomedLabel",
@@ -67880,6 +67973,119 @@
               "privacy": "private",
               "readonly": true
             },
+            {
+              "kind": "field",
+              "name": "hint",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "private",
+              "default": "''",
+              "description": "The hint on the map while one shows, put there by a gesture the map let pass."
+            },
+            {
+              "kind": "field",
+              "name": "hinting",
+              "type": {
+                "text": "ReturnType<typeof setTimeout> | undefined"
+              },
+              "privacy": "private",
+              "description": "When the hint goes."
+            },
+            {
+              "kind": "field",
+              "name": "hintAt",
+              "type": {
+                "text": "{ x: number; y: number } | undefined"
+              },
+              "privacy": "private",
+              "description": "Where the gesture was, in the map's box, which the hint is shown at:\nwhere the reader is looking, and on the map wherever a page laid its own\ncontent over the rest of it."
+            },
+            {
+              "kind": "field",
+              "name": "taken",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "description": "Whether a map with `gestures=\"activate\"` has been pressed, and has the gestures."
+            },
+            {
+              "kind": "method",
+              "name": "showHint",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "words",
+                  "type": {
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "at",
+                  "optional": true,
+                  "type": {
+                    "text": "{ clientX: number; clientY: number }"
+                  }
+                }
+              ],
+              "description": "Shows a hint over the map for a moment, where the gesture was."
+            },
+            {
+              "kind": "field",
+              "name": "handleWheel",
+              "privacy": "private",
+              "readonly": true,
+              "description": "A wheel the map let pass to the page, which is said: a reader scrolling\nthe page past a map that did not zoom is told why, and how to zoom it.\n**Ctrl or ⌘ with the wheel is the map's**, and is what a trackpad's pinch\narrives as."
+            },
+            {
+              "kind": "field",
+              "name": "handleTouchMove",
+              "privacy": "private",
+              "readonly": true,
+              "description": "One finger moving over the map, which scrolls the page, and is said."
+            },
+            {
+              "kind": "field",
+              "name": "handleTake",
+              "privacy": "private",
+              "readonly": true,
+              "description": "A press on the map itself, which hands a waiting map the gestures."
+            },
+            {
+              "kind": "field",
+              "name": "handleGiveBackKey",
+              "privacy": "private",
+              "readonly": true,
+              "description": "Escape, which gives the page its scroll back."
+            },
+            {
+              "kind": "field",
+              "name": "handleGiveBackOutside",
+              "privacy": "private",
+              "readonly": true,
+              "description": "A press anywhere else on the page, which gives it its scroll back."
+            },
+            {
+              "kind": "field",
+              "name": "handleGiveBackBlur",
+              "privacy": "private",
+              "readonly": true,
+              "description": "The window losing focus, as a reader switching away does."
+            },
+            {
+              "kind": "field",
+              "name": "handleLeave",
+              "privacy": "private",
+              "readonly": true,
+              "description": "The pointer leaving the frame. **Heard on the frame and not the map's\ncanvas**, which a pointer resting on a marker has left, since markers\nstand outside it. **A mouse or a pen and never a finger**, whose\n`pointerleave` is the finger lifting: a tap took the map and gave it back\nin one."
+            },
             {
               "kind": "field",
               "name": "handleSlotChange",
@@ -68975,6 +69181,15 @@
             }
           ],
           "attributes": [
+            {
+              "name": "activate-hint-label",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Press the map to use it'",
+              "description": "The hint shown when a map waiting to be pressed is scrolled or swiped\nover, with `gestures=\"activate\"`.",
+              "fieldName": "activateHintLabel"
+            },
             {
               "name": "bearing",
               "type": {
@@ -69011,6 +69226,14 @@
               "description": "What screen readers hear when the map is tilted back to looking straight down.",
               "fieldName": "flatLabel"
             },
+            {
+              "name": "gestures",
+              "type": {
+                "text": "'activate' | 'always' | 'cooperative' | undefined"
+              },
+              "description": "Which gestures the map takes from the page.\n\n- `always`, which unset is: the wheel zooms the map and one finger pans\n  it, for a map that is the page, such as a full-screen view.\n- `cooperative`: the wheel and one finger scroll the page, and the map\n  takes Ctrl or ⌘ with the wheel, and two fingers. The frame says so\n  when a gesture passes to the page. Best for a map embedded in a page.\n- `activate`: the map takes nothing until it is pressed, and gives it\n  back on Escape, when the pointer leaves it, or on a press elsewhere.\n\nThe keyboard and the frame's buttons work in every mode. The renderer is\ntold through the connector, so MapLibre and Leaflet behave alike.",
+              "fieldName": "gestures"
+            },
             {
               "name": "hybrid-label",
               "type": {
@@ -69172,6 +69395,33 @@
               "description": "What screen readers hear when the map is turned. `{degrees}` is the way the\ntop of the map faces, clockwise from north.",
               "fieldName": "turnedLabel"
             },
+            {
+              "name": "two-finger-hint-label",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Use two fingers to move the map'",
+              "description": "The hint shown when one finger swipes over a map with `gestures=\"cooperative\"`.",
+              "fieldName": "twoFingerHintLabel"
+            },
+            {
+              "name": "using-label",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Using the map. Press Escape to scroll the page again.'",
+              "description": "The line shown while a map with `gestures=\"activate\"` has the gestures.",
+              "fieldName": "usingLabel"
+            },
+            {
+              "name": "wheel-hint-label",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Use {key} and scroll to zoom the map'",
+              "description": "The hint shown when the wheel scrolls past a map with\n`gestures=\"cooperative\"`, with `{key}`, which is ⌘ on a Mac and Ctrl\nelsewhere, as the renderer reads it.",
+              "fieldName": "wheelHintLabel"
+            },
             {
               "name": "zoomed-label",
               "type": {
@@ -69356,6 +69606,10 @@
               "description": "The map has been drawn whole, after `helix-map-ready`.",
               "name": "ready"
             },
+            {
+              "description": "A map with `gestures=\"activate\"` has been pressed and has the gestures.",
+              "name": "using"
+            },
             {
               "description": "Set one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.",
               "name": "settled",

package/dist/map/area/map-area.d.ts

@@ -9,6 +9,11 @@ import { type MapPoint } from '../route/map-route.js';
  * The frame lists each area by its `label` and `description` for screen
  * readers.
  *
+ * Set `caption` to draw words on the map with the area, such as a letter for a
+ * search sector, in a color that reads on the map. It is drawn rather than
+ * focusable, so it adds nothing to the tab order, and a screen reader reads
+ * the area's `label` in the frame's list.
+ *
  * @since 0.105.0
  * @status experimental
  * @category media
@@ -18,6 +23,19 @@ import { type MapPoint } from '../route/map-route.js';
  * @event {HelixMapPartChangeEvent} helix-map-part-change - The area's points, name, or color changed. Used by `connectMap`; pages do not need to listen for it.
  */
 export declare class HelixHeadlessMapArea extends HelixElement {
+    /**
+     * Words drawn on the map with the area, such as `A` for a search sector.
+     * Unset, nothing is drawn. Keep it short: it is a caption on a map, and the
+     * area's `label` is what a screen reader hears.
+     */
+    caption?: string;
+    /**
+     * Where the caption stands. `inside`, the default, at the point of the area
+     * furthest from its edges. `outside`, just above the area's northernmost
+     * point, clear of the shape, for an area whose caption would cover what is
+     * in it.
+     */
+    captionPlacement: 'inside' | 'outside';
     /** More about the area. Read after its label in the frame's list. */
     description?: string;
     /**

package/dist/map/area/map-area.js

@@ -11,6 +11,7 @@ import { pointsConverter } from '../route/map-route.js';
 let HelixHeadlessMapArea = class HelixHeadlessMapArea extends HelixElement {
     constructor() {
         super(...arguments);
+        this.captionPlacement = 'inside';
         this.isMapLayer = true;
         this.layerKind = 'area';
         this.label = 'Area';
@@ -23,6 +24,12 @@ let HelixHeadlessMapArea = class HelixHeadlessMapArea extends HelixElement {
         return nothing;
     }
 };
+__decorate([
+    property()
+], HelixHeadlessMapArea.prototype, "caption", void 0);
+__decorate([
+    property({ attribute: 'caption-placement' })
+], HelixHeadlessMapArea.prototype, "captionPlacement", void 0);
 __decorate([
     property()
 ], HelixHeadlessMapArea.prototype, "description", void 0);

package/dist/map/root/map-root.d.ts

@@ -81,6 +81,8 @@ declare const HelixHeadlessMap_base: (new (...args: any[]) => import("@fusion.de
  * @csspart face-north - The compass: its needle points north as the map turns, and pressing it turns the map to face north.
  * @csspart footer - The strip below the map.
  * @csspart fullscreen - The button that makes the map fill the screen.
+ * @csspart gesture-hint - Words over the map for a moment when it lets a gesture pass to the page, such as how to zoom it.
+ * @csspart gesture-status - The line shown while a map with `gestures="activate"` has the gestures.
  * @csspart header - The strip above the map.
  * @csspart layer - One entry in the list of the map's layers.
  * @csspart layer-choice - One layer's tile in the layers menu, pressed while the layer is shown.
@@ -113,8 +115,14 @@ declare const HelixHeadlessMap_base: (new (...args: any[]) => import("@fusion.de
  * @cssstate fullscreen - The map fills the screen.
  * @cssstate idle - The user has been still long enough for the header and footer to fade.
  * @cssstate ready - The map has been drawn whole, after `helix-map-ready`.
+ * @cssstate using - A map with `gestures="activate"` has been pressed and has the gestures.
  */
 export declare class HelixHeadlessMap extends HelixHeadlessMap_base {
+    /**
+     * The hint shown when a map waiting to be pressed is scrolled or swiped
+     * over, with `gestures="activate"`.
+     */
+    activateHintLabel: string;
     /**
      * The map's rotation, in degrees clockwise from north. `connectMap` keeps it
      * current, and the Face north button's needle turns with it.
@@ -129,6 +137,21 @@ export declare class HelixHeadlessMap extends HelixHeadlessMap_base {
     faceNorthLabel: string;
     /** What screen readers hear when the map is tilted back to looking straight down. */
     flatLabel: string;
+    /**
+     * Which gestures the map takes from the page.
+     *
+     * - `always`, which unset is: the wheel zooms the map and one finger pans
+     *   it, for a map that is the page, such as a full-screen view.
+     * - `cooperative`: the wheel and one finger scroll the page, and the map
+     *   takes Ctrl or ⌘ with the wheel, and two fingers. The frame says so
+     *   when a gesture passes to the page. Best for a map embedded in a page.
+     * - `activate`: the map takes nothing until it is pressed, and gives it
+     *   back on Escape, when the pointer leaves it, or on a press elsewhere.
+     *
+     * The keyboard and the frame's buttons work in every mode. The renderer is
+     * told through the connector, so MapLibre and Leaflet behave alike.
+     */
+    gestures?: 'activate' | 'always' | 'cooperative';
     /** The Hybrid map type's name. */
     hybridLabel: string;
     /**
@@ -190,6 +213,16 @@ export declare class HelixHeadlessMap extends HelixHeadlessMap_base {
      * top of the map faces, clockwise from north.
      */
     turnedLabel: string;
+    /** The hint shown when one finger swipes over a map with `gestures="cooperative"`. */
+    twoFingerHintLabel: string;
+    /** The line shown while a map with `gestures="activate"` has the gestures. */
+    usingLabel: string;
+    /**
+     * The hint shown when the wheel scrolls past a map with
+     * `gestures="cooperative"`, with `{key}`, which is ⌘ on a Mac and Ctrl
+     * elsewhere, as the renderer reads it.
+     */
+    wheelHintLabel: string;
     /**
      * What screen readers hear after a zoom. `{level}` is the zoom level.
      */
@@ -315,6 +348,51 @@ export declare class HelixHeadlessMap extends HelixHeadlessMap_base {
      */
     private readonly handleMarkerKeydown;
     private readonly handleMarkerKeyup;
+    /** The hint on the map while one shows, put there by a gesture the map let pass. */
+    private hint;
+    /** When the hint goes. */
+    private hinting;
+    /**
+     * Where the gesture was, in the map's box, which the hint is shown at:
+     * where the reader is looking, and on the map wherever a page laid its own
+     * content over the rest of it.
+     */
+    private hintAt;
+    /** Whether a map with `gestures="activate"` has been pressed, and has the gestures. */
+    private taken;
+    /**
+     * @internal Which gestures the renderer takes, which `connectMap` tells it:
+     * all of them, the cooperative set, or none, while an `activate` map waits
+     * to be pressed.
+     */
+    get gestureMode(): 'cooperative' | 'free' | 'off';
+    /** Shows a hint over the map for a moment, where the gesture was. */
+    private showHint;
+    /**
+     * A wheel the map let pass to the page, which is said: a reader scrolling
+     * the page past a map that did not zoom is told why, and how to zoom it.
+     * **Ctrl or ⌘ with the wheel is the map's**, and is what a trackpad's pinch
+     * arrives as.
+     */
+    private readonly handleWheel;
+    /** One finger moving over the map, which scrolls the page, and is said. */
+    private readonly handleTouchMove;
+    /** A press on the map itself, which hands a waiting map the gestures. */
+    private readonly handleTake;
+    /** Escape, which gives the page its scroll back. */
+    private readonly handleGiveBackKey;
+    /** A press anywhere else on the page, which gives it its scroll back. */
+    private readonly handleGiveBackOutside;
+    /** The window losing focus, as a reader switching away does. */
+    private readonly handleGiveBackBlur;
+    /**
+     * The pointer leaving the frame. **Heard on the frame and not the map's
+     * canvas**, which a pointer resting on a marker has left, since markers
+     * stand outside it. **A mouse or a pen and never a finger**, whose
+     * `pointerleave` is the finger lifting: a tap took the map and gave it back
+     * in one.
+     */
+    private readonly handleLeave;
     /** A marker added or taken away is a walk of a different length. */
     private readonly handleSlotChange;
     connectedCallback(): void;

package/dist/map/root/map-root.js

@@ -37,10 +37,12 @@ const TILT_STEP = 10;
 const TILTED = 50;
 const placed = (marker) => Number.isFinite(marker.lat) && Number.isFinite(marker.lng);
 const ASK_LAPSES = 3000;
+const HINT_SHOWS = 1600;
 const SETTLES = 400;
 let HelixHeadlessMap = class HelixHeadlessMap extends MixinViewport(HelixElement) {
     constructor() {
         super(...arguments);
+        this.activateHintLabel = 'Press the map to use it';
         this.bearing = 0;
         this.cluster = false;
         this.faceNorthLabel = 'Face north';
@@ -63,6 +65,9 @@ let HelixHeadlessMap = class HelixHeadlessMap extends MixinViewport(HelixElement
         this.tiltedLabel = 'Tilted {degrees} degrees';
         this.tiltLabel = 'Show in 3D';
         this.turnedLabel = 'Facing {degrees} degrees';
+        this.twoFingerHintLabel = 'Use two fingers to move the map';
+        this.usingLabel = 'Using the map. Press Escape to scroll the page again.';
+        this.wheelHintLabel = 'Use {key} and scroll to zoom the map';
         this.zoomedLabel = 'Zoom level {level}';
         this.said = '';
         this.asked = undefined;
@@ -131,6 +136,61 @@ let HelixHeadlessMap = class HelixHeadlessMap extends MixinViewport(HelixElement
                 this.activate(marker);
             }
         };
+        this.hint = '';
+        this.taken = false;
+        this.handleWheel = (event) => {
+            if (this.gestures === 'cooperative' && !(event.ctrlKey || event.metaKey)) {
+                const mac = typeof navigator !== 'undefined' && navigator.userAgent.includes('Mac');
+                this.showHint(fillTemplate(this.wheelHintLabel, { key: mac ? '⌘' : 'Ctrl' }), event);
+            }
+            else if (this.gestures === 'activate' && !this.taken) {
+                this.showHint(this.activateHintLabel, event);
+            }
+        };
+        this.handleTouchMove = (event) => {
+            const finger = event.touches[0];
+            if (event.touches.length !== 1) {
+                return;
+            }
+            if (this.gestures === 'cooperative') {
+                this.showHint(this.twoFingerHintLabel, finger);
+            }
+            else if (this.gestures === 'activate' && !this.taken) {
+                this.showHint(this.activateHintLabel, finger);
+            }
+        };
+        this.handleTake = (event) => {
+            const viewport = this.partNamed('viewport');
+            if (this.gestures !== 'activate' || this.taken || !viewport) {
+                return;
+            }
+            const path = event.composedPath();
+            const onMap = path.includes(viewport) ||
+                path.some((one) => one instanceof Element && one.parentElement === this && one.slot === '');
+            if (onMap) {
+                this.taken = true;
+                this.hint = '';
+            }
+        };
+        this.handleGiveBackKey = (event) => {
+            if (event.key === 'Escape' && this.taken) {
+                this.taken = false;
+            }
+        };
+        this.handleGiveBackOutside = (event) => {
+            if (!event.composedPath().includes(this)) {
+                this.taken = false;
+            }
+        };
+        this.handleGiveBackBlur = () => {
+            this.taken = false;
+        };
+        this.handleLeave = (event) => {
+            this.idle.leave();
+            if (event.pointerType !== 'touch') {
+                this.taken = false;
+            }
+        };
         this.handleSlotChange = () => {
             this.requestUpdate();
         };
@@ -243,6 +303,24 @@ let HelixHeadlessMap = class HelixHeadlessMap extends MixinViewport(HelixElement
         }
         this.dispatchEvent(new HelixActivateEvent({ value: marker.name || marker.label || '' }));
     }
+    get gestureMode() {
+        if (this.gestures === 'cooperative') {
+            return 'cooperative';
+        }
+        return this.gestures === 'activate' && !this.taken ? 'off' : 'free';
+    }
+    showHint(words, at) {
+        const box = this.partNamed('viewport')?.getBoundingClientRect();
+        this.hintAt =
+            at && box && box.width > 0 && box.height > 0
+                ? { x: (at.clientX - box.left) / box.width, y: (at.clientY - box.top) / box.height }
+                : undefined;
+        this.hint = words;
+        clearTimeout(this.hinting);
+        this.hinting = setTimeout(() => {
+            this.hint = '';
+        }, HINT_SHOWS);
+    }
     connectedCallback() {
         super.connectedCallback();
         this.addEventListener(HelixMapPartChangeEvent.eventName, this.handlePartChange);
@@ -250,6 +328,10 @@ let HelixHeadlessMap = class HelixHeadlessMap extends MixinViewport(HelixElement
         this.addEventListener('focusin', this.handleFocusIn);
         this.addEventListener('keydown', this.handleMarkerKeydown);
         this.addEventListener('keyup', this.handleMarkerKeyup);
+        this.addEventListener('keydown', this.handleGiveBackKey);
+        this.addEventListener('pointerdown', this.handleTake);
+        this.addEventListener('touchmove', this.handleTouchMove, { passive: true });
+        this.addEventListener('wheel', this.handleWheel, { passive: true });
         this.hiding = new MutationObserver(() => this.requestUpdate());
         this.hiding.observe(this, { attributeFilter: ['hidden'], attributes: true, subtree: true });
     }
@@ -264,6 +346,14 @@ let HelixHeadlessMap = class HelixHeadlessMap extends MixinViewport(HelixElement
         this.removeEventListener('focusin', this.handleFocusIn);
         this.removeEventListener('keydown', this.handleMarkerKeydown);
         this.removeEventListener('keyup', this.handleMarkerKeyup);
+        this.removeEventListener('keydown', this.handleGiveBackKey);
+        this.removeEventListener('pointerdown', this.handleTake);
+        this.removeEventListener('touchmove', this.handleTouchMove);
+        this.removeEventListener('wheel', this.handleWheel);
+        clearTimeout(this.hinting);
+        this.taken = false;
+        document.removeEventListener('pointerdown', this.handleGiveBackOutside);
+        window.removeEventListener('blur', this.handleGiveBackBlur);
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
@@ -274,6 +364,20 @@ let HelixHeadlessMap = class HelixHeadlessMap extends MixinViewport(HelixElement
         if (changed.has('mapType')) {
             this.dispatchEvent(new HelixMapPartChangeEvent({ kind: 'layer' }));
         }
+        if (changed.has('gestures') || changed.has('taken')) {
+            if (this.gestures !== 'activate' && this.taken) {
+                this.taken = false;
+            }
+            if (this.taken) {
+                document.addEventListener('pointerdown', this.handleGiveBackOutside);
+                window.addEventListener('blur', this.handleGiveBackBlur);
+            }
+            else {
+                document.removeEventListener('pointerdown', this.handleGiveBackOutside);
+                window.removeEventListener('blur', this.handleGiveBackBlur);
+            }
+            this.dispatchEvent(new HelixMapPartChangeEvent({ kind: 'gestures' }));
+        }
         if (changed.has('layersOpen')) {
             if (this.layersOpen) {
                 document.addEventListener('pointerdown', this.handleOutside);
@@ -515,6 +619,7 @@ let HelixHeadlessMap = class HelixHeadlessMap extends MixinViewport(HelixElement
         hostAria(this.internals, { label: this.label });
         this.toggleState('fullscreen', this.filled);
         this.toggleState('idle', this.resting);
+        this.toggleState('using', this.taken);
     }
     renderLayers() {
         const layers = this.layers.filter((layer) => this.shown(layer));
@@ -534,7 +639,7 @@ let HelixHeadlessMap = class HelixHeadlessMap extends MixinViewport(HelixElement
       tabindex="0"
       @focusin=${this.idle.stir}
       @keydown=${this.handleKeydown}
-      @pointerleave=${this.idle.leave}
+      @pointerleave=${this.handleLeave}
       @pointermove=${this.idle.stir}
     >
       <div part="header">
@@ -542,6 +647,13 @@ let HelixHeadlessMap = class HelixHeadlessMap extends MixinViewport(HelixElement
       </div>
       <div part="viewport">
         <slot @slotchange=${this.handleSlotChange}></slot>
+        <div
+          part="gesture-hint"
+          aria-hidden="true"
+          ?hidden=${this.hint === ''}
+          style=${this.hintAt ? `--_map-hint-x: ${(this.hintAt.x * 100).toFixed(2)}%; --_map-hint-y: ${(this.hintAt.y * 100).toFixed(2)}%` : nothing}
+        >${this.hint}</div>
+        <div part="gesture-status" aria-hidden="true" ?hidden=${!this.taken}>${this.usingLabel}</div>
       </div>
       ${this.renderLayers()}
       ${this.renderControls()}
@@ -555,6 +667,9 @@ let HelixHeadlessMap = class HelixHeadlessMap extends MixinViewport(HelixElement
     </div>`;
     }
 };
+__decorate([
+    property({ attribute: 'activate-hint-label' })
+], HelixHeadlessMap.prototype, "activateHintLabel", void 0);
 __decorate([
     property({ type: Number })
 ], HelixHeadlessMap.prototype, "bearing", void 0);
@@ -567,6 +682,9 @@ __decorate([
 __decorate([
     property({ attribute: 'flat-label' })
 ], HelixHeadlessMap.prototype, "flatLabel", void 0);
+__decorate([
+    property()
+], HelixHeadlessMap.prototype, "gestures", void 0);
 __decorate([
     property({ attribute: 'hybrid-label' })
 ], HelixHeadlessMap.prototype, "hybridLabel", void 0);
@@ -624,6 +742,15 @@ __decorate([
 __decorate([
     property({ attribute: 'turned-label' })
 ], HelixHeadlessMap.prototype, "turnedLabel", void 0);
+__decorate([
+    property({ attribute: 'two-finger-hint-label' })
+], HelixHeadlessMap.prototype, "twoFingerHintLabel", void 0);
+__decorate([
+    property({ attribute: 'using-label' })
+], HelixHeadlessMap.prototype, "usingLabel", void 0);
+__decorate([
+    property({ attribute: 'wheel-hint-label' })
+], HelixHeadlessMap.prototype, "wheelHintLabel", void 0);
 __decorate([
     property({ attribute: 'zoomed-label' })
 ], HelixHeadlessMap.prototype, "zoomedLabel", void 0);
@@ -639,6 +766,15 @@ __decorate([
 __decorate([
     state()
 ], HelixHeadlessMap.prototype, "stop", void 0);
+__decorate([
+    state()
+], HelixHeadlessMap.prototype, "hint", void 0);
+__decorate([
+    state()
+], HelixHeadlessMap.prototype, "hintAt", void 0);
+__decorate([
+    state()
+], HelixHeadlessMap.prototype, "taken", void 0);
 HelixHeadlessMap = __decorate([
     customElement('helix-headless-map')
 ], HelixHeadlessMap);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-headless",
   "description": "Headless component tier. Structure, accessibility, state, and form participation. No styling.",
-  "version": "0.114.0",
+  "version": "0.116.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -46,13 +46,13 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.114.0",
-    "@fusion.dev/helix-icons": "0.114.0",
+    "@fusion.dev/helix-core": "0.116.0",
+    "@fusion.dev/helix-icons": "0.116.0",
     "uqr": "^0.1.3"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.114.0",
-    "@fusion.dev/helix-testing": "0.114.0",
+    "@fusion.dev/helix-cem": "0.116.0",
+    "@fusion.dev/helix-testing": "0.116.0",
     "@fusion.dev/scripts": "0.0.0-dev",
     "@happy-dom/global-registrator": "^20.0.0",
     "@lit-labs/ssr": "^4.1.0",

package/types/jsx.d.ts

@@ -11474,6 +11474,20 @@ export type HelixHeadlessMapAreaHelixMapPartChangeElementEvent =
   HelixHeadlessMapAreaElementEvent<HelixMapPartChangeEvent>;
 
 export type HelixHeadlessMapAreaProps = {
+  /** Words drawn on the map with the area, such as `A` for a search sector.
+Unset, nothing is drawn. Keep it short: it is a caption on a map, and the
+area's `label` is what a screen reader hears. */
+  caption?: (HelixHeadlessMapArea["caption"]) | undefined;
+  /** Where the caption stands. `inside`, the default, at the point of the area
+furthest from its edges. `outside`, just above the area's northernmost
+point, clear of the shape, for an area whose caption would cover what is
+in it. */
+  "caption-placement"?: (HelixHeadlessMapArea["captionPlacement"]) | undefined;
+  /** Where the caption stands. `inside`, the default, at the point of the area
+furthest from its edges. `outside`, just above the area's northernmost
+point, clear of the shape, for an area whose caption would cover what is
+in it. */
+  captionPlacement?: (HelixHeadlessMapArea["captionPlacement"]) | undefined;
   /** More about the area. Read after its label in the frame's list. */
   description?: (HelixHeadlessMapArea["description"]) | undefined;
   /** A name this layer shares with other layers, such as a route and its
@@ -11494,6 +11508,20 @@ first. */
 };
 
 export type HelixHeadlessMapAreaSolidJsProps = {
+  /** Words drawn on the map with the area, such as `A` for a search sector.
+Unset, nothing is drawn. Keep it short: it is a caption on a map, and the
+area's `label` is what a screen reader hears. */
+  "prop:caption"?: (HelixHeadlessMapArea["caption"]) | undefined;
+  /** Where the caption stands. `inside`, the default, at the point of the area
+furthest from its edges. `outside`, just above the area's northernmost
+point, clear of the shape, for an area whose caption would cover what is
+in it. */
+  "attr:caption-placement"?: (HelixHeadlessMapArea["captionPlacement"]) | undefined;
+  /** Where the caption stands. `inside`, the default, at the point of the area
+furthest from its edges. `outside`, just above the area's northernmost
+point, clear of the shape, for an area whose caption would cover what is
+in it. */
+  "prop:captionPlacement"?: (HelixHeadlessMapArea["captionPlacement"]) | undefined;
   /** More about the area. Read after its label in the frame's list. */
   "prop:description"?: (HelixHeadlessMapArea["description"]) | undefined;
   /** A name this layer shares with other layers, such as a route and its
@@ -12040,6 +12068,12 @@ export type HelixHeadlessMapHelixMapZoomElementEvent =
   HelixHeadlessMapElementEvent<HelixMapZoomEvent>;
 
 export type HelixHeadlessMapProps = {
+  /** The hint shown when a map waiting to be pressed is scrolled or swiped
+over, with `gestures="activate"`. */
+  "activate-hint-label"?: (HelixHeadlessMap["activateHintLabel"]) | undefined;
+  /** The hint shown when a map waiting to be pressed is scrolled or swiped
+over, with `gestures="activate"`. */
+  activateHintLabel?: (HelixHeadlessMap["activateHintLabel"]) | undefined;
   /** The map's rotation, in degrees clockwise from north. `connectMap` keeps it
 current, and the Face north button's needle turns with it. */
   bearing?: (HelixHeadlessMap["bearing"]) | undefined;
@@ -12054,6 +12088,19 @@ the map zooms in, and pressing one zooms in to its places. */
   "flat-label"?: (HelixHeadlessMap["flatLabel"]) | undefined;
   /** What screen readers hear when the map is tilted back to looking straight down. */
   flatLabel?: (HelixHeadlessMap["flatLabel"]) | undefined;
+  /** Which gestures the map takes from the page.
+
+- `always`, which unset is: the wheel zooms the map and one finger pans
+  it, for a map that is the page, such as a full-screen view.
+- `cooperative`: the wheel and one finger scroll the page, and the map
+  takes Ctrl or ⌘ with the wheel, and two fingers. The frame says so
+  when a gesture passes to the page. Best for a map embedded in a page.
+- `activate`: the map takes nothing until it is pressed, and gives it
+  back on Escape, when the pointer leaves it, or on a press elsewhere.
+
+The keyboard and the frame's buttons work in every mode. The renderer is
+told through the connector, so MapLibre and Leaflet behave alike. */
+  gestures?: (HelixHeadlessMap["gestures"]) | undefined;
   /** The Hybrid map type's name. */
   "hybrid-label"?: (HelixHeadlessMap["hybridLabel"]) | undefined;
   /** The Hybrid map type's name. */
@@ -12135,6 +12182,22 @@ top of the map faces, clockwise from north. */
   /** What screen readers hear when the map is turned. `{degrees}` is the way the
 top of the map faces, clockwise from north. */
   turnedLabel?: (HelixHeadlessMap["turnedLabel"]) | undefined;
+  /** The hint shown when one finger swipes over a map with `gestures="cooperative"`. */
+  "two-finger-hint-label"?: (HelixHeadlessMap["twoFingerHintLabel"]) | undefined;
+  /** The hint shown when one finger swipes over a map with `gestures="cooperative"`. */
+  twoFingerHintLabel?: (HelixHeadlessMap["twoFingerHintLabel"]) | undefined;
+  /** The line shown while a map with `gestures="activate"` has the gestures. */
+  "using-label"?: (HelixHeadlessMap["usingLabel"]) | undefined;
+  /** The line shown while a map with `gestures="activate"` has the gestures. */
+  usingLabel?: (HelixHeadlessMap["usingLabel"]) | undefined;
+  /** The hint shown when the wheel scrolls past a map with
+`gestures="cooperative"`, with `{key}`, which is ⌘ on a Mac and Ctrl
+elsewhere, as the renderer reads it. */
+  "wheel-hint-label"?: (HelixHeadlessMap["wheelHintLabel"]) | undefined;
+  /** The hint shown when the wheel scrolls past a map with
+`gestures="cooperative"`, with `{key}`, which is ⌘ on a Mac and Ctrl
+elsewhere, as the renderer reads it. */
+  wheelHintLabel?: (HelixHeadlessMap["wheelHintLabel"]) | undefined;
   /** What screen readers hear after a zoom. `{level}` is the zoom level. */
   "zoomed-label"?: (HelixHeadlessMap["zoomedLabel"]) | undefined;
   /** What screen readers hear after a zoom. `{level}` is the zoom level. */
@@ -12297,6 +12360,12 @@ at any zoom, and a consumer who wants their own units multiplies by them. */
 };
 
 export type HelixHeadlessMapSolidJsProps = {
+  /** The hint shown when a map waiting to be pressed is scrolled or swiped
+over, with `gestures="activate"`. */
+  "attr:activate-hint-label"?: (HelixHeadlessMap["activateHintLabel"]) | undefined;
+  /** The hint shown when a map waiting to be pressed is scrolled or swiped
+over, with `gestures="activate"`. */
+  "prop:activateHintLabel"?: (HelixHeadlessMap["activateHintLabel"]) | undefined;
   /** The map's rotation, in degrees clockwise from north. `connectMap` keeps it
 current, and the Face north button's needle turns with it. */
   "prop:bearing"?: (HelixHeadlessMap["bearing"]) | undefined;
@@ -12311,6 +12380,19 @@ the map zooms in, and pressing one zooms in to its places. */
   "attr:flat-label"?: (HelixHeadlessMap["flatLabel"]) | undefined;
   /** What screen readers hear when the map is tilted back to looking straight down. */
   "prop:flatLabel"?: (HelixHeadlessMap["flatLabel"]) | undefined;
+  /** Which gestures the map takes from the page.
+
+- `always`, which unset is: the wheel zooms the map and one finger pans
+  it, for a map that is the page, such as a full-screen view.
+- `cooperative`: the wheel and one finger scroll the page, and the map
+  takes Ctrl or ⌘ with the wheel, and two fingers. The frame says so
+  when a gesture passes to the page. Best for a map embedded in a page.
+- `activate`: the map takes nothing until it is pressed, and gives it
+  back on Escape, when the pointer leaves it, or on a press elsewhere.
+
+The keyboard and the frame's buttons work in every mode. The renderer is
+told through the connector, so MapLibre and Leaflet behave alike. */
+  "prop:gestures"?: (HelixHeadlessMap["gestures"]) | undefined;
   /** The Hybrid map type's name. */
   "attr:hybrid-label"?: (HelixHeadlessMap["hybridLabel"]) | undefined;
   /** The Hybrid map type's name. */
@@ -12392,6 +12474,22 @@ top of the map faces, clockwise from north. */
   /** What screen readers hear when the map is turned. `{degrees}` is the way the
 top of the map faces, clockwise from north. */
   "prop:turnedLabel"?: (HelixHeadlessMap["turnedLabel"]) | undefined;
+  /** The hint shown when one finger swipes over a map with `gestures="cooperative"`. */
+  "attr:two-finger-hint-label"?: (HelixHeadlessMap["twoFingerHintLabel"]) | undefined;
+  /** The hint shown when one finger swipes over a map with `gestures="cooperative"`. */
+  "prop:twoFingerHintLabel"?: (HelixHeadlessMap["twoFingerHintLabel"]) | undefined;
+  /** The line shown while a map with `gestures="activate"` has the gestures. */
+  "attr:using-label"?: (HelixHeadlessMap["usingLabel"]) | undefined;
+  /** The line shown while a map with `gestures="activate"` has the gestures. */
+  "prop:usingLabel"?: (HelixHeadlessMap["usingLabel"]) | undefined;
+  /** The hint shown when the wheel scrolls past a map with
+`gestures="cooperative"`, with `{key}`, which is ⌘ on a Mac and Ctrl
+elsewhere, as the renderer reads it. */
+  "attr:wheel-hint-label"?: (HelixHeadlessMap["wheelHintLabel"]) | undefined;
+  /** The hint shown when the wheel scrolls past a map with
+`gestures="cooperative"`, with `{key}`, which is ⌘ on a Mac and Ctrl
+elsewhere, as the renderer reads it. */
+  "prop:wheelHintLabel"?: (HelixHeadlessMap["wheelHintLabel"]) | undefined;
   /** What screen readers hear after a zoom. `{level}` is the zoom level. */
   "attr:zoomed-label"?: (HelixHeadlessMap["zoomedLabel"]) | undefined;
   /** What screen readers hear after a zoom. `{level}` is the zoom level. */
@@ -32495,10 +32593,22 @@ export type CustomElements = {
    * The frame lists each area by its `label` and `description` for screen
    * readers.
    *
+   * Set `caption` to draw words on the map with the area, such as a letter for a
+   * search sector, in a color that reads on the map. It is drawn rather than
+   * focusable, so it adds nothing to the tab order, and a screen reader reads
+   * the area's `label` in the frame's list.
+   *
    * ## Attributes & Properties
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
+   * - `caption`: Words drawn on the map with the area, such as `A` for a search sector.
+   * Unset, nothing is drawn. Keep it short: it is a caption on a map, and the
+   * area's `label` is what a screen reader hears.
+   * - `caption-placement`/`captionPlacement`: Where the caption stands. `inside`, the default, at the point of the area
+   * furthest from its edges. `outside`, just above the area's northernmost
+   * point, clear of the shape, for an area whose caption would cover what is
+   * in it.
    * - `description`: More about the area. Read after its label in the frame's list.
    * - `group`: A name this layer shares with other layers, such as a route and its
    * dotted legs. The layers menu shows layers in the same group as one entry,
@@ -33101,12 +33211,26 @@ export type CustomElements = {
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
+   * - `activate-hint-label`/`activateHintLabel`: The hint shown when a map waiting to be pressed is scrolled or swiped
+   * over, with `gestures="activate"`.
    * - `bearing`: The map's rotation, in degrees clockwise from north. `connectMap` keeps it
    * current, and the Face north button's needle turns with it.
    * - `cluster`: Combines markers that would overlap into one count. Counts split apart as
    * the map zooms in, and pressing one zooms in to its places.
    * - `face-north-label`/`faceNorthLabel`: The Face north button's label.
    * - `flat-label`/`flatLabel`: What screen readers hear when the map is tilted back to looking straight down.
+   * - `gestures`: Which gestures the map takes from the page.
+   *
+   * - `always`, which unset is: the wheel zooms the map and one finger pans
+   *   it, for a map that is the page, such as a full-screen view.
+   * - `cooperative`: the wheel and one finger scroll the page, and the map
+   *   takes Ctrl or ⌘ with the wheel, and two fingers. The frame says so
+   *   when a gesture passes to the page. Best for a map embedded in a page.
+   * - `activate`: the map takes nothing until it is pressed, and gives it
+   *   back on Escape, when the pointer leaves it, or on a press elsewhere.
+   *
+   * The keyboard and the frame's buttons work in every mode. The renderer is
+   * told through the connector, so MapLibre and Leaflet behave alike.
    * - `hybrid-label`/`hybridLabel`: The Hybrid map type's name.
    * - `label`: The map's name, read by screen readers. Name the place, such as "Delivery
    * area", so that several maps on one page can be told apart. Required.
@@ -33133,6 +33257,11 @@ export type CustomElements = {
    * - `tilt-label`/`tiltLabel`: The 3D button's label.
    * - `turned-label`/`turnedLabel`: What screen readers hear when the map is turned. `{degrees}` is the way the
    * top of the map faces, clockwise from north.
+   * - `two-finger-hint-label`/`twoFingerHintLabel`: The hint shown when one finger swipes over a map with `gestures="cooperative"`.
+   * - `using-label`/`usingLabel`: The line shown while a map with `gestures="activate"` has the gestures.
+   * - `wheel-hint-label`/`wheelHintLabel`: The hint shown when the wheel scrolls past a map with
+   * `gestures="cooperative"`, with `{key}`, which is ⌘ on a Mac and Ctrl
+   * elsewhere, as the renderer reads it.
    * - `zoomed-label`/`zoomedLabel`: What screen readers hear after a zoom. `{level}` is the zoom level.
    * - `zoom-level`/`zoomLevel`: How far the map is zoomed, in its renderer's levels. `connectMap` keeps it
    * current, and the map says it after a zoom.
@@ -33293,6 +33422,8 @@ export type CustomElements = {
    * - `face-north`: The compass: its needle points north as the map turns, and pressing it turns the map to face north.
    * - `footer`: The strip below the map.
    * - `fullscreen`: The button that makes the map fill the screen.
+   * - `gesture-hint`: Words over the map for a moment when it lets a gesture pass to the page, such as how to zoom it.
+   * - `gesture-status`: The line shown while a map with `gestures="activate"` has the gestures.
    * - `header`: The strip above the map.
    * - `layer`: One entry in the list of the map's layers.
    * - `layer-choice`: One layer's tile in the layers menu, pressed while the layer is shown.
@@ -33327,6 +33458,7 @@ export type CustomElements = {
    * - `fullscreen`: The map fills the screen.
    * - `idle`: The user has been still long enough for the header and footer to fade.
    * - `ready`: The map has been drawn whole, after `helix-map-ready`.
+   * - `using`: A map with `gestures="activate"` has been pressed and has the gestures.
    * - `settled`: Set one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
    */
   "helix-headless-map": Partial<
@@ -52564,10 +52696,22 @@ export type CustomElementsSolidJs = {
    * The frame lists each area by its `label` and `description` for screen
    * readers.
    *
+   * Set `caption` to draw words on the map with the area, such as a letter for a
+   * search sector, in a color that reads on the map. It is drawn rather than
+   * focusable, so it adds nothing to the tab order, and a screen reader reads
+   * the area's `label` in the frame's list.
+   *
    * ## Attributes & Properties
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
+   * - `caption`: Words drawn on the map with the area, such as `A` for a search sector.
+   * Unset, nothing is drawn. Keep it short: it is a caption on a map, and the
+   * area's `label` is what a screen reader hears.
+   * - `caption-placement`/`captionPlacement`: Where the caption stands. `inside`, the default, at the point of the area
+   * furthest from its edges. `outside`, just above the area's northernmost
+   * point, clear of the shape, for an area whose caption would cover what is
+   * in it.
    * - `description`: More about the area. Read after its label in the frame's list.
    * - `group`: A name this layer shares with other layers, such as a route and its
    * dotted legs. The layers menu shows layers in the same group as one entry,
@@ -53186,12 +53330,26 @@ export type CustomElementsSolidJs = {
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
+   * - `activate-hint-label`/`activateHintLabel`: The hint shown when a map waiting to be pressed is scrolled or swiped
+   * over, with `gestures="activate"`.
    * - `bearing`: The map's rotation, in degrees clockwise from north. `connectMap` keeps it
    * current, and the Face north button's needle turns with it.
    * - `cluster`: Combines markers that would overlap into one count. Counts split apart as
    * the map zooms in, and pressing one zooms in to its places.
    * - `face-north-label`/`faceNorthLabel`: The Face north button's label.
    * - `flat-label`/`flatLabel`: What screen readers hear when the map is tilted back to looking straight down.
+   * - `gestures`: Which gestures the map takes from the page.
+   *
+   * - `always`, which unset is: the wheel zooms the map and one finger pans
+   *   it, for a map that is the page, such as a full-screen view.
+   * - `cooperative`: the wheel and one finger scroll the page, and the map
+   *   takes Ctrl or ⌘ with the wheel, and two fingers. The frame says so
+   *   when a gesture passes to the page. Best for a map embedded in a page.
+   * - `activate`: the map takes nothing until it is pressed, and gives it
+   *   back on Escape, when the pointer leaves it, or on a press elsewhere.
+   *
+   * The keyboard and the frame's buttons work in every mode. The renderer is
+   * told through the connector, so MapLibre and Leaflet behave alike.
    * - `hybrid-label`/`hybridLabel`: The Hybrid map type's name.
    * - `label`: The map's name, read by screen readers. Name the place, such as "Delivery
    * area", so that several maps on one page can be told apart. Required.
@@ -53218,6 +53376,11 @@ export type CustomElementsSolidJs = {
    * - `tilt-label`/`tiltLabel`: The 3D button's label.
    * - `turned-label`/`turnedLabel`: What screen readers hear when the map is turned. `{degrees}` is the way the
    * top of the map faces, clockwise from north.
+   * - `two-finger-hint-label`/`twoFingerHintLabel`: The hint shown when one finger swipes over a map with `gestures="cooperative"`.
+   * - `using-label`/`usingLabel`: The line shown while a map with `gestures="activate"` has the gestures.
+   * - `wheel-hint-label`/`wheelHintLabel`: The hint shown when the wheel scrolls past a map with
+   * `gestures="cooperative"`, with `{key}`, which is ⌘ on a Mac and Ctrl
+   * elsewhere, as the renderer reads it.
    * - `zoomed-label`/`zoomedLabel`: What screen readers hear after a zoom. `{level}` is the zoom level.
    * - `zoom-level`/`zoomLevel`: How far the map is zoomed, in its renderer's levels. `connectMap` keeps it
    * current, and the map says it after a zoom.
@@ -53378,6 +53541,8 @@ export type CustomElementsSolidJs = {
    * - `face-north`: The compass: its needle points north as the map turns, and pressing it turns the map to face north.
    * - `footer`: The strip below the map.
    * - `fullscreen`: The button that makes the map fill the screen.
+   * - `gesture-hint`: Words over the map for a moment when it lets a gesture pass to the page, such as how to zoom it.
+   * - `gesture-status`: The line shown while a map with `gestures="activate"` has the gestures.
    * - `header`: The strip above the map.
    * - `layer`: One entry in the list of the map's layers.
    * - `layer-choice`: One layer's tile in the layers menu, pressed while the layer is shown.
@@ -53412,6 +53577,7 @@ export type CustomElementsSolidJs = {
    * - `fullscreen`: The map fills the screen.
    * - `idle`: The user has been still long enough for the header and footer to fade.
    * - `ready`: The map has been drawn whole, after `helix-map-ready`.
+   * - `using`: A map with `gestures="activate"` has been pressed and has the gestures.
    * - `settled`: Set one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
    */
   "helix-headless-map": Partial<

package/types/vue.d.ts

@@ -5872,6 +5872,20 @@ export type HelixHeadlessMapAreaHelixMapPartChangeElementEvent =
   HelixHeadlessMapAreaElementEvent<HelixMapPartChangeEvent>;
 
 export type HelixHeadlessMapAreaVueProps = {
+  /** Words drawn on the map with the area, such as `A` for a search sector.
+Unset, nothing is drawn. Keep it short: it is a caption on a map, and the
+area's `label` is what a screen reader hears. */
+  caption?: (HelixHeadlessMapArea["caption"]) | undefined;
+  /** Where the caption stands. `inside`, the default, at the point of the area
+furthest from its edges. `outside`, just above the area's northernmost
+point, clear of the shape, for an area whose caption would cover what is
+in it. */
+  "caption-placement"?: (HelixHeadlessMapArea["captionPlacement"]) | undefined;
+  /** Where the caption stands. `inside`, the default, at the point of the area
+furthest from its edges. `outside`, just above the area's northernmost
+point, clear of the shape, for an area whose caption would cover what is
+in it. */
+  captionPlacement?: (HelixHeadlessMapArea["captionPlacement"]) | undefined;
   /** More about the area. Read after its label in the frame's list. */
   description?: (HelixHeadlessMapArea["description"]) | undefined;
   /** A name this layer shares with other layers, such as a route and its
@@ -6184,6 +6198,12 @@ export type HelixHeadlessMapHelixMapZoomElementEvent =
   HelixHeadlessMapElementEvent<HelixMapZoomEvent>;
 
 export type HelixHeadlessMapVueProps = {
+  /** The hint shown when a map waiting to be pressed is scrolled or swiped
+over, with `gestures="activate"`. */
+  "activate-hint-label"?: (HelixHeadlessMap["activateHintLabel"]) | undefined;
+  /** The hint shown when a map waiting to be pressed is scrolled or swiped
+over, with `gestures="activate"`. */
+  activateHintLabel?: (HelixHeadlessMap["activateHintLabel"]) | undefined;
   /** The map's rotation, in degrees clockwise from north. `connectMap` keeps it
 current, and the Face north button's needle turns with it. */
   bearing?: (HelixHeadlessMap["bearing"]) | undefined;
@@ -6198,6 +6218,19 @@ the map zooms in, and pressing one zooms in to its places. */
   "flat-label"?: (HelixHeadlessMap["flatLabel"]) | undefined;
   /** What screen readers hear when the map is tilted back to looking straight down. */
   flatLabel?: (HelixHeadlessMap["flatLabel"]) | undefined;
+  /** Which gestures the map takes from the page.
+
+- `always`, which unset is: the wheel zooms the map and one finger pans
+  it, for a map that is the page, such as a full-screen view.
+- `cooperative`: the wheel and one finger scroll the page, and the map
+  takes Ctrl or ⌘ with the wheel, and two fingers. The frame says so
+  when a gesture passes to the page. Best for a map embedded in a page.
+- `activate`: the map takes nothing until it is pressed, and gives it
+  back on Escape, when the pointer leaves it, or on a press elsewhere.
+
+The keyboard and the frame's buttons work in every mode. The renderer is
+told through the connector, so MapLibre and Leaflet behave alike. */
+  gestures?: (HelixHeadlessMap["gestures"]) | undefined;
   /** The Hybrid map type's name. */
   "hybrid-label"?: (HelixHeadlessMap["hybridLabel"]) | undefined;
   /** The Hybrid map type's name. */
@@ -6279,6 +6312,22 @@ top of the map faces, clockwise from north. */
   /** What screen readers hear when the map is turned. `{degrees}` is the way the
 top of the map faces, clockwise from north. */
   turnedLabel?: (HelixHeadlessMap["turnedLabel"]) | undefined;
+  /** The hint shown when one finger swipes over a map with `gestures="cooperative"`. */
+  "two-finger-hint-label"?: (HelixHeadlessMap["twoFingerHintLabel"]) | undefined;
+  /** The hint shown when one finger swipes over a map with `gestures="cooperative"`. */
+  twoFingerHintLabel?: (HelixHeadlessMap["twoFingerHintLabel"]) | undefined;
+  /** The line shown while a map with `gestures="activate"` has the gestures. */
+  "using-label"?: (HelixHeadlessMap["usingLabel"]) | undefined;
+  /** The line shown while a map with `gestures="activate"` has the gestures. */
+  usingLabel?: (HelixHeadlessMap["usingLabel"]) | undefined;
+  /** The hint shown when the wheel scrolls past a map with
+`gestures="cooperative"`, with `{key}`, which is ⌘ on a Mac and Ctrl
+elsewhere, as the renderer reads it. */
+  "wheel-hint-label"?: (HelixHeadlessMap["wheelHintLabel"]) | undefined;
+  /** The hint shown when the wheel scrolls past a map with
+`gestures="cooperative"`, with `{key}`, which is ⌘ on a Mac and Ctrl
+elsewhere, as the renderer reads it. */
+  wheelHintLabel?: (HelixHeadlessMap["wheelHintLabel"]) | undefined;
   /** What screen readers hear after a zoom. `{level}` is the zoom level. */
   "zoomed-label"?: (HelixHeadlessMap["zoomedLabel"]) | undefined;
   /** What screen readers hear after a zoom. `{level}` is the zoom level. */
@@ -12140,7 +12189,7 @@ export interface WcToolkitVueGlobalComponents {
     HelixHeadlessLoaderVueProps,
     HelixHeadlessLoaderVueEvents
   >;
-  /** 'connectMap' fills the shape as a layer of the map, under its place names. The frame lists each area by its 'label' and 'description' for screen readers. */
+  /** 'connectMap' fills the shape as a layer of the map, under its place names. The frame lists each area by its 'label' and 'description' for screen readers.  Set 'caption' to draw words on the map with the area, such as a letter for a search sector, in a color that reads on the map. It is drawn rather than focusable, so it adds nothing to the tab order, and a screen reader reads the area's 'label' in the frame's list. */
   "helix-headless-map-area": DefineCustomElement<
     HelixHeadlessMapArea,
     HelixHeadlessMapAreaVueProps,