@fusion.dev/helix-headless 0.146.0 → 0.148.0

package/dist/button-group/root/button-group-root.js

@@ -4,22 +4,156 @@ 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, HelixElement, hostAria } from '@fusion.dev/helix-core';
+import { auditName, commaList, customElement, HelixElement, hostAria, inlineStep, pressedValue, reportRuntime, requestValue, rovingStop, toolbarAround, whenHydrated, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
+import { arrowTarget } from '../arrows.js';
+const isGroupButton = (child) => child instanceof HTMLElement && 'focusable' in child && 'value' in child;
 let HelixHeadlessButtonGroup = class HelixHeadlessButtonGroup extends HelixElement {
     constructor() {
         super(...arguments);
         this.label = '';
+        this.value = '';
+        this.lastFocused = undefined;
+        this.told = new Map();
+        this.warned = false;
+        this.handlePress = (event) => {
+            const mode = this.selectionMode;
+            const button = this.buttons.find((one) => event.composedPath().includes(one));
+            if (mode && button && button.value !== '') {
+                requestValue(this, pressedValue(mode, this.value, button.value), (next) => {
+                    this.value = next;
+                });
+            }
+        };
+        this.handleKeydown = (event) => {
+            const buttons = this.roving ? this.buttons.filter((one) => one.disabled !== true) : [];
+            const from = buttons.findIndex((one) => event.composedPath().includes(one));
+            const to = arrowTarget(event.key, inlineStep(this, event.key), from, buttons.length);
+            if (to >= 0 && !event.defaultPrevented) {
+                event.preventDefault();
+                buttons[to]?.focus();
+            }
+        };
+        this.noteFocus = (event) => {
+            const button = this.buttons.find((one) => event.composedPath().includes(one));
+            if (button && button !== this.lastFocused) {
+                this.lastFocused = button;
+                this.sync();
+            }
+        };
+    }
+    get buttons() {
+        return this.selectionMode && this.children ? [...this.children].filter(isGroupButton) : [];
+    }
+    get roving() {
+        return this.selectionMode !== undefined && toolbarAround(this) === null;
+    }
+    pressed(button) {
+        return button.value !== '' && commaList(this.value).includes(button.value);
+    }
+    sync() {
+        const buttons = this.buttons;
+        const roving = this.roving;
+        const stop = roving
+            ? rovingStop(buttons, this.lastFocused, {
+                disabled: (button) => button.disabled === true,
+                selected: (button) => this.pressed(button),
+            })
+            : undefined;
+        for (const [button, roved] of this.told) {
+            if (!buttons.includes(button)) {
+                this.told.delete(button);
+                this.mark(button);
+                if (roved) {
+                    whenHydrated(button, () => {
+                        button.focusable = true;
+                    });
+                }
+            }
+        }
+        for (const button of buttons) {
+            this.told.set(button, roving);
+            this.mark(button);
+            if (roving) {
+                whenHydrated(button, () => {
+                    button.focusable = button === stop;
+                });
+            }
+        }
+        for (const child of this.selectionMode && this.children ? this.children : []) {
+            if (child.localName.includes('-') && !isGroupButton(child)) {
+                void customElements.whenDefined(child.localName).then(() => this.sync());
+            }
+            else if (child.localName === 'button' && !child.hasAttribute('aria-pressed')) {
+                this.warn(child);
+            }
+        }
+    }
+    warn(button) {
+        if (this.warned) {
+            return;
+        }
+        this.warned = true;
+        reportRuntime({
+            kind: 'untold-toggle',
+            message: `<${this.localName}> cannot press a native <button>: its state would be written onto your ` +
+                'markup. Slot a Helix button with a `value`, or set `aria-pressed` on the button yourself.',
+            tag: button.localName,
+        });
+    }
+    mark(button) {
+        void button.updateComplete.then(() => {
+            const control = button.shadowRoot?.querySelector('button');
+            if (control && !button.hasAttribute('aria-pressed')) {
+                const toggle = this.told.has(button) && button.value !== '';
+                this.markPressed(control, toggle ? this.pressed(button) : undefined);
+            }
+        });
+    }
+    markPressed(control, pressed) {
+        if (pressed === undefined) {
+            control.removeAttribute('aria-pressed');
+        }
+        else {
+            control.setAttribute('aria-pressed', String(pressed));
+        }
+        control.style.setProperty('--button-group-pressed', pressed === undefined ? '' : pressed ? '1' : '0');
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this.addEventListener('focusin', this.noteFocus);
+        this.addEventListener('helix-press', this.handlePress);
+        this.addEventListener('keydown', this.handleKeydown);
+        this.watcher = new MutationObserver(() => this.sync());
+        this.watcher.observe(this, {
+            attributeFilter: ['disabled', 'value'],
+            childList: true,
+            subtree: true,
+        });
+        this.requestUpdate();
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.removeEventListener('focusin', this.noteFocus);
+        this.removeEventListener('helix-press', this.handlePress);
+        this.removeEventListener('keydown', this.handleKeydown);
+        this.watcher?.disconnect();
     }
     willUpdate(changed) {
         super.willUpdate(changed);
-        hostAria(this.internals, { label: this.label, role: 'group' });
+        const toolbar = this.selectionMode !== undefined && toolbarAround(this) === null;
+        hostAria(this.internals, { label: this.label, role: toolbar ? 'toolbar' : 'group' });
+        this.internals.ariaOrientation = toolbar ? (this.orientation ?? null) : null;
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
         auditName(this, () => null, 'Give it a `label`, or an `aria-label` that says what the buttons are for.', () => this.label !== '');
     }
+    updated(changed) {
+        super.updated(changed);
+        this.sync();
+    }
     render() {
         return html `<slot></slot>`;
     }
@@ -30,6 +164,12 @@ __decorate([
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessButtonGroup.prototype, "orientation", void 0);
+__decorate([
+    property({ attribute: 'selection-mode', reflect: true })
+], HelixHeadlessButtonGroup.prototype, "selectionMode", void 0);
+__decorate([
+    property()
+], HelixHeadlessButtonGroup.prototype, "value", void 0);
 HelixHeadlessButtonGroup = __decorate([
     customElement('helix-headless-button-group')
 ], HelixHeadlessButtonGroup);

package/dist/canvas/edge-pan.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Moving the view while something is carried to its edge: a card, a corner, a
+ * connection being drawn, or the box that selects.
+ *
+ * **A board is larger than its box, and a hand stops at the edge of the box.**
+ * Without this, carrying a card to a place off screen took a drop at the edge,
+ * a pan, and a second pick-up, and a connection to a card off screen could not
+ * be drawn by pointer at all.
+ */
+/** A point on screen, in pixels. */
+export interface EdgePoint {
+    x: number;
+    y: number;
+}
+/** The box the view is drawn in, on screen. */
+export interface EdgeRect {
+    bottom: number;
+    left: number;
+    right: number;
+    top: number;
+}
+/** How near an edge, in pixels, the view starts to move. */
+export declare const EDGE_ZONE = 32;
+/** The most the view moves in one frame, in pixels: at the edge and past it. */
+export declare const EDGE_MOST = 12;
+/**
+ * How far the view should move toward each side in one frame, in pixels, for
+ * a pointer at `point`: positive toward the right and the bottom, nothing
+ * outside the zone, and faster the nearer the edge, up to `most` at it and
+ * past it.
+ *
+ * A box narrower than two zones moves only once the pointer is past its edge,
+ * so a small board is not always moving.
+ */
+export declare const edgeSpeed: (point: EdgePoint, rect: EdgeRect, zone?: number, most?: number) => EdgePoint;
+/**
+ * The frames that move the view while a pointer holds something near an edge.
+ *
+ * `follow` with every pointer move keeps it going while the pointer is in the
+ * zone, and `stop` ends it, which the board calls when the gesture ends and
+ * when it leaves the page. Each frame hands `step` how far to move, and the
+ * board moves the view and carries what is in hand with it.
+ */
+export declare class EdgePan {
+    private readonly rect;
+    private readonly step;
+    private readonly ended;
+    /** The frame asked for, while the view is moving. */
+    private frame;
+    /** Where the pointer last was. */
+    private point;
+    constructor(rect: () => EdgeRect | undefined, step: (by: EdgePoint) => void, ended?: () => void);
+    /** Whether the view is moving. */
+    get moving(): boolean;
+    /** Where the pointer is now, which starts the frames where it is in the zone. */
+    follow(point: EdgePoint): void;
+    /** Ends the frames. */
+    stop(): void;
+    private speed;
+    private readonly tick;
+}

package/dist/canvas/edge-pan.js

@@ -0,0 +1,63 @@
+export const EDGE_ZONE = 32;
+export const EDGE_MOST = 12;
+export const edgeSpeed = (point, rect, zone = EDGE_ZONE, most = EDGE_MOST) => {
+    const along = (at, start, end) => {
+        if (at >= end) {
+            return 1;
+        }
+        if (at <= start) {
+            return -1;
+        }
+        const reach = end - start < zone * 2 ? 0 : zone;
+        if (reach > 0 && at > end - reach) {
+            return (at - (end - reach)) / reach;
+        }
+        if (reach > 0 && at < start + reach) {
+            return -(start + reach - at) / reach;
+        }
+        return 0;
+    };
+    return {
+        x: Math.round(along(point.x, rect.left, rect.right) * most),
+        y: Math.round(along(point.y, rect.top, rect.bottom) * most),
+    };
+};
+export class EdgePan {
+    constructor(rect, step, ended = () => undefined) {
+        this.rect = rect;
+        this.step = step;
+        this.ended = ended;
+        this.tick = () => {
+            const by = this.speed();
+            if (by.x === 0 && by.y === 0) {
+                this.frame = undefined;
+                this.ended();
+                return;
+            }
+            this.step(by);
+            this.frame = requestAnimationFrame(this.tick);
+        };
+    }
+    get moving() {
+        return this.frame !== undefined;
+    }
+    follow(point) {
+        this.point = point;
+        const by = this.speed();
+        if (this.frame === undefined && (by.x !== 0 || by.y !== 0)) {
+            this.frame = requestAnimationFrame(this.tick);
+        }
+    }
+    stop() {
+        this.point = undefined;
+        if (this.frame !== undefined) {
+            cancelAnimationFrame(this.frame);
+            this.frame = undefined;
+            this.ended();
+        }
+    }
+    speed() {
+        const rect = this.rect();
+        return this.point && rect ? edgeSpeed(this.point, rect) : { x: 0, y: 0 };
+    }
+}

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

@@ -150,6 +150,16 @@ export declare class HelixHeadlessCanvasNode extends HelixElement {
      * point and one to a circle on its curve without the board knowing which.
      */
     shape?: 'circle' | 'diamond' | 'pill' | 'square';
+    /**
+     * @internal What the card's state adds to what it says, in the page's words,
+     * written by the board: its `selected-label` while it is selected. Read
+     * first, before what the tone means.
+     *
+     * **A selection a reader cannot see has to be said.** A card is an article,
+     * and an article has no selected state for `aria-selected` to carry, so a
+     * reader who selected three cards heard nothing on any of them.
+     */
+    status: string;
     /**
      * @internal Whether this is the card the reader selected, written by the
      * board. Kept apart from focus, so a reader who clicks a button beside the
@@ -211,8 +221,8 @@ export declare class HelixHeadlessCanvasNode extends HelixElement {
      */
     focus(options?: FocusOptions): void;
     /**
-     * The card, and the sentence that says what its tone means and where it
-     * leads.
+     * The card, and the sentence that says whether it is selected, what its
+     * tone means and where it leads.
      *
      * **`aria-describedby` at a hidden element, which is allowed and is the
      * point.** A description is computed from its target whether or not the

package/dist/canvas/node/canvas-node.js

@@ -33,6 +33,7 @@ let HelixHeadlessCanvasNode = class HelixHeadlessCanvasNode extends HelixElement
         this.links = '';
         this.meaning = '';
         this.readOnly = false;
+        this.status = '';
         this.selected = false;
         this.movable = false;
         this.resizable = false;
@@ -72,7 +73,7 @@ let HelixHeadlessCanvasNode = class HelixHeadlessCanvasNode extends HelixElement
           </svg>`
             : nothing}<div
       part="node"
-      aria-describedby=${this.meaning || this.links ? 'about' : nothing}
+      aria-describedby=${this.status || this.meaning || this.links ? 'about' : nothing}
       aria-label=${this.label || nothing}
       aria-labelledby=${this.label || this.group ? nothing : 'content'}
       aria-keyshortcuts=${this.connectable ? 'Enter F2 Space Shift+ArrowRight Shift+ArrowDown Alt+ArrowRight Alt+ArrowDown C Delete' : nothing}
@@ -81,7 +82,7 @@ let HelixHeadlessCanvasNode = class HelixHeadlessCanvasNode extends HelixElement
     >
       <slot id="content"></slot>
       <slot name="description"></slot>
-      <span id="about" hidden>${[this.meaning, this.links].filter(Boolean).join(', ')}</span>
+      <span id="about" hidden>${[this.status, this.meaning, this.links].filter(Boolean).join(', ')}</span>
     </div>
     ${this.connectable
             ? html `<span part="handle handle-top" aria-hidden="true" data-side="top"></span>
@@ -131,6 +132,9 @@ __decorate([
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessCanvasNode.prototype, "shape", void 0);
+__decorate([
+    state()
+], HelixHeadlessCanvasNode.prototype, "status", void 0);
 __decorate([
     state()
 ], HelixHeadlessCanvasNode.prototype, "selected", void 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

@@ -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
@@ -75,7 +89,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.
@@ -171,6 +192,15 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
      * Third", rather than with a comma this component chose.
      */
     leadsToLabel: 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 +238,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 +266,35 @@ 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: 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 +312,11 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
      * told the same. A tone left out is not read.
      */
     toneLabels: Partial<Record<CanvasTone, string>>;
+    /**
+     * What screen readers hear after a zoom button or key, with `{zoom}` for the
+     * zoom as a percentage, written the way the page's language writes one.
+     */
+    zoomedLabel: string;
     /** The card or connection that holds the board's one tab stop, by its key. */
     private stop;
     /**
@@ -254,8 +324,20 @@ 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;
+    /** Numbers as the page's language writes them. */
+    private get numbers();
     /**
      * Where focus goes once something a reader removed has gone.
      *
@@ -469,7 +551,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 +714,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.
      *
@@ -767,7 +866,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,