@fusion.dev/helix-headless 0.177.2 → 0.179.0

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

@@ -20,6 +20,23 @@ declare const HelixHeadlessGraph_base: (new (...args: any[]) => import("@fusion.
  * Set `depth` to show the local graph: only the notes within that many links
  * of the selected one.
  *
+ * The search field is a combobox over the list. Down and Up move through the
+ * notes while the focus stays in the field, and Enter selects one.
+ *
+ * **Walk the links with Alt and the arrow keys**, in the list or in the
+ * search field once its keys are on a note. The note the keys are on is
+ * marked in the drawing.
+ *
+ * | Key | What it does |
+ * |---|---|
+ * | Alt+Right | Follows a link, to the first note the one the keys are on links to or from. |
+ * | Alt+Down, Alt+Up | Moves to the next or the previous note linked to the one the step came from, wrapping. |
+ * | Alt+Left | Goes back along the links walked. |
+ *
+ * Right and Left swap on a right-to-left page. Each step says the note, how it
+ * stands to the note it came from, and its place among that note's links,
+ * such as "Hiring plan. Linked from Roadmap. 2 of 3". Enter selects the note.
+ *
  * Set `legend` to name the groups over the drawing, each a button that shows
  * or hides its notes. `hiddenGroups` holds the groups turned off, and the
  * list holds only what the drawing shows. The legend is a toolbar and one tab
@@ -59,7 +76,7 @@ declare const HelixHeadlessGraph_base: (new (...args: any[]) => import("@fusion.
  * @event {HelixGraphFilterEvent} helix-graph-filter - A group in the legend was pressed, to show or hide its notes. The detail's `hidden` is every group that would be hidden. Cancelable: cancel it to keep the groups as they were, or to set `hiddenGroups` yourself.
  * @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`, and `z` where a renderer draws in three dimensions.
  * @event {HelixGraphPanEvent} helix-graph-pan - A pan button or arrow key was pressed. `connectGraph` moves the drawing, then calls `moved()`.
- * @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 {HelixGraphPartChangeEvent} helix-graph-part-change - The notes, the links, the selection, the depth, the note the keys are on, 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 {HelixGraphSignalEvent} helix-graph-signal - Something passed between two notes, sent by `signal()`. Used by `connectGraph`; pages do not need to listen for it.
  * @event {HelixGraphZoomEvent} helix-graph-zoom - A zoom button or key was pressed. `connectGraph` zooms the drawing, then calls `moved()`.
@@ -166,6 +183,12 @@ export declare class HelixHeadlessGraph extends HelixHeadlessGraph_base {
     legend: boolean;
     /** The legend's name, read by screen readers. */
     legendLabel: string;
+    /**
+     * What screen readers hear when a walk along the links reaches a note that
+     * has no link to follow, or goes back to a note: `{note}` for its name and
+     * `{count}` for how many notes the list holds that it links to or from.
+     */
+    linkCountLabel: string;
     /** How a note linked both to and from the selected one is described, with `{note}`. */
     linkedBothLabel: string;
     /** How a note the selected one links to is described, with `{note}`, the selected note's name. */
@@ -231,6 +254,13 @@ export declare class HelixHeadlessGraph extends HelixHeadlessGraph_base {
     twoFingerHintLabel: string;
     /** The line shown while the graph, with `gestures="activate"`, has the gestures. */
     usingLabel: string;
+    /**
+     * What screen readers hear when a walk along the links moves to a note:
+     * `{note}` for its name, `{relation}` for how it stands to the note the
+     * step came from, such as "Linked from Roadmap", and `{index}` and `{count}`
+     * for its place among that note's links.
+     */
+    walkLabel: string;
     /**
      * The hint shown when the wheel scrolls past the graph with
      * `gestures="cooperative"`. `{key}` is ⌘ on a Mac and Ctrl elsewhere.
@@ -246,6 +276,22 @@ export declare class HelixHeadlessGraph extends HelixHeadlessGraph_base {
     private cursor;
     /** Whether the search and the list are open over the drawing, with `no-panel`. */
     private panelOpen;
+    /**
+     * Whether the search field's arrow keys have moved onto a note, which the
+     * field then names as its `aria-activedescendant` while the focus stays in
+     * it. Typing, Left, Right, Escape, and leaving the field let it go.
+     */
+    private fieldKeys;
+    /** Whether the list has the focus, so the drawing marks the note its keys are on. */
+    private listKeys;
+    /**
+     * The notes a walk along the links stepped from, by `id`, the last the one
+     * the note the keys are on was reached from. Empty when the keys moved some
+     * other way.
+     */
+    private trail;
+    /** The note the drawing last heard the keys are on, so it hears each move once. */
+    private keyedSent;
     /** Which notes link to and from each, read again when `links` changes. */
     private adjacency;
     /** The notes in the order of their names, read again when `nodes` changes. */
@@ -292,6 +338,18 @@ export declare class HelixHeadlessGraph extends HelixHeadlessGraph_base {
      * within `depth` of the selected note, or `undefined` for every note.
      */
     get shown(): ReadonlySet<string> | undefined;
+    /**
+     * @internal The note the keys are on, while the list or the search field
+     * has them, which `connectGraph` marks in the drawing as it marks the note
+     * under the pointer. `walked` is true where a walk along the links reached
+     * it, which brings it into view.
+     */
+    get keyed(): {
+        id: string;
+        walked: boolean;
+    } | undefined;
+    /** The `id` of the note the keys are on, or `undefined` where neither the list nor the field has them. */
+    private keyedId;
     /** Whether the graph has been drawn whole. For code that runs after `helix-graph-ready`. */
     get ready(): boolean;
     /**
@@ -404,6 +462,33 @@ export declare class HelixHeadlessGraph extends HelixHeadlessGraph_base {
      * together, and a repeated letter steps through the names that start with it.
      */
     private typeahead;
+    /**
+     * The rows of the notes `id` links to or is linked from, in the list's
+     * order, which is the order of their names. Only the notes the list holds:
+     * a search, the legend, or `depth` leaves the others out.
+     */
+    private linkedRows;
+    /** How the note `id` stands to the note `from`, in the words the list uses for the selection. */
+    private relationFrom;
+    /**
+     * A walk along the links from the note the keys are on, with Alt and the
+     * arrow keys, so a reader follows the lines of the drawing and not only
+     * the order of the list. **The same four keys a tree takes**, with Alt,
+     * since the list's own arrows already move through it:
+     *
+     * - Alt+Right follows a link, to the first note the one the keys are on
+     *   links to or from.
+     * - Alt+Down and Alt+Up move to the next and the previous note linked to
+     *   the one the step came from, wrapping.
+     * - Alt+Left goes back along the links walked.
+     *
+     * Right and Left swap on a right-to-left page. Each step says the note, how
+     * it stands to the note it was reached from, and its place among that
+     * note's links. Returns whether the key was one of the walk's.
+     */
+    private walk;
+    /** Says the note at row `at` and how many notes in the list it links to or from. */
+    private sayLinks;
     /**
      * How many rows Page Down and Page Up move: the rows that fit in the list's
      * box, or in the window where the list does not scroll, less one, so the
@@ -412,10 +497,22 @@ export declare class HelixHeadlessGraph extends HelixHeadlessGraph_base {
     private pageRows;
     /**
      * The search field's keys, which belong to the field and never pan the
-     * graph. Escape empties a search that has words in it, and passes through
-     * an empty one to whatever the page does with it.
+     * graph.
+     *
+     * **The field is a combobox over the list**, as React Aria's Autocomplete
+     * and the APG combobox are: the focus stays in the field, and Down and Up
+     * move the keys through the notes, which the field names as its
+     * `aria-activedescendant`. Down starts on the note the keys were last on,
+     * the first after a search, and Up on the last. Page Down and Page Up move
+     * a page, Enter selects, Alt and the arrows walk the links as in the list,
+     * and Left, Right, Home and End go back to the text.
+     *
+     * Escape lets the note go, then empties a search that has words in it, and
+     * passes through an empty one to whatever the page does with it.
      */
     private readonly handleSearchKeydown;
+    /** Leaving the field lets go of the note its keys were on. */
+    private readonly handleSearchBlur;
     /**
      * Opens the search and the list over the drawing, or closes them, with
      * `no-panel`. **Opened, the search field takes the focus**, since finding
@@ -430,6 +527,7 @@ export declare class HelixHeadlessGraph extends HelixHeadlessGraph_base {
      * the controls after zoom, where the frame leaves them out with `no-panel`.
      */
     protected renderMoreControls(): TemplateResult | typeof nothing;
+    /** Typing is a new search, read from its top, with no note under the keys until Down. */
     private readonly handleSearch;
     /**
      * The mark in the search field, behind a seam: a slot for the page, and a

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 { auditName, customElement, focusItemOf, formatWords, HelixElement, HelixGraphFilterEvent, HelixGraphLayoutEvent, HelixGraphPanEvent, HelixGraphPartChangeEvent, HelixGraphReadyEvent, HelixGraphSignalEvent, HelixGraphZoomEvent, KeyboardNavigationController, MixinControllerActive, MixinViewport, scrollItemIntoView, scrollRoom, Typeahead, typeaheadBy, VirtualizeController, words, wordsLocale, } from '@fusion.dev/helix-core';
+import { auditName, customElement, focusItemOf, formatWords, HelixElement, HelixGraphFilterEvent, HelixGraphLayoutEvent, HelixGraphPanEvent, HelixGraphPartChangeEvent, HelixGraphReadyEvent, HelixGraphSignalEvent, HelixGraphZoomEvent, isRtl, KeyboardNavigationController, MixinControllerActive, MixinViewport, scrollItemIntoView, scrollRoom, Typeahead, typeaheadBy, VirtualizeController, words, wordsLocale, } from '@fusion.dev/helix-core';
 import { list, magnifyingGlass } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
@@ -23,6 +23,7 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
         this.label = '';
         this.legend = false;
         this.legendLabel = 'Groups';
+        this.linkCountLabel = '{note}. {count, plural, =0 {No links} one {# link} other {# links}}';
         this.linkedBothLabel = 'Linked both ways with {note}';
         this.linkedFromLabel = 'Linked from {note}';
         this.links = [];
@@ -42,12 +43,16 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
         this.selectionLabel = '{note}, selected. {count}';
         this.twoFingerHintLabel = 'Use two fingers to move the graph';
         this.usingLabel = 'Using the graph. Press Escape to scroll the page again.';
+        this.walkLabel = '{note}. {relation}. {index} of {count}';
         this.wheelHintLabel = 'Use {key} and scroll to zoom the graph';
         this.zoomedInLabel = 'Zoomed in';
         this.zoomedOutLabel = 'Zoomed out';
         this.query = '';
         this.cursor = 0;
         this.panelOpen = false;
+        this.fieldKeys = false;
+        this.listKeys = false;
+        this.trail = [];
         this.adjacency = new Map();
         this.sorted = [];
         this.entries = [];
@@ -74,6 +79,9 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
             })),
         });
         this.handleListKeydown = (event) => {
+            if (this.walk(event)) {
+                return;
+            }
             const moves = {
                 ArrowDown: this.cursor + 1,
                 ArrowUp: this.cursor - 1,
@@ -102,19 +110,51 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
         };
         this.typed = new Typeahead();
         this.handleSearchKeydown = (event) => {
-            if (event.key === 'ArrowDown') {
+            if (event.isComposing) {
+                return;
+            }
+            if (this.fieldKeys && this.walk(event)) {
+                return;
+            }
+            const last = this.entries.length - 1;
+            const moves = this.fieldKeys
+                ? {
+                    ArrowDown: this.cursor + 1,
+                    ArrowUp: this.cursor - 1,
+                    PageDown: this.cursor + this.pageRows(),
+                    PageUp: this.cursor - this.pageRows(),
+                }
+                : { ArrowDown: this.cursor, ArrowUp: last };
+            if (event.key in moves && !event.altKey && last >= 0) {
                 event.preventDefault();
-                this.partNamed('list')?.focus();
+                this.fieldKeys = true;
+                this.moveTo(moves[event.key]);
+            }
+            else if (event.key === 'Enter' && this.fieldKeys) {
+                event.preventDefault();
+                this.choose(this.cursor);
             }
-            if (event.key === 'Escape') {
-                if (this.query === '') {
+            else if (event.key === 'Escape') {
+                if (this.fieldKeys) {
+                    event.preventDefault();
+                    this.fieldKeys = false;
+                }
+                else if (this.query === '') {
                     return;
                 }
-                event.preventDefault();
-                this.query = '';
+                else {
+                    event.preventDefault();
+                    this.query = '';
+                }
+            }
+            else if (['ArrowLeft', 'ArrowRight', 'End', 'Home'].includes(event.key)) {
+                this.fieldKeys = false;
             }
             event.stopPropagation();
         };
+        this.handleSearchBlur = () => {
+            this.fieldKeys = false;
+        };
         this.handlePanelKeydown = (event) => {
             if (event.key === 'Escape' && this.noPanel && this.panelOpen) {
                 event.preventDefault();
@@ -124,12 +164,20 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
         };
         this.handleSearch = (event) => {
             this.query = event.target.value;
+            this.fieldKeys = false;
         };
     }
     static { this.words = 'helix-graph'; }
     get shown() {
         return this.kept;
     }
+    get keyed() {
+        const id = this.keyedId();
+        return id === undefined ? undefined : { id, walked: this.trail.length > 0 };
+    }
+    keyedId() {
+        return this.listKeys || this.fieldKeys ? this.entries[this.cursor]?.node.id : undefined;
+    }
     get ready() {
         return this.whole;
     }
@@ -204,6 +252,7 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
             if (['active', 'depth', 'hiddenGroups', 'query'].some((name) => changed.has(name)) ||
                 !this.hasUpdated) {
                 this.cursor = 0;
+                this.trail = [];
                 if (list) {
                     list.scrollTop = 0;
                 }
@@ -230,10 +279,16 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
     updated(changed) {
         super.updated(changed);
         this.virtualize.measure();
+        const keyed = this.keyedId();
+        const rekeyed = keyed !== this.keyedSent;
+        this.keyedSent = keyed;
         if (changed.has('nodes') || changed.has('links')) {
             this.dispatchEvent(new HelixGraphPartChangeEvent({ kind: 'data' }));
         }
-        else if (changed.has('active') || changed.has('depth') || changed.has('hiddenGroups')) {
+        else if (changed.has('active') ||
+            changed.has('depth') ||
+            changed.has('hiddenGroups') ||
+            rekeyed) {
             this.dispatchEvent(new HelixGraphPartChangeEvent({ kind: 'focus' }));
         }
     }
@@ -316,7 +371,10 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
             this.requestActive(entry.node.id);
         }
     }
-    moveTo(index) {
+    moveTo(index, walking = false) {
+        if (!walking) {
+            this.trail = [];
+        }
         const last = this.entries.length - 1;
         this.cursor = Math.min(Math.max(index, 0), Math.max(last, 0));
         void this.updateComplete.then(() => this.revealCursor());
@@ -352,6 +410,99 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
             this.moveTo(at);
         }
     }
+    linkedRows(id) {
+        const near = this.adjacency.get(id);
+        if (!near) {
+            return [];
+        }
+        const rows = [];
+        for (const [index, entry] of this.entries.entries()) {
+            const other = entry.node.id;
+            if (other !== id && (near.to.has(other) || near.from.has(other))) {
+                rows.push(index);
+            }
+        }
+        return rows;
+    }
+    relationFrom(from, id) {
+        const near = this.adjacency.get(from);
+        const origin = this.nodes.find((node) => node.id === from);
+        const note = origin ? nameOf(origin) : from;
+        const to = near?.to.has(id) === true;
+        const back = near?.from.has(id) === true;
+        return formatWords(this, to && back ? 'linkedBothLabel' : to ? 'linkedFromLabel' : 'linksToLabel', { note });
+    }
+    walk(event) {
+        if (!event.altKey || event.ctrlKey || event.metaKey || this.entries.length === 0) {
+            return false;
+        }
+        const flip = isRtl(this);
+        const key = event.key === 'ArrowRight'
+            ? flip
+                ? 'back'
+                : 'follow'
+            : event.key === 'ArrowLeft'
+                ? flip
+                    ? 'follow'
+                    : 'back'
+                : event.key === 'ArrowDown'
+                    ? 'next'
+                    : event.key === 'ArrowUp'
+                        ? 'previous'
+                        : undefined;
+        if (key === undefined) {
+            return false;
+        }
+        event.preventDefault();
+        event.stopPropagation();
+        const here = this.entries[this.cursor]?.node.id;
+        if (here === undefined) {
+            return true;
+        }
+        if (key === 'back') {
+            const back = this.trail.pop();
+            const row = back === undefined ? -1 : this.entries.findIndex((entry) => entry.node.id === back);
+            const at = row >= 0 ? row : this.cursor;
+            this.moveTo(at, true);
+            this.sayLinks(at);
+            return true;
+        }
+        const from = key === 'follow' || this.trail.length === 0 ? here : this.trail.at(-1);
+        const rows = this.linkedRows(from);
+        if (rows.length === 0) {
+            this.sayLinks(this.cursor);
+            return true;
+        }
+        let place;
+        if (from === here) {
+            place = key === 'previous' ? rows.length - 1 : 0;
+            this.trail.push(here);
+        }
+        else {
+            const now = rows.indexOf(this.cursor);
+            const by = key === 'previous' ? -1 : 1;
+            place = now < 0 ? 0 : (now + by + rows.length) % rows.length;
+        }
+        const at = rows[place];
+        this.moveTo(at, true);
+        const entry = this.entries[at];
+        this.say(formatWords(this, 'walkLabel', {
+            count: rows.length,
+            index: place + 1,
+            note: nameOf(entry.node),
+            relation: this.relationFrom(from, entry.node.id),
+        }));
+        return true;
+    }
+    sayLinks(at) {
+        const entry = this.entries[at];
+        if (entry) {
+            this.say(formatWords(this, 'linkCountLabel', {
+                count: this.linkedRows(entry.node.id).length,
+                note: nameOf(entry.node),
+            }));
+        }
+    }
     pageRows() {
         const room = scrollRoom(this.partNamed('list'));
         const tall = this.virtualize.sizeOf(this.cursor) || 32;
@@ -473,11 +624,17 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
             <input
               part="search-field"
               type="text"
+              role="combobox"
               autocomplete="off"
               spellcheck="false"
               aria-label=${this.searchLabel}
+              aria-autocomplete="list"
+              aria-controls="note-list"
+              aria-expanded=${this.entries.length > 0 ? 'true' : 'false'}
+              aria-activedescendant=${this.fieldKeys ? cursor : nothing}
               placeholder=${this.searchLabel}
               .value=${this.query}
+              @blur=${this.handleSearchBlur}
               @input=${this.handleSearch}
               @keydown=${this.handleSearchKeydown}
             />
@@ -485,12 +642,20 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
           </div>
           <div
             part="list"
+            id="note-list"
             role="listbox"
             tabindex="0"
             data-scroller
             aria-label=${this.notesLabel}
             aria-activedescendant=${cursor}
             aria-busy=${this.loading ? 'true' : nothing}
+            aria-keyshortcuts="Alt+ArrowRight Alt+ArrowLeft Alt+ArrowDown Alt+ArrowUp"
+            @blur=${() => {
+            this.listKeys = false;
+        }}
+            @focus=${() => {
+            this.listKeys = true;
+        }}
             @keydown=${this.handleListKeydown}
             @scroll=${() => this.virtualize.measure()}
           >
@@ -548,6 +713,10 @@ __decorate([
     words,
     property({ attribute: 'legend-label' })
 ], HelixHeadlessGraph.prototype, "legendLabel", void 0);
+__decorate([
+    words,
+    property({ attribute: 'link-count-label' })
+], HelixHeadlessGraph.prototype, "linkCountLabel", void 0);
 __decorate([
     words,
     property({ attribute: 'linked-both-label' })
@@ -623,6 +792,10 @@ __decorate([
     words,
     property({ attribute: 'using-label' })
 ], HelixHeadlessGraph.prototype, "usingLabel", void 0);
+__decorate([
+    words,
+    property({ attribute: 'walk-label' })
+], HelixHeadlessGraph.prototype, "walkLabel", void 0);
 __decorate([
     words,
     property({ attribute: 'wheel-hint-label' })
@@ -644,6 +817,12 @@ __decorate([
 __decorate([
     state()
 ], HelixHeadlessGraph.prototype, "panelOpen", void 0);
+__decorate([
+    state()
+], HelixHeadlessGraph.prototype, "fieldKeys", void 0);
+__decorate([
+    state()
+], HelixHeadlessGraph.prototype, "listKeys", void 0);
 __decorate([
     state()
 ], HelixHeadlessGraph.prototype, "said", void 0);