@fusion.dev/helix-headless 0.145.0 → 0.147.0

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

@@ -4,9 +4,10 @@ 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 { AriaForwardController, customElement, drawStatus, elementById, HelixFallbackCommandEvent, HelixFormElement, StatusController, supportsInvokers, } from '@fusion.dev/helix-core';
+import { AriaForwardController, customElement, defaultButton, drawStatus, elementById, HelixFallbackCommandEvent, HelixFormElement, HelixPressEvent, pressType, StatusController, submitsOnEnter, supportsInvokers, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
+import { submitAs } from '../submitter.js';
 let HelixHeadlessButton = class HelixHeadlessButton extends HelixFormElement {
     constructor() {
         super(...arguments);
@@ -27,27 +28,23 @@ let HelixHeadlessButton = class HelixHeadlessButton extends HelixFormElement {
         this.pending = false;
         this.pendingLabel = 'Loading';
         this.status = new StatusController(this);
+        this.recent = {};
+        this.notePress = (event) => {
+            if (event.type === 'pointerdown') {
+                this.recent = { pointer: event.pointerType };
+            }
+            else if (event.key === 'Enter' || event.key === ' ') {
+                this.recent = { key: true };
+            }
+        };
         this.handleClick = (event) => {
             if (this.pending) {
                 event.preventDefault();
                 event.stopImmediatePropagation();
                 return;
             }
-            this.linkCommand();
-            this.sendCommand();
-            if (this.type === 'button') {
-                return;
-            }
-            const { form } = this;
-            if (!form) {
-                return;
-            }
-            if (this.type === 'submit') {
-                this.submit(form);
-            }
-            else {
-                form.reset();
-            }
+            this.act();
+            this.announcePress(event);
         };
         this.type = 'button';
         this.value = '';
@@ -57,8 +54,8 @@ let HelixHeadlessButton = class HelixHeadlessButton extends HelixFormElement {
             if (event.key !== 'Enter' ||
                 event.defaultPrevented ||
                 !form ||
-                !HelixFormElement.submitsOnEnter(event.composedPath()[0], form) ||
-                HelixFormElement.defaultButton(form) !== this) {
+                !submitsOnEnter(event.composedPath()[0], form) ||
+                defaultButton(form) !== this) {
                 return;
             }
             event.preventDefault();
@@ -84,44 +81,31 @@ let HelixHeadlessButton = class HelixHeadlessButton extends HelixFormElement {
         ...HelixFormElement.shadowRootOptions,
         delegatesFocus: true,
     }; }
-    submit(form) {
-        const undo = [];
-        const override = (attribute, value) => {
-            if (value === null) {
-                return;
-            }
-            const had = form.getAttribute(attribute);
-            form.setAttribute(attribute, value);
-            undo.push(() => {
-                if (had === null) {
-                    form.removeAttribute(attribute);
-                }
-                else {
-                    form.setAttribute(attribute, had);
-                }
-            });
-        };
-        override('action', this.formAction || null);
-        override('enctype', this.formEnctype || null);
-        override('method', this.formMethod || null);
-        override('novalidate', this.formNoValidate ? '' : null);
-        override('target', this.formTarget || null);
-        const reports = this.name !== '';
-        if (reports) {
-            this.internals.setFormValue(this.value);
+    announcePress(click) {
+        const pointerType = pressType(click, this.recent);
+        this.recent = {};
+        this.dispatchEvent(new HelixPressEvent({ pointerType }));
+    }
+    act() {
+        this.linkCommand();
+        this.sendCommand();
+        if (this.type === 'button') {
+            return;
         }
-        try {
-            form.requestSubmit();
+        const { form } = this;
+        if (!form) {
+            return;
         }
-        finally {
-            for (const put of undo) {
-                put();
-            }
-            if (reports) {
-                this.internals.setFormValue(null);
-            }
+        if (this.type === 'submit') {
+            this.submit(form);
+        }
+        else {
+            form.reset();
         }
     }
+    submit(form) {
+        submitAs(form, this);
+    }
     get commandForElement() {
         const button = this.renderRoot?.querySelector('button');
         return button?.commandForElement ?? this.commandTarget();
@@ -201,10 +185,15 @@ let HelixHeadlessButton = class HelixHeadlessButton extends HelixFormElement {
       tabindex=${stop}
       ?disabled=${this.isDisabled}
       @click=${this.handleClick}
+      @keydown=${this.notePress}
+      @pointerdown=${this.notePress}
     >
-      ${label}
+      ${label}${this.renderSpinner()}
     </button>${this.renderLive()}`;
     }
+    renderSpinner() {
+        return this.pending ? html `<span part="spinner" aria-hidden="true"></span>` : nothing;
+    }
 };
 __decorate([
     property()

package/dist/button/submitter.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Submitting a form through a native submit button that stands in for one in a
+ * shadow root.
+ *
+ * `requestSubmit(submitter)` takes only a native submit button whose form is
+ * the form, and a button inside a shadow root is neither. A hidden native
+ * `<button type="submit">` carrying the same name, value and `form*`
+ * overrides is put into the form for the one synchronous call, as Shoelace and
+ * Web Awesome do, so the platform does the rest: `event.submitter` is a
+ * button with the name and value, `new FormData(form, event.submitter)`
+ * includes them, and the overrides apply to that submission alone.
+ */
+/** What a submit button carries into the submission it starts. */
+export interface Carried {
+    formAction: string;
+    formEnctype: string;
+    formMethod: string;
+    formNoValidate: boolean;
+    formTarget: string;
+    name: string;
+    value: string;
+}
+/**
+ * Submits `form` as a native submit button carrying `carried` would, and takes
+ * that button out again whether or not a listener refused the submission.
+ */
+export declare const submitAs: (form: HTMLFormElement, carried: Carried) => void;

package/dist/button/submitter.js

@@ -0,0 +1,25 @@
+export const submitAs = (form, carried) => {
+    const stand = form.ownerDocument.createElement('button');
+    stand.type = 'submit';
+    stand.hidden = true;
+    for (const [attribute, value] of [
+        ['formaction', carried.formAction],
+        ['formenctype', carried.formEnctype],
+        ['formmethod', carried.formMethod],
+        ['formtarget', carried.formTarget],
+        ['name', carried.name],
+    ]) {
+        if (value !== '') {
+            stand.setAttribute(attribute, value);
+        }
+    }
+    stand.value = carried.value;
+    stand.formNoValidate = carried.formNoValidate;
+    form.append(stand);
+    try {
+        form.requestSubmit(stand);
+    }
+    finally {
+        stand.remove();
+    }
+};

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.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';
@@ -2043,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,18 +12,31 @@ 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
  * is no wrapper and every region is a bare slot. A server cannot see slotted
  * content, so served actions sit on their own line until the script runs.
  *
+ * **The card says which regions it holds**, as `:state(has-media)`,
+ * `:state(has-header)` and `:state(has-footer)`, so a sheet can draw a card
+ * with a header differently, as Web Awesome's `with-header` does, with no
+ * attribute written onto the card. Read in the browser, so a served card
+ * carries none until the script runs.
+ *
  * @since 0.1.0
  * @status stable
  * @category layout
@@ -37,10 +50,28 @@ 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.
+ *
+ * @cssstate has-footer - Something is slotted into `footer` or `footer-actions`.
+ * @cssstate has-header - Something is slotted into `header` or `header-actions`.
+ * @cssstate has-media - Something is slotted into `media`.
  */
 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.
      *
@@ -71,7 +102,8 @@ export declare class HelixHeadlessCard extends HelixElement {
     private headerActions;
     protected willUpdate(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
-    private readonly readActions;
+    protected firstUpdated(changed: PropertyValues): void;
+    private readonly readRegions;
     protected render(): TemplateResult;
 }
 declare global {

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

@@ -10,38 +10,57 @@ 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;
         this.headerActions = false;
-        this.readActions = () => {
+        this.readRegions = () => {
             const filled = (name) => slotFilled(this.renderRoot?.querySelector(`slot[name="${name}"]`));
             this.headerActions = filled('header-actions');
             this.footerActions = filled('footer-actions');
+            this.toggleState('has-media', filled('media'));
+            this.toggleState('has-header', this.headerActions || filled('header'));
+            this.toggleState('has-footer', this.footerActions || filled('footer'));
         };
     }
     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();
+        this.readRegions();
+    }
+    firstUpdated(changed) {
+        super.firstUpdated(changed);
+        this.renderRoot.addEventListener('slotchange', this.readRegions);
     }
     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.readRegions}
+      ></slot>`;
+        const footer = html `<slot name="footer" part="footer"></slot
+      ><slot
+        name="footer-actions"
+        part="footer-actions"
+        @slotchange=${this.readRegions}
+      ></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);

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

@@ -24,10 +24,30 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * polite live region. While the carousel rotates the region is off, so a
  * screen reader is not interrupted every few seconds.
  *
- * The indicators are one tab stop. The arrow keys along the track move between
- * them, Up and Down on a vertical carousel, and Home and End go to the first
- * and the last. Without `loop`, Previous on the first slide and Next on the
- * last are marked `aria-disabled`.
+ * **Keyboard.** The indicators are one tab stop.
+ *
+ * | Key | What it does |
+ * |---|---|
+ * | Tab | Moves through the rotation control, Previous, Next, the slides' own links and buttons, and the indicators, in that order. |
+ * | Enter, Space | Presses the control or the indicator that has focus. |
+ * | Right, Left | On an indicator, moves to the next or the previous slide and its indicator. Left moves on, on a right-to-left page. |
+ * | Down, Up | The same, on a vertical carousel. |
+ * | Home, End | On an indicator, moves to the first or the last slide. |
+ *
+ * Without `loop`, Previous on the first slide and Next on the last are marked
+ * `aria-disabled`, and keep focus.
+ *
+ * **What a screen reader hears.** The carousel is a group named by `label`,
+ * announced as `role-label` ("carousel"). Each slide is a group announced as
+ * `slide-role-label` ("slide") and named by `slide-label` ("2 of 5"). After a
+ * move by a control, an indicator, a key, or a drag, the `live` part says the
+ * slide's name politely. While the carousel rotates the region is off.
+ *
+ * **`slides-per-move` moves several slides at a time.** With `per-view="3"`
+ * and `slides-per-move="3"`, Next shows the next three, there is one
+ * indicator for each stop, and the track snaps only at the stops. The last
+ * stop is always the end of the run, so a run that does not divide evenly
+ * ends on its last slides. Unset moves one slide.
  *
  * **`mouse-drag` lets a mouse drag the track**, which otherwise only a touch
  * screen, a trackpad, or the scroll wheel moves. The drag follows the pointer
@@ -282,6 +302,12 @@ export declare class HelixHeadlessCarousel extends HelixElement {
      * `aria-roledescription`. Translate it with the rest of your text.
      */
     slideRoleLabel: string;
+    /**
+     * How many slides Previous, Next, the indicators, rotation, and a drag move
+     * at a time. Unset moves one. The track stops at every `slides-per-move`th
+     * position from the first, and at the last.
+     */
+    slidesPerMove?: number;
     /**
      * The name of the rotation control while rotation is stopped.
      */
@@ -350,6 +376,8 @@ export declare class HelixHeadlessCarousel extends HelixElement {
      * withheld rather than counted from it. See `across`.
      */
     get positions(): number;
+    /** The positions the track stops at, `slides-per-move` apart, and the last. See `stopsOf`. */
+    private get stops();
     /**
      * How many slides the box turned out to hold, from the pane it laid out.
      *
@@ -494,6 +522,11 @@ export declare class HelixHeadlessCarousel extends HelixElement {
      * sends neither, being a correction rather than a move anybody asked for.
      */
     private applyIndex;
+    /**
+     * The position one stop forward or back lands on, wrapping where `loop`
+     * says so.
+     */
+    private move;
     /** Moves to a slide. It wraps past either end only when `loop` is set. */
     goTo(index: number): void;
     /**
@@ -795,6 +828,12 @@ export declare class HelixHeadlessCarousel extends HelixElement {
      * is slotted. A tier above overrides this to draw its own caret.
      */
     protected renderNextMark(): TemplateResult;
+    /**
+     * A pane's own declarations: the last pane's `runEnd`, and no snap point on
+     * a pane the track does not stop at under `slides-per-move`, so a swipe
+     * settles on a stop as the controls do.
+     */
+    private paneStyle;
     protected render(): TemplateResult;
 }
 declare global {