@fusion.dev/helix-headless 0.116.0 → 0.118.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

@@ -87,6 +87,15 @@ registerElementEvents({
         'toggle',
     ],
     'helix-headless-filter-menu': ['helix-facet'],
+    'helix-headless-graph': [
+        'helix-activate',
+        'helix-before-activate',
+        'helix-graph-layout',
+        'helix-graph-pan',
+        'helix-graph-part-change',
+        'helix-graph-ready',
+        'helix-graph-zoom',
+    ],
     'helix-headless-heatmap': ['helix-resize'],
     'helix-headless-image': ['error', 'load'],
     'helix-headless-input': ['change', 'helix-before-change', 'input'],

package/dist/graph/index.d.ts

@@ -0,0 +1,3 @@
+export type { Adjacency, Entry, GraphLink, GraphNode, Relation } from './root/graph-model.js';
+export { adjacencyOf, entriesOf, nameOf, sortedOf, within } from './root/graph-model.js';
+export { HelixHeadlessGraph } from './root/graph-root.js';

package/dist/graph/index.js

@@ -0,0 +1,2 @@
+export { adjacencyOf, entriesOf, nameOf, sortedOf, within } from './root/graph-model.js';
+export { HelixHeadlessGraph } from './root/graph-root.js';

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

@@ -0,0 +1,63 @@
+/** One note in a graph. */
+export interface GraphNode {
+    /** Unique in the graph, and what `active` and a link's ends name. */
+    id: string;
+    /** What the note is called. Its `id` where it has none. */
+    label?: string | undefined;
+    /** A kind the note belongs to, such as a tag, which a renderer colors it by. */
+    group?: string | undefined;
+    /** How large the renderer draws it, relative to the others. */
+    size?: number | undefined;
+    /** Where the note stands, where the page already knows. Laid out where it does not. */
+    x?: number | undefined;
+    /** Where the note stands, where the page already knows. Laid out where it does not. */
+    y?: number | undefined;
+}
+/** One link between two notes, from `source` to `target`. */
+export interface GraphLink {
+    source: string;
+    target: string;
+    /** What the link says, such as "cites". */
+    label?: string | undefined;
+}
+/** Which notes each note links to and is linked from. */
+export type Adjacency = Map<string, {
+    from: Set<string>;
+    to: Set<string>;
+}>;
+/** How a note in the list stands to the selected one. */
+export type Relation = 'both' | 'from' | 'selected' | 'to';
+/** One row of the list: a note, and how it stands to the selected one where it does. */
+export interface Entry {
+    node: GraphNode;
+    relation?: Relation | undefined;
+}
+/** A note's name, its `id` where it has no label. */
+export declare const nameOf: (node: GraphNode) => string;
+/**
+ * Which notes each note links to and is linked from, in one pass over the
+ * links. A link naming a note that is not in the graph is kept: the list
+ * shows notes and not links, so it does no harm, and a page adding the note a
+ * moment later finds its links already counted.
+ */
+export declare const adjacencyOf: (links: readonly GraphLink[]) => Adjacency;
+/**
+ * The notes within `depth` links of `from`, whichever way each link runs, the
+ * note itself included: the local graph.
+ *
+ * **Both ways, as a reader thinks of a note's neighborhood**: a note that
+ * cites this one is as near to it as one this one cites.
+ */
+export declare const within: (adjacency: Adjacency, from: string, depth: number) => Set<string>;
+/**
+ * The list's rows, in the order a reader wants them: the selected note, then
+ * the notes it links to and from, then every other note, each part in the
+ * order of its names, and only the notes `shown` holds and `query` matches.
+ *
+ * **The neighborhood first**, because it is what a reader came to the graph
+ * for and what a picture of it shows by its lines, which a list has to say in
+ * its order instead.
+ */
+export declare const entriesOf: (sorted: readonly GraphNode[], adjacency: Adjacency, active: string, query: string, shown?: ReadonlySet<string>) => Entry[];
+/** The notes in the order of their names, as the page's language orders words. */
+export declare const sortedOf: (nodes: readonly GraphNode[], lang?: string) => GraphNode[];

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

@@ -0,0 +1,75 @@
+export const nameOf = (node) => node.label || node.id;
+export const adjacencyOf = (links) => {
+    const adjacency = new Map();
+    const at = (id) => {
+        let found = adjacency.get(id);
+        if (!found) {
+            found = { from: new Set(), to: new Set() };
+            adjacency.set(id, found);
+        }
+        return found;
+    };
+    for (const { source, target } of links) {
+        if (source === target) {
+            continue;
+        }
+        at(source).to.add(target);
+        at(target).from.add(source);
+    }
+    return adjacency;
+};
+export const within = (adjacency, from, depth) => {
+    const reached = new Set([from]);
+    let edge = [from];
+    for (let step = 0; step < depth && edge.length > 0; step++) {
+        const next = [];
+        for (const id of edge) {
+            const near = adjacency.get(id);
+            for (const one of [...(near?.to ?? []), ...(near?.from ?? [])]) {
+                if (!reached.has(one)) {
+                    reached.add(one);
+                    next.push(one);
+                }
+            }
+        }
+        edge = next;
+    }
+    return reached;
+};
+export const entriesOf = (sorted, adjacency, active, query, shown) => {
+    const wanted = query.trim().toLocaleLowerCase();
+    const kept = (node) => (!shown || shown.has(node.id)) &&
+        (wanted === '' || nameOf(node).toLocaleLowerCase().includes(wanted));
+    const near = adjacency.get(active);
+    const relationOf = (id) => {
+        if (id === active) {
+            return 'selected';
+        }
+        const to = near?.to.has(id) === true;
+        const from = near?.from.has(id) === true;
+        return to && from ? 'both' : to ? 'to' : from ? 'from' : undefined;
+    };
+    const first = [];
+    const neighbors = [];
+    const rest = [];
+    for (const node of sorted) {
+        if (!kept(node)) {
+            continue;
+        }
+        const relation = relationOf(node.id);
+        if (relation === 'selected') {
+            first.push({ node, relation });
+        }
+        else if (relation) {
+            neighbors.push({ node, relation });
+        }
+        else {
+            rest.push({ node });
+        }
+    }
+    return [...first, ...neighbors, ...rest];
+};
+export const sortedOf = (nodes, lang) => {
+    const collator = new Intl.Collator(lang || undefined, { numeric: true, sensitivity: 'base' });
+    return [...nodes].sort((one, other) => collator.compare(nameOf(one), nameOf(other)));
+};

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

@@ -0,0 +1,209 @@
+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;
+/**
+ * @summary A frame around a graph of notes drawn by another library, and the list that makes it readable.
+ *
+ * @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, 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
+ * find a note for anyone. The selected note comes first, then the notes it
+ * links to and from, then every other note, and the search field narrows it.
+ * Selecting a note in the list or in the drawing is the same selection.
+ *
+ * Set `depth` to show the local graph: only the notes within that many links
+ * of the selected one.
+ *
+ * `nodes` and `links` are properties, never markup: a graph of ten thousand
+ * notes as ten thousand elements would cost what the renderer exists to save.
+ * The list draws only the rows in view.
+ *
+ * The list scrolls on this tier. It carries `data-scroller`, and `core` ships
+ * `[data-scroller] { overflow: auto }` into every shadow root. You still need
+ * to set a block size on the list, or it grows to hold every row.
+ *
+ * @since 0.116.0
+ * @status experimental
+ * @category media
+ * @aliases Knowledge graph, Network, Note graph, Second brain
+ * @documentation https://fusion.dev/helix/components/graph
+ *
+ * @slot - The renderer's box, which the drawing is made in.
+ * @slot filter-icon - The icon in the search field. Defaults to a magnifying glass.
+ * @slot footer - Content below the graph.
+ * @slot header - Content above the graph.
+ *
+ * @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 {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. `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.
+ * @csspart body - The drawing beside the list, or above it where the frame is narrow.
+ * @csspart controls - The group the pan and zoom buttons sit in.
+ * @csspart count - How many notes the list holds, which a search narrows, at the end of the search bar.
+ * @csspart filter-icon - The icon beside the search field.
+ * @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.
+ * @csspart note - One note in the list.
+ * @csspart note-cursor - The note the keyboard is on in the list.
+ * @csspart note-linked - A note linked to or from the selected one.
+ * @csspart note-name - A note's name in the list.
+ * @csspart note-relation - How a note stands to the selected one, such as "Linked from Alpha".
+ * @csspart note-selected - The selected note, first in the list.
+ * @csspart pan-down - The button that moves the graph down.
+ * @csspart pan-end - The button that moves the graph toward the end of a line of text: right in English.
+ * @csspart pan-start - The button that moves the graph toward the start of a line of text: left in English.
+ * @csspart pan-up - The button that moves the graph up.
+ * @csspart panel - The search field and the list, beside the drawing or below it.
+ * @csspart region - The frame: the drawing, its controls and the list.
+ * @csspart search - The bar holding the icon, the search field and the count.
+ * @csspart search-field - The field that finds a note by its name.
+ * @csspart stage - The drawing and its controls.
+ * @csspart viewport - The box the renderer draws in.
+ * @csspart zoom-in - The zoom in button.
+ * @csspart zoom-out - The zoom out button.
+ *
+ * @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}`. */
+    countLabel: string;
+    /**
+     * How many links from the selected note to show, for its local graph. Unset
+     * shows every note. The list holds what the drawing shows.
+     */
+    depth?: number;
+    /**
+     * The graph's name, read by screen readers, such as "Research notes".
+     * Required.
+     */
+    label: 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. */
+    linkedFromLabel: string;
+    /** The links between notes, each from `source` to `target`. A property, never an attribute. */
+    links: readonly GraphLink[];
+    /** How a note that links to the selected one is described, with `{note}`. */
+    linksToLabel: string;
+    /** The notes. A property, never an attribute. */
+    nodes: readonly GraphNode[];
+    /** The list's name, read by screen readers. */
+    notesLabel: string;
+    /** The search field's name. */
+    searchLabel: string;
+    /** How the selected note is described in the list. */
+    selectedLabel: string;
+    /** What the search field holds. */
+    private query;
+    /** The row the keyboard is on, as an index into the list. */
+    private cursor;
+    /** 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. */
+    private sorted;
+    /** The list's rows, read again when anything they come from changes. */
+    private entries;
+    /** The notes the local graph keeps, or every note where there is no `depth`. */
+    private kept;
+    /** Whether the graph has been drawn whole, which `drawn()` says. */
+    private whole;
+    /** How many notes there were when the count was last said. */
+    private said;
+    private readonly virtualize;
+    /**
+     * @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;
+    /** Whether the graph has been drawn whole. For code that runs after `helix-graph-ready`. */
+    get ready(): boolean;
+    /**
+     * Says the graph has been drawn whole, or with `false`, that it no longer
+     * 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. */
+    private relationText;
+    /** Selects the note a row names, through the request a page can refuse. */
+    private choose;
+    /**
+     * Moves the keyboard to a row, and the list to show it.
+     *
+     * **Scrolled by the row's own box where it is drawn, and by the estimate
+     * where it is not**, so a jump to the end of ten thousand notes lands there
+     * and the row is drawn by the update the scroll asks for.
+     */
+    private moveTo;
+    /**
+     * The keys in the list. **Kept from the frame**, whose arrows pan the
+     * drawing: a reader moving through the list was moving the graph under it.
+     */
+    private readonly handleListKeydown;
+    /**
+     * 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.
+     */
+    private readonly handleSearchKeydown;
+    private readonly handleSearch;
+    /**
+     * The mark in the search field, behind a seam: a slot for the page, and a
+     * method for the tier above, as the listbox's filter has.
+     */
+    protected renderFilterIcon(): TemplateResult;
+    private renderRows;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-graph': HelixHeadlessGraph;
+    }
+}
+export {};