@fusion.dev/helix-headless 0.103.2 → 0.104.0

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

@@ -0,0 +1,912 @@
+import { type CanvasView, HelixElement, type ViewportPanDetail, type ViewportWay, type ViewportZoomDetail } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+import { type CanvasDocument } from './canvas-document.js';
+export type { CanvasDocument, CanvasEdge, CanvasEdgeProps, CanvasEnd, CanvasNode, CanvasNodeProps, CanvasPath, 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;
+/**
+ * @summary A board of cards and the connections between them, which a reader can walk, rearrange and connect.
+ *
+ * @description
+ * **The first of these surfaces Helix draws itself**, and the reason is where
+ * the positions come from. On a canvas **position is data**: somebody placed
+ * every card and the placement carries the meaning, so there is no layout to
+ * compute and drawing is arithmetic over rectangles. A map is somebody else's
+ * tiles and a graph view's positions are computed, which is why `Map` takes a
+ * slotted map and this takes a document.
+ *
+ * **The format is open.** [JSON Canvas](https://jsoncanvas.org) gives each node
+ * an `x`, `y`, `width`, `height` and a type, and each edge the two nodes it
+ * joins and the sides it leaves and arrives on. A card belongs to a group when
+ * it sits inside the group's bounds, which the format leaves to the geometry.
+ *
+ * **Accessibility is the design work, not the drawing.** The cards are text in
+ * the DOM, so they are readable already; what space does not supply is an order
+ * and the connections. So the family chooses an order, walks the cards in it,
+ * and says every card's links as text. `order` takes `spatial`, which bands the
+ * cards into rows, and `edges`, which follows the arrows from the cards nothing
+ * points to.
+ *
+ * **Cards move by default, the way a form control takes input by default.**
+ * The board writes the new `x` and `y` onto the card itself, as an input writes
+ * its own value, and says so twice: `helix-before-move` for every step, which a
+ * consumer holding the positions in their own state refuses and applies
+ * themselves, and `helix-move` once the move is finished. A resize is the same
+ * pair with a size in it. `readonly` keeps every card where it is, for a board
+ * that is published rather than worked on, and `readonly` on one card or
+ * connection keeps that one.
+ *
+ * **The cards are the way around it.** One of them holds the board's tab stop,
+ * arrow keys walk them in reading order, and the one a reader lands on is
+ * brought into view with what it connects to read out beside it. Shift with an
+ * arrow moves it, which is the keyboard's way to do what a drag does. The
+ * connections leaving a card are stops of their own, straight after it, and
+ * Enter on one goes to the card it arrives at.
+ *
+ * **Every drag can be done with clicks instead**, which WCAG 2.5.7 asks of a
+ * pointer that cannot hold a button down. A click on a selected card's move
+ * handle, a corner, a card's connection point or the end of a selected
+ * connection picks the thing up; it follows the pointer with no button held,
+ * and the next click puts it down wherever a drag let go there would have. On
+ * touch, the next tap is where it lands. Escape, or a press off the board,
+ * puts it back.
+ *
+ * **Connecting and removing are requests, and the page acts on them.** Drawing
+ * from a card's handle to another card, or pressing C on one and Enter on
+ * another, sends `helix-connect`; Delete on a card or a connection sends
+ * `helix-remove`, naming every connection a removed card would strand. A move
+ * can be applied by the board because the card is already there. A connection
+ * is a new element, and one a board added to markup React renders would be
+ * thrown away on the next render, so the board asks and the page writes it.
+ *
+ * **Markup rather than a `src` or a document property.** Nothing in this
+ * library fetches, and an array handed to an element is missing from the first
+ * paint of every server-rendered React page. The cards and connections are
+ * `helix-canvas-node` and `helix-canvas-edge` elements, in the served markup
+ * whichever renderer wrote them; `fromJsonCanvas` turns a JSON Canvas document
+ * into their props and `toJsonCanvas()` writes a board back out.
+ *
+ * @since 0.100.0
+ * @status experimental
+ * @category media
+ * @aliases Board, JSON Canvas, Whiteboard
+ * @documentation https://fusion.dev/helix/components/canvas
+ *
+ * @slot empty - What to show where the document has no nodes.
+ * @slot footer - Chrome below the board.
+ * @slot header - Chrome above the board.
+ *
+ * @event {HelixBeforeMoveEvent} helix-before-move - Cards are about to move. Refuse 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. Refuse 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. Refuse it to keep labels in your own state.
+ * @event {HelixCanvasEditEvent} helix-canvas-edit - The reader asked to edit a card: a double-click, or Enter or F2. Open your own editor for it.
+ * @event {HelixCanvasPanEvent} helix-canvas-pan - The board was moved a step, by its controls or the arrow keys: a fact rather than a request. A drag says so through `helix-canvas-view`.
+ * @event {HelixCanvasViewEvent} helix-canvas-view - Where the board is looking changed, however it changed. The detail is the new view.
+ * @event {HelixCanvasZoomEvent} helix-canvas-zoom - The board zoomed a step, by its controls or the keys. A wheel or a pinch says so through `helix-canvas-view`.
+ * @event {HelixConnectEvent} helix-connect - A reader asked for two cards to be joined. Add the `helix-canvas-edge` to do it.
+ * @event {HelixMoveEvent} helix-move - Cards moved and the move is finished: a drag let go, a click that put a card down, or a key pressed.
+ * @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 - A reader asked for cards or connections to go. Remove the elements it names.
+ * @event {HelixSelectEvent} helix-select - The selection changed. The detail's `value` is the names, comma separated, empty for none. Cancelable: refusing it keeps the selection where it was.
+ *
+ * @csspart arrow - The head an edge carries at an end that has one.
+ * @csspart board - The plane the cards are placed on, which is what pans and zooms.
+ * @csspart controls - The group the pan and zoom buttons sit in.
+ * @csspart draft - The connection being drawn, before it is asked for.
+ * @csspart edge - One connector between two cards.
+ * @csspart edge-end - An end of a selected connection, which a press picks up, a click as well as a drag.
+ * @csspart edge-target - The wider, unpainted line over a connector that a reader focuses and presses.
+ * @csspart edges - The layer the connectors are drawn in.
+ * @csspart footer - The strip below the board.
+ * @csspart fullscreen - The button that fills the screen.
+ * @csspart header - The strip above the board.
+ * @csspart label - The label on a connector.
+ * @csspart label-editor - The field a connection's label or a group's name is edited in, where it sits.
+ * @csspart live - What the board says while a connection is being made, for a screen reader.
+ * @csspart marquee - The box a Shift-drag across the empty board draws, which selects the cards it touches.
+ * @csspart pan-down - The button that moves the board down.
+ * @csspart pan-end - The button that moves the board the way the text ends.
+ * @csspart pan-start - The button that moves the board the way the text starts.
+ * @csspart pan-up - The button that moves the board up.
+ * @csspart region - The named region the board is drawn in.
+ * @csspart viewport - The box the board is drawn inside.
+ * @csspart zoom-in - The button that zooms in.
+ * @csspart zoom-out - The button that zooms out.
+ *
+ * @cssstate connecting - While a reader is drawing a connection.
+ * @cssstate direct - While the board moves without easing: under the reader's hand, or settling into its box.
+ * @cssstate empty - While the document has no nodes.
+ * @cssstate fullscreen - While the board fills the screen.
+ * @cssstate holding - While something a click picked up follows the pointer, until the next press puts it down.
+ * @cssstate idle - While the reader has been still long enough to hide the chrome.
+ * @cssstate pressing - While a press on the board, its cards or its connections is under way.
+ */
+export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
+    /** How a card says where its connections come from, with `{cards}`. */
+    comesFromLabel: string;
+    /** What it says when a connection is asked for, with `{from}` and `{to}`. */
+    connectedLabel: string;
+    /**
+     * What the live region says when a reader starts a connection, with `{from}`
+     * filled in.
+     *
+     * **Every sentence this board speaks is a property**, the rule the pan
+     * controls already kept with `pan-up-label` and its three: a board on a page in another
+     * language otherwise read its connections out in English.
+     */
+    connectingLabel: string;
+    /**
+     * What a connection is called, with `{from}` and `{to}`.
+     *
+     * Its own label, where it has one, is its description rather than part of
+     * this, so a reader hears the ends first and what the line says after.
+     */
+    connectionLabel: string;
+    /**
+     * Accessible name for the board, which is the one thing a consumer must write.
+     *
+     * A document has no name of its own in the format, and "Canvas" names the
+     * widget rather than the thinking on it.
+     */
+    label: string;
+    /**
+     * What the field a label is edited in is called, with `{name}` for what it
+     * labels.
+     */
+    labelEditorLabel: string;
+    /**
+     * How a card says where its connections go, with `{cards}` as the list.
+     *
+     * The list is joined the way the page's language joins one, "Second and
+     * Third", rather than with a comma this component chose.
+     */
+    leadsToLabel: string;
+    /**
+     * The order a reader meets the cards in.
+     *
+     * `spatial` bands them into rows and reads each row across, which is how a
+     * person reads a board laid out on a grid and is a heuristic a loose board
+     * defeats. `edges` follows the arrows from the cards nothing points to, which
+     * on a board that is a flow is the order its author meant.
+     *
+     * Absent is spatial, a resting value being an attribute's absence: a default
+     * that reflected would write a choice onto every host that no server sent.
+     */
+    order?: 'spatial' | 'edges';
+    /**
+     * How every connection travels, where it does not say: `straight`, or `step`
+     * for right angles.
+     *
+     * Absent is a curve. A flowchart wants `step` on all of its edges, and
+     * writing it once here rather than on each is the reason this exists; an
+     * edge's own `path` still wins.
+     */
+    path?: 'straight' | 'step';
+    /**
+     * Keeps every card where its author put it.
+     *
+     * **The attribute is `readonly`, which is the platform's spelling**, and the
+     * reverse of an `editable` switch on purpose: a form control takes input
+     * unless it is told not to, and a board a reader can rearrange is the same
+     * kind of thing. A drag on a card pans the board instead, and the keys still
+     * walk the cards.
+     */
+    readOnly: boolean;
+    /**
+     * What the live region says when a reader picks up a connection's end, with
+     * `{from}` and `{to}`.
+     */
+    reconnectingLabel: string;
+    /**
+     * The cards and connections the reader selected, by name, comma separated,
+     * and empty for none.
+     *
+     * **Comma separated, the way `Listbox` writes a multiple value**, so a page
+     * reads one selection the same way wherever it comes from. A click, or a key
+     * that lands on one, selects it alone; Shift, Command or Control with a click
+     * adds or takes one away, and so does Space; Command or Control with A
+     * selects everything; Shift and a drag across the empty board selects the
+     * cards the box touches. A click on the empty board, or Escape, selects
+     * nothing. Dragging, Shift with an arrow, and Delete act on the whole
+     * selection.
+     *
+     * **Kept apart from focus**, so it stays when focus leaves: a reader who
+     * selects cards and clicks a button beside the board to act on them has not
+     * cleared what the button acts on by clicking. A connection with no name is
+     * called by its ends, `from->to`, which is also why a name has to be unique
+     * on its board across cards and connections both, and may not hold a comma.
+     *
+     * Written to select from outside, and read to act on the selection.
+     */
+    selected: string;
+    /**
+     * A label being edited in place: whose, and what it said before.
+     */
+    private editing;
+    /** What it says when a reader stops connecting without asking. */
+    stoppedLabel: string;
+    /** The card or connection that holds the board's one tab stop, by its key. */
+    private stop;
+    /**
+     * A connection being made: the card it starts from, the side where a pointer
+     * 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. */
+    private said;
+    /**
+     * Where focus goes once something a reader removed has gone.
+     *
+     * **Held until the page acts**, because the board only asks: React removes the
+     * element on its next render rather than inside the listener, so moving focus
+     * at the moment of asking would move it off an element that is still there,
+     * or, for a page that declines, off one that stays.
+     */
+    private refocus;
+    /**
+     * Where the plane's corner was on the last render, in the document's units.
+     *
+     * **A card moved past the edge of the board moves the corner**, since the
+     * plane is sized to what it holds, and every card is placed from that corner:
+     * without holding the view against it, dragging one card left slid every
+     * other card right by the same distance.
+     */
+    private origin?;
+    /** Where the board sits, in board coordinates, and how far it is zoomed. */
+    private at;
+    /**
+     * Whether the move under way should land rather than glide: the reader's own
+     * hand, or the board settling into its box.
+     *
+     * **A drag must not be eased, and that is what made it feel like it snapped.**
+     * The plane carries a transition so a press on the pad glides rather than
+     * jumping, and a drag writes a new transform on every pointer move: each one
+     * was then animated toward the last, so the board chased the pointer a
+     * fraction behind and arrived in steps. Continuous input is direct and
+     * discrete input is eased, which is the rule a map or an editor follows.
+     */
+    private direct;
+    /**
+     * Whether the reader has moved the board, which is what stops it re-fitting.
+     *
+     * A board opens showing all of itself, and keeps doing so while the box it is
+     * drawn in settles: a list wraps to a second row, a panel opens, a container
+     * resizes. The moment a reader pans or zooms they have chosen a view, and a
+     * later resize must not take it away from them.
+     */
+    private touched;
+    /** Watches the box, because the fit is a fraction of a measurement. */
+    private sizes?;
+    /** The element the observer is on, so a render does not observe it again. */
+    private watched;
+    /**
+     * Hears what the cards and connections change that no property of theirs
+     * says: the words in a card, and a color written into an element's `style`.
+     *
+     * Both are read into what is drawn, a card's words into every connection's
+     * name and the sentence saying where it leads, and neither reaches the board
+     * otherwise: a card whose text a page rewrote was read out under its old
+     * words for the life of the board.
+     */
+    private words?;
+    /** The custom color each card and connection was last drawn in. */
+    private readonly painted;
+    /** Where each card was last written to be, so one that did not move is left alone. */
+    private readonly placed;
+    /** The box as the observer last measured it, so a resize knows what it gained. */
+    private measured?;
+    /**
+     * The box the board is drawn in, which is not the host.
+     *
+     * **The host measures nothing**: it draws no box of its own, so `clientWidth`
+     * on it is zero and every sum against it is zero too. The viewport inside the
+     * shadow root is the thing with a size, and it is what a fit, a pan step and a
+     * card brought to the middle are all fractions of.
+     */
+    private get box();
+    /**
+     * The cards, read from the light DOM.
+     *
+     * **`children` and not a slot**, which is what every family here that reads
+     * its own contents does, and it is undefined on the server: a board cannot
+     * count its cards while it is being rendered, so the plane, the connectors and
+     * the reading list are assembled on hydration and the cards themselves are in
+     * the served markup because the consumer wrote them there.
+     */
+    private get cards();
+    /** A card by its name, looked up rather than searched for. */
+    private get byName();
+    /** A card's geometry by its name. */
+    private get byId();
+    /** The groups alone, which is all a card's group is chosen from. */
+    private get groups();
+    /**
+     * What the board reads from its children, kept for the rest of the turn.
+     *
+     * **Read once rather than on every question.** A render asked for the cards,
+     * the connections and the reading order a dozen times over, and the
+     * selection asked for the reading order once per name in it: every step of a
+     * drag rebuilt all of them from the DOM that many times. Cleared when an
+     * update is asked for, which every change the board makes or hears about
+     * does, and at the end of the turn, so a question asked later reads again.
+     */
+    private cache;
+    private remember;
+    /**
+     * @internal Forgets what the board read from its children, then asks for an
+     * update as Lit does: every change the board makes or hears about asks for
+     * one, which makes this the one place the reading goes stale.
+     */
+    requestUpdate(name?: PropertyKey, oldValue?: unknown, options?: Parameters<HelixElement['requestUpdate']>[2]): void;
+    /** The same, as the shape the geometry works in. */
+    private get nodes();
+    private readNodes;
+    /** A custom color written on an element, remembered as the one drawn. */
+    private paint;
+    /** The connectors a consumer declared, which draw nothing themselves. */
+    private get edges();
+    /**
+     * The sides each connection was first drawn from and to, where it names none.
+     *
+     * **Chosen once, and kept while the cards move.** A connection that names no
+     * side takes the ones facing the other card, and that was asked on every
+     * draw: a card dragged past the diagonal between the two flipped the answer,
+     * and the connection jumped from one point to another under the reader's
+     * hand. So the first answer is remembered for as long as the connection joins
+     * the same two cards, and a side the page writes still wins. Keyed on the two
+     * cards as well as the connection, so a reconnected one chooses again.
+     */
+    private readonly sides;
+    private readEdges;
+    /** The events this family names for itself, the surface being shared. */
+    protected panEvent(detail: ViewportPanDetail): Event;
+    protected zoomEvent(detail: ViewportZoomDetail): Event;
+    protected get restingControlsLabel(): string;
+    /**
+     * Zoom and fullscreen, without the pad.
+     *
+     * A board is dragged, and its cards walked with the arrow keys, so the four
+     * pan buttons were a third way to do what two others already did, and they
+     * took a third of the frame's corner. `controls="pan zoom fullscreen"` puts
+     * them back.
+     */
+    protected get restingControls(): string;
+    /**
+     * Moves the board, and says so.
+     *
+     * **`Map` asks and this tells.** The mixin's `pan` announces a request, which
+     * is all a frame around somebody else's map can do; here the board is drawn
+     * from a document this component holds, so the same press moves it. The event
+     * still goes out, because a consumer keeping a minimap or a scroll position in
+     * step needs to hear it, and it is not cancelable for the same reason: it
+     * reports rather than asks.
+     */
+    pan(to: ViewportWay): void;
+    /**
+     * Zooms the board about the middle of the view, and says so.
+     *
+     * **The middle, not the corner, and the difference is whether zooming is
+     * usable.** The plane scales from its own origin, so leaving the offset alone
+     * grows the board away from the top-left: what a reader was looking at slides
+     * out of the box and they have to pan it back after every press. Holding the
+     * center point still is two lines of arithmetic and it is what every canvas
+     * does.
+     *
+     * Held between a tenth and eight times, which is far enough out to see a
+     * large board whole and far enough in to read what a small card holds.
+     */
+    zoom(by: number): void;
+    /**
+     * Brings a card, by name, to the middle of the viewport.
+     *
+     * What a reader landing on a card off the edge of the view gets, and what a
+     * page's own search or outline can call to take a reader to one.
+     */
+    show(name: string): void;
+    /**
+     * Whether a press on the board is under way, a drag of the board, a card or
+     * a connection, so a stylesheet can stop the press selecting text while it
+     * lasts and only then: a board that never let its text be selected also
+     * never let a page's own editor type into a card.
+     */
+    private pressing;
+    /**
+     * Whether the press under way began on a card or a connection, so the focus
+     * it moves is not also read as a keyboard landing, which selects.
+     */
+    private pointing;
+    /** A box being drawn across the empty board, in the document's units. */
+    private marquee;
+    /** A card being resized from a corner, with the box it started from. */
+    private sizing;
+    /** Where a drag started, and where the board was when it did. */
+    private dragging;
+    /**
+     * A press on a card that may become a move, with where everything it carries
+     * started. `moved` is what the last step settled on, which the drop reports.
+     */
+    private carrying;
+    /**
+     * Every stop in the order the arrows walk them: each card in reading order,
+     * then the connections leaving it.
+     */
+    private get walk();
+    private readWalk;
+    /** Focuses a stop, a card by its own method and a connection by its target. */
+    private focusStop;
+    /** The connection an event came from, where it came from one. */
+    private edgeOf;
+    /** A point on screen, in the document's own units. */
+    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.
+     */
+    private cardAt;
+    /** What a card is called, by id, for what the live region says. */
+    private nameOf;
+    /** Starts a connection from a card, from the keyboard. */
+    private startLinking;
+    /**
+     * A card a connection could arrive at, or nothing: not the card it started
+     * from, and not one that is held.
+     */
+    private arrival;
+    /**
+     * Whether a connection is being drawn, which a press on a connection is not
+     * until it moves.
+     *
+     * **A click on a connection is a click.** The press picks up the nearer end
+     * so a drag can start from it, and every card lit up its handles for as long
+     * as the button was down: a reader selecting a line watched the whole board
+     * flash as though they had started connecting.
+     */
+    private get drawing();
+    /** Ends a connection, asking for it where it has somewhere to go. */
+    private finishLinking;
+    /**
+     * Picks up one end of a connection, from the keyboard or a drag.
+     *
+     * The end in hand is the one a drag started nearer, and `to` from the
+     * keyboard, where there is no nearer; the other end stays where it is,
+     * side and all.
+     */
+    private startReconnect;
+    /**
+     * Lets go of a connection's end: onto a card, which moves it there; or onto
+     * nothing, which asks for the connection to go.
+     *
+     * **Dropped on nothing is a disconnect**, which is what a reader pulling a
+     * line off a card means, and what every editor with draggable ends does. It
+     * is a request like Delete, because the element is the page's to remove.
+     */
+    private finishReconnect;
+    /**
+     * Carries the selection and the tab stop from a connection's old key to its
+     * new one.
+     *
+     * **A connection with no `name` is known by its two cards**, so moving an end
+     * gives it a new key: the selection went on naming one that no longer
+     * existed, so the connection just moved was selected and drawn as not, and
+     * the tab stop pointed at nothing. A named connection keeps its key, and
+     * nothing moves.
+     */
+    private rekey;
+    /**
+     * Asks for a card or a connection to go, and moves focus on once it has.
+     *
+     * A card takes every connection touching it, which would otherwise stop being
+     * drawn and stay behind in the page's markup as an element joining nothing.
+     */
+    private requestRemove;
+    /**
+     * A click on a card or a connection: it alone, or with a modifier, added or
+     * taken away.
+     */
+    private clicked;
+    /**
+     * The cards a box touches, by name, and the groups it holds whole.
+     *
+     * **A group only when the box takes all of it.** A box drawn to select the
+     * cards inside a group starts and ends inside the group, and touching was
+     * enough to select the group too, so a box could not select a group's cards
+     * without its box coming along.
+     */
+    private within;
+    /**
+     * The line a connection is drawn along on the plane, and its middle, where
+     * both its cards are on the board; nothing where either is not.
+     */
+    private geometryOf;
+    /** The card an event came from, wherever inside it the event began. */
+    private cardOf;
+    /**
+     * The card and everything a move of it carries.
+     *
+     * A group carries every card inside its bounds, groups inside it included,
+     * which is what the format means by a group and what every board does.
+     */
+    private carried;
+    /**
+     * Everything a move of a card carries, and of every other selected card with
+     * it where it is one of the selection: each card's group contents too, and
+     * each card once however many ways it is reached.
+     */
+    private carriedAll;
+    /**
+     * The box a resize from a corner draws, held to a least size so a card
+     * cannot be dragged inside out.
+     */
+    private resized;
+    /**
+     * Whether a card is held where it is, by its own switch or the board's.
+     *
+     * A read-only card is not moved, connected from, connected to, or removed,
+     * and a read-only board holds every card whatever each one says.
+     */
+    private fixed;
+    /** The element behind a connection's key, for what only the element knows. */
+    private edgeElement;
+    /** The connections declared, in the order they were written. */
+    private get edgeElements();
+    /**
+     * What a connection is called in the walk and on the tab stop.
+     *
+     * Its element's id where it has one, and its two ends where it does not: a
+     * page that writes edges without ids still gets one stop per connection.
+     * **And a count where two share both ends**, the second `a->b#2`: under one
+     * key the walk found the first every time and never reached the card after.
+     */
+    private keyOfElement;
+    /** The key of a connection as the board read it, which is its element's. */
+    private keyOf;
+    /** Each connection read, and the key of the element it was read from. */
+    private edgeKeys;
+    /** A stop's key as the name a page sees: a card's name, a connection's name or ends. */
+    private publicName;
+    /** The stop a public name means, where it means one. */
+    private keyNamed;
+    /** The selection, as the keys of the stops in it. */
+    private get picked();
+    /**
+     * Selects stops, or nothing, and says so: `helix-select`, which a page can
+     * refuse, with the names as its value.
+     */
+    private choose;
+    /** Adds a stop to the selection, or takes it out where it was in. */
+    private toggle;
+    /** The cards in the selection. */
+    private get pickedCards();
+    /** A card by name. */
+    private cardNamed;
+    /**
+     * Moves cards, having asked first.
+     *
+     * **The same contract as `open` on a dialog.** The request goes out before
+     * anything moves; refused, nothing does, because the consumer is holding the
+     * positions and will render them. Unrefused, the board writes them onto the
+     * cards, which is the uncontrolled board a consumer gets by doing nothing.
+     * Returns whether it applied, so a caller knows whether to report a finish.
+     */
+    private requestMove;
+    /**
+     * Drag to move the board, which is the gesture a canvas is reached for with.
+     *
+     * **Here rather than in the surface, because a map handles its own.** What
+     * `Map` frames is somebody else's renderer, and MapLibre and Leaflet both
+     * drag their own view: a frame that dragged too would move the map twice. A
+     * board is drawn here, so the drag is this family's.
+     *
+     * The capture is an enhancement and the drag survives losing it, which is what
+     * `capturePointer` is for: a pointer that leaves the box mid-drag keeps
+     * moving the board rather than sticking.
+     *
+     * **Heard on the host rather than on the viewport**, and the cards are why.
+     * A card is the consumer's element, slotted in, so what happens on one
+     * reaches the host whatever else it passes on the way; a listener in the
+     * shadow root depends on the event being routed through the slot, which a
+     * browser does and a DOM implementation a consumer's tests run in need not.
+     * So the host listens, and the path says what was pressed.
+     */
+    private readonly handlePointerDown;
+    private readonly handlePointerMove;
+    private readonly handlePointerUp;
+    /**
+     * Whether a release picks up what its press took hold of, rather than
+     * putting it down.
+     *
+     * **Moving without dragging, which WCAG 2.5.7 asks every drag to offer.** A
+     * press on a corner, a handle, a connection's end or a card's move handle
+     * that is let go where it was pressed is a click, and a click picks the thing
+     * up: the box, the line or the card then follows the pointer with no button
+     * held, and the next press puts it down wherever a drag let go there would
+     * have. On touch, where nothing follows a finger that is not down, the next
+     * tap is where it lands. Escape, or a press off the board, puts it back.
+     *
+     * Not while putting down, or the press that puts a thing down where it was
+     * picked up would pick it up again.
+     */
+    private picksUp;
+    /** Whether something a click picked up is being carried to the next press. */
+    private get held();
+    /** Whether the document is being listened to for the end of a hold. */
+    private holding;
+    /** Whether the press putting something down is being handled, which picks nothing up. */
+    private putting;
+    /** When something was last put down, which a double click that follows is not. */
+    private putAt;
+    /**
+     * Puts down what a click picked up, where this press is: the step a drag
+     * would take to here, then its release.
+     */
+    private putDown;
+    /**
+     * Puts back what a click picked up, as though it had never been.
+     *
+     * A card and a corner go back to where they started, asked for like any
+     * move so a board whose page holds the positions is told; a line is dropped.
+     * Nothing is announced as moved, because nothing did.
+     */
+    private putBack;
+    /** Stops listening for the press or the key that ends a hold. */
+    private letGo;
+    private readonly handleHeldKey;
+    /** A press off the board while something is held, which puts it back. */
+    private readonly handleHeldOutside;
+    /**
+     * A pinch, which zooms, and the wheel, which pans only once the board fills
+     * the screen.
+     *
+     * **`ctrlKey` is a pinch as well as a control press**, which is the platform's
+     * own convention rather than this component's: a trackpad pinch arrives as a
+     * wheel event with `ctrlKey` set, on every browser, and a component that
+     * ignored it would be the one thing on the page a pinch does not work on.
+     *
+     * **A plain wheel belongs to the page while the board is part of one.** Taking
+     * it trapped the reader: a board is most of a screen tall, so scrolling down a
+     * page stopped the moment the pointer crossed one and panned it instead, with
+     * no way on but to move the pointer off it first. Measured on the examples
+     * page, where the second board could not be scrolled to. A drag is how an
+     * embedded board moves, which is the bargain an embedded map makes too; once
+     * the reader has filled the screen with it there is no page left to scroll, so
+     * the wheel is the board's.
+     */
+    private readonly handleWheel;
+    /**
+     * The keys on a card or a connection.
+     *
+     * **Only from the stop itself**, not from inside what a card holds: a card may
+     * hold a link, a field or a chart that answers the arrows itself, and a press
+     * taken from under one of those walked the board instead of the chart.
+     *
+     * **Arrows walk in reading order rather than in space.** The next card in the
+     * order is the one a reader who cannot see the board needs, and the spatial
+     * neighbor is a guess about where they think they are. Right and down go on,
+     * left and up go back, Home and End go to the ends, and Escape goes back out
+     * to the board, where the arrows pan it again.
+     *
+     * On a card, Shift with an arrow moves it, C starts a connection and Delete
+     * asks for it to go. On a connection, Enter goes to the card it arrives at and
+     * Delete asks for it to go. While a connection is being made, Enter on a card
+     * asks for it and Escape stops.
+     */
+    private readonly handleStopKeydown;
+    /**
+     * A stop a reader landed on becomes the tab stop, and a card comes into view.
+     *
+     * Into view rather than to the middle: a reader walking a row of cards that
+     * are all on screen should see the focus ring move along it, not the board
+     * lurch under every press.
+     */
+    private readonly handleFocusIn;
+    /** Brings a card into view, where it is not already whole in it. */
+    private reveal;
+    /**
+     * Edits a stop: a connection's label or a group's name in place, which the
+     * 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. */
+    private readonly handleDoubleClick;
+    /**
+     * Finishes editing a label: asks, writes it where the page did not refuse,
+     * and says it did. The same value is no change and asks nothing.
+     */
+    private finishEditing;
+    /**
+     * The keys in a label being edited, which are the field's: Enter keeps,
+     * Escape puts it back, and nothing reaches the board, whose arrows would
+     * otherwise pan it out from under the caret.
+     */
+    private readonly handleEditorKeydown;
+    private readonly handleEditorBlur;
+    /** The field a label is edited in, where the label is, while one is. */
+    private renderEditor;
+    /** The box a Shift-drag is drawing, on the plane, while it is. */
+    private renderMarquee;
+    /** Scales about a point in the box, which is what both the buttons and a pinch want. */
+    private zoomAbout;
+    /** What one card says in the reading list, its links included. */
+    private linksOf;
+    /**
+     * Every card's sentence at once: one pass over the connections, and one
+     * list formatter, rather than both again for every card.
+     */
+    private readLinks;
+    /** What a node is called, whichever kind it is. */
+    private textOf;
+    /**
+     * The part of the box a fit may use, which is the box less the controls.
+     *
+     * **The controls are chrome, not free space.** They float over the board in
+     * a corner, and a fit that used the whole box put the nearest card under
+     * them: the opening view of a board hid part of the board behind the buttons
+     * that move it. A map can let its controls sit over the tiles because a map
+     * is continuous; a card is not, and one half-covered reads as a broken layout.
+     *
+     * **A band or a column, whichever costs less.** The cluster sits in a corner,
+     * so keeping the board clear of it takes either a band across the edge it sits
+     * on or a column down the side it sits on, and either alone is enough. The
+     * cheaper wins, measured rather than guessed from the shape: a wide short box
+     * loses less to a column and a tall narrow one less to a band. Never more than
+     * half the box, or a small frame would fit its board into nothing.
+     *
+     * Measured rather than computed from `controls` and `controls-placement`, so
+     * a consumer who restyles the cluster, moves it with a part rule, or hides it
+     * with `controls="none"` gets a fit that follows what is actually there.
+     */
+    private get free();
+    /**
+     * Where the board is looking: the document's point at the middle of the view,
+     * and the zoom.
+     *
+     * **Read to save a view and written to restore one**, which a consumer keeping
+     * a minimap in step, or putting a reader back where they were, had no way to
+     * do: where the board sat was private, and the events said only which way a
+     * control had moved it. The middle rather than a corner, so a view saved in
+     * one box shows the same thing in the middle of a box of another size.
+     * Writing one counts as the reader choosing a view, so a later resize keeps
+     * it rather than fitting the board again.
+     */
+    get view(): CanvasView;
+    set view(next: CanvasView);
+    /** The view last reported, so a render that did not move the board says nothing. */
+    private reported?;
+    /**
+     * The board as a JSON Canvas document, for saving it.
+     *
+     * What each card holds is the consumer's DOM, so a card comes back as a card
+     * of text holding what it says; a file or a link the consumer drew inside one
+     * is theirs to write back, which `fromJsonCanvas` handed them on the way in.
+     */
+    toJsonCanvas(): CanvasDocument;
+    /**
+     * Fits the whole board into the box, centered, and never magnified past its
+     * own size.
+     *
+     * **Automatic while nobody has touched the board, and public for when they
+     * have.** The document carries every rectangle, so the extent is arithmetic
+     * rather than a guess, and a board that opened cropped would be one a reader
+     * has to go looking for. Never magnified past its own size: a four-card board
+     * blown up to fill a screen is a worse first view than a small one in the
+     * middle.
+     */
+    fit(): void;
+    /**
+     * The fit, gliding or landing.
+     *
+     * **A fit the board makes for itself lands; one a consumer asks for glides.**
+     * The automatic fit runs as the page loads and whenever the box resizes, and
+     * easing it made the board visibly drift into place after everything else had
+     * settled, and trail a container being resized by a fraction of a second.
+     * It also left Chrome's screenshot of the SVG labels rastered at the scale the
+     * glide started from, which is how it was found: the two twins of an example
+     * matched to the attribute and differed on every label. A consumer's own
+     * `fit()` is a press on a button of theirs, and glides like the pad.
+     */
+    private fitInto;
+    /**
+     * Asks for the render a hydration put off, so the cards get read.
+     *
+     * The mixin starts the idle wait here, and this adds the half a board needs:
+     * the update that hydrated the server's markup could not look at the children,
+     * so the one after it does.
+     */
+    protected firstUpdated(changed: PropertyValues): void;
+    /** A card added or taken away is a board of a different size. */
+    private readonly handleSlotChange;
+    protected updated(changed: PropertyValues): void;
+    /**
+     * Watches the cards' words and the colors written onto the elements.
+     *
+     * A `style` change redraws only where the color it carries moved, because
+     * the board writes each card's place into the same attribute on every
+     * render, and answering that would be a render asking for the next one.
+     */
+    private watchWords;
+    private redraws;
+    /**
+     * Keeps one observer on the box, so a fit follows a resize that has not
+     * happened yet.
+     *
+     * **Observed once, not on every render**, which is what threw "ResizeObserver
+     * loop completed with undelivered notifications" in every example that
+     * resized. A resize fits the board, the fit renders, and the render ran inside
+     * the browser's pass over the observers: re-observing there queues a first
+     * notification for the viewport at a depth the pass has already delivered,
+     * so the browser gives up on it and says so. The viewport is the same element
+     * from the first render on, so there is nothing to re-observe.
+     */
+    private watchBox;
+    /**
+     * Watches again after a move, which a disconnect would otherwise end.
+     *
+     * A reorder is a disconnect and a connect with no render between them, so an
+     * observer torn down on the way out and rebuilt only on the next update is one
+     * that watches nothing until something else happens to change.
+     */
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected willUpdate(changed: PropertyValues): void;
+    /**
+     * Places the cards, which is writing onto elements somebody else wrote.
+     *
+     * **The board positions its children rather than drawing them**, the way
+     * `Tabs` marks its panels: the card is the consumer's element, holding the
+     * consumer's DOM, and what this knows that they do not is where the extent
+     * starts and therefore what their coordinates come to on this plane. Written
+     * as custom properties so the styled tier decides what placement looks like.
+     */
+    private place;
+    /**
+     * The two ends of each selected connection, which a press picks up.
+     *
+     * **The pointer's way to move an end without dragging**: a click on one
+     * picks it up and the next puts it down, where pressing the line and
+     * dragging picks up the nearer end as before. Only on a connection the
+     * reader selected, so a board is not dotted with them, and never on one the
+     * board or the connection holds. Hidden from assistive technology, which
+     * moves an end with the keyboard.
+     *
+     * **Over the cards, not with the lines.** An end sits exactly on the point
+     * of the card it arrives at, and the cards are drawn over the lines, so an
+     * end drawn with them was always under that point: a click on it drew a new
+     * connection from the card instead.
+     */
+    private renderEnds;
+    /**
+     * The connectors, in one layer under the cards.
+     *
+     * **The arrowhead is measured in the board's own units, not in multiples of
+     * the line's width.** `markerUnits="strokeWidth"` multiplies by the stroke, so
+     * an eight-unit head on a two-pixel line drew a sixteen-pixel triangle that
+     * read as a shape of its own rather than as a direction. In user space it is
+     * eight units of the document, which is what the cards are measured in, and it
+     * grows with the zoom like everything else.
+     */
+    private renderEdges;
+    /**
+     * The connections' labels, as text on the plane over the lines.
+     *
+     * **HTML and not SVG text, which is the whole of the fix.** Drawn in the
+     * SVG, a label's ground was a filter flooding the text's box, and Chrome
+     * kept the filter's first picture: a label drawn before the page's font had
+     * loaded kept its ground and lost its words, on every board a server had not
+     * rendered first. Measured as a box with nothing in it on the examples page.
+     * A box of text with a background is what HTML has always done, as wide as
+     * its words, spaces and all, and drawn again whenever the font changes.
+     */
+    private renderLabels;
+    /**
+     * The connection being made, drawn from where it starts to the pointer, or to
+     * the card a keyboard reader is on.
+     */
+    private renderDraft;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-canvas': HelixHeadlessCanvas;
+    }
+}