@fusion.dev/helix-headless 0.147.0 → 0.149.0

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

@@ -127,6 +127,16 @@ export declare const ends: (edge: CanvasEdge, from: CanvasNode, to: CanvasNode)
     fromSide: CanvasSide;
     toSide: CanvasSide;
 };
+/**
+ * How far a point is from a card's box, in the document's units: nothing
+ * inside it, and the shortest way to its edge outside.
+ */
+export declare const distanceTo: (node: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, point: Point) => number;
 /**
  * The side of a card nearest a point, which is where a connection a reader is
  * holding arrives.

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

@@ -175,6 +175,7 @@ export const ends = (edge, from, to) => {
     const toSide = edge.toSide ?? fallbackTo;
     return { end: port(to, toSide), fromSide, start: port(from, fromSide), toSide };
 };
+export const distanceTo = (node, point) => Math.hypot(Math.max(node.x - point.x, 0, point.x - (node.x + node.width)), Math.max(node.y - point.y, 0, point.y - (node.y + node.height)));
 export const sideNear = (node, point) => ['top', 'right', 'bottom', 'left']
     .map((side) => {
     const at = port(node, side);

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

@@ -1,4 +1,4 @@
-import { type CanvasView, HelixElement, type ViewportGestureLabels, type ViewportPanDetail, type ViewportWay, type ViewportZoomDetail } from '@fusion.dev/helix-core';
+import { type CanvasView, HelixElement, 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';
@@ -34,20 +34,34 @@ declare const HelixHeadlessCanvas_base: (new (...args: any[]) => import("@fusion
  * keep every card in place, such as on a published board. Set `readonly` on one
  * card or connection to keep only that one in place.
  *
+ * Set `snap` to a length in the document's units, such as `32`, and a card
+ * that is moved or resized lands on a multiple of it. Carrying a card, a
+ * corner, a connection, or the selection box near the edge of the board moves
+ * the board under it, so a card can be taken to a place off screen in one
+ * drag. A connection let go within 20 pixels of a card arrives at it. A
+ * double click on the empty board zooms in about that point, and Shift with a
+ * double click zooms out.
+ *
  * Keyboard behavior:
  * - One card holds the board's tab stop.
  * - The arrow keys move through the cards in reading order. The card you land
  *   on scrolls into view, and its connections are announced with it.
- * - Shift with an arrow key moves the card.
+ * - Shift with an arrow key moves the card: by 16 units, or to the next
+ *   multiple of `snap` where it is set. Alt with an arrow key resizes it from
+ *   its bottom right corner the same way.
  * - The connections leaving a card are stops of their own, straight after it.
  *   Enter on one moves to the card it arrives at.
+ * - What a key changes that a reader cannot see is said: where a card moved
+ *   to, its new size, how many cards are selected, and the zoom. A selected
+ *   card or connection says so when a reader arrives on it.
  *
  * Every drag also works with clicks, as WCAG 2.5.7 requires for a pointer that
  * cannot hold a button down. Click a selected card's move handle, a corner, a
  * card's connection point, or the end of a selected connection to pick it up.
  * It follows the pointer with no button held, and the next click puts it down
  * where a drag would have. On touch, the next tap sets where it lands. Escape,
- * or a press outside the board, puts it back.
+ * or a press outside the board, puts it back. So a finger connects two cards
+ * with three taps: the card, one of its points, and the card to connect to.
  *
  * Connecting and removing dispatch requests, and your code applies them:
  * - Drawing from a card's handle to another card, or pressing C on one card and
@@ -55,6 +69,11 @@ declare const HelixHeadlessCanvas_base: (new (...args: any[]) => import("@fusion
  * - Delete on a card or a connection dispatches `helix-remove`. The event names
  *   every connection that removing the card would leave without an end.
  *
+ * Once your page removes what Delete asked for, focus moves to the next stop,
+ * to the one before where it was the last, and to the board where none is
+ * left. A focused card your page removes for its own reasons hands focus on
+ * the same way, unless the reader has already moved focus somewhere else.
+ *
  * The board applies a move itself, because the card already exists. A
  * connection is a new element, and React discards an element the board adds to
  * its markup on the next render, so you write the connection.
@@ -75,7 +94,14 @@ declare const HelixHeadlessCanvas_base: (new (...args: any[]) => import("@fusion
  * @slot - The board's `helix-canvas-node` and `helix-canvas-edge` elements, drawn on the plane.
  * @slot empty - Content shown when the document has no nodes.
  * @slot footer - Content below the board.
+ * @slot fullscreen-icon - Replaces the glyph inside the fullscreen button.
  * @slot header - Content above the board.
+ * @slot pan-down-icon - Replaces the glyph inside the pan down button.
+ * @slot pan-end-icon - Replaces the glyph inside the button that pans toward the end of a line of text.
+ * @slot pan-start-icon - Replaces the glyph inside the button that pans toward the start of a line of text.
+ * @slot pan-up-icon - Replaces the glyph inside the pan up button.
+ * @slot zoom-in-icon - Replaces the glyph inside the zoom-in button.
+ * @slot zoom-out-icon - Replaces the glyph inside the zoom-out button.
  *
  * @event {HelixBeforeMoveEvent} helix-before-move - Cards are about to move. Cancelable: cancel it to keep the positions in your own state.
  * @event {HelixBeforeReconnectEvent} helix-before-reconnect - A connection's end is about to move to another card or side. Cancelable: cancel it to keep connections in your own state.
@@ -128,10 +154,20 @@ declare const HelixHeadlessCanvas_base: (new (...args: any[]) => import("@fusion
  * @cssstate using - A board with `gestures="activate"` has been pressed and has the gestures.
  */
 export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
+    /**
+     * The key this family's words are registered under, its styled tag:
+     * `registerWords('de', { 'helix-canvas': { stoppedLabel: 'Verbinden beendet.' } })`.
+     */
+    static words: string;
     /** The connection whose target had focus as an update began, and that target. */
     private focusedEdge;
     /** Each card is assigned to its own slot, in the order the arrows walk them. */
     static shadowRootOptions: ShadowRootInit;
+    /**
+     * The hint shown when the board, waiting to be pressed with
+     * `gestures="activate"`, is scrolled or swiped over.
+     */
+    activateHintLabel: string;
     /** The text read with a card to say where its connections come from, with `{cards}`. */
     comesFromLabel: string;
     /** The text announced when a connection is requested, with `{from}` and `{to}`. */
@@ -151,6 +187,13 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
      * this, so a reader hears the ends first and what the line says after.
      */
     connectionLabel: string;
+    /**
+     * The name of the group of controls, read by screen readers, which names
+     * what the controls drive rather than the mechanism.
+     */
+    controlsLabel: string;
+    /** The board's name where `label` is empty. */
+    fallbackLabel: string;
     /**
      * The accessible name for the board. Required.
      *
@@ -171,6 +214,20 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
      * Third", rather than with a comma this component chose.
      */
     leadsToLabel: string;
+    /**
+     * The text read with a card that has connections both ways. `{leadsTo}` is
+     * `leads-to-label` and `{comesFrom}` is `comes-from-label`, each filled in.
+     */
+    linkedLabel: string;
+    /**
+     * What screen readers hear after a key moves a card, with `{name}` for the
+     * card and `{x}` and `{y}` for where it now is, in the document's units.
+     *
+     * **A move a reader cannot see has to be said.** Shift with an arrow moved
+     * the card and said nothing, so a reader moving one by keys could not tell
+     * whether it had moved, or how far.
+     */
+    movedLabel: string;
     /**
      * The order the arrow keys and screen readers move through the cards:
      * `spatial` or `edges`.
@@ -208,6 +265,12 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
      * `{to}`.
      */
     reconnectingLabel: string;
+    /**
+     * What screen readers hear after a key resizes a card, with `{name}` for the
+     * card and `{width}` and `{height}` for its new size, in the document's
+     * units.
+     */
+    resizedLabel: string;
     /**
      * The names of the selected cards and connections, comma separated. Empty
      * when nothing is selected.
@@ -230,6 +293,36 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
      * Written to select from outside, and read to act on the selection.
      */
     selected: string;
+    /**
+     * What a selected card or connection adds to what screen readers hear on
+     * it, before its tone and its connections. Empty adds nothing.
+     *
+     * A card is an article and a connection a button, and neither has a selected
+     * state for `aria-selected` to carry, so the state is said in words.
+     */
+    selectedLabel: string;
+    /**
+     * What screen readers hear after the selection grows or shrinks, with
+     * `{count}` for how many cards and connections are selected, written in the
+     * locale, where a language that needs plural forms writes them: by Space, a
+     * click with Shift, Command or Control, Command or Control with A, a box
+     * drawn across the board, or Escape.
+     *
+     * A selection of one made by arriving on a card or clicking it is not said,
+     * since the card is.
+     */
+    selectionLabel: string;
+    /**
+     * Snaps the cards a reader moves or resizes to a multiple of this many of the
+     * document's units, such as `32` to land on the lines `grid` draws.
+     *
+     * **A drag lets go on the nearest line and a key goes to the next one.**
+     * Shift with an arrow moves a card to the next line that way, rather than
+     * by its step of 16, and Alt with an arrow moves its bottom right corner
+     * the same way. A group moves with what it carries, so a card inside one
+     * keeps its place in it. Absent, cards land where they are let go.
+     */
+    snap?: number;
     /**
      * A label being edited in place: whose, and what it said before.
      */
@@ -247,6 +340,20 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
      * told the same. A tone left out is not read.
      */
     toneLabels: Partial<Record<CanvasTone, string>>;
+    /** The hint shown when one finger swipes over the board with `gestures="cooperative"`. */
+    twoFingerHintLabel: string;
+    /** The line shown while the board, with `gestures="activate"`, has the gestures. */
+    usingLabel: string;
+    /**
+     * The hint shown when the wheel scrolls past the board with
+     * `gestures="cooperative"`. `{key}` is ⌘ on a Mac and Ctrl elsewhere.
+     */
+    wheelHintLabel: string;
+    /**
+     * What screen readers hear after a zoom button or key, with `{zoom}` for the
+     * zoom as a percentage, written the way the element's locale writes one.
+     */
+    zoomedLabel: string;
     /** The card or connection that holds the board's one tab stop, by its key. */
     private stop;
     /**
@@ -254,8 +361,18 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
      * started it, and where the pointer is, in the document's own units.
      */
     private linking;
-    /** What the live region says, which is only ever about a connection being made. */
+    /**
+     * What the live region says: a connection being made, and what a key did
+     * that a reader cannot see, a move, a resize, the selection, the zoom.
+     */
     private said;
+    /**
+     * Says something in the live region.
+     *
+     * The same words twice would change nothing in the region and be heard
+     * once, so a second "2 selected" differs by a space no reader says.
+     */
+    private say;
     /**
      * Where focus goes once something a reader removed has gone.
      *
@@ -265,6 +382,17 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
      * or, for a page that declines, off one that stays.
      */
     private refocus;
+    /**
+     * The card focus is on, while it is.
+     *
+     * **Kept so a card the page takes away hands focus on**, as Delete does: a
+     * filter, an undo or another person's edit removed the card a reader was on,
+     * and the browser dropped focus to the page's body, putting the reader back
+     * at its top with nothing said. Map does the same for its markers.
+     */
+    private focusedCard;
+    /** The stops in the order the arrows walked them on the last update. */
+    private walked;
     /**
      * Where the plane's corner was on the last render, in the document's units.
      *
@@ -381,9 +509,6 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
     /** The events this family names for itself, the surface being shared. */
     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.
      *
@@ -469,7 +594,8 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
     private toDocument;
     /**
      * The card under a point, the smallest where they overlap, so a card inside
-     * a group is found before the group around it.
+     * a group is found before the group around it. Where none is, the nearest
+     * within `reach`, in the document's units.
      */
     private cardAt;
     /** What a card is called, by id, for what the live region says. */
@@ -631,6 +757,22 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
      * Returns whether it applied, so a caller knows whether to report a finish.
      */
     private requestMove;
+    /**
+     * Moves the view while a pointer carries something near its edge, and
+     * carries it along: a card, a corner, a connection being drawn, the box that
+     * selects.
+     */
+    private readonly edgePan;
+    /** The last pointer move of a carry, which a frame of `edgePan` moves on from. */
+    private carryPointer;
+    /**
+     * One frame of moving the view under something carried to its edge: the
+     * board moves by `by` and what is in hand stays under the pointer, so a card
+     * goes on moving over the board while the hand is still.
+     */
+    private panCarrying;
+    /** Follows a pointer carrying something, which moves the view at an edge. */
+    private carryOn;
     /**
      * Drag to move the board, which is the gesture a canvas is reached for with.
      *
@@ -760,6 +902,20 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
      * own, ended by its release.
      */
     private readonly handleFocusOut;
+    /**
+     * Forgets the card focus left, unless the page took it away.
+     *
+     * Focus leaving for nothing is a press on the page or the card removed, and
+     * which one is known once the removal has finished: a card still on the
+     * board was left, and one gone is owed a place for focus to land.
+     */
+    private forget;
+    /**
+     * Gives focus on from a card the page took away with focus in it: to the
+     * next stop, the one before where it was the last, and the board where none
+     * is left. Not where the reader has gone somewhere else already.
+     */
+    private handOn;
     /** Brings a card into view, where it is not already whole in it. */
     private reveal;
     /**
@@ -767,7 +923,10 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
      * board draws; a card's content by asking, which the board does not.
      */
     private editStop;
-    /** A double-click on a card or a connection edits it, the pointer's F2. */
+    /**
+     * A double-click on a card or a connection edits it, the pointer's F2, and
+     * one on the empty board zooms in about where it landed.
+     */
     private readonly handleDoubleClick;
     /**
      * Finishes editing a label: asks, writes it where the page did not refuse,