@fusion.dev/helix-headless 0.165.0 → 0.167.0

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

@@ -1,5 +1,5 @@
-import { HelixElement } from '@fusion.dev/helix-core';
-import { type PropertyValues, type TemplateResult } from 'lit';
+import { type HelixDismissEvent, HelixElement } from '@fusion.dev/helix-core';
+import { type CSSResultGroup, type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessCallout_base: (new (...args: any[]) => import("@fusion.dev/helix-core").DismissibleElement) & typeof HelixElement;
 /**
  * @summary A passage set apart as a note, information, a warning, or an error.
@@ -52,6 +52,7 @@ declare const HelixHeadlessCallout_base: (new (...args: any[]) => import("@fusio
  * @cssstate has-icon - An icon of your own is slotted into `icon`, in place of the tone's.
  */
 export declare class HelixHeadlessCallout extends HelixHeadlessCallout_base {
+    static styles: CSSResultGroup;
     /**
      * The key this family's words are registered under, its styled tag:
      * `registerWords('de', { 'helix-callout': { toneLabels: { danger: 'Fehler' } } })`.
@@ -141,6 +142,11 @@ export declare class HelixHeadlessCallout extends HelixHeadlessCallout_base {
      * heading.
      */
     private dismissName;
+    /**
+     * The event a dismissal sends, naming the note by its heading where it has
+     * one, the words its dismiss button is named by, and otherwise by its text.
+     */
+    protected dismissEvent(): HelixDismissEvent;
     protected firstUpdated(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
     /**

package/dist/callout/root/callout-root.js

@@ -5,7 +5,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { animationsSettled, customElement, drawDismiss, drawDismissGlyph, formatWords, HelixElement, hostAria, MixinDismissible, slottedWords, TONE_MARKS, toneMark, words, wordsConverter, } from '@fusion.dev/helix-core';
-import { html, nothing } from 'lit';
+import { css, html, nothing, } from 'lit';
 import { property } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
 let HelixHeadlessCallout = class HelixHeadlessCallout extends MixinDismissible(HelixElement) {
@@ -32,6 +32,11 @@ let HelixHeadlessCallout = class HelixHeadlessCallout extends MixinDismissible(H
             this.toggleState('has-icon', filled('icon'));
         };
     }
+    static { this.styles = css `
+    :host {
+      display: block;
+    }
+  `; }
     static { this.words = 'helix-callout'; }
     get present() {
         return this.isConnected && !this.hasAttribute('hidden');
@@ -66,6 +71,14 @@ let HelixHeadlessCallout = class HelixHeadlessCallout extends MixinDismissible(H
             ? formatWords(this, 'dismissLabel', { label: heading || tone }).trim()
             : this.dismissLabel;
     }
+    dismissEvent() {
+        const event = super.dismissEvent();
+        const heading = slottedWords(this, ['heading']);
+        if (heading) {
+            event.detail.label = heading;
+        }
+        return event;
+    }
     firstUpdated(changed) {
         super.firstUpdated(changed);
         this.finishHydration();

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