@fusion.dev/helix-headless 0.105.0 → 0.107.0

package/dist/bar-chart/root/bar-chart-root.d.ts

@@ -3,29 +3,23 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 import '../../tooltip/index.js';
 declare const HelixHeadlessBarChart_base: typeof HelixElement & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinChartSourceInterface);
 /**
- * @summary Categories as columns, read from a table.
+ * @summary A chart that draws a table's categories as columns.
  *
  * @description
- * Two decisions are made here rather than left to a consumer.
+ * Every bar is measured from zero, and no property changes the baseline,
+ * because a bar's length is its value. To show the differences between values,
+ * use a line chart.
  *
- * **It measures from zero and there is no property to change that.** A bar's
- * length *is* its value, so a baseline anywhere else makes the lengths
- * proportional to nothing. A reader who wants the differences between values
- * rather than the values should be drawing a line, which claims only a shape.
+ * The labels are HTML beside the drawing. An `<svg>` that fills its box scales
+ * the text inside it: the same `font-size` renders at 10px in a narrow chart
+ * and 43px in a wide one, and SVG has no setting that keeps text at one size
+ * the way `vector-effect` does for strokes.
  *
- * **The labels are HTML beside the drawing rather than `<text>` inside it.** An
- * `<svg>` that fills its box scales everything in it, including type: the same
- * `font-size` comes out at 10px in a narrow chart and 43px in a wide one, and
- * there is no non-scaling-font to answer it the way `vector-effect` answers
- * strokes. So the columns are drawn and the words are written around them.
+ * The table is the accessible representation, and the drawing is `aria-hidden`,
+ * so screen reader users get the numbers themselves.
  *
- * The table is the accessible representation and this drawing is `aria-hidden`.
- * A reader who wants the numbers gets the numbers, not a described picture of
- * them.
- *
- * The custom properties below are written by this component and read by whoever
- * draws it. A consumer sets none of them: they carry a number this element
- * computed and CSS cannot.
+ * The component writes the custom properties below with numbers it computes,
+ * and the stylesheet that draws the chart reads them. Do not set them yourself.
  *
  * @since 0.1.0
  * @status stable
@@ -33,47 +27,47 @@ declare const HelixHeadlessBarChart_base: typeof HelixElement & (new (...args: a
  * @aliases Column Chart, Categorical Chart
  * @documentation https://fusion.dev/helix/components/bar-chart
  *
- * @csspart axis - One scale's numbers, drawn only when `secondary` splits them.
- * @csspart band - The slot the pointer is resting in.
+ * @csspart axis - The numbers of one scale, drawn only when `secondary` splits the chart into two scales.
+ * @csspart band - The category band under the pointer.
  * @csspart bar - One column.
  * @csspart bar-wash-end - The far stop of a bar's gradient, where one is used.
  * @csspart bar-wash-start - The stop of a bar's gradient at its base.
- * @csspart baseline - The rule the columns stand on.
- * @csspart gridline - One rule across the plot, under `gridlines`.
+ * @csspart baseline - The line the columns stand on.
+ * @csspart gridline - One gridline across the plot, drawn when `gridlines` is set.
  * @csspart group - One category's columns, together.
- * @csspart group-active - The group the tooltip is about, beside `group`.
+ * @csspart group-active - The group the tooltip describes. Set together with `group`.
  * @csspart label - One category's name.
  * @csspart labels - The row of category names.
- * @csspart line - A series drawn as a line rather than as columns, under `lines`.
+ * @csspart line - A series drawn as a line, named in `lines`.
  * @csspart mark - The invisible point the tooltip is anchored to.
  * @csspart plot - The drawing.
  * @csspart svg - The drawing surface the bars and lines sit on.
  * @csspart tick - One number on an axis.
- * @csspart tooltip - The bubble, forwarded from `Tooltip`.
+ * @csspart tooltip - The tooltip bubble, forwarded from `Tooltip`.
  * @csspart tooltip-anchor - The `Tooltip` element itself.
- * @csspart tooltip-arrow - The bubble's point, forwarded from `Tooltip`.
- * @csspart tooltip-arrow-bottom - The point while the bubble is below the reading, so on its top edge, beside `tooltip-arrow`.
- * @csspart tooltip-arrow-left - The point while the bubble is left of the reading, so on its right edge, beside `tooltip-arrow`.
- * @csspart tooltip-arrow-right - The point while the bubble is right of the reading, so on its left edge, beside `tooltip-arrow`.
- * @csspart tooltip-arrow-top - The point while the bubble is above the reading, so on its bottom edge, beside `tooltip-arrow`.
- * @csspart tooltip-bottom - The bubble while it is below the reading, beside `tooltip`.
+ * @csspart tooltip-arrow - The tooltip's arrow, forwarded from `Tooltip`.
+ * @csspart tooltip-arrow-bottom - The arrow while the bubble is below the reading, on the bubble's top edge. Set together with `tooltip-arrow`.
+ * @csspart tooltip-arrow-left - The arrow while the bubble is left of the reading, on the bubble's right edge. Set together with `tooltip-arrow`.
+ * @csspart tooltip-arrow-right - The arrow while the bubble is right of the reading, on the bubble's left edge. Set together with `tooltip-arrow`.
+ * @csspart tooltip-arrow-top - The arrow while the bubble is above the reading, on the bubble's bottom edge. Set together with `tooltip-arrow`.
+ * @csspart tooltip-bottom - The bubble while it is below the reading. Set together with `tooltip`.
  * @csspart tooltip-cell - One column's name and value inside the tooltip.
- * @csspart tooltip-label - The reading's own name inside the tooltip.
- * @csspart tooltip-left - The bubble while it is left of the reading, beside `tooltip`.
+ * @csspart tooltip-label - The reading's category name inside the tooltip.
+ * @csspart tooltip-left - The bubble while it is left of the reading. Set together with `tooltip`.
  * @csspart tooltip-name - A column's name inside the tooltip.
- * @csspart tooltip-right - The bubble while it is right of the reading, beside `tooltip`.
- * @csspart tooltip-top - The bubble while it is above the reading, beside `tooltip`.
+ * @csspart tooltip-right - The bubble while it is right of the reading. Set together with `tooltip`.
+ * @csspart tooltip-top - The bubble while it is above the reading. Set together with `tooltip`.
  * @csspart tooltip-value - A column's value inside the tooltip.
  *
- * @cssproperty --bar-chart-axis - How wide an axis column is drawn, in `ch`, from the widest number on it. Written on the axis itself, and only where the categories run along the bottom: turned sideways an axis is a row and takes a line's height instead.
- * @cssproperty --bar-chart-secondary - The color of the secondary axis, where one series owns it. Written by the component from that series' `--chart-series-*`, so it promises the series color and nothing more: whatever that hook resolves to is what the axis is drawn in.
- * @cssproperty --chart-bar-wash - The gradient a bar would take, named per bar so the
- *   styled tier can point `fill` at it. Drawn whatever the treatment and used only where
- *   `wash="gradient"` asks for it.
+ * @cssproperty --bar-chart-axis - The width of an axis, in `ch`, set from the widest number on it. The chart sets it on the axis itself, and only when the categories run along the bottom. In a horizontal chart the axis is a row, one line high.
+ * @cssproperty --bar-chart-secondary - The color of the secondary axis, when one series is on it. The chart sets it from that series' `--chart-series-*` property, so the axis is drawn in whatever color that property resolves to.
+ * @cssproperty --chart-bar-wash - The gradient for a bar, named per bar so the styled
+ *   tier can use it as the `fill`. It is always drawn, and used only when
+ *   `wash="gradient"` is set.
  */
 export declare class HelixHeadlessBarChart extends HelixHeadlessBarChart_base {
     /**
-     * Which rules are drawn across the plot, if any.
+     * Which gridlines are drawn across the plot, if any.
      *
      * Absent draws none. `value` rules the axis the columns are *measured* on,
      * `category` rules the axis they are *arranged* on with one through each
@@ -94,7 +88,8 @@ export declare class HelixHeadlessBarChart extends HelixHeadlessBarChart_base {
      */
     gridlines?: 'both' | 'category' | 'value';
     /**
-     * Which series are drawn as a line instead of as columns, by name.
+     * The names of the series to draw as lines. The other series are drawn as
+     * columns.
      *
      * Separated by whitespace or commas and matched against the column headings
      * the table gives, so a chart says `lines="Margin"` rather than counting
@@ -118,7 +113,8 @@ export declare class HelixHeadlessBarChart extends HelixHeadlessBarChart_base {
      */
     lines?: string;
     /**
-     * Whether the categories run down the side rather than along the bottom.
+     * Where the categories run. Leave it unset for categories along the bottom,
+     * or set `horizontal` to run them down the side.
      *
      * Absent is columns. `horizontal` is the one to reach for when the category
      * names are words rather than dates: a row of long names either overlaps or
@@ -130,7 +126,7 @@ export declare class HelixHeadlessBarChart extends HelixHeadlessBarChart_base {
      */
     orientation?: 'horizontal';
     /**
-     * Which series are measured against a scale of their own, by name.
+     * The names of the series measured against a second scale of their own.
      *
      * Separated and matched the way `lines` is, against the column headings the
      * table gives. Opt in: absent, every series shares one domain, which is what

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

@@ -4,13 +4,11 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @summary A passage set off from the prose around it.
  *
  * @description
- * Renders a real `<blockquote>` with a `<footer>` for the attribution, which is
- * the structure the HTML spec describes for exactly this: the attribution is
- * about the quotation rather than part of it, and putting it inside the quoted
- * text claims the source said their own name.
+ * Renders a `<blockquote>` with a `<footer>` for the attribution, the structure
+ * the HTML spec describes. The attribution sits outside the quoted text because
+ * it is about the quotation.
  *
- * A quotation run inside a sentence is a `Quote`, which is a different element
- * because it is a different job.
+ * For a quotation inside a sentence, use `Quote`.
  *
  * @since 0.1.0
  * @status stable
@@ -26,7 +24,7 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  */
 export declare class HelixHeadlessBlockquote extends HelixElement {
     /**
-     * URL identifying where the passage came from.
+     * The URL of the source the passage came from.
      */
     cite: string;
     /**

package/dist/breadcrumbs/breadcrumb/breadcrumb.d.ts

@@ -4,56 +4,47 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @summary One step in a breadcrumb trail.
  *
  * @description
- * Contributes the separator, the list-item role, and the link itself where one
- * is wanted.
+ * Each crumb renders its separator and sets its list-item role. It hides its
+ * own separator with `:host(:first-child)`, so the trail needs no index from
+ * the parent.
  *
- * **`href` makes the crumb the link.** A router cannot reach an anchor inside a
- * shadow root, and the consumer restores the soft navigation by intercepting the
- * click on the way out, which is what `Tree.Item` and `List.Item` both do. What
- * the anchor buys is the whole crumb as a target, Enter, middle click, the
- * status bar, and a trail that works before any JavaScript runs.
+ * Set `href` to make the whole crumb an anchor, which works with Enter, middle
+ * click, and the status bar, and before any JavaScript runs. A router cannot
+ * reach an anchor inside a shadow root, so intercept the click for client-side
+ * navigation, as with `Tree.Item` and `List.Item`. A trail that collapses also
+ * reads `href` to rebuild its hidden crumbs elsewhere.
  *
- * **And the parent needs it.** A trail that collapses has to rebuild its hidden
- * crumbs somewhere else, which means reading each one's destination. From a
- * property that is a read; from a consumer's slotted markup it is a hunt for an
- * anchor and a guess about which element is the link.
+ * Without `href`, the crumb renders a plain `<span>` around what you slot,
+ * including your own anchor.
  *
- * A crumb with no `href` is unchanged: the consumer slots whatever they like,
- * including their own anchor, and this renders a plain `<span>` around it.
- *
- * Each item renders its own separator and hides it with `:host(:first-child)`,
- * so the trail needs no index and no coordination from the parent. `:host()`
- * takes a structural pseudo-class, unlike `:has()`, which it rejects.
- *
- * The current page is text, not a link. Linking a page to itself is a known
- * screen-reader annoyance, and `aria-current="page"` on the host is what
- * conveys position.
+ * The current page is plain text, and `aria-current="page"` on the host conveys
+ * the position.
  *
  * @since 0.1.0
  * @status stable
  * @aliases Crumb
  * @documentation https://fusion.dev/helix/components/breadcrumbs
  *
- * @slot - The step's label. Without an `href` this may be the consumer's own
- * anchor, styled with `data-link="quiet"`, since a slotted anchor belongs to the
- * outer tree and cannot be reached from this component's styles.
- * @slot end - After the label and outside the link, so it may be a control: this is where a
- * switcher's menu trigger goes. A count or a mark is equally at home here and is no longer
- * read into the link's accessible name.
+ * @slot - The step's label. Without an `href`, you can slot your own anchor
+ * here. Give it `data-link="quiet"`, because a slotted anchor belongs to the
+ * outer tree and the crumb's styles cannot reach it.
+ * @slot end - Content after the label and outside the link, such as a switcher's
+ * menu trigger, a count, or a mark. It can hold a control, and it is not read as
+ * part of the link's accessible name.
  * @slot separator - Replaces the chevron shown before this item.
- * @slot start - Before the label, for an icon.
+ * @slot start - Content before the label, such as an icon.
  *
  * @csspart link - The crumb itself, which is an `<a>` where `href` is set.
  * @csspart separator - The separator preceding the item.
- * @csspart separator-mark - The glyph between this crumb and the next, where none is slotted.
+ * @csspart separator-mark - The chevron between crumbs, shown when no separator is slotted.
  */
 export declare class HelixHeadlessBreadcrumb extends HelixElement {
     /**
-     * Whether this item is the page the reader is on.
+     * Marks this item as the page you are on.
      */
     current: boolean;
     /**
-     * Where the crumb goes, and nothing where it is the current page.
+     * The URL the crumb links to. The current page has none.
      *
      * **Optional and reflected, because a stylesheet does select on it.** A sheet
      * writes `:host(:not([href])) [part="link"]` to take the block padding off a
@@ -72,13 +63,14 @@ export declare class HelixHeadlessBreadcrumb extends HelixElement {
      */
     href?: string;
     /**
-     * What the link declares about where it goes.
+     * The link's `rel` value, which describes how the linked page relates to this
+     * one.
      *
      * The consumer's decision.
      */
     rel: string;
     /**
-     * Where the link opens, for the rare crumb that leaves the site.
+     * Where the link opens. Use it for a crumb that leaves the site.
      */
     target: string;
     protected willUpdate(changed: PropertyValues): void;

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

@@ -4,18 +4,19 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @summary Shows the path to the current page.
  *
  * @description
- * The host is the landmark, so `aria-label` on it names the trail directly. A
- * page may hold more than one navigation, and landmarks are how a
- * screen-reader user chooses between them.
+ * The host is the navigation landmark, so an `aria-label` on it names the
+ * trail. When a page has more than one navigation landmark, screen reader users
+ * choose between them by name.
  *
- * `role="list"` is set explicitly on the `<ol>` even though it is one:
- * `list-style: none` strips list semantics in Safari, and a breadcrumb trail
- * always removes its markers.
+ * The `<ol>` has an explicit `role="list"`, because Safari removes list
+ * semantics from a list with `list-style: none`, and the trail always hides its
+ * markers.
  *
- * Items are slotted rather than wrapped, so they are `<ol>` children in the
- * flat tree and each carries `role="listitem"` itself.
+ * The items are slotted directly, so they are `<ol>` children in the flat tree,
+ * and each item sets `role="listitem"` on itself.
  *
- * **The trail does not measure itself, and the overflow is markup.**
+ * The trail does not measure itself, and you write its overflow in markup: put
+ * the crumb that holds the folded items where the gap should appear.
  *
  * @since 0.1.0
  * @status stable
@@ -23,8 +24,8 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @aliases Breadcrumb, Crumbs
  * @documentation https://fusion.dev/helix/components/breadcrumbs
  *
- * @slot - The trail's items, in order from root to current page, with the
- * crumb holding the fold wherever the gap should appear.
+ * @slot - The trail's items, in order from the root to the current page. Put
+ * the crumb that holds the folded items where the gap should appear.
  *
  * @csspart list - The ordered list.
  */

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

@@ -4,25 +4,22 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @summary Triggers an action, submits a form, or navigates.
  *
  * @description
- * Renders a real `<button>`, so activation, focus, and the browser's own
- * affordances come from the platform rather than from key handlers.
+ * Renders a real `<button>`, so activation, focus, and other browser behavior
+ * come from the platform.
  *
- * **It never renders an anchor.** A router has to render its own `<a>` to
- * intercept a click and cannot render one inside this shadow root, so a button
- * that could also be a link forced every such navigation to be a full page
- * load. A link that looks like a button is styling rather than behavior, so it
- * is a recipe in the base layer: `<Link data-button="solid">` is the same
- * control, and the consumer keeps their anchor.
+ * **It never renders an anchor.** A router renders its own `<a>` to intercept a
+ * click, and it cannot render one inside the button's shadow root. For a link
+ * that looks like a button, use the base layer recipe on your own anchor:
+ * `<Link data-button="solid">` draws the same control.
  *
- * `delegatesFocus` puts focus on the inner control, and it serializes into the
- * server's markup, so the button is keyboard reachable before any JavaScript
+ * `delegatesFocus` moves focus to the inner control. It is serialized into the
+ * server markup, so the button is reachable by keyboard before any JavaScript
  * loads.
  *
- * Form submission is explicit. A `<button type="submit">` inside a shadow root
- * submits nothing, because the form is on the other side of the boundary, so
- * the inner control is always `type="button"` and this element calls
- * `requestSubmit()` on its form instead. That routes through validation, unlike
- * `submit()`.
+ * The inner control is always `type="button"`, because a
+ * `<button type="submit">` inside a shadow root cannot submit a form outside
+ * it. To submit, the button calls `requestSubmit()` on its form, which runs
+ * validation, unlike `submit()`.
  *
  * @since 0.1.0
  * @status stable
@@ -137,7 +134,8 @@ export declare class HelixHeadlessButton extends HelixFormElement {
      */
     formTarget: string;
     /**
-     * Accessible name, for a button whose content is not text.
+     * The button's name, read by screen readers, for a button whose content is
+     * not text.
      *
      * Lives here rather than only on `IconButton` so the two share one render.
      * An icon-only button without it is a control a screen reader announces as
@@ -152,7 +150,8 @@ export declare class HelixHeadlessButton extends HelixFormElement {
      */
     type: 'button' | 'submit' | 'reset';
     /**
-     * What this button submits under its own `name`, the way a native submitter does.
+     * The value this button submits under its own `name`, as a native submit
+     * button does.
      *
      * **Reported for exactly the submission this button starts and not otherwise.**
      * A native submit button contributes `name=value` only when it is the one

package/dist/button-group/root/button-group-root.d.ts

@@ -4,17 +4,16 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @summary Groups related buttons into one control.
  *
  * @description
- * The host is the group, so `role="group"` sits on it through internals and
- * `label` names it. A group of buttons with no name is announced as a run of
- * separate controls, which is what the grouping exists to say it is not.
+ * Sets `role="group"` on the host through internals, and `label` names the
+ * group. Without a name, a screen reader announces the buttons as separate
+ * controls.
  *
- * It manages no focus. A group is not a toolbar: the APG toolbar pattern asks
- * for one tab stop with arrow keys inside it, and that is what Toolbar is for.
- * Here every button keeps its own tab stop, which is what a reader expects from
- * buttons sitting side by side.
+ * The group does not manage focus, so each button keeps its own tab stop. For
+ * one tab stop with arrow keys between the buttons, the APG toolbar pattern,
+ * use Toolbar.
  *
- * Buttons are slotted rather than wrapped, so they stay the consumer's own
- * elements and keep whatever appearance and size they were given.
+ * Buttons are slotted, so they stay your own elements and keep their own
+ * appearance and size.
  *
  * @since 0.1.0
  * @status stable
@@ -26,7 +25,7 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  */
 export declare class HelixHeadlessButtonGroup extends HelixElement {
     /**
-     * Accessible name for the group.
+     * The group's name, read by screen readers.
      *
      * On the host through internals, so an author's `aria-label` still overrides
      * it and nothing lands on the host that a consumer's markup did not have.

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

@@ -1,24 +1,19 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 /**
- * @summary Sets a passage apart as information, a warning, or an error.
+ * @summary A passage set apart as information, a warning, or an error.
  *
  * @description
- * `tone` lives on the headless tier rather than being a treatment on the styled
- * one, because it is meaning and not decoration. It picks the icon and that
- * icon's accessible name, so a reader who cannot see that the box is red still
- * hears "Error". A callout whose meaning existed only as a color would say
- * nothing to them at all.
+ * `tone` is on the headless tier because it carries meaning. It picks the icon
+ * and the icon's accessible name, so a screen reader announces "Error" for an
+ * error callout whether or not the color is seen.
  *
- * The icon is the fallback content of a slot, so a consumer replaces it by
- * slotting their own and the default disappears with no emptiness check. That
- * is what slot fallback is for.
+ * The icon is the fallback content of a slot. Slot your own icon to replace it,
+ * and the default disappears with no extra check.
  *
- * Not an `Announcement`, which is the other thing this could be mistaken for.
- * A callout interrupts a document to set a passage apart and is read where it
- * sits; an announcement is page-level chrome above the masthead, announces
- * itself as a live region, and can be dismissed. Neither is a variant of the
- * other.
+ * A callout sets a passage apart inside a document and is read where it sits.
+ * For page-level chrome above the masthead that is a live region and can be
+ * dismissed, use `Announcement`.
  *
  * @since 0.1.0
  * @status stable
@@ -32,7 +27,7 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  *
  * @csspart content - The content region.
  * @csspart icon - The icon region.
- * @csspart icon-mark - The tone glyph, where none is slotted.
+ * @csspart icon-mark - The icon for the tone, shown when no icon is slotted.
  */
 export declare class HelixHeadlessCallout extends HelixElement {
     protected willUpdate(changed: PropertyValues): void;

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

@@ -5,15 +5,14 @@ import type { CanvasEnd, CanvasSide } from '../root/canvas-document.js';
  * @summary A connector between two cards on a canvas.
  *
  * @description
- * **A declaration rather than a drawing**, which is the shape `Table.Column`
- * has: this element renders nothing at all and the board draws the line,
- * because a connector is geometry between two other elements and neither end of
- * it belongs here. What this carries is which cards, which sides, and what sits
- * at the ends.
+ * Declares a connector between two cards, the way `Table.Column` declares a
+ * column. The element renders nothing, and the board draws the line. The
+ * element carries which cards the connector joins, which sides it leaves and
+ * arrives on, and what sits at each end.
  *
- * Written as markup for the reason its cards are: an array of edges handed to a
- * custom element does not survive React's hydration, and a connector a consumer
- * can write is one they can also put a condition around.
+ * Connectors are markup for the same reason cards are: an array of edges passed
+ * to a custom element does not survive React hydration. As markup, a connector
+ * can also be rendered conditionally.
  *
  * @since 0.100.0
  * @status experimental
@@ -22,21 +21,22 @@ import type { CanvasEnd, CanvasSide } from '../root/canvas-document.js';
  * @documentation https://fusion.dev/helix/components/canvas
  */
 export declare class HelixHeadlessCanvasEdge extends HelixElement {
-    /** The card it leaves. */
+    /** The name of the card the connection starts from. */
     from: string;
     /**
-     * What sits at the end it leaves from.
+     * The marker at the start of the connection.
      *
      * Absent is nothing, which is the format's own default and what makes an
      * ordinary connector a one-way arrow.
      */
     fromEnd?: CanvasEnd;
-    /** Which side of that card it leaves, where the document says. */
+    /** The side of the `from` card the connection leaves from, when the document sets one. */
     fromSide?: CanvasSide | undefined;
-    /** What the connector says, drawn at its middle. */
+    /** Text drawn at the middle of the connection. */
     label?: string | undefined;
     /**
-     * What a request calls this connection, unique on its board.
+     * The connection's name, unique on its board, which events use to refer to
+     * it.
      *
      * Optional, unlike a card's: a connection is also known by its two ends,
      * which `helix-remove` carries beside this, so a page that names none of its
@@ -44,7 +44,7 @@ export declare class HelixHeadlessCanvasEdge extends HelixElement {
      */
     name: string;
     /**
-     * How it travels: `straight`, or `step` for right angles.
+     * The route the line takes: `straight`, or `step` for right angles.
      *
      * Absent is whatever the board says, and a curve where the board says
      * nothing. Not part of JSON Canvas, which draws every edge one way; a
@@ -57,30 +57,30 @@ export declare class HelixHeadlessCanvasEdge extends HelixElement {
      */
     path?: 'straight' | 'step';
     /**
-     * Keeps this connection: a reader cannot remove it.
+     * Prevents the connection from being removed.
      *
      * The board's `readonly` still wins. A connection is still removed with a
      * card at either end of it, since a line to a card that has gone is not one
      * the board can draw.
      */
     readOnly: boolean;
-    /** The card it arrives at. */
+    /** The name of the card the connection ends at. */
     to: string;
-    /** What sits at the end it arrives at. Absent is an arrow, as the format says. */
+    /** The marker at the end of the connection. Unset is an arrow, as JSON Canvas specifies. */
     toEnd?: CanvasEnd;
     /**
-     * What the connection means, in the words every Helix component uses.
+     * The meaning of the connection, shown by its color, in the same tones as
+     * other Helix components.
      *
      * A color with no meaning is `--canvas-edge-color`, written in the edge's own
      * `style`: the line is drawn by the board rather than by this element, so the
      * board carries the value across from where it was written.
      */
     tone?: 'accent' | 'danger' | 'info' | 'neutral' | 'primary' | 'success' | 'warning';
-    /** Which side of that card it arrives at, where the document says. */
+    /** The side of the `to` card the connection arrives at, when the document sets one. */
     toSide?: CanvasSide | undefined;
     /**
-     * How the line is drawn: `dashed` or `dotted`, and solid where it says
-     * neither.
+     * How the line is drawn: `dashed` or `dotted`. Unset is solid.
      *
      * **A variant rather than an axis**, which is what the registry keeps it for:
      * no other family draws a line whose stroke says something, and a dashed