@fusion.dev/helix-headless 0.166.0 → 0.168.0

package/dist/canvas/arrange.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Where `arrange()` puts every card: the arithmetic, kept apart from the board
+ * that moves them there.
+ */
+import { type CanvasEdge, type CanvasNode } from './root/canvas-document.js';
+/** How a board is arranged. */
+export interface CanvasArrangeOptions {
+    /**
+     * Which way the arrows run: `down` puts each card below the cards that point
+     * to it, and `right` beside them. `down` by default.
+     */
+    direction?: 'down' | 'right';
+    /** The space between two cards, in the document's own units. 64 by default. */
+    gap?: number;
+}
+/**
+ * Where each card goes, by id, so that no two cards overlap.
+ *
+ * **Layers where there are connections.** A card goes one layer past the
+ * furthest card that points to it, a connection that would close a loop is
+ * read as pointing back, and the cards in each layer are ordered by where
+ * the cards they connect to sit, so connections cross less. **A grid where
+ * there are none**, in reading order, about as many columns as rows.
+ *
+ * A group is placed as one box and carries the cards inside it, so a card
+ * stays in its group. What is arranged starts where the board's top left
+ * corner was, and every place lands on a multiple of `snap` where it is set.
+ */
+export declare const arrangement: (nodes: readonly CanvasNode[], edges: readonly CanvasEdge[], options?: CanvasArrangeOptions, snap?: number) => Map<string, {
+    x: number;
+    y: number;
+}>;

package/dist/canvas/arrange.js

@@ -0,0 +1,144 @@
+import { groupOf, reading } from './root/canvas-document.js';
+import { snapTo } from './snap.js';
+export const arrangement = (nodes, edges, options = {}, snap) => {
+    const gap = Math.max(0, options.gap ?? 64, snap ?? 0);
+    const across = options.direction === 'right';
+    const groups = nodes.filter((node) => node.type === 'group');
+    const top = (node) => {
+        const seen = new Set([node]);
+        let at = node;
+        for (let held = groupOf(at, groups); held && !seen.has(held); held = groupOf(at, groups)) {
+            seen.add(held);
+            at = held;
+        }
+        return at;
+    };
+    const holder = new Map(nodes.map((node) => [node.id, top(node)]));
+    const units = reading([...nodes], [], 'spatial').filter((node) => holder.get(node.id) === node);
+    const order = new Map(units.map((unit, index) => [unit.id, index]));
+    const into = new Map();
+    const out = new Map();
+    for (const edge of edges) {
+        const from = holder.get(edge.fromNode)?.id;
+        const to = holder.get(edge.toNode)?.id;
+        if (from !== undefined && to !== undefined && from !== to) {
+            out.set(from, (out.get(from) ?? new Set()).add(to));
+            into.set(to, (into.get(to) ?? new Set()).add(from));
+        }
+    }
+    const layer = new Map();
+    if (out.size === 0) {
+        const columns = Math.ceil(Math.sqrt(units.length));
+        for (const [index, unit] of units.entries()) {
+            layer.set(unit.id, Math.floor(index / Math.max(columns, 1)));
+        }
+    }
+    else {
+        const done = new Set();
+        const open = new Set();
+        const back = new Set();
+        const visit = (id) => {
+            open.add(id);
+            for (const next of out.get(id) ?? []) {
+                if (open.has(next)) {
+                    back.add(`${id}>${next}`);
+                }
+                else if (!done.has(next)) {
+                    visit(next);
+                }
+            }
+            open.delete(id);
+            done.add(id);
+        };
+        for (const unit of units) {
+            if (!done.has(unit.id) && !into.get(unit.id)?.size) {
+                visit(unit.id);
+            }
+        }
+        for (const unit of units) {
+            if (!done.has(unit.id)) {
+                visit(unit.id);
+            }
+        }
+        const depth = (id, seen) => {
+            const known = layer.get(id);
+            if (known !== undefined) {
+                return known;
+            }
+            seen.add(id);
+            let deepest = 0;
+            for (const from of into.get(id) ?? []) {
+                if (!back.has(`${from}>${id}`) && !seen.has(from)) {
+                    deepest = Math.max(deepest, depth(from, seen) + 1);
+                }
+            }
+            layer.set(id, deepest);
+            return deepest;
+        };
+        for (const unit of units) {
+            depth(unit.id, new Set());
+        }
+    }
+    const layers = [];
+    for (const unit of units) {
+        const at = layer.get(unit.id) ?? 0;
+        layers[at] = [...(layers[at] ?? []), unit];
+    }
+    if (out.size > 0) {
+        const place = new Map();
+        const settle = (row, near) => {
+            const mean = (unit) => {
+                const known = [...(near.get(unit.id) ?? [])].filter((id) => place.has(id));
+                return known.length === 0
+                    ? (order.get(unit.id) ?? 0) / Math.max(units.length, 1)
+                    : known.reduce((sum, id) => sum + (place.get(id) ?? 0), 0) / known.length;
+            };
+            const means = new Map(row.map((unit) => [unit.id, mean(unit)]));
+            row.sort((a, b) => (means.get(a.id) ?? 0) - (means.get(b.id) ?? 0));
+            for (const [index, unit] of row.entries()) {
+                place.set(unit.id, (index + 0.5) / row.length);
+            }
+        };
+        for (const row of layers) {
+            settle(row ?? [], into);
+        }
+        for (const row of [...layers].reverse()) {
+            settle(row ?? [], out);
+        }
+    }
+    const main = (node) => (across ? node.width : node.height);
+    const cross = (node) => (across ? node.height : node.width);
+    const span = (row) => row.reduce((sum, unit) => sum + cross(unit), 0) + gap * Math.max(row.length - 1, 0);
+    const widest = Math.max(0, ...layers.map((row) => span(row ?? [])));
+    const start = {
+        x: Math.min(...units.map((unit) => unit.x)),
+        y: Math.min(...units.map((unit) => unit.y)),
+    };
+    const moved = new Map();
+    let along = 0;
+    for (const row of layers) {
+        if (!row) {
+            continue;
+        }
+        let at = out.size === 0 ? 0 : (widest - span(row)) / 2;
+        for (const unit of row) {
+            const x = snapTo(start.x + (across ? along : at), snap);
+            const y = snapTo(start.y + (across ? at : along), snap);
+            const dx = x - unit.x;
+            const dy = y - unit.y;
+            for (const node of nodes) {
+                if (holder.get(node.id) === unit) {
+                    moved.set(node.id, { x: node.x + dx, y: node.y + dy });
+                }
+            }
+            at += cross(unit) + gap;
+        }
+        along += Math.max(...row.map(main)) + gap;
+    }
+    for (const node of nodes) {
+        if (!moved.has(node.id)) {
+            moved.set(node.id, { x: node.x, y: node.y });
+        }
+    }
+    return moved;
+};

package/dist/canvas/paste.d.ts

@@ -0,0 +1,25 @@
+/**
+ * What a paste adds to a board: the arithmetic, kept apart from the board that
+ * adds it.
+ */
+import type { CanvasDocument, CanvasNode } from './root/canvas-document.js';
+/**
+ * A JSON Canvas document read from pasted text, or nothing where the text is
+ * not one: any text that does not parse, or a node without an id, a type and
+ * a box. An edge whose ends are not both among the nodes is left out.
+ */
+export declare const parseCanvas: (text: string) => CanvasDocument | undefined;
+/**
+ * The document a paste adds to a board that already holds `nodes` and the
+ * connections named in `taken`.
+ *
+ * **Every id is made new where the board has it**, by a count after it, and
+ * the connections follow their cards to the new ids. **The cards move clear
+ * of what they were copied from**: a step down and to the right, and another
+ * while any pasted card would still sit where a card already is, so a second
+ * paste lands beside the first. Cards from another board, where nothing sits,
+ * stay where they were.
+ *
+ * @param step How far each move is, in the document's own units.
+ */
+export declare const pasteInto: (document: CanvasDocument, nodes: readonly CanvasNode[], taken: ReadonlySet<string>, step: number) => CanvasDocument;

package/dist/canvas/paste.js

@@ -0,0 +1,58 @@
+const finite = (value) => typeof value === 'number' && Number.isFinite(value);
+export const parseCanvas = (text) => {
+    let read;
+    try {
+        read = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    const { edges, nodes } = (read ?? {});
+    if (!Array.isArray(nodes) || nodes.length === 0) {
+        return undefined;
+    }
+    const valid = nodes.every((node) => typeof node?.id === 'string' &&
+        typeof node.type === 'string' &&
+        [node.x, node.y, node.width, node.height].every(finite));
+    if (!valid) {
+        return undefined;
+    }
+    const ids = new Set(nodes.map((node) => node.id));
+    return {
+        edges: (Array.isArray(edges) ? edges : []).filter((edge) => ids.has(edge?.fromNode) && ids.has(edge?.toNode)),
+        nodes: nodes,
+    };
+};
+export const pasteInto = (document, nodes, taken, step) => {
+    const used = new Set([...taken, ...nodes.map((node) => node.id)]);
+    const unique = (id) => {
+        let next = id;
+        for (let count = 2; used.has(next); count++) {
+            next = `${id}-${count}`;
+        }
+        used.add(next);
+        return next;
+    };
+    const corners = new Set(nodes.map((node) => `${Math.round(node.x)},${Math.round(node.y)}`));
+    const pasted = document.nodes ?? [];
+    let by = 0;
+    while (step > 0 &&
+        pasted.some((node) => corners.has(`${Math.round(node.x + by)},${Math.round(node.y + by)}`))) {
+        by += step;
+    }
+    const renamed = new Map();
+    const out = pasted.map((node) => {
+        const id = unique(node.id);
+        renamed.set(node.id, id);
+        return { ...node, id, x: node.x + by, y: node.y + by };
+    });
+    return {
+        edges: (document.edges ?? []).map((edge) => ({
+            ...edge,
+            fromNode: renamed.get(edge.fromNode) ?? edge.fromNode,
+            id: unique(edge.id || `${edge.fromNode}-${edge.toNode}`),
+            toNode: renamed.get(edge.toNode) ?? edge.toNode,
+        })),
+        nodes: out,
+    };
+};

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

@@ -1,6 +1,8 @@
 import { type CanvasView, HelixElement, type ViewportPanDetail, type ViewportWay, type ViewportZoomDetail } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
+import { type CanvasArrangeOptions } from '../arrange.js';
 import { type CanvasDocument, type CanvasRoute, type CanvasTone } from './canvas-document.js';
+export type { CanvasArrangeOptions } from '../arrange.js';
 export type { CanvasDocument, CanvasEdge, CanvasEdgeProps, CanvasEnd, CanvasNode, CanvasNodeProps, CanvasPath, CanvasRoute, CanvasRouteEnds, CanvasSide, CanvasTone, } from './canvas-document.js';
 export { fromJsonCanvas } from './canvas-document.js';
 declare const HelixHeadlessCanvas_base: (new (...args: any[]) => import("@fusion.dev/helix-core").ViewportElement) & typeof HelixElement;
@@ -60,15 +62,24 @@ declare const HelixHeadlessCanvas_base: (new (...args: any[]) => import("@fusion
  *   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.
+ *   an app that reads the format takes.
+ * - Control or Command with V pastes a JSON Canvas document: the board adds
+ *   its cards and connections, a step down and to the right of any card they
+ *   would sit on, and selects them. It asks with `helix-before-paste` first.
+ *   A page that renders its cards from its own state cancels it and adds the
+ *   detail's document to that state, through `fromJsonCanvas`. `paste()` does
+ *   the same from a script.
  * - 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.
  *
+ * **`arrange()` moves every card so that none overlaps another**, in layers
+ * that follow the arrows, or in a grid on a board with no connections. The
+ * cards glide for as long as the board's own transition, and `undo()` puts
+ * them back.
+ *
  * 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.
@@ -129,6 +140,7 @@ declare const HelixHeadlessCanvas_base: (new (...args: any[]) => import("@fusion
  * @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 {HelixBeforePasteEvent} helix-before-paste - Cards and connections are about to be pasted. Cancelable: cancel it to add the detail's document to 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.
  * @event {HelixBeforeRelabelEvent} helix-before-relabel - A connection's label or a group's name is about to change. Cancelable: cancel it to keep labels in your own state.
  * @event {HelixCanvasEditEvent} helix-canvas-edit - A card was double-clicked, or Enter or F2 was pressed on it. Open your own editor for the card.
@@ -137,6 +149,7 @@ declare const HelixHeadlessCanvas_base: (new (...args: any[]) => import("@fusion
  * @event {HelixCanvasZoomEvent} helix-canvas-zoom - The board zoomed one step, from its controls or the keys. A wheel or a pinch sends `helix-canvas-view`.
  * @event {HelixConnectEvent} helix-connect - Two cards were chosen to be joined. Add a `helix-canvas-edge` to join them.
  * @event {HelixMoveEvent} helix-move - Cards moved and the move is finished: a drag was released, a click put a card down, or a key was pressed.
+ * @event {HelixPastedEvent} helix-pasted - Cards and connections were pasted, and the board holds them.
  * @event {HelixReconnectEvent} helix-reconnect - A connection's end moved, and the move is finished.
  * @event {HelixRelabelEvent} helix-relabel - A connection's label or a group's name changed.
  * @event {HelixRemoveEvent} helix-remove - Cards or connections were chosen for removal. Remove the elements it names.
@@ -198,6 +211,8 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
      * `gestures="activate"`, is scrolled or swiped over.
      */
     activateHintLabel: string;
+    /** What screen readers hear after `arrange()` moves the cards. */
+    arrangedLabel: 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}`. */
@@ -282,6 +297,8 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
      * that reflected would write a choice onto every host that no server sent.
      */
     order?: 'spatial' | 'edges';
+    /** What screen readers hear after a paste, with `{count}` for the cards pasted. */
+    pastedLabel: string;
     /**
      * The route every connection takes when it sets no `path` of its own:
      * `straight`, or `step` for right angles.
@@ -308,6 +325,12 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
     reconnectingLabel: string;
     /** What screen readers hear after a move or a resize is made again. */
     redoneLabel: string;
+    /**
+     * What screen readers hear when Delete asks to remove what is selected, with
+     * `{count}` for how many cards and connections, and `{name}` for the one
+     * where there is one.
+     */
+    removedLabel: 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
@@ -846,6 +869,40 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
      * holds, nor over text a reader selected, which are the platform's to copy.
      */
     private readonly handleCopy;
+    /**
+     * A paste on the board of a JSON Canvas document, the text a copy writes,
+     * adds its cards and connections. Not into a field a card holds, nor onto a
+     * `readonly` board, nor text that is not a board, which are the platform's.
+     */
+    private readonly handlePaste;
+    /**
+     * Adds the cards and connections of a JSON Canvas document, as a paste does,
+     * and selects the cards. Ids the board already holds are given a count after
+     * them, and the cards move a step down and to the right while they would sit
+     * on cards already there.
+     *
+     * Asks with `helix-before-paste` first: cancel it to add the detail's
+     * document to your own state. Returns whether the board added the cards:
+     * false on a `readonly` board, for text that is not a board, or when the
+     * request was refused.
+     */
+    paste(document: CanvasDocument | string): boolean;
+    /** The glide `arrange()` started, while it runs. */
+    private gliding;
+    /** Ends a glide where it was going. */
+    private settle;
+    /**
+     * Moves the cards so that none overlaps another: in layers that follow the
+     * connections, or in a grid where there are none. A group moves as one box
+     * with its cards. Each place lands on a multiple of `snap` where it is set.
+     *
+     * Asks with `helix-before-move` first and tells with `helix-move`, as a
+     * move does, so `undo()` puts every card back. The cards glide to their
+     * places for as long as the board's plane takes to glide, and land at once
+     * where it does not, such as under `prefers-reduced-motion`. Returns whether
+     * the cards moved.
+     */
+    arrange(options?: CanvasArrangeOptions): boolean;
     /**
      * 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

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

@@ -4,16 +4,18 @@ 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 { assignSlots, auditName, capturePointer, customElement, formatPercent, formatWords, HelixBeforeMoveEvent, HelixBeforeReconnectEvent, HelixBeforeRelabelEvent, HelixCanvasEditEvent, HelixCanvasPanEvent, HelixCanvasViewEvent, HelixCanvasZoomEvent, HelixConnectEvent, HelixElement, HelixMoveEvent, HelixReconnectEvent, HelixRelabelEvent, HelixRemoveEvent, HelixSelectEvent, hostAria, inlineStep, isRtl, MixinViewport, words, wordsConverter, wordsLocale, } from '@fusion.dev/helix-core';
+import { assignSlots, auditName, capturePointer, customElement, formatPercent, formatWords, HelixBeforeMoveEvent, HelixBeforePasteEvent, HelixBeforeReconnectEvent, HelixBeforeRelabelEvent, HelixCanvasEditEvent, HelixCanvasPanEvent, HelixCanvasViewEvent, HelixCanvasZoomEvent, HelixConnectEvent, HelixElement, HelixMoveEvent, HelixPastedEvent, HelixReconnectEvent, HelixRelabelEvent, HelixRemoveEvent, HelixSelectEvent, hostAria, inlineStep, isRtl, MixinViewport, words, wordsConverter, wordsLocale, } from '@fusion.dev/helix-core';
 import { html, nothing, svg } from 'lit';
 import { property, state } from 'lit/decorators.js';
+import { arrangement } from '../arrange.js';
 import { descriptionOf } from '../describe.js';
 import { HelixHeadlessCanvasEdge } from '../edge/canvas-edge.js';
 import { EdgePan } from '../edge-pan.js';
 import { neighborOf } from '../neighbor.js';
 import { HelixHeadlessCanvasNode } from '../node/canvas-node.js';
+import { parseCanvas, pasteInto } from '../paste.js';
 import { snapBox, snapTo, stepTo } from '../snap.js';
-import { colorOf, connector, distanceTo, ends, extent, inside, port, reading, sideNear, } from './canvas-document.js';
+import { colorOf, connector, distanceTo, ends, extent, fromJsonCanvas, inside, port, reading, sideNear, } from './canvas-document.js';
 export { fromJsonCanvas } from './canvas-document.js';
 const MARGIN = 32;
 const ARROW = 'canvas-arrow';
@@ -43,6 +45,7 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
     constructor() {
         super(...arguments);
         this.activateHintLabel = 'Press the board to use it';
+        this.arrangedLabel = 'Cards arranged';
         this.comesFromLabel = 'from {cards}';
         this.connectedLabel = 'Asked to connect {from} to {to}.';
         this.connectingLabel = 'Connecting from {from}. Move to another card and press Enter, or Escape to stop.';
@@ -55,9 +58,11 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
         this.leadsToLabel = 'leads to {cards}';
         this.linkedLabel = '{leadsTo}; {comesFrom}';
         this.movedLabel = '{name} moved to {x}, {y}';
+        this.pastedLabel = '{count, plural, one {# card pasted} other {# cards pasted}}';
         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.removedLabel = '{count, plural, one {Asked to remove {name}.} other {Asked to remove # items.}}';
         this.resizedLabel = '{name} resized to {width} by {height}';
         this.roleLabel = 'canvas';
         this.selected = '';
@@ -106,6 +111,15 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
             event.preventDefault();
             this.say(formatWords(this, 'copiedLabel', { count: copy.nodes?.length ?? 0 }));
         };
+        this.handlePaste = (event) => {
+            const origin = event.composedPath()[0];
+            if (event.defaultPrevented || origin?.closest?.(INTERACTIVE)) {
+                return;
+            }
+            if (this.paste(event.clipboardData?.getData('text/plain') ?? '')) {
+                event.preventDefault();
+            }
+        };
         this.handleHistoryKey = (event) => {
             if (event.defaultPrevented || event.altKey || !(event.ctrlKey || event.metaKey)) {
                 return;
@@ -129,6 +143,7 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
             }
         });
         this.handlePointerDown = (event) => {
+            this.settle();
             if (!this.gestureAllowed(event)) {
                 return;
             }
@@ -494,6 +509,7 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
             }
         };
         this.handleStopKeydown = (event) => {
+            this.settle();
             const origin = event.composedPath()[0];
             const edge = this.edgeOf(event);
             const card = edge === undefined ? this.cardOf(event) : undefined;
@@ -1122,6 +1138,19 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
         const at = Math.min(...asked.map((one) => walk.findIndex((stop) => stop.key === one)));
         const next = neighborOf(walk.map((one) => one.key), at, (key) => !gone.has(key));
         this.refocus = { gone: [...gone], next };
+        const only = asked[0];
+        const edge = only?.startsWith('edge:')
+            ? edges.find((one) => this.keyOf(one) === only)
+            : undefined;
+        this.say(formatWords(this, 'removedLabel', {
+            count: asked.length,
+            name: edge
+                ? formatWords(this, 'connectionLabel', {
+                    from: this.nameOf(edge.fromNode),
+                    to: this.nameOf(edge.toNode),
+                })
+                : this.nameOf(only ?? ''),
+        }));
         this.dispatchEvent(new HelixRemoveEvent(detail));
     }
     clicked(key, event) {
@@ -1290,6 +1319,7 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
         return name === undefined ? undefined : this.byName.get(name);
     }
     requestMove(detail) {
+        this.settle();
         if (!this.dispatchEvent(new HelixBeforeMoveEvent(detail))) {
             return false;
         }
@@ -1359,6 +1389,125 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
         this.say(words);
         return true;
     }
+    paste(document) {
+        const read = typeof document === 'string' ? parseCanvas(document) : document;
+        if (this.readOnly || !read?.nodes?.length) {
+            return false;
+        }
+        const taken = new Set(this.edgeElements.map((one) => one.name).filter(Boolean));
+        const placed = pasteInto(read, this.nodes, taken, (this.snap ?? 0) > 0 ? this.snap : NUDGE * 2);
+        if (!this.dispatchEvent(new HelixBeforePasteEvent({ document: placed }))) {
+            return false;
+        }
+        const tier = this.constructor.tier;
+        const add = (name, attributes, color, text = '') => {
+            const element = this.ownerDocument.createElement(`${tier}${name}`);
+            for (const [key, value] of Object.entries(attributes)) {
+                if (value !== undefined && value !== false && value !== '') {
+                    element.setAttribute(key, value === true ? '' : String(value));
+                }
+            }
+            if (color) {
+                element.style.setProperty(`--${name}-color`, color);
+            }
+            element.textContent = text;
+            this.append(element);
+        };
+        const { edges, nodes } = fromJsonCanvas(placed);
+        for (const one of nodes) {
+            const { color, group, height, label, name, text, tone, width, x, y } = one;
+            add('canvas-node', { group, height, label, name, tone, width, x, y }, color, text ?? one.url ?? one.file);
+        }
+        for (const one of edges) {
+            add('canvas-edge', {
+                from: one.from,
+                'from-end': one.fromEnd,
+                'from-side': one.fromSide,
+                label: one.label,
+                name: one.name,
+                to: one.to,
+                'to-end': one.toEnd,
+                'to-side': one.toSide,
+                tone: one.tone,
+            }, one.color);
+        }
+        this.requestUpdate();
+        this.choose(nodes.map((one) => one.name));
+        this.say(formatWords(this, 'pastedLabel', { count: nodes.length }));
+        this.dispatchEvent(new HelixPastedEvent({ document: placed }));
+        return true;
+    }
+    settle() {
+        const glide = this.gliding;
+        if (!glide) {
+            return;
+        }
+        cancelAnimationFrame(glide.frame);
+        this.gliding = undefined;
+        for (const { name, x, y } of glide.to) {
+            const card = this.byName.get(name);
+            if (card) {
+                card.x = x;
+                card.y = y;
+            }
+        }
+        this.requestUpdate();
+    }
+    arrange(options = {}) {
+        this.settle();
+        const places = arrangement(this.nodes, this.edges, options, this.snap);
+        const from = new Map(this.cards.map((card) => [card.name, { x: card.x, y: card.y }]));
+        const detail = {
+            nodes: [...places]
+                .filter(([name, at]) => from.get(name)?.x !== at.x || from.get(name)?.y !== at.y)
+                .map(([name, at]) => ({ name, ...at })),
+        };
+        if (this.readOnly || detail.nodes.length === 0 || !this.requestMove(detail)) {
+            return false;
+        }
+        this.finishMove(detail);
+        this.say(this.arrangedLabel);
+        const board = this.partNamed('board');
+        let time = 0;
+        if (board && !globalThis.matchMedia?.('(prefers-reduced-motion: reduce)').matches) {
+            this.toggleState('direct', false);
+            time = Number.parseFloat(getComputedStyle(board).transitionDuration) * 1000;
+            this.toggleState('direct', this.direct);
+        }
+        if (!(time > 0) || typeof requestAnimationFrame === 'undefined') {
+            return true;
+        }
+        for (const { name } of detail.nodes) {
+            const card = this.byName.get(name);
+            const start = from.get(name);
+            if (card && start) {
+                card.x = start.x;
+                card.y = start.y;
+            }
+        }
+        const begun = performance.now();
+        const step = (now) => {
+            const t = Math.min(1, (now - begun) / time);
+            const eased = t < 0.5 ? 4 * t ** 3 : 1 - (-2 * t + 2) ** 3 / 2;
+            for (const { name, x, y } of detail.nodes) {
+                const card = this.byName.get(name);
+                const start = from.get(name);
+                if (card && start) {
+                    card.x = start.x + (x - start.x) * eased;
+                    card.y = start.y + (y - start.y) * eased;
+                }
+            }
+            this.requestUpdate();
+            if (t < 1 && this.gliding) {
+                this.gliding.frame = requestAnimationFrame(step);
+            }
+            else {
+                this.gliding = undefined;
+            }
+        };
+        this.gliding = { frame: requestAnimationFrame(step), to: detail.nodes };
+        return true;
+    }
     panCarrying(by) {
         const last = this.carryPointer;
         if (!last) {
@@ -1925,6 +2074,7 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
         this.addEventListener('keydown', this.handleStopKeydown);
         this.addEventListener('keydown', this.handleHistoryKey);
         this.addEventListener('copy', this.handleCopy);
+        this.addEventListener('paste', this.handlePaste);
         this.addEventListener('pointercancel', this.handlePointerUp);
         this.addEventListener('pointerdown', this.handlePointerDown);
         this.addEventListener('pointermove', this.handlePointerMove);
@@ -1947,6 +2097,8 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
         this.removeEventListener('keydown', this.handleStopKeydown);
         this.removeEventListener('keydown', this.handleHistoryKey);
         this.removeEventListener('copy', this.handleCopy);
+        this.removeEventListener('paste', this.handlePaste);
+        this.settle();
         this.removeEventListener('pointercancel', this.handlePointerUp);
         this.removeEventListener('pointerdown', this.handlePointerDown);
         this.removeEventListener('pointermove', this.handlePointerMove);
@@ -2323,6 +2475,10 @@ __decorate([
     words,
     property({ attribute: 'activate-hint-label' })
 ], HelixHeadlessCanvas.prototype, "activateHintLabel", void 0);
+__decorate([
+    words,
+    property({ attribute: 'arranged-label' })
+], HelixHeadlessCanvas.prototype, "arrangedLabel", void 0);
 __decorate([
     words,
     property({ attribute: 'comes-from-label' })
@@ -2376,6 +2532,10 @@ __decorate([
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessCanvas.prototype, "order", void 0);
+__decorate([
+    words,
+    property({ attribute: 'pasted-label' })
+], HelixHeadlessCanvas.prototype, "pastedLabel", void 0);
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessCanvas.prototype, "path", void 0);
@@ -2390,6 +2550,10 @@ __decorate([
     words,
     property({ attribute: 'redone-label' })
 ], HelixHeadlessCanvas.prototype, "redoneLabel", void 0);
+__decorate([
+    words,
+    property({ attribute: 'removed-label' })
+], HelixHeadlessCanvas.prototype, "removedLabel", void 0);
 __decorate([
     words,
     property({ attribute: 'resized-label' })

package/dist/chat/composer/chat-composer.js

@@ -120,7 +120,11 @@ let HelixHeadlessChatComposer = class HelixHeadlessChatComposer extends HelixFor
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
-        this.addEventListener('invalid', this.touch);
+        this.addEventListener('invalid', () => {
+            if (!this.checkingValidity) {
+                this.touch();
+            }
+        });
     }
     willUpdate(changed) {
         super.willUpdate(changed);