feat(pie-toast): DSW-2204 implement auto-dismiss / persistent feature

apps/pie-storybook/stories/pie-toast-docs/variants.mdx

@@ -0,0 +1,44 @@
+import { Meta, Canvas } from '@storybook/blocks';
+import * as ToastStories from '../pie-toast.stories.ts';
+import { ComponentStatus } from '../../docblocks/component-status.jsx';
+
+<ComponentStatus component="pie-toast" />
+
+<Meta of={ToastStories} />
+
+### Neutral
+
+<Canvas of={ToastStories.Neutral} />
+
+### Info
+
+<Canvas of={ToastStories.Info} />
+
+### Info Strong
+
+<Canvas of={ToastStories.InfoStrong} />
+
+### Warning
+
+<Canvas of={ToastStories.Warning} />
+
+### Warning Strong
+
+<Canvas of={ToastStories.WarningStrong} />
+
+### Success
+
+<Canvas of={ToastStories.Success} />
+
+### Success Strong
+
+<Canvas of={ToastStories.SuccessStrong} />
+
+### Error
+
+<Canvas of={ToastStories.Error} />
+
+### Error Strong
+
+<Canvas of={ToastStories.ErrorStrong} />
+

apps/pie-storybook/stories/pie-toast.stories.ts

@@ -2,7 +2,7 @@ import { html } from 'lit';
 import { ToastProps, defaultProps, variants } from '@justeattakeaway/pie-toast';
 import { action } from '@storybook/addon-actions';
 import { type StoryMeta } from '../types';
-import { createStory } from '../utilities';
+import { createStory, TemplateFunction } from '../utilities';
 
 type ToastStoryMeta = StoryMeta<ToastProps>;
 
@@ -13,6 +13,7 @@ const defaultArgs: ToastProps = {
         text: 'Confirm',
         ariaLabel: 'Descriptive confirmation text',
     },
+    duration: null,
 };
 
 const toastStoryMeta: ToastStoryMeta = {
@@ -27,7 +28,7 @@ const toastStoryMeta: ToastStoryMeta = {
             },
         },
         variant: {
-            description: 'Set the variant of the notification.',
+            description: 'Set the variant of the toast.',
             control: 'select',
             options: variants,
             defaultValue: {
@@ -63,6 +64,10 @@ const toastStoryMeta: ToastStoryMeta = {
             description: 'The leading action configuration for the toast.',
             control: 'object',
         },
+        duration: {
+            description: 'It set the duration of the toast in milliseconds before it auto-dismiss.',
+            control: 'number',
+        },
     },
     args: defaultArgs,
     parameters: {
@@ -76,34 +81,43 @@ const toastStoryMeta: ToastStoryMeta = {
 export default toastStoryMeta;
 
 const pieToastLeadingActionClick = action('pie-toast-leading-action-click');
-const pieToastSupportingActionClick = action('pie-toast-supporting-action-click');
 const pieToastClose = action('pie-toast-close');
 const pieToastOpen = action('pie-toast-open');
 
-// TODO: remove the eslint-disable rule when props are added
-// eslint-disable-next-line no-empty-pattern
-const Template = ({
+const Template : TemplateFunction<ToastProps> = ({
     isOpen,
     isDismissible,
     message,
     leadingAction,
     isMultiline,
     isStrong,
     variant,
+    duration,
 }: ToastProps) => html`
     <pie-toast 
         ?isOpen="${isOpen}" 
         ?isDismissible="${isDismissible}" 
         ?isStrong="${isStrong}"
         variant="${variant}"
         message="${message}" 
+        .duration="${duration}"
         ?isMultiline="${isMultiline}"
         .leadingAction="${leadingAction}"
         @pie-toast-leading-action-click="${pieToastLeadingActionClick}"
-        @pie-toast-supporting-action-click="${pieToastSupportingActionClick}"
         @pie-toast-close="${pieToastClose}"
         @pie-toast-open="${pieToastOpen}"
     /></pie-toast>
 `;
 
-export const Default = createStory<ToastProps>(Template, defaultArgs)();
+const createToastStory = createStory<ToastProps>(Template, defaultArgs);
+
+export const Neutral = createToastStory();
+export const Info = createToastStory({ variant: 'info' });
+export const InfoStrong = createToastStory({ variant: 'info', isStrong: true });
+export const Warning = createToastStory({ variant: 'warning' });
+export const WarningStrong = createToastStory({ variant: 'warning', isStrong: true });
+export const Success = createToastStory({ variant: 'success' });
+export const SuccessStrong = createToastStory({ variant: 'success', isStrong: true });
+export const Error = createToastStory({ variant: 'error' });
+export const ErrorStrong = createToastStory({ variant: 'error', isStrong: true });
+export const AutoDismiss = createToastStory({ duration: 3000, message: 'Closing in three seconds' });

packages/components/pie-toast/src/defs.ts

@@ -2,6 +2,8 @@ import { type ComponentDefaultProps } from '@justeattakeaway/pie-webc-core';
 
 export const variants = ['neutral', 'info', 'warning', 'success', 'error'] as const;
 
+export const defaultDuration = 5000;
+
 export type ActionProps = {
   /**
    * The text to display inside the button.
@@ -44,6 +46,13 @@ export interface ToastProps {
    * The leading action for the toast.
    */
   leadingAction?: ActionProps;
+
+  /**
+   * It set the duration of the toast in milliseconds before it auto-dismiss
+   * If the value is null auto-dismiss is disabled
+   * If the value is not provided it auto-dismiss after 5 seconds (5000 milliseconds)
+   */
+  duration?: number | null;
 }
 
 export const componentSelector = 'pie-toast';
@@ -70,7 +79,7 @@ export const ON_TOAST_OPEN_EVENT = `${componentSelector}-open`;
  */
 export const ON_TOAST_LEADING_ACTION_CLICK_EVENT = `${componentSelector}-leading-action-click`;
 
-export type DefaultProps = ComponentDefaultProps<ToastProps, keyof Omit<ToastProps, 'message' | 'leadingAction'>>;
+export type DefaultProps = ComponentDefaultProps<ToastProps, keyof Omit<ToastProps, 'message' | 'leadingAction' | 'duration'>>;
 
 export const defaultProps: DefaultProps = {
     isOpen: true,

packages/components/pie-toast/src/index.ts

@@ -33,6 +33,7 @@ import {
     ON_TOAST_LEADING_ACTION_CLICK_EVENT,
     defaultProps,
     variants,
+    defaultDuration,
 } from './defs';
 
 // Valid values available to consumers
@@ -64,15 +65,67 @@ export class PieToast extends RtlMixin(LitElement) implements ToastProps {
     @property({ type: Object })
     public leadingAction: ToastProps['leadingAction'];
 
+    @property()
+    public duration: ToastProps['duration'];
+
     @query('pie-button') actionButton?: HTMLElement;
 
+    @query('pie-icon-button') closeButton?: HTMLElement;
+
     private _actionButtonOffset = 0;
 
     private _messageAreaMaxWidth = 0;
 
+    private _timeoutId: NodeJS.Timeout | null = null;
+
+    private _abortController: AbortController | null = null;
+
     // Renders a `CSSResult` generated from SCSS by Vite
     static styles = unsafeCSS(styles);
 
+    /**
+     * Create a timeout function and set its id into a private attribute.
+     *
+     * @private
+     */
+    private setAutoDismiss () {
+        this._timeoutId = setTimeout(() => {
+            this.closeToastComponent();
+        }, this.setAutoDismissDuration());
+    }
+
+    /**
+     * It gets the duration of the timeout in milliseconds.
+     * If the duration is undefined it returns 5000 which is the default value.
+     * If the duration is an arbitrary number provided by the user, it returns the number itself.
+     *
+     * @returns number
+     * @private
+     */
+    private setAutoDismissDuration (): number {
+        switch (typeof this.duration) {
+            case 'undefined':
+                return defaultDuration;
+            case 'number':
+                return this.duration as number;
+            default:
+                return 0 as never;
+        }
+    }
+
+    /**
+     * If the _abortController is set, it aborts all event
+     * listeners in this controller and the controller turns into null.
+     *
+     * @private
+     */
+    private abortAndCleanEventListeners () {
+        if (this._abortController) {
+            this._abortController.abort();
+            this._abortController = null;
+        }
+    }
+
     /**
      * Calculates and returns the width of the message based on the toast properties.
      *
@@ -111,6 +164,52 @@ export class PieToast extends RtlMixin(LitElement) implements ToastProps {
         return toastMaxWidthWithoutPadding - offset;
     }
 
+    /**
+     * Adds event listeners to the specified element for handling the auto dismiss behavior.
+     *
+     * @param {typeof this | HTMLElement | undefined} element - The element to which the listeners will be added. It can be the current instance, an HTMLElement, or undefined.
+     * @param {keyof HTMLElementEventMap} inEvent - The event type to listen for when entering the element. (e.g., 'mouseenter', 'focusin').
+     * @param {keyof HTMLElementEventMap} outEvent - The event type to listen for when leaving the element. (e.g., 'mouseleave', 'focusout').
+     * @param {AddEventListenerOptions['signal']} abortSignal - An AbortSignal that can be used to remove the event listeners.
+     *
+     * @private
+     */
+    private addListenersToElement (
+        element: typeof this | HTMLElement | undefined,
+        inEvent: keyof HTMLElementEventMap,
+        outEvent: keyof HTMLElementEventMap,
+        abortSignal: AddEventListenerOptions['signal'],
+    ) {
+        if (element) {
+            element.addEventListener(inEvent, () => {
+                if (this._timeoutId) {
+                    clearTimeout(this._timeoutId);
+                }
+            }, { signal: abortSignal });
+            element.addEventListener(outEvent, () => {
+                this.setAutoDismiss();
+            }, { signal: abortSignal });
+        }
+    }
+
+    /**
+     * It created all event listeners to handle the auto-dismiss capability
+     * as well the controller responsible to remove the events when needed.
+     *
+     * @private
+     */
+    private createAutoDismissEventListeners () {
+        this._abortController = new AbortController();
+
+        this.setAutoDismiss();
+
+        const { signal } = this._abortController;
+
+        this.addListenersToElement(this.actionButton, 'focus', 'focusout', signal);
+        this.addListenersToElement(this.closeButton, 'focus', 'focusout', signal);
+        this.addListenersToElement(this, 'mouseover', 'mouseout', signal);
+    }
+
     /**
      * Lifecycle method executed when component is updated.
      * It dispatches an event if toast is opened.
@@ -119,6 +218,14 @@ export class PieToast extends RtlMixin(LitElement) implements ToastProps {
     protected async updated (_changedProperties: PropertyValues<this>) {
         if (_changedProperties.has('isOpen') && this.isOpen) {
             dispatchCustomEvent(this, ON_TOAST_OPEN_EVENT, { targetNotification: this });
+
+            if (this.duration !== null) {
+                this.createAutoDismissEventListeners();
+            }
+        }
+
+        if (_changedProperties.has('isOpen') && !this.isOpen && this._abortController) {
+            this.abortAndCleanEventListeners();
         }
 
         await this.updateComplete;
@@ -137,7 +244,8 @@ export class PieToast extends RtlMixin(LitElement) implements ToastProps {
             _changedProperties.has('message') ||
             _changedProperties.has('isDismissible') ||
             _changedProperties.has('isMultiline') ||
-            _changedProperties.has('leadingAction')) {
+            _changedProperties.has('leadingAction') ||
+            _changedProperties.has('duration')) {
             this.requestUpdate();
         }
     }
@@ -234,6 +342,7 @@ export class PieToast extends RtlMixin(LitElement) implements ToastProps {
     private closeToastComponent () {
         this.isOpen = false;
         dispatchCustomEvent(this, ON_TOAST_CLOSE_EVENT, { targetNotification: this });
+        this.abortAndCleanEventListeners();
     }
 
     /**
@@ -288,14 +397,12 @@ export class PieToast extends RtlMixin(LitElement) implements ToastProps {
             _messageAreaMaxWidth,
         } = this;
 
-        if (!isOpen) {
-            return nothing;
-        }
-
         const componentWrapperClasses = {
             [componentClass]: true,
             [`${componentClass}--${variant}`]: true,
             [`${componentClass}--strong`]: isStrong,
+            [`${componentClass}--animate-in`]: isOpen,
+            [`${componentClass}--animate-out`]: !isOpen,
         };
 
         const messageAreaClasses = {
@@ -304,7 +411,11 @@ export class PieToast extends RtlMixin(LitElement) implements ToastProps {
         };
 
         return html`
-            <div data-test-id="${componentSelector}" class="${classMap(componentWrapperClasses)}">
+            <div 
+                data-test-id="${componentSelector}" 
+                class="${classMap(componentWrapperClasses)}" 
+                aria-live="${variant === 'error' ? 'assertive' : 'polite'}"
+            >
                 <div class="${componentClass}-contentArea">
                     <div class="${classMap(messageAreaClasses)}">
                         ${this.variantHasIcon(variant) ? this.getVariantIcon() : nothing}