@fusion.dev/helix-headless 0.142.1 → 0.144.0

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,24 @@ 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
+ * opened after it. Position the `region` part, which is the box in the top
+ * layer. While a modal `Dialog`, `Drawer` or `Lightbox` is open, the browser
+ * makes everything outside it inert, the stack included, so a message stays
+ * visible and its actions cannot be pressed. Where the browser has
+ * `ariaNotify`, a message that arrives then is announced through it. For a
+ * message with an action, render a second region inside the dialog.
+ *
+ * When a message with focus inside it is dismissed, focus moves to the next
+ * message, then the one before it, then back to where it was before it entered
+ * the stack.
  *
  * @since 0.1.0
  * @status stable
@@ -33,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.
+ * @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;
     /**
@@ -68,6 +95,76 @@ export declare class HelixHeadlessToast extends HelixElement {
      */
     placement?: 'bottom-center' | 'bottom-end' | 'bottom-start' | 'top-center' | 'top-end' | 'top-start';
     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. */
+    private get showing();
+    private get region();
+    /**
+     * Puts the stack in the top layer while a message shows, and on top of it.
+     *
+     * Shown again when a message arrives under a modal opened after it, because
+     * the top layer is ordered by when each element entered it. Only then,
+     * because showing it again starts every message's entrance over.
+     */
+    private place;
+    /**
+     * Takes the stack out of the top layer once the last message has finished
+     * leaving. Hidden at once, the stack would cut the exit short.
+     */
+    private lowerWhenStill;
+    /**
+     * Whether a modal dialog this stack is not inside is open, which makes the
+     * stack inert.
+     *
+     * Two places to look: the modal `Dialog` and `Drawer` the scroll lock
+     * records, whose `<dialog>` is in a shadow root, and an open modal `<dialog>`
+     * in the document itself.
+     */
+    private blocked;
+    /**
+     * Announces messages that arrived while the live region is inert.
+     *
+     * `ariaNotify` speaks without a live region in the accessibility tree, which
+     * is the one channel left under a modal. A browser without it says nothing,
+     * as it did before.
+     */
+    private notify;
+    /** Remembers where focus came from when it enters the stack. */
+    private readonly handleFocusIn;
+    /**
+     * Keeps focus on the stack when the message holding it goes.
+     *
+     * Read after the item's update, because the dismissal is a request a
+     * listener after this one can still refuse. A refused one leaves the
+     * message, and focus with it.
+     */
+    private readonly handleDismiss;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected firstUpdated(changed: PropertyValues): void;
     protected render(): TemplateResult;
 }
 declare global {

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

@@ -4,25 +4,219 @@ 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 { 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)) {
+                this.focusOrigin = from;
+            }
+        };
+        this.handleDismiss = (event) => {
+            const item = event.target;
+            if (!(item instanceof HTMLElement) || item.parentElement !== this) {
+                return;
+            }
+            if (!deepContains(item, deepActiveElement())) {
+                return;
+            }
+            const before = this.showing;
+            const at = before.indexOf(item);
+            void Promise.resolve()
+                .then(() => item.updateComplete)
+                .then(() => {
+                if (!item.hidden) {
+                    return;
+                }
+                const active = deepActiveElement();
+                if (active && active !== document.body && !deepContains(item, active)) {
+                    return;
+                }
+                const after = before.slice(at + 1).filter((one) => !one.hidden);
+                const earlier = before
+                    .slice(0, at)
+                    .filter((one) => !one.hidden)
+                    .reverse();
+                for (const next of [...after, ...earlier]) {
+                    const target = focusTarget(next);
+                    if (target) {
+                        target.focus();
+                        return;
+                    }
+                }
+                if (this.focusOrigin?.isConnected) {
+                    this.focusOrigin.focus();
+                }
+            });
+        };
     }
     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);
+    }
+    get region() {
+        return this.partNamed('region');
+    }
+    place(added = []) {
+        const region = this.region;
+        if (!region || typeof region.showPopover !== 'function') {
+            return;
+        }
+        const showing = this.showing;
+        const open = popoverOpen(region);
+        if (showing.length === 0) {
+            if (open) {
+                this.lowerWhenStill(region);
+            }
+            return;
+        }
+        const arrived = added.filter((one) => one instanceof HTMLElement && showing.includes(one));
+        const blocked = arrived.length > 0 && this.blocked();
+        if (open && blocked) {
+            region.hidePopover();
+        }
+        if (!open || blocked) {
+            region.showPopover();
+        }
+        if (blocked) {
+            this.notify(arrived);
+        }
+    }
+    lowerWhenStill(region) {
+        const running = typeof this.getAnimations === 'function' ? this.getAnimations({ subtree: true }) : [];
+        void Promise.allSettled(running.map((one) => one.finished)).then(() => {
+            if (this.showing.length === 0 && popoverOpen(region)) {
+                region.hidePopover();
+            }
+        });
+    }
+    blocked() {
+        const holders = scrollHolders();
+        try {
+            const native = document.querySelector('dialog:modal');
+            if (native) {
+                holders.push(native);
+            }
+        }
+        catch {
+        }
+        return holders.some((holder) => !deepContains(holder, this));
+    }
+    notify(arrived) {
+        const speaker = document;
+        if (typeof speaker.ariaNotify !== 'function') {
+            return;
+        }
+        for (const one of arrived) {
+            const words = (one.textContent ?? '').replace(/\s+/gu, ' ').trim();
+            if (words !== '') {
+                speaker.ariaNotify(words);
+            }
+        }
+    }
+    connectedCallback() {
+        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'],
+            attributes: true,
+            childList: true,
+            subtree: true,
+        });
+        if (this.hasUpdated) {
+            this.place();
+        }
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.removeEventListener('focusin', this.handleFocusIn);
+        this.removeEventListener('helix-dismiss', this.handleDismiss);
+        document.removeEventListener('keydown', this.handleHotkey);
+        this.watcher?.disconnect();
+        this.watcher = undefined;
+    }
+    firstUpdated(changed) {
+        super.firstUpdated(changed);
+        this.place();
+    }
     render() {
-        return html `<div part="region"><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);
@@ -33,3 +227,14 @@ HelixHeadlessToast = __decorate([
     customElement('helix-headless-toast')
 ], HelixHeadlessToast);
 export { HelixHeadlessToast };
+const popoverOpen = (region) => {
+    try {
+        return region.matches(':popover-open');
+    }
+    catch {
+        return false;
+    }
+};
+const focusTarget = (item) => item.shadowRoot?.querySelector('[part="dismiss"]') ??
+    focusableElements(item)[0] ??
+    null;

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
@@ -21,10 +32,13 @@ declare const HelixHeadlessToggleGroup_base: (new (...args: any[]) => import("@f
  *
  * @slot - The group's items.
  * @slot end - Content after the track, on the same line, such as a count or a reset.
+ * @slot feedback - The message that says what is wrong, for content richer than a string. It shows while there is a message.
+ * @slot hint - Help under the control, for content richer than the `hint` text.
+ * @slot label - The label, for content richer than the `label` text.
  * @slot start - Content before the track, on the same line, such as an icon or a caption.
  *
  * @event {Event} change - Fired after the value changes.
- * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the choice changes. Cancelable: call `preventDefault()` to keep the current choice. It is the only way to block a change.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the choice changes. Cancelable: call `preventDefault()` to keep the current choice.
  * @event {HelixSelectEvent} helix-select - Fired when an item is chosen. The item sends it, and you listen for it on the group. Cancelable: call `preventDefault()` to keep the current choice.
  * @event {Event} input - Fired after the value changes.
  *
@@ -85,16 +99,91 @@ export declare class HelixHeadlessToggleGroup extends HelixHeadlessToggleGroup_b
     private adopt;
     /** Marks the chosen item, separately from placing the indicator. */
     private sync;
+    /**
+     * The item that holds the group's tab stop: the chosen one.
+     *
+     * With nothing chosen there is no selection to carry the tab stop, so the
+     * first item holds one until there is. Otherwise an unanswered group is a
+     * control the keyboard cannot enter, which is what the fallback was quietly
+     * also doing for it. A disabled answer takes no focus either, so the entry
+     * 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.
+     *
+     * A toolbar is one tab stop, so a toolbar the group sits in sets this to
+     * `false` while its stop is on another control, and every item, the chosen
+     * one too, is then out of the tab order. The arrow keys inside the group
+     * work as before once focus is in it.
+     *
+     * No attribute: it is coordination between elements, and a consumer has no
+     * 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
+     * refused submission still lands in the group.
+     */
+    protected get focusTarget(): HTMLElement | null;
     private readonly indicator;
     protected readonly keys: KeyboardNavigationController;
     protected readonly cascade: DisabledCascadeController;
     private get items();
     private readonly handleSelection;
+    /**
+     * Whether the group holds an answer the form can submit: a value an item
+     * here carries. A chosen item that was removed is no longer an answer, and
+     * `value` keeps the name for an item that arrives later.
+     */
+    private get answered();
     connectedCallback(): void;
     disconnectedCallback(): void;
     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.
      *
@@ -108,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.
      *