@fusion.dev/helix-headless 0.105.0 → 0.106.0

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

@@ -4,38 +4,33 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @summary One card or group on a canvas.
  *
  * @description
- * **Markup rather than an entry in an array**, which is the rule
- * `VideoPlaylist` writes out: an array handed to a custom element is missing
- * from the first paint of every server-rendered React page, because React skips
- * the properties it would have to apply imperatively while hydrating. A card
- * written as an element is in the served HTML whichever renderer wrote it, and
- * what is inside it is the consumer's own DOM rather than a string this
- * component parses.
+ * A card is an element in the markup, the rule `VideoPlaylist` also follows. An
+ * array passed to a custom element is missing from the first paint of every
+ * server-rendered React page, because React skips the properties it would have
+ * to set imperatively during hydration. A card element is in the served HTML
+ * whichever renderer wrote it, and its contents are your own DOM.
  *
- * **Where it sits is data**, which is what makes a canvas a canvas: somebody
- * placed this card and the placement carries meaning, so `x` and `y` are given
- * rather than computed. The board reads them and places the card; a page with
- * no JavaScript has the cards and their text and not the arrangement, which is
- * the honest half of what a board can promise before it hydrates.
+ * Set `x` and `y` to place the card. On a canvas the placement carries meaning,
+ * so positions are given and never computed. The board reads them and places
+ * the card. Without JavaScript, the page shows the cards and their text without
+ * the arrangement.
  *
- * **Named by `name`, which only has to be unique on its board**, the way a
- * form control's is in its form. An `id` has to be unique on the whole page,
- * and two boards written from one template, or one board shown twice, would
- * each have a card called `write` with no way to say which one a connection
- * meant. `id` is left for the page, which can still use it.
+ * `name` identifies the card and only has to be unique on its board, like a
+ * form control's name in its form. An `id` must be unique on the whole page,
+ * which fails when two boards come from one template or one board is shown
+ * twice. `id` stays free for your own use.
  *
- * **What it holds is the consumer's**, which is why there is no card type any
- * more: a card of text is text, a link is a link they put inside it, a file is
- * whatever they show for one. The one kind the board treats differently is a
- * group, a box drawn behind the cards inside it, and `group` says so. JSON
- * Canvas's four types are mapped by `fromJsonCanvas` on the way in.
+ * The card holds your content, and there is no card type. Text is text, a link
+ * is a link you put inside the card, and a file is whatever you show for one.
+ * The board treats one kind differently: a group, drawn as a box behind the
+ * cards inside it. Set `group` for a group. `fromJsonCanvas` maps the four JSON
+ * Canvas node types on the way in.
  *
- * **The card is the way around the board, for a reader who cannot see it.** The
- * board keeps one tab stop among its cards, arrow keys walk them in reading
- * order, and the one a reader lands on is brought into view. What it connects
- * to is read out with it, so the arrows between cards are heard as well as
- * seen. That replaced a list of every card under the board, which said the same
- * thing twice to a sighted reader and took a row from the board to do it.
+ * The cards are how you move around the board with a keyboard or a screen
+ * reader. The board keeps one tab stop among its cards, the arrow keys move
+ * through them in reading order, and the card you land on scrolls into view.
+ * Its connections are announced with it, so a screen reader reads the arrows
+ * between cards.
  *
  * @since 0.100.0
  * @status experimental
@@ -43,31 +38,31 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @aliases CanvasCard, BoardNode
  * @documentation https://fusion.dev/helix/components/canvas
  *
- * @slot - What the card holds, which is anything: text, a picture, a chart.
- * @slot description - A quieter line under it.
+ * @slot - The card's content, such as text, a picture, or a chart.
+ * @slot description - A line of secondary text under the content.
  *
- * @csspart grip - A corner a selected card is resized from, on every one of the four.
+ * @csspart grip - A corner handle that resizes a selected card, on each of the four corners.
  * @csspart grip-bottom-left - The bottom left corner.
  * @csspart grip-bottom-right - The bottom right corner.
  * @csspart grip-top-left - The top left corner.
  * @csspart grip-top-right - The top right corner.
- * @csspart handle - A point on a side a connection is drawn from, on every one of the four.
+ * @csspart handle - A point that you draw a connection from, on each of the four sides.
  * @csspart handle-bottom - The point on the bottom side.
  * @csspart handle-left - The point on the left side.
  * @csspart handle-right - The point on the right side.
  * @csspart handle-top - The point on the top side.
- * @csspart move - The handle a selected card is moved by, a click to pick it up and another to put it down, as well as a drag.
+ * @csspart move - The handle that moves a selected card. Drag it, or click once to pick the card up and again to put it down.
  * @csspart node - The box the content sits in.
- * @csspart outline - The drawn outline of a card whose shape a box cannot draw, a diamond.
+ * @csspart outline - The drawn outline of a `diamond` card, a shape a box cannot draw.
  *
  * @cssstate candidate - While a connection is being drawn and this card is somewhere it could arrive.
- * @cssstate current - While this is the card a reader lands on when they tab into the board.
- * @cssstate selected - While this is the card the reader selected, until they select something else or nothing.
- * @cssstate target - While a connection being drawn would arrive here if it were let go.
+ * @cssstate current - The card that receives focus when you tab into the board.
+ * @cssstate selected - The card is selected.
+ * @cssstate target - A connection being drawn would end here if you released it.
  */
 export declare class HelixHeadlessCanvasNode extends HelixElement {
     /**
-     * A box drawn behind the cards inside it rather than a card.
+     * Makes this a group: a box drawn behind the cards inside it.
      *
      * The board works out what is inside it from the geometry, which is what the
      * format does too, and moves them with it. Its `label` is drawn above it.
@@ -94,7 +89,8 @@ export declare class HelixHeadlessCanvasNode extends HelixElement {
     /** How tall the card is, in the document's own units. */
     height: number;
     /**
-     * What the card is called, for a group and wherever another card names it.
+     * The card's name as text. A group shows it, and another card's connections
+     * read it out.
      *
      * A group needs one because it has no text of its own; a card that has text
      * is named by it, and one holding a picture or a figure is named by nothing
@@ -102,7 +98,8 @@ export declare class HelixHeadlessCanvasNode extends HelixElement {
      */
     label: string;
     /**
-     * What connections and requests call this card, unique on its board.
+     * The name that connections and events use for this card, unique on its
+     * board.
      *
      * Required: a card with no name is drawn but nothing can connect to it, and
      * the board has nothing to say when a reader asks for it to go.
@@ -115,7 +112,7 @@ export declare class HelixHeadlessCanvasNode extends HelixElement {
      */
     links: string;
     /**
-     * Keeps this card where it is: not moved, not connected, not removed.
+     * Prevents the card from being moved, connected, or removed.
      *
      * **The board's own word, meaning the same thing one card at a time.** A
      * board of cards a reader rearranges often has one that anchors it, a start
@@ -124,8 +121,8 @@ export declare class HelixHeadlessCanvasNode extends HelixElement {
      */
     readOnly: boolean;
     /**
-     * The card's outline: `circle`, `diamond`, `pill` or `square`, and a rounded
-     * box where it says none.
+     * The card's outline: `circle`, `diamond`, `pill`, or `square`. Unset is a
+     * rounded box.
      *
      * **A flowchart's vocabulary, and the reason it is on this tier**: a diamond
      * is drawn as an outline the card renders, because a border follows a box
@@ -152,7 +149,8 @@ export declare class HelixHeadlessCanvasNode extends HelixElement {
      */
     resizable: boolean;
     /**
-     * What the card means, in the words every Helix component uses for it.
+     * The meaning of the card, shown by its color, in the same tones as other
+     * Helix components.
      *
      * **`tone` rather than the format's `color`**, which was a second word for
      * the same thing on this family alone: JSON Canvas writes `1` to `6` and
@@ -188,7 +186,7 @@ export declare class HelixHeadlessCanvasNode extends HelixElement {
      */
     protected updated(changed: PropertyValues): void;
     /**
-     * Focuses the card rather than the host, which draws no box of its own.
+     * Focuses the card's `node` part. The host draws no box of its own.
      *
      * The board calls this to walk the cards, and a consumer can too: the part is
      * what holds the tab stop and what a focus ring is drawn around.

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

@@ -5,66 +5,66 @@ export type { CanvasDocument, CanvasEdge, CanvasEdgeProps, CanvasEnd, CanvasNode
 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.
+ * @summary A board of cards and the connections between them, which can be navigated, rearranged, and connected.
  *
  * @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.
+ * A board of cards and connectors, drawn by Helix. On a canvas every position
+ * is data that someone placed, so drawing is arithmetic over rectangles with no
+ * layout to compute. `Map` takes a slotted map, because another renderer draws
+ * its tiles.
  *
- * **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.
+ * The format is [JSON Canvas](https://jsoncanvas.org), an open format. Each
+ * node has an `x`, `y`, `width`, `height`, and a type. Each edge names 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.
  *
- * **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.
+ * The cards are text in the DOM, so a screen reader can read them. The family
+ * adds a reading order and states each card's connections as text. `order` sets
+ * the reading order:
+ * - `spatial` bands the cards into rows.
+ * - `edges` follows the arrows, starting from the cards that 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.
+ * **Cards move by default.** The board writes the new `x` and `y` onto the
+ * card, the way an input writes its own value, and dispatches two events:
+ * - `helix-before-move` for every step. Cancel it to hold the positions in your
+ *   own state and apply them yourself.
+ * - `helix-move` once the move is finished.
  *
- * **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.
+ * A resize dispatches the same pair with a size. Set `readonly` on the board to
+ * keep every card in place, such as on a published board. Set `readonly` on one
+ * card or connection to keep only that one in place.
  *
- * **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.
+ * Keyboard behavior:
+ * - One card holds the board's tab stop.
+ * - The arrow keys move through the cards in reading order. The card you land
+ *   on scrolls into view, and its connections are announced with it.
+ * - Shift with an arrow key moves the card.
+ * - The connections leaving a card are stops of their own, straight after it.
+ *   Enter on one moves to the card it arrives at.
  *
- * **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.
+ * Every drag also works with clicks, as WCAG 2.5.7 requires for a pointer that
+ * cannot hold a button down. Click a selected card's move handle, a corner, a
+ * card's connection point, or the end of a selected connection to pick it up.
+ * It follows the pointer with no button held, and the next click puts it down
+ * where a drag would have. On touch, the next tap sets where it lands. Escape,
+ * or a press outside the board, puts it back.
  *
- * **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.
+ * Connecting and removing dispatch requests, and your code applies them:
+ * - Drawing from a card's handle to another card, or pressing C on one card and
+ *   Enter on another, dispatches `helix-connect`.
+ * - Delete on a card or a connection dispatches `helix-remove`. The event names
+ *   every connection that removing the card would leave without an end.
+ *
+ * The board applies a move itself, because the card already exists. A
+ * connection is a new element, and React discards an element the board adds to
+ * its markup on the next render, so you write the connection.
+ *
+ * Cards and connections are `helix-canvas-node` and `helix-canvas-edge`
+ * elements, so they are in the served markup whichever renderer wrote them. The
+ * library fetches nothing, and an array passed to an element is missing from
+ * the first paint of a server-rendered React page. `fromJsonCanvas` turns a
+ * JSON Canvas document into their props, and `toJsonCanvas()` writes a board
+ * back out.
  *
  * @since 0.100.0
  * @status experimental
@@ -72,64 +72,63 @@ declare const HelixHeadlessCanvas_base: (new (...args: any[]) => import("@fusion
  * @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.
+ * @slot empty - Content shown when the document has no nodes.
+ * @slot footer - Content below the board.
+ * @slot header - Content 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 {HelixBeforeMoveEvent} helix-before-move - Cards are about to move. Cancelable: cancel it to keep the positions in your own state.
+ * @event {HelixBeforeReconnectEvent} helix-before-reconnect - A connection's end is about to move to another card or side. Cancelable: cancel it to keep connections in your own state.
+ * @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.
+ * @event {HelixCanvasPanEvent} helix-canvas-pan - The board moved one step, from its controls or the arrow keys. A drag sends `helix-canvas-view`.
+ * @event {HelixCanvasViewEvent} helix-canvas-view - The board's view changed, by any means. The detail is the new view.
+ * @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 {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.
+ * @event {HelixRemoveEvent} helix-remove - Cards or connections were chosen for removal. 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: canceling it keeps the selection as 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 arrow - The arrowhead at an end of a connection that has one.
+ * @csspart board - The plane the cards are placed on, which 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 draft - The connection being drawn, before `helix-connect` is sent.
  * @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 edge-end - An end of a selected connection. Drag it, or click it to pick it up.
+ * @csspart edge-target - A wider, invisible line over a connection, which receives focus 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 fullscreen - The button that makes the board fill 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 label-editor - The field for editing a connection's label or a group's name, placed over that text.
+ * @csspart live - A live region that screen readers announce while a connection is being made.
  * @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-end - The button that moves the board toward the end of a line of text: right in English.
+ * @csspart pan-start - The button that moves the board toward the start of a line of text: left in English.
  * @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 connecting - While you draw a connection.
+ * @cssstate direct - The board moves without easing, while you drag it or while it settles 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 holding - An item picked up with a click follows the pointer until the next press puts it down.
+ * @cssstate idle - The user has been still long enough for the controls to hide.
  * @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}`. */
+    /** The text read with a card to say where its connections come from, with `{cards}`. */
     comesFromLabel: string;
-    /** What it says when a connection is asked for, with `{from}` and `{to}`. */
+    /** The text announced when a connection is requested, with `{from}` and `{to}`. */
     connectedLabel: string;
     /**
-     * What the live region says when a reader starts a connection, with `{from}`
-     * filled in.
+     * The text announced when a connection is started, 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
@@ -137,33 +136,35 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
      */
     connectingLabel: string;
     /**
-     * What a connection is called, with `{from}` and `{to}`.
+     * The accessible name of a connection, 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.
+     * The accessible name for the board. Required.
      *
      * 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.
+     * The accessible name of the field for editing a label, with `{name}` for what
+     * the label belongs to.
      */
     labelEditorLabel: string;
     /**
-     * How a card says where its connections go, with `{cards}` as the list.
+     * The text read with a card to say 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.
+     * The order the arrow keys and screen readers move through the cards:
+     * `spatial` or `edges`.
      *
      * `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
@@ -175,8 +176,8 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
      */
     order?: 'spatial' | 'edges';
     /**
-     * How every connection travels, where it does not say: `straight`, or `step`
-     * for right angles.
+     * The route every connection takes when it sets no `path` of its own:
+     * `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
@@ -184,7 +185,7 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
      */
     path?: 'straight' | 'step';
     /**
-     * Keeps every card where its author put it.
+     * Prevents every card from being moved, connected, or removed.
      *
      * **The attribute is `readonly`, which is the platform's spelling**, and the
      * reverse of an `editable` switch on purpose: a form control takes input
@@ -194,13 +195,13 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
      */
     readOnly: boolean;
     /**
-     * What the live region says when a reader picks up a connection's end, with
-     * `{from}` and `{to}`.
+     * The text announced when a connection's end is picked up, with `{from}` and
+     * `{to}`.
      */
     reconnectingLabel: string;
     /**
-     * The cards and connections the reader selected, by name, comma separated,
-     * and empty for none.
+     * The names of the selected cards and connections, comma separated. Empty
+     * when nothing is selected.
      *
      * **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
@@ -224,7 +225,7 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
      * A label being edited in place: whose, and what it said before.
      */
     private editing;
-    /** What it says when a reader stops connecting without asking. */
+    /** The text announced when a connection is stopped before it is requested. */
     stoppedLabel: string;
     /** The card or connection that holds the board's one tab stop, by its key. */
     private stop;
@@ -770,7 +771,7 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
      */
     private get free();
     /**
-     * Where the board is looking: the document's point at the middle of the view,
+     * The board's current view: 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
@@ -794,7 +795,7 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
      */
     toJsonCanvas(): CanvasDocument;
     /**
-     * Fits the whole board into the box, centered, and never magnified past its
+     * Fits the whole board into its box, centered, and never zoomed in past its
      * own size.
      *
      * **Automatic while nobody has touched the board, and public for when they

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

@@ -4,19 +4,17 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @summary Groups related content and actions into a single surface.
  *
  * @description
- * Regions are slots rather than separate elements, because a header, body, and
- * footer carry no state, no behavior, and no API of their own. Slotting them
- * costs one custom element instead of five and lets the consumer bring their
- * own markup, so a title can be a real `<h2>` rather than an emulated one.
+ * The header, body, and footer regions are slots, because they have no state,
+ * behavior, or API of their own. You bring your own markup, so a title can be a
+ * real `<h2>`.
  *
- * The host is the surface. A wrapper `<div part="container">` would be a second
- * box doing nothing the host cannot: the element itself takes the border, the
- * radius, and the grid, and a consumer styles `Card` rather than reaching
- * through `::part`. One node instead of two, on every card on the page.
+ * The host is the surface. The element itself takes the border, the radius, and
+ * the grid, so you style `Card` directly and there is no wrapper part to reach
+ * through with `::part`.
  *
- * Name the card with `aria-label` or `aria-labelledby`. That is the only
- * naming that survives server rendering: reading a title out of the light DOM
- * needs a DOM, and the server has none.
+ * Name the card with `aria-label` or `aria-labelledby`. These are the only
+ * names that work with server rendering, because reading a title from the light
+ * DOM needs a DOM, and the server has none.
  *
  * @since 0.1.0
  * @status stable
@@ -31,7 +29,7 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  */
 export declare class HelixHeadlessCard extends HelixElement {
     /**
-     * Puts the media after the content instead of before it.
+     * Places the media after the content. By default it comes before.
      *
      * **A figure that concludes a card is the same region as one that opens it**,
      * and the only thing that differs is which edge it is flush against. Media is