@justeattakeaway/pie-toast-provider 1.2.3 → 1.3.1

package/README.md

@@ -37,6 +37,7 @@ Ideally, you should install the component using the **`@justeattakeaway/pie-webc
 |----------|---------|---------------------------------------------------------------------------------------------------|---------|
 | options  | `{}`    | Default options for all toasts; accepts all toast [props](https://webc.pie.design/?path=/story/components-toast).        | `{}`    |
 | position | `"default"`, `"bottom-left"`, `"bottom-right"`, `"bottom-center"` | Sets the position of the toast provider. When set to `default`, the toasts will be positioned at bottom-left for RTL languages and bottom-right for LTR languages. | `default` |
+| isStacked | `true`, `false` | When true, up to 3 toasts are displayed at the same time in a vertical stack. When false, a single toast is displayed at a time and the rest wait in the queue. | `false` |
 
 ### Slots
 This component does not have any slots. All content is controlled through properties.

package/custom-elements.json

@@ -34,7 +34,7 @@
           "type": {
             "text": "DefaultProps"
           },
-          "default": "{ options: {}, position: 'default', }"
+          "default": "{ options: {}, position: 'default', isStacked: false, }"
         },
         {
           "kind": "variable",
@@ -44,6 +44,15 @@
           },
           "default": "'pie-toast-provider-queue-update'",
           "description": "Event name for when the toast provider queue is updated."
+        },
+        {
+          "kind": "variable",
+          "name": "MAX_VISIBLE_TOASTS",
+          "type": {
+            "text": "number"
+          },
+          "default": "3",
+          "description": "The most toasts the provider will display at once when `isStacked` is true.\n\nWith `isStacked` false (the default) a single toast is displayed regardless of this value."
         }
       ],
       "exports": [
@@ -78,6 +87,14 @@
             "name": "ON_TOAST_PROVIDER_QUEUE_UPDATE_EVENT",
             "module": "src/defs.js"
           }
+        },
+        {
+          "kind": "js",
+          "name": "MAX_VISIBLE_TOASTS",
+          "declaration": {
+            "name": "MAX_VISIBLE_TOASTS",
+            "module": "src/defs.js"
+          }
         }
       ]
     },
@@ -102,6 +119,12 @@
               "privacy": "public",
               "attribute": "position"
             },
+            {
+              "kind": "field",
+              "name": "isStacked",
+              "privacy": "public",
+              "attribute": "isStacked"
+            },
             {
               "kind": "field",
               "name": "_toasts",
@@ -113,12 +136,100 @@
             },
             {
               "kind": "field",
-              "name": "_currentToast",
+              "name": "_visibleToasts",
               "type": {
-                "text": "ExtendedToastProps | null"
+                "text": "ExtendedToastProps[]"
               },
               "privacy": "private",
-              "default": "null"
+              "default": "[]"
+            },
+            {
+              "kind": "field",
+              "name": "_dismissingToasts",
+              "type": {
+                "text": "ExtendedToastProps[]"
+              },
+              "privacy": "private",
+              "default": "[]"
+            },
+            {
+              "kind": "field",
+              "name": "_collapsingToasts",
+              "type": {
+                "text": "ExtendedToastProps[]"
+              },
+              "privacy": "private",
+              "default": "[]"
+            },
+            {
+              "kind": "field",
+              "name": "_announcements",
+              "type": {
+                "text": "ExtendedToastProps[]"
+              },
+              "privacy": "private",
+              "default": "[]",
+              "description": "Messages currently held in the live regions, in the order they became visible.\n\nThe toast objects themselves are reused as entries: they are unique per `createToast`, which\ngives `repeat` a stable key and lets the entries be pruned by identity when a toast leaves."
+            },
+            {
+              "kind": "field",
+              "name": "_motionFallbacks",
+              "privacy": "private",
+              "default": "new Map<ExtendedToastProps, ReturnType<typeof setTimeout>>()",
+              "description": "Pending MOTION_FALLBACK_MS timers, keyed by the toast they will advance."
+            },
+            {
+              "kind": "method",
+              "name": "_scheduleMotionFallback",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "toast",
+                  "type": {
+                    "text": "ExtendedToastProps"
+                  }
+                },
+                {
+                  "name": "advance",
+                  "type": {
+                    "text": "() => void"
+                  }
+                }
+              ],
+              "description": "Replaces any pending fallback for `toast` with one that runs `advance`.\n\nEach phase supersedes the previous phase's fallback, so a toast only ever has one timer."
+            },
+            {
+              "kind": "method",
+              "name": "_clearMotionFallback",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "toast",
+                  "type": {
+                    "text": "ExtendedToastProps"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "_clearMotionFallbacks",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
             },
             {
               "kind": "method",
@@ -163,13 +274,94 @@
               "kind": "method",
               "name": "_dismissToast",
               "privacy": "private",
-              "description": "Handles the dismissal of the current toast and displays the next one in the queue (if any)."
+              "parameters": [
+                {
+                  "name": "toast",
+                  "type": {
+                    "text": "ExtendedToastProps"
+                  }
+                }
+              ],
+              "description": "Starts the slide-out animation for the dismissed toast."
+            },
+            {
+              "kind": "method",
+              "name": "_handleToastOpen",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "toast",
+                  "type": {
+                    "text": "ExtendedToastProps"
+                  }
+                }
+              ],
+              "description": "Forwards the toast's open event to the consumer.\n\n`isOpen` is bound with the `live` directive, so a toast that sets `isOpen` to false while\ndismissing is reopened on the next render in order to keep it visible for the slide-out\nanimation. That reopen dispatches a second `pie-toast-open`, which is not a real open, so it\nis not forwarded."
+            },
+            {
+              "kind": "method",
+              "name": "_getToastClass",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "string"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "toast",
+                  "type": {
+                    "text": "ExtendedToastProps"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "_getToastDuration",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "toast",
+                  "type": {
+                    "text": "ExtendedToastProps"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "_finalizeDismiss",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "toast",
+                  "type": {
+                    "text": "ExtendedToastProps"
+                  }
+                }
+              ],
+              "description": "Starts the height-collapse phase after the slide-out animation ends."
+            },
+            {
+              "kind": "method",
+              "name": "_finalizeCollapse",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "toast",
+                  "type": {
+                    "text": "ExtendedToastProps"
+                  }
+                }
+              ],
+              "description": "Called after the collapse transition ends. Removes the toast from DOM and promotes the next queued toast."
             },
             {
               "kind": "method",
               "name": "_showNextToast",
               "privacy": "private",
-              "description": "Displays the next toast in the queue, if available."
+              "description": "Fills the visible slots from the queue.\n\nThe loop only ever adds toasts, so turning `isStacked` off while several are on screen\ndoes not remove any: the extras stay until they dismiss normally, then the provider\nsettles back to one at a time."
             },
             {
               "kind": "method",
@@ -184,13 +376,13 @@
                   "description": "The toast props to display."
                 }
               ],
-              "description": "Adds a new toast to the queue and triggers its display if no toast is currently active."
+              "description": "Adds a new toast to the queue (sorted by priority) and fills visible slots."
             },
             {
               "kind": "method",
               "name": "clearToasts",
               "privacy": "public",
-              "description": "\nClears all toasts from the queue and dismisses the currently visible toast."
+              "description": "Clears all toasts from the queue and dismisses all visible toasts."
             }
           ],
           "events": [
@@ -210,6 +402,10 @@
             {
               "name": "position",
               "fieldName": "position"
+            },
+            {
+              "name": "isStacked",
+              "fieldName": "isStacked"
             }
           ],
           "superclass": {

package/dist/index.d.ts

@@ -29,6 +29,15 @@ export declare interface ExtendedToastProps extends ToastProps {
     onPieToastLeadingActionClick?: (event: Event) => void;
 }
 
+/**
+ * The most toasts the provider will display at once when `isStacked` is true.
+ *
+ * With `isStacked` false (the default) a single toast is displayed regardless of this value.
+ *
+ * @constant
+ */
+export declare const MAX_VISIBLE_TOASTS = 3;
+
 /**
  * Event name for when the toast provider queue is updated.
  *
@@ -43,8 +52,29 @@ export declare const ON_TOAST_PROVIDER_QUEUE_UPDATE_EVENT = "pie-toast-provider-
 export declare class PieToastProvider extends PieElement implements ToastProviderProps {
     options: Partial<ExtendedToastProps>;
     position: "default" | "bottom-left" | "bottom-right" | "bottom-center";
+    isStacked: boolean;
     private _toasts;
-    private _currentToast;
+    private _visibleToasts;
+    private _dismissingToasts;
+    private _collapsingToasts;
+    /**
+     * 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.
+     */
+    private _announcements;
+    /** Pending {@link MOTION_FALLBACK_MS} timers, keyed by the toast they will advance. */
+    private _motionFallbacks;
+    disconnectedCallback(): void;
+    /**
+     * 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;
+    private _clearMotionFallback;
+    private _clearMotionFallbacks;
     updated(changedProperties: PropertyValues<this>): void;
     private _dispatchQueueUpdateEvent;
     /**
@@ -55,21 +85,43 @@ export declare class PieToastProvider extends PieElement implements ToastProvide
      */
     private getPriority;
     /**
-     * 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;
     /**
-     * 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;
+    private _getToastClass;
+    private _getToastDuration;
+    /**
+     * Starts the height-collapse phase after the slide-out animation ends.
+     */
+    private _finalizeDismiss;
+    /**
+     * Called after the collapse transition ends. Removes the toast from DOM and promotes the next queued toast.
+     */
+    private _finalizeCollapse;
+    /**
+     * 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;
     /**
-     * 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.
      */
     createToast(toast: ExtendedToastProps): void;
     /**
-     *
-     * Clears all toasts from the queue and dismisses the currently visible toast.
+     * Clears all toasts from the queue and dismisses all visible toasts.
      */
     clearToasts(): void;
     render(): TemplateResult<1>;
@@ -112,6 +164,11 @@ export declare interface ToastProviderProps {
      * When set to `default`, the toasts will be positioned at bottom-left for RTL languages and bottom-right for LTR languages.
      */
     position?: typeof positions[number];
+    /**
+     * When true, up to 3 toasts are displayed at the same time in a vertical stack. When false,
+     * a single toast is displayed at a time and the rest wait in the queue.
+     */
+    isStacked?: boolean;
 }
 
 export { }