@fusion.dev/helix-headless 0.115.0 → 0.116.0

package/custom-elements.json

@@ -67213,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"
@@ -67337,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",
@@ -67377,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",
@@ -67557,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",
@@ -67916,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",
@@ -69011,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": {
@@ -69047,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": {
@@ -69208,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": {
@@ -69392,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/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.115.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.115.0",
-    "@fusion.dev/helix-icons": "0.115.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.115.0",
-    "@fusion.dev/helix-testing": "0.115.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

@@ -12068,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;
@@ -12082,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. */
@@ -12163,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. */
@@ -12325,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;
@@ -12339,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. */
@@ -12420,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. */
@@ -33141,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.
@@ -33173,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.
@@ -33333,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.
@@ -33367,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<
@@ -53238,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.
@@ -53270,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.
@@ -53430,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.
@@ -53464,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

@@ -6198,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;
@@ -6212,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. */
@@ -6293,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. */