@fusion.dev/helix-headless 0.143.0 → 0.145.0

package/dist/toast/item/toast-item.d.ts

@@ -1,4 +1,4 @@
-import { HelixElement, type ToneMark } from '@fusion.dev/helix-core';
+import { HelixElement, SwipeController, type ToneMark } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessToastItem_base: (new (...args: any[]) => import("@fusion.dev/helix-core").DismissibleElement) & typeof HelixElement;
 /**
@@ -12,6 +12,16 @@ declare const HelixHeadlessToastItem_base: (new (...args: any[]) => import("@fus
  * with each new message, and the last of three messages would stay for nine
  * seconds.
  *
+ * **Each message is an `alertdialog` named by its words**, which is how a reader
+ * who moves into the stack hears which message they are on. A `danger` message
+ * is its own assertive live region, so it is announced at once; every other one
+ * is announced politely by the region.
+ *
+ * A touch or a pen swipes a message toward the end of the line, and past
+ * halfway, or quickly, dismisses it through the same `helix-dismiss` as its
+ * control. While it moves, the distance is on the `item` part as
+ * `--toast-swipe-x`.
+ *
  * **Messages are inverted by default.** The item flips `color-scheme`, so a new
  * message stands out from the page without using a color that carries meaning.
  *
@@ -39,6 +49,7 @@ declare const HelixHeadlessToastItem_base: (new (...args: any[]) => import("@fus
  * @csspart timer - The bar showing how long is left, where a duration was given.
  *
  * @cssproperty --toast-duration - How long this message stays, in milliseconds, for a progress hint.
+ * @cssproperty --toast-swipe-x - How far a swipe has moved the message across, in pixels, toward the right.
  */
 export declare class HelixHeadlessToastItem extends HelixHeadlessToastItem_base {
     /**
@@ -64,11 +75,19 @@ export declare class HelixHeadlessToastItem extends HelixHeadlessToastItem_base
      */
     get open(): boolean;
     set open(next: boolean);
-    /** When the current run of the timer began, or nothing while it is paused. */
-    private startedAt;
-    /** What is left of the duration, so resuming continues rather than restarts. */
-    private remaining;
-    private timer;
+    protected readonly swipes: SwipeController;
+    /** Writes how far a swipe has moved the message toward the end of the line. */
+    private slide;
+    /**
+     * The dismiss timer, which pauses while a reader is on the message and
+     * continues from what was left.
+     *
+     * Paused is said on the host so the indicator can freeze with the clock. A
+     * `data-` attribute rather than a property, because it is written after
+     * upgrade from a pointer moving: nothing declares it and no server rendered
+     * it, which is the same reason `Carousel` names its slides from here.
+     */
+    private readonly countdown;
     /**
      * The kind of message, which sets its mark and the mark's accessible name.
      *
@@ -90,22 +109,11 @@ export declare class HelixHeadlessToastItem extends HelixHeadlessToastItem_base
     pause(): void;
     /** Restarts the dismiss timer from where it paused. */
     resume(): void;
-    /**
-     * How many reasons there are to hold the clock, rather than whether there is
-     * one.
-     *
-     * Hover and focus stop the same timer, and the two are genuinely independent:
-     * a pointer can leave while focus stays, and focus can leave while the
-     * pointer stays. Uncounted, a reader who tabs into a message and then moves
-     * the pointer off it has the clock restarted underneath them, which is the
-     * case the pause exists for. Only the last one out starts it again.
-     */
-    private holds;
     private readonly handlePause;
     private readonly handleResume;
     connectedCallback(): void;
-    disconnectedCallback(): void;
     protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
     protected firstUpdated(changed: PropertyValues): void;
     /**
      * The mark for the message's tone, behind a seam.

package/dist/toast/item/toast-item.js

@@ -4,25 +4,47 @@ 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, MixinDismissible, requestChange, toneMark, } from '@fusion.dev/helix-core';
-import { x } from '@fusion.dev/helix-icons';
+import { CountdownController, customElement, drawDismiss, drawDismissGlyph, HelixElement, hostAria, isRtl, MixinDismissible, requestChange, SwipeController, settleSwipe, swipeEdge, toneMark, towardEdge, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
 let HelixHeadlessToastItem = class HelixHeadlessToastItem extends MixinDismissible(HelixElement) {
     constructor() {
         super(...arguments);
+        this.swipes = new SwipeController(this, {
+            axis: () => (this.open ? 'x' : undefined),
+            end: (dx, _dy, vx) => {
+                const edge = swipeEdge('end', isRtl(this));
+                const width = this.partNamed('item')?.getBoundingClientRect().width ?? 0;
+                const shown = settleSwipe({
+                    points: [1],
+                    size: width,
+                    travel: Math.max(0, towardEdge(edge, dx, 0)),
+                    velocity: towardEdge(edge, vx, 0),
+                });
+                if (shown === 0 && this.dismiss()) {
+                    return;
+                }
+                this.slide(0);
+            },
+            move: (dx) => this.slide(Math.max(0, towardEdge(swipeEdge('end', isRtl(this)), dx, 0))),
+            start: (_target, event) => event.pointerType !== 'mouse',
+            surface: () => this.partNamed('item'),
+        });
+        this.countdown = new CountdownController(this, {
+            done: () => {
+                this.dismiss();
+            },
+            paused: (paused) => {
+                this.toggleAttribute('data-paused', paused);
+            },
+        });
         this.openState = undefined;
-        this.holds = 0;
         this.handlePause = () => {
-            this.holds += 1;
-            this.pause();
+            this.countdown.hold();
         };
         this.handleResume = () => {
-            this.holds = Math.max(this.holds - 1, 0);
-            if (this.holds === 0) {
-                this.resume();
-            }
+            this.countdown.release();
         };
     }
     get open() {
@@ -33,12 +55,15 @@ let HelixHeadlessToastItem = class HelixHeadlessToastItem extends MixinDismissib
         this.openState = next;
         this.requestUpdate('open', previous);
     }
+    slide(travel) {
+        const physical = isRtl(this) ? -travel : travel;
+        this.partNamed('item')?.style.setProperty('--toast-swipe-x', travel === 0 ? '' : `${Math.round(physical)}px`);
+    }
     dismiss() {
         if (!this.open) {
             return true;
         }
-        clearTimeout(this.timer);
-        this.timer = undefined;
+        this.countdown.cancel();
         return requestChange({
             apply: () => {
                 const previous = this.open;
@@ -51,25 +76,10 @@ let HelixHeadlessToastItem = class HelixHeadlessToastItem extends MixinDismissib
         });
     }
     pause() {
-        if (this.timer === undefined || this.startedAt === undefined) {
-            return;
-        }
-        clearTimeout(this.timer);
-        this.timer = undefined;
-        this.remaining = Math.max((this.remaining ?? 0) - (Date.now() - this.startedAt), 0);
-        this.startedAt = undefined;
-        this.toggleAttribute('data-paused', true);
+        this.countdown.pause();
     }
     resume() {
-        if (this.timer !== undefined || this.remaining === undefined || this.remaining <= 0) {
-            return;
-        }
-        this.startedAt = Date.now();
-        this.toggleAttribute('data-paused', false);
-        this.timer = setTimeout(() => {
-            this.timer = undefined;
-            this.dismiss();
-        }, this.remaining);
+        this.countdown.resume();
     }
     connectedCallback() {
         super.connectedCallback();
@@ -77,22 +87,24 @@ let HelixHeadlessToastItem = class HelixHeadlessToastItem extends MixinDismissib
             this.resume();
         }
     }
-    disconnectedCallback() {
-        super.disconnectedCallback();
-        this.pause();
-        this.holds = 0;
-    }
     willUpdate(changed) {
         super.willUpdate(changed);
         this.toggleAttribute('data-closed', !this.open);
         this.toggleAttribute('hidden', !this.open);
+        hostAria(this.internals, { role: 'alertdialog' });
+        this.internals.ariaModal = 'false';
+        this.internals.ariaLive = this.tone === 'danger' ? 'assertive' : null;
+    }
+    updated(changed) {
+        super.updated(changed);
+        const words = this.partNamed('content');
+        if (words) {
+            hostAria(this.internals, { labelledBy: [words] });
+        }
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
-        if (this.duration !== undefined && this.duration > 0) {
-            this.remaining = this.duration;
-            this.resume();
-        }
+        this.countdown.start(this.duration);
     }
     renderIcon(mark) {
         return html `<slot name="icon">
@@ -108,9 +120,7 @@ let HelixHeadlessToastItem = class HelixHeadlessToastItem extends MixinDismissib
     }
     renderDismissIcon() {
         return html `<slot name="dismiss-icon">
-      <svg part="dismiss-mark" viewBox=${x.viewBox} fill="currentColor" aria-hidden="true">
-        ${unsafeSVG(x.content)}
-      </svg>
+      ${drawDismissGlyph()}
     </slot>`;
     }
     render() {
@@ -130,14 +140,11 @@ let HelixHeadlessToastItem = class HelixHeadlessToastItem extends MixinDismissib
       <div part="content"><slot></slot></div>
       <div part="actions"><slot name="actions"></slot></div>
       ${this.dismissible
-            ? html `<button
-              part="dismiss"
-              type="button"
-              aria-label=${this.dismissLabel}
-              @click=${() => this.dismiss()}
-            >
-              ${this.renderDismissIcon()}
-            </button>`
+            ? drawDismiss({
+                label: this.dismissLabel,
+                mark: this.renderDismissIcon(),
+                onDismiss: () => this.dismiss(),
+            })
             : nothing}
       ${this.duration
             ? html `<div

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

@@ -9,9 +9,15 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * announce a region that arrives already holding its message. `Radio.Group` is
  * part of its family for the same reason.
  *
- * **The region is polite, never assertive.** `role="alert"` interrupts whatever
- * a screen reader is reading. For something that cannot wait, use a `Dialog`,
- * which stops the page for every user.
+ * **The region is a landmark named by `label`, and a polite live region.** A
+ * `danger` message is announced assertively, and every other one politely.
+ * Each message is an `alertdialog` named by its words, so a reader who moves
+ * into the stack hears which message they are on.
+ *
+ * **`hotkey` takes focus to the stack and back**, F8 unless you set it, and
+ * `label` says which key: `{hotkey}` in it is filled in, so the default name
+ * is "Notifications (F8)". Pressed while focus is in the stack, it gives focus
+ * back to where it was.
  *
  * **The region never creates or removes items.** You render items and remove
  * them. An item requests closing with a cancelable `helix-dismiss` event. A
@@ -19,9 +25,11 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * and the DOM stay in sync. It hides on its own unless you set `open`, which
  * makes the state yours.
  *
- * There is no `toast.show()`. For a `toast()` function, write a small one over
- * your app's state, which also lets you render the same messages on the server,
- * in a test, or more than once.
+ * **`add()` shows a message from script**, for a page with no framework state
+ * to render them from: it appends a message of the region's own tier and
+ * removes it once it has been dismissed and has finished leaving. Messages
+ * you render yourself stay yours, and the region never removes them. A touch
+ * or a pen swipes a message away toward the end of the line.
  *
  * **The stack is in the top layer.** The `region` part is a `popover="manual"`
  * shown while a message is showing, and shown again above a modal dialog that
@@ -46,11 +54,17 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  *
  * @event {HelixDismissEvent} helix-dismiss - A message is being dismissed, by its control or by its timer. The message sends it, and you can listen for it on the region. Cancelable: canceling it keeps the message.
  *
- * @csspart region - The stack the messages are in. It is in the top layer while a message shows.
+ * @csspart region - The stack the messages are in. It is in the top layer while a message shows, and takes focus from `hotkey` where no message holds a control.
  */
 export declare class HelixHeadlessToast extends HelixElement {
     /**
-     * Accessible name for the region, such as "Notifications".
+     * The key that takes focus to the stack and back, such as `F8` or `Alt+T`:
+     * keys joined by `+`, the last one the key. Empty turns it off.
+     */
+    hotkey: string;
+    /**
+     * Accessible name for the region, with `{hotkey}` filled in. Translate it with
+     * the rest of your interface.
      */
     label: string;
     /**
@@ -83,6 +97,26 @@ export declare class HelixHeadlessToast extends HelixElement {
     protected willUpdate(changed: PropertyValues): void;
     /** The element focus came from when it entered the stack. */
     private focusOrigin;
+    private readonly scope;
+    /** Takes focus to the stack and back, on `hotkey`. */
+    private readonly handleHotkey;
+    /** Messages `add()` made, which are the region's to remove. */
+    private readonly made;
+    /**
+     * Shows a message from script, and returns the element.
+     *
+     * The message is the region's own tier of `Toast.Item`, appended to the
+     * stack, holding `message` as its text. The region removes it once it has
+     * been dismissed and has finished leaving, which is the one case where it
+     * removes anything: a message you render stays yours.
+     */
+    add(message: string, options?: {
+        dismissible?: boolean;
+        duration?: number;
+        tone?: 'danger' | 'info' | 'success' | 'warning';
+    }): HTMLElement;
+    /** Removes a message `add()` made, once it has hidden and finished leaving. */
+    private sweep;
     /** Watches the messages arrive and hide, to raise or lower the stack. */
     private watcher;
     /** The messages that are showing, in order. */

package/dist/toast/root/toast-root.js

@@ -4,13 +4,37 @@ 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, deepActiveElement, deepContains, focusableElements, HelixElement, hostAria, scrollHolders, } from '@fusion.dev/helix-core';
+import { customElement, deepActiveElement, deepContains, FocusScopeController, fillTemplate, focusableElements, HelixElement, hostAria, scrollHolders, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
+import { matchesHotkey, parseHotkey } from '../hotkey.js';
 let HelixHeadlessToast = class HelixHeadlessToast extends HelixElement {
     constructor() {
         super(...arguments);
-        this.label = 'Notifications';
+        this.hotkey = 'F8';
+        this.label = 'Notifications ({hotkey})';
+        this.scope = new FocusScopeController(this, {
+            contents: () => this.showing.flatMap((one) => {
+                const target = focusTarget(one);
+                return target ? [target] : [];
+            }),
+            surface: () => this.region,
+        });
+        this.handleHotkey = (event) => {
+            if (event.defaultPrevented || !matchesHotkey(event, parseHotkey(this.hotkey))) {
+                return;
+            }
+            if (this.scope.holdsFocus) {
+                event.preventDefault();
+                this.scope.leave();
+                return;
+            }
+            if (this.showing.length > 0) {
+                event.preventDefault();
+                this.scope.enter();
+            }
+        };
+        this.made = new WeakSet();
         this.handleFocusIn = (event) => {
             const from = event.relatedTarget;
             if (from instanceof HTMLElement && !deepContains(this, from)) {
@@ -57,11 +81,41 @@ let HelixHeadlessToast = class HelixHeadlessToast extends HelixElement {
     }
     willUpdate(changed) {
         super.willUpdate(changed);
-        hostAria(this.internals, { label: this.label, role: 'status' });
+        hostAria(this.internals, {
+            label: fillTemplate(this.label, { hotkey: this.hotkey }),
+            role: 'region',
+        });
         this.internals.ariaLive = 'polite';
         this.internals.ariaRelevant = 'additions';
         this.internals.ariaAtomic = 'false';
     }
+    add(message, options = {}) {
+        const tier = this.constructor.tier;
+        const item = document.createElement(`${tier}toast-item`);
+        item.textContent = message;
+        if (options.tone) {
+            item.setAttribute('tone', options.tone);
+        }
+        if (options.duration !== undefined) {
+            item.setAttribute('duration', String(options.duration));
+        }
+        if (options.dismissible ?? true) {
+            item.toggleAttribute('dismissible', true);
+        }
+        this.made.add(item);
+        this.append(item);
+        return item;
+    }
+    sweep() {
+        for (const one of [...this.children]) {
+            if (!(one instanceof HTMLElement) || !one.hidden || !this.made.has(one)) {
+                continue;
+            }
+            this.made.delete(one);
+            const running = typeof one.getAnimations === 'function' ? one.getAnimations({ subtree: true }) : [];
+            void Promise.allSettled(running.map((animation) => animation.finished)).then(() => one.remove());
+        }
+    }
     get showing() {
         return [...this.children].filter((one) => one instanceof HTMLElement && !one.hidden);
     }
@@ -129,8 +183,10 @@ let HelixHeadlessToast = class HelixHeadlessToast extends HelixElement {
         super.connectedCallback();
         this.addEventListener('focusin', this.handleFocusIn);
         this.addEventListener('helix-dismiss', this.handleDismiss);
+        document.addEventListener('keydown', this.handleHotkey);
         this.watcher = new MutationObserver((records) => {
             this.place(records.flatMap((record) => [...record.addedNodes]));
+            this.sweep();
         });
         this.watcher.observe(this, {
             attributeFilter: ['hidden'],
@@ -146,6 +202,7 @@ let HelixHeadlessToast = class HelixHeadlessToast extends HelixElement {
         super.disconnectedCallback();
         this.removeEventListener('focusin', this.handleFocusIn);
         this.removeEventListener('helix-dismiss', this.handleDismiss);
+        document.removeEventListener('keydown', this.handleHotkey);
         this.watcher?.disconnect();
         this.watcher = undefined;
     }
@@ -154,9 +211,12 @@ let HelixHeadlessToast = class HelixHeadlessToast extends HelixElement {
         this.place();
     }
     render() {
-        return html `<div part="region" popover="manual"><slot></slot></div>`;
+        return html `<div part="region" popover="manual" tabindex="-1"><slot></slot></div>`;
     }
 };
+__decorate([
+    property()
+], HelixHeadlessToast.prototype, "hotkey", void 0);
 __decorate([
     property()
 ], HelixHeadlessToast.prototype, "label", void 0);

package/dist/toggle/group/toggle-group.d.ts

@@ -14,6 +14,17 @@ declare const HelixHeadlessToggleGroup_base: (new (...args: any[]) => import("@f
  * Measurement happens on the client, so the server renders the indicator hidden
  * and it fades in once measured.
  *
+ * `selection-mode="multiple"` makes the group a toolbar of buttons that each
+ * say whether they are pressed with `aria-pressed`, as React Aria's
+ * ToggleButtonGroup and Radix's ToggleGroup do. A press presses or releases
+ * one item, the arrow keys move focus without pressing, and `value` is the
+ * pressed values, comma separated, which `values` also gives as a list. The
+ * form receives one entry per pressed value. The indicator stays hidden, and
+ * each pressed item is marked with `:state(pressed)`.
+ *
+ * `orientation="vertical"` runs the items down a column, says so to the
+ * accessibility tree, and the up and down arrows move between them.
+ *
  * @since 0.1.0
  * @status stable
  * @aliases SegmentedControl, Segmented, Navigation, Switcher
@@ -98,6 +109,11 @@ export declare class HelixHeadlessToggleGroup extends HelixHeadlessToggleGroup_b
      * goes to the first item that can be chosen, as in `Radio.Group`.
      */
     private entry;
+    /** The item focus was last on, in a toolbar, which holds its tab stop. */
+    private lastFocused;
+    private readonly noteFocus;
+    /** Whether several items can be pressed at once. */
+    private get multiple();
     /**
      * Whether the group holds a tab stop of its own.
      *
@@ -110,6 +126,37 @@ export declare class HelixHeadlessToggleGroup extends HelixHeadlessToggleGroup_b
      * reason to set it.
      */
     focusable: boolean;
+    /**
+     * Where the group's label sits. `start` puts it on the track's line.
+     *
+     * Absent is above, which is what a field looks like and what almost every
+     * group wants. `start` is for a row of controls that are labeled rather than
+     * a form of fields: a toolbar reads as one line, and a label stacked over
+     * every group in it turns one row into two.
+     *
+     * **A placement rather than a slot, and that is the whole point of it.** A
+     * `start` slot would let a consumer put the word there, and would also let
+     * them put it there *instead of* setting `label`, which is the group's
+     * accessible name: the set would then be named for nobody using a screen
+     * reader while looking correct to everybody else. Worse, setting both draws
+     * it twice. One property moves the label the consumer already has to give,
+     * and cannot be used to remove it.
+     */
+    labelPlacement?: 'start';
+    /**
+     * The direction the items run. `vertical` puts them in a column, and the up
+     * and down arrows move between them.
+     *
+     * Optional, so the attribute is absent until a consumer writes it.
+     */
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     * Whether one item is chosen, as a radio group, or several can be pressed,
+     * as a toolbar of buttons with `aria-pressed`.
+     *
+     * Optional, so the attribute is absent until a consumer writes it.
+     */
+    selectionMode?: 'multiple' | 'single';
     /**
      * Focus goes to the item that holds the stop, and to the item that would
      * hold it while a toolbar holds the stop instead, so a label press or a
@@ -132,6 +179,11 @@ export declare class HelixHeadlessToggleGroup extends HelixHeadlessToggleGroup_b
     protected firstUpdated(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
     protected willUpdate(changed: PropertyValues): void;
+    /**
+     * What the form receives: the value, or under `selection-mode="multiple"`
+     * one entry per pressed value, as a native `<select multiple>` sends.
+     */
+    private formValue;
     /**
      * The verdict on the answer `required` asks for.
      *
@@ -145,22 +197,12 @@ export declare class HelixHeadlessToggleGroup extends HelixHeadlessToggleGroup_b
      */
     private validate;
     /**
-     * Where the group's label sits. `start` puts it on the track's line.
-     *
-     * Absent is above, which is what a field looks like and what almost every
-     * group wants. `start` is for a row of controls that are labeled rather than
-     * a form of fields: a toolbar reads as one line, and a label stacked over
-     * every group in it turns one row into two.
-     *
-     * **A placement rather than a slot, and that is the whole point of it.** A
-     * `start` slot would let a consumer put the word there, and would also let
-     * them put it there *instead of* setting `label`, which is the group's
-     * accessible name: the set would then be named for nobody using a screen
-     * reader while looking correct to everybody else. Worse, setting both draws
-     * it twice. One property moves the label the consumer already has to give,
-     * and cannot be used to remove it.
+     * The pressed values as a list, under `selection-mode="multiple"`, in the
+     * order the items are written. Written, it presses exactly those items.
+     * Where one item is chosen, it is that one value, or none.
      */
-    labelPlacement?: 'start';
+    get values(): string[];
+    set values(next: string[]);
     /**
      * The row the track sits in, so something can sit beside it.
      *