@justeattakeaway/pie-toast-provider 1.2.3 → 1.3.0

package/src/index.ts

@@ -8,6 +8,8 @@ import { PieElement } from '@justeattakeaway/pie-webc-core/src/internals/PieElem
 import { state, property } from 'lit/decorators.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
 import { classMap } from 'lit/directives/class-map.js';
+import { live } from 'lit/directives/live.js';
+import { repeat } from 'lit/directives/repeat.js';
 import {
     dispatchCustomEvent,
     safeCustomElement,
@@ -19,6 +21,7 @@ import {
     positions,
     defaultProps,
     PRIORITY_ORDER,
+    MAX_VISIBLE_TOASTS,
     type Priority,
     type ToastProviderProps,
     type ExtendedToastProps,
@@ -31,6 +34,9 @@ export { toaster } from './toaster';
 
 const componentSelector = 'pie-toast-provider';
 
+// Fallback timeout if motion events don't fire (e.g., when motion is disabled).
+const MOTION_FALLBACK_MS = 500;
+
 /**
  * @tagname pie-toast-provider
  * @event {CustomEvent} pie-toast-provider-queue-update - when a toast is added or removed from the queue.
@@ -44,11 +50,61 @@ export class PieToastProvider extends PieElement implements ToastProviderProps {
     @validPropertyValues(componentSelector, positions, defaultProps.position)
     public position = defaultProps.position;
 
+    @property({ type: Boolean })
+    public isStacked = defaultProps.isStacked;
+
     @state()
     private _toasts: ExtendedToastProps[] = [];
 
     @state()
-    private _currentToast: ExtendedToastProps | null = null;
+    private _visibleToasts: ExtendedToastProps[] = [];
+
+    @state()
+    private _dismissingToasts: ExtendedToastProps[] = [];
+
+    @state()
+    private _collapsingToasts: ExtendedToastProps[] = [];
+
+    /**
+     * Messages currently held in the live regions, in the order they became visible.
+     *
+     * The toast objects themselves are reused as entries: they are unique per `createToast`, which
+     * gives `repeat` a stable key and lets the entries be pruned by identity when a toast leaves.
+     */
+    @state()
+    private _announcements: ExtendedToastProps[] = [];
+
+    /** Pending {@link MOTION_FALLBACK_MS} timers, keyed by the toast they will advance. */
+    private _motionFallbacks = new Map<ExtendedToastProps, ReturnType<typeof setTimeout>>();
+
+    public disconnectedCallback (): void {
+        this._clearMotionFallbacks();
+        super.disconnectedCallback();
+    }
+
+    /**
+     * Replaces any pending fallback for `toast` with one that runs `advance`.
+     *
+     * Each phase supersedes the previous phase's fallback, so a toast only ever has one timer.
+     */
+    private _scheduleMotionFallback (toast: ExtendedToastProps, advance: () => void): void {
+        this._clearMotionFallback(toast);
+        this._motionFallbacks.set(toast, setTimeout(advance, MOTION_FALLBACK_MS));
+    }
+
+    private _clearMotionFallback (toast: ExtendedToastProps): void {
+        const timer = this._motionFallbacks.get(toast);
+
+        if (timer) {
+            clearTimeout(timer);
+            this._motionFallbacks.delete(toast);
+        }
+    }
+
+    private _clearMotionFallbacks (): void {
+        this._motionFallbacks.forEach((timer) => clearTimeout(timer));
+        this._motionFallbacks.clear();
+    }
 
     updated (changedProperties: PropertyValues<this>): void {
         if (changedProperties.has('_toasts' as keyof PieToastProvider)) {
@@ -75,59 +131,114 @@ export class PieToastProvider extends PieElement implements ToastProviderProps {
     }
 
     /**
-     * Handles the dismissal of the current toast and displays the next one in the queue (if any).
+     * Starts the slide-out animation for the dismissed toast.
      */
-    private _dismissToast () {
-        this._currentToast?.onPieToastClose?.();
-        this._currentToast = null;
-        requestAnimationFrame(() => { this._showNextToast(); });
+    private _dismissToast (toast: ExtendedToastProps) {
+        if (this._dismissingToasts.includes(toast)) return;
+        toast.onPieToastClose?.();
+        this._dismissingToasts = [...this._dismissingToasts, toast];
+        this._scheduleMotionFallback(toast, () => this._finalizeDismiss(toast));
     }
 
     /**
-     * Displays the next toast in the queue, if available.
+     * Forwards the toast's open event to the consumer.
+     *
+     * `isOpen` is bound with the `live` directive, so a toast that sets `isOpen` to false while
+     * dismissing is reopened on the next render in order to keep it visible for the slide-out
+     * animation. That reopen dispatches a second `pie-toast-open`, which is not a real open, so it
+     * is not forwarded.
+     */
+    private _handleToastOpen (toast: ExtendedToastProps) {
+        if (this._dismissingToasts.includes(toast)) return;
+        toast.onPieToastOpen?.();
+    }
+
+    private _getToastClass (toast: ExtendedToastProps): string {
+        if (this._dismissingToasts.includes(toast)) return 'pie-animation--slide-out';
+        if (this._collapsingToasts.includes(toast)) return '';
+        return 'pie-animation--slide-in';
+    }
+
+    private _getToastDuration (toast: ExtendedToastProps) {
+        if (this._dismissingToasts.includes(toast) || this._collapsingToasts.includes(toast)) return null;
+        return typeof toast.duration === 'undefined' ? nothing : toast.duration;
+    }
+
+    /**
+     * Starts the height-collapse phase after the slide-out animation ends.
+     */
+    private _finalizeDismiss (toast: ExtendedToastProps) {
+        if (!this._dismissingToasts.includes(toast)) return;
+
+        this._dismissingToasts = this._dismissingToasts.filter((t) => t !== toast);
+        this._collapsingToasts = [...this._collapsingToasts, toast];
+        this._scheduleMotionFallback(toast, () => this._finalizeCollapse(toast));
+    }
+
+    /**
+     * Called after the collapse transition ends. Removes the toast from DOM and promotes the next queued toast.
+     */
+    private _finalizeCollapse (toast: ExtendedToastProps) {
+        if (!this._collapsingToasts.includes(toast)) return;
+
+        this._clearMotionFallback(toast);
+        this._collapsingToasts = this._collapsingToasts.filter((t) => t !== toast);
+        this._visibleToasts = this._visibleToasts.filter((t) => t !== toast);
+        this._announcements = this._announcements.filter((t) => t !== toast);
+        this._showNextToast();
+    }
+
+    /**
+     * Fills the visible slots from the queue.
+     *
+     * The loop only ever adds toasts, so turning `isStacked` off while several are on screen
+     * does not remove any: the extras stay until they dismiss normally, then the provider
+     * settles back to one at a time.
      */
     private _showNextToast () {
-        if (this._toasts.length > 0) {
+        const maxVisibleToasts = this.isStacked ? MAX_VISIBLE_TOASTS : 1;
+
+        while (this._visibleToasts.length < maxVisibleToasts && this._toasts.length > 0) {
             const [nextToast, ...remainingToasts] = this._toasts;
-            this._currentToast = nextToast;
+            this._visibleToasts = [...this._visibleToasts, nextToast];
             this._toasts = remainingToasts;
-        } else {
-            this._currentToast = null;
+            this._announcements = [...this._announcements, nextToast];
         }
     }
 
     /**
-     * Adds a new toast to the queue and triggers its display if no toast is currently active.
+     * Adds a new toast to the queue (sorted by priority) and fills visible slots.
      * @param {ToastProps} toast - The toast props to display.
      */
     public createToast (toast: ExtendedToastProps) {
         const newToast = { ...toastDefaultProps, ...this.options, ...toast };
 
         this._toasts = [...this._toasts, newToast].sort((a, b) => {
-            const priorityB = this.getPriority(b.variant, !!b.leadingAction?.text);
             const priorityA = this.getPriority(a.variant, !!a.leadingAction?.text);
+            const priorityB = this.getPriority(b.variant, !!b.leadingAction?.text);
 
             return priorityA - priorityB;
         });
 
-        if (!this._currentToast) {
-            this._showNextToast();
-        }
+        this._showNextToast();
     }
 
     /**
-     *
-     * Clears all toasts from the queue and dismisses the currently visible toast.
+     * Clears all toasts from the queue and dismisses all visible toasts.
      */
     public clearToasts () {
+        this._clearMotionFallbacks();
         this._toasts = [];
-        this._currentToast = null;
+        this._visibleToasts = [];
+        this._dismissingToasts = [];
+        this._collapsingToasts = [];
+        this._announcements = [];
     }
 
     render () {
         const {
             position,
-            _currentToast,
+            _visibleToasts,
         } = this;
 
         const classes = {
@@ -135,46 +246,64 @@ export class PieToastProvider extends PieElement implements ToastProviderProps {
             [`c-toast-provider--${position}`]: true,
         };
 
-        const toastClasses = {
-            'pie-animation--slide-in': Boolean(_currentToast),
-            'pie-animation--slide-out': _currentToast === null,
-        };
-
-        const isError = _currentToast?.variant === 'error';
+        // Two regions with fixed politeness, rather than one region that switches: a neutral toast
+        // arriving after an error must not downgrade the error's announcement.
+        //
+        // `aria-atomic="false"` is what makes batching work. Lit renders several newly visible
+        // toasts in a single update, and assistive tech announces only the nodes added in that
+        // update, so each message is read in turn instead of the last one replacing the rest.
+        // `aria-relevant` defaults to `additions text`, so pruning a departed toast is silent.
+        const politeAnnouncements = this._announcements.filter(({ variant }) => variant !== 'error');
+        const assertiveAnnouncements = this._announcements.filter(({ variant }) => variant === 'error');
 
-        // The provider owns the announcement, so the rendered toast's own live region is disabled
-        // (`aria-live: off`) to prevent the message being announced twice.
-        const toastAria = { ..._currentToast?.aria, live: 'off' as const };
+        const renderAnnouncements = (announcements: ExtendedToastProps[]) => repeat(
+            announcements,
+            (toast) => toast,
+            (toast) => html`<div>${toast.message}</div>`,
+        );
 
         return html`
         <div
             class=${classMap(classes)}
             data-test-id="pie-toast-provider">
             <div
-                class="c-toast-provider-announcer is-visuallyHidden"
-                role="${isError ? 'alert' : 'status'}"
-                aria-live="${isError ? 'assertive' : 'polite'}"
-                aria-atomic="true"
+                class="c-toast-provider-announcer"
+                role="status"
+                aria-live="polite"
+                aria-atomic="false"
                 data-test-id="pie-toast-provider-announcer">
-                ${_currentToast?.message ?? ''}
+                ${renderAnnouncements(politeAnnouncements)}
+            </div>
+            <div
+                class="c-toast-provider-announcer"
+                role="alert"
+                aria-live="assertive"
+                aria-atomic="false"
+                data-test-id="pie-toast-provider-announcer-assertive">
+                ${renderAnnouncements(assertiveAnnouncements)}
             </div>
-            ${_currentToast &&
-            html`
-                <pie-toast
-                    class=${classMap(toastClasses)}
-                    message="${_currentToast.message}"
-                    variant="${ifDefined(_currentToast.variant)}"
-                    ?isStrong="${_currentToast.isStrong}"
-                    ?isDismissible="${_currentToast.isDismissible}"
-                    ?isMultiline="${_currentToast.isMultiline}"
-                    .leadingAction="${_currentToast.leadingAction}"
-                    .aria="${toastAria}"
-                    .duration="${typeof _currentToast.duration === 'undefined' ? nothing : _currentToast.duration}"
-                    @pie-toast-close="${this._dismissToast}"
-                    @pie-toast-open="${_currentToast.onPieToastOpen}"
-                    @pie-toast-leading-action-click="${_currentToast.onPieToastLeadingActionClick}">
-                </pie-toast>
-            `}
+            ${repeat(_visibleToasts, (toast) => toast, (toast) => html`
+                <div
+                    class="c-toast-provider-item${this._collapsingToasts.includes(toast) ? ' c-toast-provider-item--collapsing' : ''}"
+                    @transitionend="${() => { if (this._collapsingToasts.includes(toast)) this._finalizeCollapse(toast); }}">
+                    <pie-toast
+                        class="${this._getToastClass(toast)}"
+                        .isOpen="${live(true)}"
+                        message="${toast.message}"
+                        variant="${ifDefined(toast.variant)}"
+                        ?isStrong="${toast.isStrong}"
+                        ?isDismissible="${toast.isDismissible}"
+                        ?isMultiline="${toast.isMultiline}"
+                        .leadingAction="${toast.leadingAction}"
+                        .aria="${{ ...toast.aria, live: 'off' as const }}"
+                        .duration="${this._getToastDuration(toast)}"
+                        @pie-toast-close="${() => this._dismissToast(toast)}"
+                        @pie-toast-open="${() => this._handleToastOpen(toast)}"
+                        @pie-toast-leading-action-click="${toast.onPieToastLeadingActionClick}"
+                        @animationend="${() => { if (this._dismissingToasts.includes(toast)) this._finalizeDismiss(toast); }}">
+                    </pie-toast>
+                </div>
+            `)}
             </div>
         `;
     }

package/src/toast-provider.scss

@@ -15,6 +15,8 @@
 .c-toast-provider {
     position: var(--toast-provider-position);
     z-index: var(--toast-provider-z-index);
+    display: flex;
+    flex-direction: column-reverse;
 
     &-announcer {
         @include p.visually-hidden;
@@ -43,6 +45,30 @@
         bottom: var(--toast-provider-offset);
     }
 
+    .c-toast-provider-item {
+        display: grid;
+        grid-template-rows: 1fr;
+
+        padding-block-start: var(--dt-spacing-d);
+        transition:
+            grid-template-rows var(--dt-motion-timing-200) var(--dt-motion-easing-in),
+            padding-block-start var(--dt-motion-timing-200) var(--dt-motion-easing-in);
+
+        > pie-toast {
+            min-block-size: 0;
+            overflow: hidden;
+        }
+
+        &--collapsing {
+            grid-template-rows: 0fr;
+            padding-block-start: 0;
+
+            > pie-toast {
+                visibility: hidden;
+            }
+        }
+    }
+
     &.c-toast-provider--bottom-center {
         --pie-animation-slide-translate-start: 0, 100%;
 
@@ -50,4 +76,4 @@
         bottom: var(--toast-provider-offset);
         transform: translateX(-50%);
     }
-}
+}