@fusion.dev/helix-headless 0.115.0 → 0.117.0

package/dist/index.js

@@ -38,6 +38,7 @@ export * from './empty/index.js';
 export * from './file-input/index.js';
 export * from './filter-input/index.js';
 export * from './format-date/index.js';
+export * from './graph/index.js';
 export * from './heatmap/index.js';
 export * from './icon/index.js';
 export * from './icon-button/index.js';

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.117.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.117.0",
+    "@fusion.dev/helix-icons": "0.117.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.117.0",
+    "@fusion.dev/helix-testing": "0.117.0",
     "@fusion.dev/scripts": "0.0.0-dev",
     "@happy-dom/global-registrator": "^20.0.0",
     "@lit-labs/ssr": "^4.1.0",