@fusion.dev/helix-headless 0.160.0 → 0.161.0

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

@@ -58,6 +58,16 @@ declare const HelixHeadlessCanvas_base: (new (...args: any[]) => import("@fusion
  * - 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.
+ * - Control or Command with C copies the selected cards, and the connections
+ *   between them, as a JSON Canvas document in text, which another board or
+ *   an app that reads the format takes. A paste is your page's: listen for
+ *   `paste` on the board, read the text with `fromJsonCanvas`, and add the
+ *   cards it holds.
+ * - Control or Command with Z undoes the last move or resize the board made,
+ *   and with Shift, or Control with Y, makes it again. `undo()` and `redo()`
+ *   do the same from a script. Each asks with `helix-before-move` and tells
+ *   with `helix-move`, as a move does, so a board that holds its positions in
+ *   your state is undone through your state.
  *
  * 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
@@ -198,6 +208,8 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
      * what the controls drive rather than the mechanism.
      */
     controlsLabel: string;
+    /** What screen readers hear after a copy, with `{count}` for the cards copied. */
+    copiedLabel: string;
     /** The board's name where `label` is empty. */
     fallbackLabel: string;
     /**
@@ -271,6 +283,8 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
      * `{to}`.
      */
     reconnectingLabel: string;
+    /** What screen readers hear after a move or a resize is made again. */
+    redoneLabel: 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
@@ -336,12 +350,12 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
      * keeps its place in it. Absent, cards land where they are let go.
      */
     snap?: number;
+    /** The text announced when a connection is stopped before it is requested. */
+    stoppedLabel: string;
     /**
      * A label being edited in place: whose, and what it said before.
      */
     private editing;
-    /** The text announced when a connection is stopped before it is requested. */
-    stoppedLabel: string;
     /**
      * What each tone means on this board, in words read out with the cards and
      * connections in it, such as `{"danger": "Blocked", "success": "Done"}`.
@@ -355,6 +369,8 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
     toneLabels: Partial<Record<CanvasTone, string>>;
     /** The hint shown when one finger swipes over the board with `gestures="cooperative"`. */
     twoFingerHintLabel: string;
+    /** What screen readers hear after a move or a resize is undone. */
+    undoneLabel: string;
     /** The line shown while the board, with `gestures="activate"`, has the gestures. */
     usingLabel: string;
     /**
@@ -770,6 +786,47 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
      * Returns whether it applied, so a caller knows whether to report a finish.
      */
     private requestMove;
+    /**
+     * The moves and resizes the board made, oldest first, each as where its
+     * cards stood before and after, for `undo` to take back. At most 100.
+     */
+    private undoable;
+    /** The moves undone, most recent last, for `redo` to make again. */
+    private redoable;
+    /** Where the cards of the gesture in progress stood before its first step. */
+    private moving;
+    /** Whether a move is an undo or a redo, which history does not record again. */
+    private replaying;
+    /**
+     * Says a move is finished, and keeps it for `undo`: where its cards stood
+     * before the gesture, and where they stand now.
+     */
+    private finishMove;
+    /**
+     * Puts the cards of the last move or resize back where they stood, asking
+     * with `helix-before-move` first. Returns whether anything moved: false
+     * with nothing to undo, or when the request was refused.
+     */
+    undo(): boolean;
+    /**
+     * Makes the last move or resize `undo` took back again, asking with
+     * `helix-before-move` first. Returns whether anything moved.
+     */
+    redo(): boolean;
+    /** Moves the cards of the last entry of `from` to its `side`, and files it in `to`. */
+    private replay;
+    /**
+     * A copy on the board with cards selected writes them, and the connections
+     * between them, as a JSON Canvas document in text. Not from a field a card
+     * holds, nor over text a reader selected, which are the platform's to copy.
+     */
+    private readonly handleCopy;
+    /**
+     * Control or Command with Z undoes, and with Shift, or Control with Y,
+     * redoes, from anywhere on the board but a field a card holds, where the
+     * keys are the field's.
+     */
+    private readonly handleHistoryKey;
     /**
      * 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

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

@@ -48,6 +48,7 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
         this.connectingLabel = 'Connecting from {from}. Move to another card and press Enter, or Escape to stop.';
         this.connectionLabel = 'From {from} to {to}';
         this.controlsLabel = 'Board controls';
+        this.copiedLabel = '{count, plural, one {# card copied} other {# cards copied}}';
         this.fallbackLabel = 'Canvas';
         this.label = '';
         this.labelEditorLabel = 'Label for {name}';
@@ -56,6 +57,7 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
         this.movedLabel = '{name} moved to {x}, {y}';
         this.readOnly = false;
         this.reconnectingLabel = 'Moving the end of the connection from {from} to {to}. Move to a card and press Enter, or Escape to stop.';
+        this.redoneLabel = 'Move made again';
         this.resizedLabel = '{name} resized to {width} by {height}';
         this.roleLabel = 'canvas';
         this.selected = '';
@@ -64,6 +66,7 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
         this.stoppedLabel = 'Stopped connecting.';
         this.toneLabels = {};
         this.twoFingerHintLabel = 'Use two fingers to move the board';
+        this.undoneLabel = 'Move undone';
         this.usingLabel = 'Using the board. Press Escape to scroll the page again.';
         this.wheelHintLabel = 'Use {key} and scroll to zoom the board';
         this.zoomedLabel = 'Zoom {zoom}';
@@ -81,6 +84,45 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
         this.fingers = new Map();
         this.keying = undefined;
         this.edgeKeys = new WeakMap();
+        this.undoable = [];
+        this.redoable = [];
+        this.replaying = false;
+        this.handleCopy = (event) => {
+            const origin = event.composedPath()[0];
+            const text = globalThis.getSelection?.()?.toString() ?? '';
+            if (this.picked.length === 0 || !event.clipboardData || text !== '') {
+                return;
+            }
+            if (origin?.closest?.(INTERACTIVE)) {
+                return;
+            }
+            const picked = new Set(this.picked);
+            const whole = this.toJsonCanvas();
+            const copy = {
+                edges: (whole.edges ?? []).filter((edge) => picked.has(edge.fromNode) && picked.has(edge.toNode)),
+                nodes: (whole.nodes ?? []).filter((node) => picked.has(node.id)),
+            };
+            event.clipboardData.setData('text/plain', JSON.stringify(copy));
+            event.preventDefault();
+            this.say(formatWords(this, 'copiedLabel', { count: copy.nodes?.length ?? 0 }));
+        };
+        this.handleHistoryKey = (event) => {
+            if (event.defaultPrevented || event.altKey || !(event.ctrlKey || event.metaKey)) {
+                return;
+            }
+            const key = event.key.toLowerCase();
+            const again = (key === 'z' && event.shiftKey) || (key === 'y' && !event.shiftKey);
+            if (key !== 'z' && !again) {
+                return;
+            }
+            const origin = event.composedPath()[0];
+            if (origin?.closest?.(INTERACTIVE)) {
+                return;
+            }
+            if (again ? this.redo() : this.undo()) {
+                event.preventDefault();
+            }
+        };
         this.edgePan = new EdgePan(() => this.partNamed('viewport')?.getBoundingClientRect(), (by) => this.panCarrying(by), () => {
             if (!this.dragging) {
                 this.direct = false;
@@ -348,7 +390,7 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
                 }
                 this.sizing = undefined;
                 if (sizing.moved) {
-                    this.dispatchEvent(new HelixMoveEvent(sizing.moved));
+                    this.finishMove(sizing.moved);
                 }
                 return;
             }
@@ -393,7 +435,7 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
                     this.clicked(carry.pressed, event);
                 }
                 if (carry.moved) {
-                    this.dispatchEvent(new HelixMoveEvent(carry.moved));
+                    this.finishMove(carry.moved);
                 }
                 return;
             }
@@ -478,7 +520,7 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
                     })),
                 };
                 if (this.requestMove(detail)) {
-                    this.dispatchEvent(new HelixMoveEvent(detail));
+                    this.finishMove(detail);
                     this.say(formatWords(this, 'movedLabel', {
                         name: this.nameOf(card.name),
                         x: card.x,
@@ -498,7 +540,7 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
                 const box = this.resized({ height: card.height, width: card.width, x: card.x, y: card.y }, 'bottom-right', step ? stepTo(edge.x, along, step) - edge.x : along * NUDGE, step ? stepTo(edge.y, down, step) - edge.y : down * NUDGE);
                 const detail = { nodes: [{ name: card.name, ...box }] };
                 if (this.requestMove(detail)) {
-                    this.dispatchEvent(new HelixMoveEvent(detail));
+                    this.finishMove(detail);
                     this.say(formatWords(this, 'resizedLabel', {
                         height: box.height,
                         name: this.nameOf(card.name),
@@ -1209,6 +1251,12 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
         for (const { height, name, width, x, y } of detail.nodes) {
             const card = this.byName.get(name);
             if (card) {
+                if (!this.replaying) {
+                    this.moving ??= new Map();
+                    if (!this.moving.has(name)) {
+                        this.moving.set(name, { height: card.height, width: card.width, x: card.x, y: card.y });
+                    }
+                }
                 card.x = x;
                 card.y = y;
                 if (width !== undefined && height !== undefined) {
@@ -1220,6 +1268,52 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
         this.requestUpdate();
         return true;
     }
+    finishMove(detail) {
+        const moving = this.moving;
+        this.moving = undefined;
+        if (moving && moving.size > 0) {
+            const place = (name) => {
+                const card = this.byName.get(name);
+                return card
+                    ? { height: card.height, name, width: card.width, x: card.x, y: card.y }
+                    : undefined;
+            };
+            this.undoable.push({
+                after: {
+                    nodes: [...moving.keys()]
+                        .map(place)
+                        .filter((one) => one !== undefined),
+                },
+                before: { nodes: [...moving].map(([name, at]) => ({ name, ...at })) },
+            });
+            this.undoable = this.undoable.slice(-100);
+            this.redoable = [];
+        }
+        this.dispatchEvent(new HelixMoveEvent(detail));
+    }
+    undo() {
+        return this.replay(this.undoable, this.redoable, 'before', this.undoneLabel);
+    }
+    redo() {
+        return this.replay(this.redoable, this.undoable, 'after', this.redoneLabel);
+    }
+    replay(from, to, side, words) {
+        const entry = from.pop();
+        if (!entry) {
+            return false;
+        }
+        this.replaying = true;
+        const applied = this.requestMove(entry[side]);
+        this.replaying = false;
+        if (!applied) {
+            from.push(entry);
+            return false;
+        }
+        to.push(entry);
+        this.dispatchEvent(new HelixMoveEvent(entry[side]));
+        this.say(words);
+        return true;
+    }
     panCarrying(by) {
         const last = this.carryPointer;
         if (!last) {
@@ -1299,6 +1393,7 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
             this.linking = undefined;
             this.said = this.stoppedLabel;
         }
+        this.moving = undefined;
         this.letGo();
     }
     letGo() {
@@ -1703,8 +1798,9 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
         }
         this.handOn();
         this.walked = this.walk;
+        const watching = this.watched !== undefined;
         this.watchBox();
-        if (!this.touched) {
+        if (watching && !this.touched) {
             this.fitInto(true);
         }
     }
@@ -1782,6 +1878,8 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
         this.addEventListener('focusin', this.handleFocusIn);
         this.addEventListener('focusout', this.handleFocusOut);
         this.addEventListener('keydown', this.handleStopKeydown);
+        this.addEventListener('keydown', this.handleHistoryKey);
+        this.addEventListener('copy', this.handleCopy);
         this.addEventListener('pointercancel', this.handlePointerUp);
         this.addEventListener('pointerdown', this.handlePointerDown);
         this.addEventListener('pointermove', this.handlePointerMove);
@@ -1802,6 +1900,8 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
         this.removeEventListener('focusin', this.handleFocusIn);
         this.removeEventListener('focusout', this.handleFocusOut);
         this.removeEventListener('keydown', this.handleStopKeydown);
+        this.removeEventListener('keydown', this.handleHistoryKey);
+        this.removeEventListener('copy', this.handleCopy);
         this.removeEventListener('pointercancel', this.handlePointerUp);
         this.removeEventListener('pointerdown', this.handlePointerDown);
         this.removeEventListener('pointermove', this.handlePointerMove);
@@ -1826,6 +1926,9 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
             };
         }
         this.origin = origin;
+        if (this.watched && !this.touched) {
+            this.fitInto(true);
+        }
         hostAria(this.internals, { label: this.label });
         this.toggleState('connecting', this.drawing);
         this.toggleState('direct', this.direct);
@@ -2148,6 +2251,10 @@ __decorate([
     words,
     property({ attribute: 'controls-label' })
 ], HelixHeadlessCanvas.prototype, "controlsLabel", void 0);
+__decorate([
+    words,
+    property({ attribute: 'copied-label' })
+], HelixHeadlessCanvas.prototype, "copiedLabel", void 0);
 __decorate([
     words,
     property({ attribute: 'fallback-label' })
@@ -2184,6 +2291,10 @@ __decorate([
     words,
     property({ attribute: 'reconnecting-label' })
 ], HelixHeadlessCanvas.prototype, "reconnectingLabel", void 0);
+__decorate([
+    words,
+    property({ attribute: 'redone-label' })
+], HelixHeadlessCanvas.prototype, "redoneLabel", void 0);
 __decorate([
     words,
     property({ attribute: 'resized-label' })
@@ -2206,13 +2317,13 @@ __decorate([
 __decorate([
     property({ type: Number })
 ], HelixHeadlessCanvas.prototype, "snap", void 0);
-__decorate([
-    state()
-], HelixHeadlessCanvas.prototype, "editing", void 0);
 __decorate([
     words,
     property({ attribute: 'stopped-label' })
 ], HelixHeadlessCanvas.prototype, "stoppedLabel", void 0);
+__decorate([
+    state()
+], HelixHeadlessCanvas.prototype, "editing", void 0);
 __decorate([
     property({ attribute: 'tone-labels', converter: wordsConverter })
 ], HelixHeadlessCanvas.prototype, "toneLabels", void 0);
@@ -2220,6 +2331,10 @@ __decorate([
     words,
     property({ attribute: 'two-finger-hint-label' })
 ], HelixHeadlessCanvas.prototype, "twoFingerHintLabel", void 0);
+__decorate([
+    words,
+    property({ attribute: 'undone-label' })
+], HelixHeadlessCanvas.prototype, "undoneLabel", void 0);
 __decorate([
     words,
     property({ attribute: 'using-label' })

package/dist/chat/message/chat-message.d.ts

@@ -112,6 +112,14 @@ export declare class HelixHeadlessChatMessage extends HelixElement {
      * holds the reason. Everything else that moves it is the consumer's.
      */
     state?: 'failed' | 'sending' | 'sent' | 'streaming';
+    /** @internal Set by the chat with `turnPosition`: how many turns there are. */
+    turnCount: number;
+    /**
+     * @internal Set by the chat: where the turn stands in the conversation,
+     * from 1, and how many turns there are, which a screen reader says as
+     * "3 of 40". Zero where no chat has said.
+     */
+    turnPosition: number;
     /**
      * @internal Set by the chat: the word for `me` and the sentence that names a
      * turn with both an author and a time, in the chat's language.

package/dist/chat/message/chat-message.js

@@ -19,6 +19,8 @@ let HelixHeadlessChatMessage = class HelixHeadlessChatMessage extends HelixEleme
         this.locale = '';
         this.retryLabel = 'Try again';
         this.sendingLabel = 'Sending';
+        this.turnCount = 0;
+        this.turnPosition = 0;
         this.turnWords = TURN_WORDS;
         this.isChatMessage = true;
         this.clock = new RelativeClockController(this, {
@@ -64,6 +66,9 @@ let HelixHeadlessChatMessage = class HelixHeadlessChatMessage extends HelixEleme
         }
         hostAria(this.internals, { label: this.name, role: 'article' });
         this.internals.ariaBusy = this.state === 'streaming' ? 'true' : null;
+        const placed = this.turnPosition > 0 && this.turnCount > 0;
+        this.internals.ariaPosInSet = placed ? String(this.turnPosition) : null;
+        this.internals.ariaSetSize = placed ? String(this.turnCount) : null;
     }
     get reading() {
         const moment = this.moment;
@@ -160,6 +165,12 @@ __decorate([
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessChatMessage.prototype, "state", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessChatMessage.prototype, "turnCount", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessChatMessage.prototype, "turnPosition", void 0);
 __decorate([
     property({ attribute: false })
 ], HelixHeadlessChatMessage.prototype, "turnWords", void 0);

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

@@ -59,6 +59,19 @@ declare const HelixHeadlessChat_base: (new (...args: any[]) => import("@fusion.d
  * "Ada is typing" (`typing-label`), which a screen reader hears, and clearing
  * it takes them away. Anything slotted into `status` is drawn first.
  *
+ * **Keyboard.** The transcript moves between turns the way a feed does. Each
+ * turn says its place, such as "3 of 40", windowed or not.
+ *
+ * | Key | What it does |
+ * |---|---|
+ * | Page Down, Page Up | On a turn or inside one, moves focus to the next or the previous turn. On the transcript itself, moves focus to the turn at the top of the view. |
+ * | Control with End | Moves focus to the composer. |
+ * | Control with Home | Moves focus to the first control above the transcript, or to the transcript. |
+ *
+ * While you are scrolled away from the newest turn, the `resume` region shows
+ * a button that takes you back, named by `resume-label`, "Jump to latest".
+ * Slot your own control into `resume` to replace it.
+ *
  * A screen reader names each turn by its author and its time, such as "You, 2
  * minutes ago". Set `me-label` and `message-label` to say it in your language,
  * and give each turn by `them` an `author-label`. A turn with neither an author
@@ -84,7 +97,7 @@ declare const HelixHeadlessChat_base: (new (...args: any[]) => import("@fusion.d
  * @slot actions - Controls for the whole conversation, beside the header.
  * @slot composer - The composer, below the transcript.
  * @slot header - Content above the transcript that names the conversation.
- * @slot resume - The control that returns to the bottom, shown while the user has scrolled away.
+ * @slot resume - The control that returns to the bottom, shown while the user has scrolled away. Defaults to a button named by `resume-label`.
  * @slot status - Status beside the composer, such as someone typing or a lost connection.
  *
  * @event {HelixBeforePinEvent} helix-before-pin - Fired when the user pins or unpins the transcript by scrolling. Cancelable.
@@ -124,6 +137,8 @@ declare const HelixHeadlessChat_base: (new (...args: any[]) => import("@fusion.d
  * @csspart message-state - The state text of a turn from `turns`, when there is one to show.
  * @csspart message-time - The time of a turn from `turns`.
  * @csspart resume - The control shown while the user is scrolled away from the bottom.
+ * @csspart resume-button - The button the `resume` region shows when nothing is slotted into it.
+ * @csspart resume-mark - The arrow on the default `resume-button`.
  * @csspart status - The status region, outside the log.
  * @csspart turn - The wrapper around the message drawn for one turn from `turns`.
  * @csspart typing - The words that say who is typing, in the status band, while `typing` names someone.
@@ -232,6 +247,8 @@ export declare class HelixHeadlessChat extends HelixHeadlessChat_base {
      */
     get pinned(): boolean;
     set pinned(next: boolean);
+    /** The words on the button that returns to the newest turn, where `resume` is empty. */
+    resumeLabel: string;
     /**
      * How near the bottom still counts as being at it, in pixels.
      *
@@ -484,6 +501,30 @@ export declare class HelixHeadlessChat extends HelixHeadlessChat_base {
      * has hydrated, so its first render is the server's.
      */
     private tellTurns;
+    /**
+     * Which turn an event came from, by its place, `-1` for the transcript
+     * itself, or `undefined` for anywhere else.
+     */
+    private turnFrom;
+    /** The place of the turn at the top of the view, or the first turn. */
+    private topTurn;
+    /**
+     * Moves focus to turn `at`, drawing it first where the transcript is
+     * windowed and it is not drawn.
+     *
+     * **A turn takes focus only once a reader moves to it**, so the
+     * `tabindex="-1"` a turn written as a child needs is written then, long
+     * after any server's markup has hydrated, and never on a turn nobody moved
+     * to.
+     */
+    private focusTurn;
+    /** The first control in the regions `names` holds, in their order. */
+    private firstControlIn;
+    /**
+     * Page Down and Page Up move between turns, and Control with End or Home
+     * leaves the transcript, the keys the APG's feed answers.
+     */
+    private readonly handleKeydown;
     private readonly handleSlotChange;
     private readonly handleSettle;
     /**
@@ -513,6 +554,11 @@ export declare class HelixHeadlessChat extends HelixHeadlessChat_base {
     private readonly handleScroll;
     /** The turns fed as data, a window of them, between the room the rest would take. */
     private renderTurns;
+    /**
+     * The `resume` slot, with the way back drawn where nothing is slotted, behind a seam:
+     * the slot answers a page, and this answers the tier above.
+     */
+    protected renderResume(): TemplateResult;
     protected render(): TemplateResult;
 }
 declare global {