@fusion.dev/helix-headless 0.144.0 → 0.146.0

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

@@ -6,7 +6,7 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @description
  * 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.
+ * controls, and a development build warns once with the kind `missing-name`.
  *
  * 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,
@@ -52,6 +52,7 @@ export declare class HelixHeadlessButtonGroup extends HelixElement {
      */
     orientation?: 'horizontal' | 'vertical';
     protected willUpdate(changed: PropertyValues): void;
+    protected firstUpdated(changed: PropertyValues): void;
     protected render(): TemplateResult;
 }
 declare global {

package/dist/button-group/root/button-group-root.js

@@ -4,7 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { customElement, HelixElement, hostAria } from '@fusion.dev/helix-core';
+import { auditName, customElement, HelixElement, hostAria } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
 let HelixHeadlessButtonGroup = class HelixHeadlessButtonGroup extends HelixElement {
@@ -16,6 +16,10 @@ let HelixHeadlessButtonGroup = class HelixHeadlessButtonGroup extends HelixEleme
         super.willUpdate(changed);
         hostAria(this.internals, { label: this.label, role: 'group' });
     }
+    firstUpdated(changed) {
+        super.firstUpdated(changed);
+        auditName(this, () => null, 'Give it a `label`, or an `aria-label` that says what the buttons are for.', () => this.label !== '');
+    }
     render() {
         return html `<slot></slot>`;
     }

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

@@ -93,9 +93,10 @@ export declare class HelixHeadlessCanvasNode extends HelixElement {
      * 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
-     * short enough to read out in another card's connections.
+     * A group needs one because it has no text of its own. A card is named by
+     * it where it is set, and by its content where it is not, so a screen reader
+     * moving between cards hears each one's name. Set it on a card holding a
+     * picture or a figure, which has no words short enough to name it.
      */
     label: string;
     /** Where the card was placed, kept in its own shadow root. */

package/dist/canvas/node/canvas-node.js

@@ -73,12 +73,13 @@ let HelixHeadlessCanvasNode = class HelixHeadlessCanvasNode extends HelixElement
             : nothing}<div
       part="node"
       aria-describedby=${this.meaning || this.links ? 'about' : nothing}
-      aria-label=${this.group ? this.label || nothing : nothing}
+      aria-label=${this.label || nothing}
+      aria-labelledby=${this.label || this.group ? nothing : 'content'}
       aria-keyshortcuts=${this.connectable ? 'Enter F2 Space Shift+ArrowRight Shift+ArrowDown Alt+ArrowRight Alt+ArrowDown C Delete' : nothing}
       role=${this.group ? 'group' : 'article'}
       tabindex=${this.current ? '0' : '-1'}
     >
-      <slot></slot>
+      <slot id="content"></slot>
       <slot name="description"></slot>
       <span id="about" hidden>${[this.meaning, this.links].filter(Boolean).join(', ')}</span>
     </div>

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

@@ -98,7 +98,7 @@ declare const HelixHeadlessCanvas_base: (new (...args: any[]) => import("@fusion
  * @csspart edge - One connector between two cards.
  * @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 edges - A layer the connectors are drawn in: one holding the arrowhead, and one after each card holding the connections leaving it, so they are read in the order the arrows walk them. Give it `z-index: -1` to draw it under the cards.
  * @csspart footer - The strip below the board.
  * @csspart fullscreen - The button that makes the board fill the screen.
  * @csspart gesture-hint - Words over the board for a moment when it lets a gesture pass to the page, such as how to zoom it.
@@ -128,6 +128,10 @@ declare const HelixHeadlessCanvas_base: (new (...args: any[]) => import("@fusion
  * @cssstate using - A board with `gestures="activate"` has been pressed and has the gestures.
  */
 export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
+    /** The connection whose target had focus as an update began, and that target. */
+    private focusedEdge;
+    /** Each card is assigned to its own slot, in the order the arrows walk them. */
+    static shadowRootOptions: ShadowRootInit;
     /** The text read with a card to say where its connections come from, with `{cards}`. */
     comesFromLabel: string;
     /** The text announced when a connection is requested, with `{from}` and `{to}`. */
@@ -951,16 +955,47 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
      */
     private renderEnds;
     /**
-     * The connectors, in one layer under the cards.
+     * The layer that holds the arrowhead and the connection being drawn.
      *
      * **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.
+     * grows with the zoom like everything else. Each card's connections reach it
+     * by its id, which every layer in this shadow root shares.
      */
     private renderEdges;
+    /**
+     * Each card, and then the connections leaving it, in the order the arrows
+     * walk them.
+     *
+     * **The order is the accessibility tree's.** The connections were one layer
+     * drawn before every card, so a screen reader's reading went through every
+     * connection and then every card, while the arrow keys went card by card
+     * with each card's connections after it. Each card now has a slot of its
+     * own, assigned by hand, with its connections' layer straight after it, so
+     * both orders are the walk. The cards are read before hydration, which
+     * knows none, from the default slot after these, as they always were.
+     *
+     * **Every layer sits under the cards by its stacking.** A layer after a card
+     * in the tree would otherwise paint over it, so the styled sheet sets
+     * `--helix-layer-beneath` on `edges`, and a headless page sets `z-index: -1`.
+     */
+    private renderStops;
+    /** One connector: the target that takes focus and presses, and the line it paints. */
+    private renderEdge;
+    /**
+     * Sends each card to its slot, and everything else to the slot it names.
+     *
+     * A root that assigns by hand routes nothing by itself, the named slots
+     * included, so the header, the footer and the empty state are assigned here
+     * too. Paired with the walk by position, as the template was built, and a
+     * card the walk does not reach, a second one of the same name, goes to the
+     * default slot with everything else. On a root a server sent, which routes
+     * by name, each card is sent to its slot by name instead.
+     */
+    private assign;
     /**
      * The connections' labels, as text on the plane over the lines.
      *

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

@@ -4,7 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { capturePointer, customElement, fillTemplate, HelixBeforeMoveEvent, HelixBeforeReconnectEvent, HelixBeforeRelabelEvent, HelixCanvasEditEvent, HelixCanvasPanEvent, HelixCanvasViewEvent, HelixCanvasZoomEvent, HelixConnectEvent, HelixElement, HelixMoveEvent, HelixReconnectEvent, HelixRelabelEvent, HelixRemoveEvent, HelixSelectEvent, hostAria, inlineStep, isRtl, MixinViewport, } from '@fusion.dev/helix-core';
+import { capturePointer, customElement, fillTemplate, HelixBeforeMoveEvent, HelixBeforeReconnectEvent, HelixBeforeRelabelEvent, HelixCanvasEditEvent, HelixCanvasPanEvent, HelixCanvasViewEvent, HelixCanvasZoomEvent, HelixConnectEvent, HelixElement, HelixMoveEvent, HelixReconnectEvent, HelixRelabelEvent, HelixRemoveEvent, HelixSelectEvent, hostAria, inlineStep, isRtl, MixinViewport, wordsConverter, } from '@fusion.dev/helix-core';
 import { html, nothing, svg } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { HelixHeadlessCanvasEdge } from '../edge/canvas-edge.js';
@@ -610,6 +610,10 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
             this.requestUpdate();
         };
     }
+    static { this.shadowRootOptions = {
+        ...HelixElement.shadowRootOptions,
+        slotAssignment: 'manual',
+    }; }
     get box() {
         const viewport = this.renderRoot?.querySelector('[part="viewport"]');
         return {
@@ -1530,6 +1534,12 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
     updated(changed) {
         this.keying = undefined;
         super.updated(changed);
+        this.assign();
+        const edge = this.focusedEdge;
+        this.focusedEdge = undefined;
+        if (edge && (!edge.target.isConnected || edge.target.getAttribute('data-edge') !== edge.key)) {
+            this.focusStop(edge.key);
+        }
         if (this.holding && !this.held) {
             this.letGo();
         }
@@ -1661,6 +1671,11 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
     willUpdate(changed) {
         this.keying = this.keyAll();
         super.willUpdate(changed);
+        const focused = this.ownerDocument?.activeElement === this
+            ? this.renderRoot.activeElement
+            : undefined;
+        const key = focused?.getAttribute?.('data-edge');
+        this.focusedEdge = focused && key ? { key, target: focused } : undefined;
         const drawn = extent(this.nodes);
         const origin = { x: drawn.x - MARGIN, y: drawn.y - MARGIN };
         if (this.origin && (origin.x !== this.origin.x || origin.y !== this.origin.y)) {
@@ -1732,9 +1747,6 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
         });
     }
     renderEdges(origin, box) {
-        const elements = new Map(this.edgeElements.map((child) => [this.keyOfElement(child), child]));
-        const stop = this.stop !== undefined && this.keyNamed(this.stop) === this.stop ? this.stop : undefined;
-        const pickedKeys = new Set(this.picked);
         return html `<svg
       part="edges"
       role="none"
@@ -1755,46 +1767,114 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
           <path part="arrow" d="M0 0 L8 4 L0 8 z" />
         </marker>
       </defs>
-      ${this.edges.map((edge) => {
-            const key = this.keyOf(edge);
-            const element = elements.get(key);
-            const drawn = this.geometryOf(edge, origin);
-            const lifted = this.linking?.edge === key && !this.linking.pressed;
-            if (!drawn || (lifted && this.linking?.pointer !== undefined)) {
-                return nothing;
-            }
-            const { from, to } = drawn;
-            const ends = heads(edge);
-            return svg `<path
-            part="edge-target"
-            aria-description=${[element?.tone ? this.toneLabels[element.tone] : undefined, edge.label].filter(Boolean).join(', ') || nothing}
-            aria-label=${fillTemplate(this.connectionLabel, { from: this.textOf(from), to: this.textOf(to) })}
-            d=${drawn.d}
-            data-edge=${key}
-            fill="none"
-            aria-keyshortcuts="Enter F2 C Delete"
-            role="button"
-            tabindex=${key === stop ? '0' : '-1'}
-          />
-          ${lifted
-                ? nothing
-                : svg `<path
-            part="edge"
-            aria-hidden="true"
-            d=${drawn.d}
-            data-selected=${pickedKeys.has(key) ? '' : nothing}
-            data-tone=${element?.tone ?? nothing}
-            data-variant=${element?.variant ?? nothing}
-            fill="none"
-            marker-end=${ends.end ? `url(#${ARROW})` : nothing}
-            marker-start=${ends.start ? `url(#${ARROW})` : nothing}
-            style=${custom(element, '--canvas-edge-color') ? `--_canvas-edge-color: ${custom(element, '--canvas-edge-color')}` : nothing}
-          />`}
-`;
-        })}
       ${this.renderDraft(origin)}
     </svg>`;
     }
+    renderStops(origin, box) {
+        const elements = new Map(this.edgeElements.map((child) => [this.keyOfElement(child), child]));
+        const stop = this.stop !== undefined && this.keyNamed(this.stop) === this.stop ? this.stop : undefined;
+        const picked = new Set(this.picked);
+        const groups = [];
+        for (const one of this.walk) {
+            if (one.kind === 'node') {
+                groups.push({ edges: [], key: one.key });
+            }
+            else {
+                groups.at(-1)?.edges.push(one.edge);
+            }
+        }
+        return groups.map(({ edges }, at) => html `<slot name=${`card-${at}`}></slot>${edges.length === 0
+            ? nothing
+            : html `<svg
+                part="edges"
+                role="none"
+                viewBox=${`0 0 ${box.width} ${box.height}`}
+                width=${box.width}
+                height=${box.height}
+              >
+                ${edges.map((edge) => this.renderEdge(edge, origin, elements, stop, picked))}
+              </svg>`}`);
+    }
+    renderEdge(edge, origin, elements, stop, pickedKeys) {
+        const key = this.keyOf(edge);
+        const element = elements.get(key);
+        const drawn = this.geometryOf(edge, origin);
+        const lifted = this.linking?.edge === key && !this.linking.pressed;
+        if (!drawn || (lifted && this.linking?.pointer !== undefined)) {
+            return nothing;
+        }
+        const { from, to } = drawn;
+        const ends = heads(edge);
+        return svg `<path
+        part="edge-target"
+        aria-description=${[element?.tone ? this.toneLabels[element.tone] : undefined, edge.label].filter(Boolean).join(', ') || nothing}
+        aria-label=${fillTemplate(this.connectionLabel, { from: this.textOf(from), to: this.textOf(to) })}
+        d=${drawn.d}
+        data-edge=${key}
+        fill="none"
+        aria-keyshortcuts="Enter F2 C Delete"
+        role="button"
+        tabindex=${key === stop ? '0' : '-1'}
+      />
+      ${lifted
+            ? nothing
+            : svg `<path
+        part="edge"
+        aria-hidden="true"
+        d=${drawn.d}
+        data-selected=${pickedKeys.has(key) ? '' : nothing}
+        data-tone=${element?.tone ?? nothing}
+        data-variant=${element?.variant ?? nothing}
+        fill="none"
+        marker-end=${ends.end ? `url(#${ARROW})` : nothing}
+        marker-start=${ends.start ? `url(#${ARROW})` : nothing}
+        style=${custom(element, '--canvas-edge-color') ? `--_canvas-edge-color: ${custom(element, '--canvas-edge-color')}` : nothing}
+      />`}
+`;
+    }
+    assign() {
+        if (!this.childrenKnown) {
+            return;
+        }
+        const cards = new Map();
+        for (const card of this.cards) {
+            if (!cards.has(card.name)) {
+                cards.set(card.name, card);
+            }
+        }
+        const placed = new Map();
+        for (const [at, one] of this.walk.filter((stop) => stop.kind === 'node').entries()) {
+            const card = cards.get(one.key);
+            if (card) {
+                placed.set(card, `card-${at}`);
+            }
+        }
+        if (this.assignsByName) {
+            for (const card of this.cards) {
+                this.route(card, placed.get(card));
+            }
+            return;
+        }
+        const root = this.renderRoot;
+        const rest = [];
+        const named = new Map();
+        for (const child of this.knownChildren) {
+            const name = placed.get(child) ?? child.getAttribute('slot') ?? undefined;
+            if (name === undefined) {
+                rest.push(child);
+            }
+            else {
+                named.set(name, [...(named.get(name) ?? []), child]);
+            }
+        }
+        for (const slot of root?.querySelectorAll?.('slot') ?? []) {
+            const wanted = slot.name === '' ? rest : (named.get(slot.name) ?? []);
+            const had = slot.assignedNodes();
+            if (had.length !== wanted.length || had.some((one, at) => one !== wanted[at])) {
+                slot.assign?.(...wanted);
+            }
+        }
+    }
     renderLabels(origin) {
         return this.edges.map((edge) => {
             const lifted = this.linking?.edge === this.keyOf(edge) && !this.linking.pressed;
@@ -1903,6 +1983,7 @@ let HelixHeadlessCanvas = class HelixHeadlessCanvas extends MixinViewport(HelixE
           @focusin=${this.handleFocusIn}
         >
           ${this.renderEdges(origin, box)} ${this.renderLabels(origin)}
+          ${this.renderStops(origin, box)}
           <slot @slotchange=${this.handleSlotChange}></slot>
           ${this.renderEnds(origin)}
           ${this.renderEditor(origin)}
@@ -1962,7 +2043,7 @@ __decorate([
     property({ attribute: 'stopped-label' })
 ], HelixHeadlessCanvas.prototype, "stoppedLabel", void 0);
 __decorate([
-    property({ attribute: 'tone-labels', type: Object })
+    property({ attribute: 'tone-labels', converter: wordsConverter })
 ], HelixHeadlessCanvas.prototype, "toneLabels", void 0);
 __decorate([
     state()

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

@@ -12,12 +12,19 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * 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`. 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. **A named card is a group**, so a
+ * Name the card with `label`, as a Stat Group is named, or 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. `label` is set through `ElementInternals`, so it writes no
+ * attribute onto the card. **A named card is a group**, so a
  * reader entering it hears its name; an unnamed one has no role, since a group
  * with no name only adds "group" to what a reader says.
  *
+ * Each region's slot is a part of the same name, `body` for the main content,
+ * as Web Awesome's card names its regions. A slot draws no box, so a part
+ * passes inherited properties to what is slotted, and a page wanting a box
+ * there gives it one with `display`.
+ *
  * `header-actions` and `footer-actions` hold controls at the end of the
  * header's and the footer's line, as Web Awesome's card does. While one holds
  * something, its line is a `header-row` or `footer-row` part; otherwise there
@@ -37,10 +44,24 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @slot header-actions - Controls for the whole card at the end of the header's line, such as a menu.
  * @slot media - Image, video, or chart that runs edge to edge, outside the inset.
  *
+ * @csspart body - The slot the main content arrives through. A slot draws no box, so it passes inherited properties, such as color and font, to the content; `display: block` gives it one.
+ * @csspart footer - The slot the footer arrives through, drawing no box, as `body` does.
+ * @csspart footer-actions - The slot the footer's controls arrive through, drawing no box, as `body` does.
  * @csspart footer-row - The line holding `footer` and `footer-actions`, drawn only while `footer-actions` holds something.
+ * @csspart header - The slot the header arrives through, drawing no box, as `body` does.
+ * @csspart header-actions - The slot the header's controls arrive through, drawing no box, as `body` does.
  * @csspart header-row - The line holding `header` and `header-actions`, drawn only while `header-actions` holds something.
+ * @csspart media - The slot the media arrives through, drawing no box, as `body` does.
  */
 export declare class HelixHeadlessCard extends HelixElement {
+    /**
+     * The card's accessible name, which makes it a named group.
+     *
+     * The name `Stat.Group` and the other named regions take, set through
+     * `ElementInternals`. `aria-label` and `aria-labelledby` written on the card
+     * name it too, and win over this, as an author's attribute does.
+     */
+    label: string;
     /**
      * Places the media after the content. By default it comes before.
      *

package/dist/card/root/card-root.js

@@ -10,6 +10,7 @@ import { property, state } from 'lit/decorators.js';
 let HelixHeadlessCard = class HelixHeadlessCard extends HelixElement {
     constructor() {
         super(...arguments);
+        this.label = '';
         this.labelledBy = null;
         this.namedBy = null;
         this.footerActions = false;
@@ -22,26 +23,37 @@ let HelixHeadlessCard = class HelixHeadlessCard extends HelixElement {
     }
     willUpdate(changed) {
         super.willUpdate(changed);
-        const named = Boolean(this.namedBy?.trim() || this.labelledBy?.trim());
-        hostAria(this.internals, { role: named ? 'group' : '' });
+        const named = Boolean(this.label.trim() || this.namedBy?.trim() || this.labelledBy?.trim());
+        hostAria(this.internals, { label: this.label, role: named ? 'group' : '' });
     }
     updated(changed) {
         super.updated(changed);
         this.readActions();
     }
     render() {
-        const header = html `<slot name="header"></slot
-      ><slot name="header-actions" @slotchange=${this.readActions}></slot>`;
-        const footer = html `<slot name="footer"></slot
-      ><slot name="footer-actions" @slotchange=${this.readActions}></slot>`;
+        const header = html `<slot name="header" part="header"></slot
+      ><slot
+        name="header-actions"
+        part="header-actions"
+        @slotchange=${this.readActions}
+      ></slot>`;
+        const footer = html `<slot name="footer" part="footer"></slot
+      ><slot
+        name="footer-actions"
+        part="footer-actions"
+        @slotchange=${this.readActions}
+      ></slot>`;
         return html `
-      <slot name="media"></slot>
+      <slot name="media" part="media"></slot>
       ${this.headerActions ? html `<div part="header-row">${header}</div>` : header}
-      <slot></slot>
+      <slot part="body"></slot>
       ${this.footerActions ? html `<div part="footer-row">${footer}</div>` : footer}
     `;
     }
 };
+__decorate([
+    property()
+], HelixHeadlessCard.prototype, "label", void 0);
 __decorate([
     property({ attribute: 'media-placement', reflect: true })
 ], HelixHeadlessCard.prototype, "mediaPlacement", void 0);