@fusion.dev/helix-headless 0.117.0 → 0.119.0

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

@@ -1,4 +1,4 @@
-import { type CanvasView, HelixElement, type ViewportPanDetail, type ViewportWay, type ViewportZoomDetail } from '@fusion.dev/helix-core';
+import { type CanvasView, HelixElement, type ViewportGestureLabels, type ViewportPanDetail, type ViewportWay, type ViewportZoomDetail } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 import { type CanvasDocument, type CanvasTone } from './canvas-document.js';
 export type { CanvasDocument, CanvasEdge, CanvasEdgeProps, CanvasEnd, CanvasNode, CanvasNodeProps, CanvasPath, CanvasSide, CanvasTone, } from './canvas-document.js';
@@ -100,6 +100,8 @@ declare const HelixHeadlessCanvas_base: (new (...args: any[]) => import("@fusion
  * @csspart edges - The layer the connectors are drawn in.
  * @csspart footer - The strip below the board.
  * @csspart fullscreen - The button that makes the board fill the screen.
+ * @csspart gesture-hint - Words over the board 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 board with `gestures="activate"` has the gestures.
  * @csspart header - The strip above the board.
  * @csspart label - The label on a connector.
  * @csspart label-editor - The field for editing a connection's label or a group's name, placed over that text.
@@ -121,6 +123,8 @@ declare const HelixHeadlessCanvas_base: (new (...args: any[]) => import("@fusion
  * @cssstate holding - An item picked up with a click follows the pointer until the next press puts it down.
  * @cssstate idle - The user has been still for `idle-delay` milliseconds. The board's own controls stay; select on it to hide chrome of your own.
  * @cssstate pressing - While a press on the board, its cards or its connections is under way.
+ * @cssstate sharing - The page keeps the plain wheel and one finger, with `gestures="cooperative"` or while a board with `gestures="activate"` waits to be pressed.
+ * @cssstate using - A board with `gestures="activate"` has been pressed and has the gestures.
  */
 export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
     /** The text read with a card to say where its connections come from, with `{cards}`. */
@@ -373,6 +377,8 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
     protected panEvent(detail: ViewportPanDetail): Event;
     protected zoomEvent(detail: ViewportZoomDetail): Event;
     protected get restingControlsLabel(): string;
+    /** What the board says about its gestures where the page does not say it. */
+    protected get restingGestureLabels(): ViewportGestureLabels;
     /**
      * Zoom and fullscreen, without the pad.
      *
@@ -703,6 +709,13 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
      * the wheel is the board's.
      */
     private readonly handleWheel;
+    /**
+     * A second finger on a cooperative board, which would otherwise go on
+     * scrolling the page the first finger started: stopped at the start, so
+     * the two fingers pinch and move the board. **Not passive**, which is the
+     * only way a start can be stopped.
+     */
+    private readonly handleTouchStart;
     /**
      * The keys on a card or a connection.
      *

package/dist/canvas/root/canvas-root.js

@@ -63,6 +63,9 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
         this.keying = undefined;
         this.edgeKeys = new WeakMap();
         this.handlePointerDown = (event) => {
+            if (!this.gestureAllowed(event)) {
+                return;
+            }
             const path = event.composedPath();
             const on = (name) => path.some((one) => one instanceof Element && (one.getAttribute('part') ?? '').split(' ').includes(name));
             const card = this.cardOf(event);
@@ -77,6 +80,9 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
                     }
                     return;
                 }
+                if (this.gestureMode === 'cooperative') {
+                    return;
+                }
             }
             if (this.held) {
                 event.preventDefault();
@@ -388,13 +394,17 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
             }
         };
         this.handleWheel = (event) => {
-            if (!event.ctrlKey && !this.filled) {
+            const zooming = event.ctrlKey || event.metaKey;
+            if (!this.gestureAllowed(event)) {
+                return;
+            }
+            if (!zooming && !this.filled && this.gestures !== 'always') {
                 return;
             }
             event.preventDefault();
             this.touched = true;
             this.direct = true;
-            if (event.ctrlKey) {
+            if (zooming) {
                 const box = event.currentTarget.getBoundingClientRect();
                 const about = { x: event.clientX - box.left, y: event.clientY - box.top };
                 this.zoomAbout(event.deltaY < 0 ? 1.1 : 1 / 1.1, about);
@@ -402,6 +412,11 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
             }
             this.at = { ...this.at, x: this.at.x - event.deltaX, y: this.at.y - event.deltaY };
         };
+        this.handleTouchStart = (event) => {
+            if (this.gestureMode === 'cooperative' && event.touches.length > 1) {
+                event.preventDefault();
+            }
+        };
         this.handleStopKeydown = (event) => {
             const origin = event.composedPath()[0];
             const edge = this.edgeOf(event);
@@ -703,6 +718,14 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
     get restingControlsLabel() {
         return 'Board controls';
     }
+    get restingGestureLabels() {
+        return {
+            activate: 'Press the board to use it',
+            twoFinger: 'Use two fingers to move the board',
+            using: 'Using the board. Press Escape to scroll the page again.',
+            wheel: 'Use {key} and scroll to zoom the board',
+        };
+    }
     get restingControls() {
         return 'zoom fullscreen';
     }
@@ -1615,6 +1638,7 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
         this.addEventListener('pointerdown', this.handlePointerDown);
         this.addEventListener('pointermove', this.handlePointerMove);
         this.addEventListener('pointerup', this.handlePointerUp);
+        this.addEventListener('touchstart', this.handleTouchStart, { passive: false });
     }
     disconnectedCallback() {
         super.disconnectedCallback();
@@ -1632,6 +1656,7 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
         this.removeEventListener('pointerdown', this.handlePointerDown);
         this.removeEventListener('pointermove', this.handlePointerMove);
         this.removeEventListener('pointerup', this.handlePointerUp);
+        this.removeEventListener('touchstart', this.handleTouchStart);
     }
     willUpdate(changed) {
         this.keying = this.keyAll();
@@ -1840,7 +1865,7 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
       tabindex="0"
       @focusin=${this.idle.stir}
       @keydown=${this.handleKeydown}
-      @pointerleave=${this.idle.leave}
+      @pointerleave=${this.handlePointerLeave}
       @pointermove=${this.idle.stir}
     >
       <div part="header">
@@ -1875,6 +1900,7 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
           ${this.renderMarquee(origin)}
         </div>
         <slot name="empty"></slot>
+        ${this.renderGestures()}
       </div>
       ${this.renderControls()}
       <span part="live" role="status">${this.said}</span>

package/dist/element-events.generated.js

@@ -90,7 +90,9 @@ registerElementEvents({
     'helix-headless-graph': [
         'helix-activate',
         'helix-before-activate',
+        'helix-graph-layout',
         'helix-graph-pan',
+        'helix-graph-part-change',
         'helix-graph-ready',
         'helix-graph-zoom',
     ],

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

@@ -1,4 +1,4 @@
-import { HelixElement, type ViewportPanDetail, type ViewportZoomDetail } from '@fusion.dev/helix-core';
+import { HelixElement, type ViewportGestureLabels, type ViewportPanDetail, type ViewportZoomDetail } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 import { type GraphLink, type GraphNode } from './graph-model.js';
 declare const HelixHeadlessGraph_base: (new (...args: any[]) => import("@fusion.dev/helix-core").ViewportElement) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerActiveInterface) & typeof HelixElement;
@@ -8,8 +8,8 @@ declare const HelixHeadlessGraph_base: (new (...args: any[]) => import("@fusion.
  * @description
  * Helix draws no graph. A force layout of thousands of notes is physics and
  * WebGL, which a renderer such as Sigma.js does. Put the renderer's box in the
- * frame, draw `nodes` and `links` in it, and answer the frame's pan and zoom
- * events by moving the drawing.
+ * frame, and `connectGraph` from `@fusion.dev/helix-graph` draws `nodes` and
+ * `links` in it and keeps it in step with the frame.
  *
  * What the frame adds is what a drawing of a graph cannot do: a list of every
  * note beside it, which is the graph for a screen reader and a quick way to
@@ -41,9 +41,11 @@ declare const HelixHeadlessGraph_base: (new (...args: any[]) => import("@fusion.
  *
  * @event {HelixActivateEvent} helix-activate - A note was selected, in the list or in the drawing. The detail's `value` is its `id`.
  * @event {HelixBeforeActivateEvent} helix-before-activate - A note is about to be selected. Cancelable: cancel it to keep the selection in your own state.
- * @event {HelixGraphPanEvent} helix-graph-pan - A pan button or arrow key was pressed. Move the drawing.
+ * @event {HelixGraphLayoutEvent} helix-graph-layout - A layout settled, with where it put each note, sent by `laidOut()`. Keep the positions and pass them back as each note's `x` and `y`.
+ * @event {HelixGraphPanEvent} helix-graph-pan - A pan button or arrow key was pressed. `connectGraph` moves the drawing.
+ * @event {HelixGraphPartChangeEvent} helix-graph-part-change - The notes, the links, the selection, the depth or the gestures changed. Used by `connectGraph`; pages do not need to listen for it.
  * @event {HelixGraphReadyEvent} helix-graph-ready - The graph has been drawn whole, laid out and settled. Sent each time `drawn()` says it is drawn after it was not.
- * @event {HelixGraphZoomEvent} helix-graph-zoom - A zoom button or key was pressed. Zoom the drawing.
+ * @event {HelixGraphZoomEvent} helix-graph-zoom - A zoom button or key was pressed. `connectGraph` zooms the drawing.
  *
  * @csspart after - The room the notes after those drawn would take, so the list scrolls its whole length.
  * @csspart before - The room the notes before those drawn would take.
@@ -54,6 +56,8 @@ declare const HelixHeadlessGraph_base: (new (...args: any[]) => import("@fusion.
  * @csspart filter-mark - The default icon beside the search field, shown when none is slotted.
  * @csspart footer - The strip below the graph.
  * @csspart fullscreen - The button that makes the graph fill the screen.
+ * @csspart gesture-hint - Words over the graph 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 graph with `gestures="activate"` has the gestures.
  * @csspart header - The strip above the graph.
  * @csspart list - The list of notes, which draws only the rows in view.
  * @csspart live - What screen readers hear when a search changes how many notes there are.
@@ -79,6 +83,8 @@ declare const HelixHeadlessGraph_base: (new (...args: any[]) => import("@fusion.
  * @cssstate fullscreen - The graph fills the screen.
  * @cssstate idle - The user has been still long enough for the header and footer to fade.
  * @cssstate ready - The graph has been drawn whole, after `helix-graph-ready`.
+ * @cssstate sharing - The page keeps the plain wheel and one finger, with `gestures="cooperative"` or while a graph with `gestures="activate"` waits to be pressed.
+ * @cssstate using - A graph with `gestures="activate"` has been pressed and has the gestures.
  */
 export declare class HelixHeadlessGraph extends HelixHeadlessGraph_base {
     /** What the list says of a note's count, with `{count}`. */
@@ -127,7 +133,7 @@ export declare class HelixHeadlessGraph extends HelixHeadlessGraph_base {
     private said;
     private readonly virtualize;
     /**
-     * @internal The notes the drawing shows, for the code that draws it: those
+     * @internal The notes the drawing shows, which `connectGraph` reads: those
      * within `depth` of the selected note, or `undefined` for every note.
      */
     get shown(): ReadonlySet<string> | undefined;
@@ -135,18 +141,32 @@ export declare class HelixHeadlessGraph extends HelixHeadlessGraph_base {
     get ready(): boolean;
     /**
      * Says the graph has been drawn whole, or with `false`, that it no longer
-     * is. Call it when the renderer's layout has settled and the graph is
-     * finished. The first call after
+     * is. Called by `connectGraph` once its layout has settled; a page drawing
+     * its own graph calls it when that graph is finished. The first call after
      * the graph was not drawn sends `helix-graph-ready` and turns on
      * `:state(ready)`.
      */
     drawn(whole?: boolean): void;
+    /**
+     * Says where a layout put each note, by its `id`: sends
+     * `helix-graph-layout` for the page to keep. Called by `connectGraph` once
+     * its layout has settled; a page laying out its own graph calls it the same
+     * way.
+     */
+    laidOut(positions: Record<string, {
+        x: number;
+        y: number;
+    }>): void;
     protected willUpdate(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
     protected panEvent(detail: ViewportPanDetail): Event;
     protected zoomEvent(detail: ViewportZoomDetail): Event;
     protected get restingControls(): string;
     protected get restingControlsLabel(): string;
+    /** Which gestures the renderer takes, which `connectGraph` hears from here. */
+    protected gesturesChanged(): void;
+    /** What the graph says about its gestures where the page does not say it. */
+    protected get restingGestureLabels(): ViewportGestureLabels;
     /** How many notes the list holds, in the page's numbers. */
     private countText;
     /** How a row stands to the selected note, in words, or nothing where it does not. */

package/dist/graph/root/graph-root.js

@@ -4,7 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { customElement, fillTemplate, formatNumbers, HelixElement, HelixGraphPanEvent, HelixGraphReadyEvent, HelixGraphZoomEvent, MixinControllerActive, MixinViewport, VirtualizeController, } from '@fusion.dev/helix-core';
+import { customElement, fillTemplate, formatNumbers, HelixElement, HelixGraphLayoutEvent, HelixGraphPanEvent, HelixGraphPartChangeEvent, HelixGraphReadyEvent, HelixGraphZoomEvent, MixinControllerActive, MixinViewport, VirtualizeController, } from '@fusion.dev/helix-core';
 import { magnifyingGlass } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
@@ -95,6 +95,9 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
             this.dispatchEvent(new HelixGraphReadyEvent());
         }
     }
+    laidOut(positions) {
+        this.dispatchEvent(new HelixGraphLayoutEvent({ positions }));
+    }
     willUpdate(changed) {
         super.willUpdate(changed);
         this.toggleState('fullscreen', this.filled);
@@ -123,6 +126,12 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
     updated(changed) {
         super.updated(changed);
         this.virtualize.measure();
+        if (changed.has('nodes') || changed.has('links')) {
+            this.dispatchEvent(new HelixGraphPartChangeEvent({ kind: 'data' }));
+        }
+        else if (changed.has('active') || changed.has('depth')) {
+            this.dispatchEvent(new HelixGraphPartChangeEvent({ kind: 'focus' }));
+        }
         if (changed.has('query') && changed.get('query') !== undefined) {
             this.said = this.countText();
         }
@@ -139,6 +148,17 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
     get restingControlsLabel() {
         return 'Graph controls';
     }
+    gesturesChanged() {
+        this.dispatchEvent(new HelixGraphPartChangeEvent({ kind: 'gestures' }));
+    }
+    get restingGestureLabels() {
+        return {
+            activate: 'Press the graph to use it',
+            twoFinger: 'Use two fingers to move the graph',
+            using: 'Using the graph. Press Escape to scroll the page again.',
+            wheel: 'Use {key} and scroll to zoom the graph',
+        };
+    }
     countText() {
         const lang = this.closest?.('[lang]')?.getAttribute('lang') ?? '';
         return fillTemplate(this.countLabel, { count: formatNumbers(lang)(this.entries.length) });
@@ -224,7 +244,7 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
       tabindex="0"
       @focusin=${this.idle.stir}
       @keydown=${this.handleKeydown}
-      @pointerleave=${this.idle.leave}
+      @pointerleave=${this.handlePointerLeave}
       @pointermove=${this.idle.stir}
     >
       <div part="header">
@@ -234,6 +254,7 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
         <div part="stage">
           <div part="viewport">
             <slot></slot>
+            ${this.renderGestures()}
           </div>
           ${this.renderControls()}
         </div>

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

@@ -1,4 +1,4 @@
-import { HelixElement, KeyboardNavigationController, type ViewportControlsPlacement, type ViewportPanDetail, type ViewportZoomDetail } from '@fusion.dev/helix-core';
+import { HelixElement, KeyboardNavigationController, type ViewportControlsPlacement, type ViewportGestureLabels, type ViewportPanDetail, type ViewportZoomDetail } from '@fusion.dev/helix-core';
 import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 /**
  * What `ViewportControlsPlacement` is called for a map.
@@ -115,14 +115,10 @@ 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 sharing - The page keeps the plain wheel and one finger, with `gestures="cooperative"` or while a map with `gestures="activate"` waits to be pressed.
  * @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.
@@ -137,21 +133,6 @@ 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;
     /**
@@ -213,16 +194,6 @@ 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.
      */
@@ -348,51 +319,10 @@ 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;
+    /** What the map says about its gestures where the page does not say it. */
+    protected get restingGestureLabels(): ViewportGestureLabels;
+    /** Which gestures the renderer takes, which `connectMap` hears from here. */
+    protected gesturesChanged(): void;
     /** A marker added or taken away is a walk of a different length. */
     private readonly handleSlotChange;
     connectedCallback(): void;