@justeattakeaway/pie-toast-provider 0.0.0 → 0.2.0

package/custom-elements.json

@@ -11,8 +11,59 @@
     {
       "kind": "javascript-module",
       "path": "src/defs.js",
-      "declarations": [],
-      "exports": []
+      "declarations": [
+        {
+          "kind": "variable",
+          "name": "PRIORITY_ORDER",
+          "type": {
+            "text": "{\n    'error-actionable': 1,\n    error: 2,\n    'warning-actionable': 3,\n    'success-actionable': 4,\n    'info-actionable': 5,\n    'neutral-actionable': 6,\n    warning: 7,\n    success: 8,\n    info: 9,\n    neutral: 10,\n}"
+          },
+          "default": "{\n    'error-actionable': 1,\n    error: 2,\n    'warning-actionable': 3,\n    'success-actionable': 4,\n    'info-actionable': 5,\n    'neutral-actionable': 6,\n    warning: 7,\n    success: 8,\n    info: 9,\n    neutral: 10,\n}"
+        },
+        {
+          "kind": "variable",
+          "name": "defaultProps",
+          "type": {
+            "text": "DefaultProps"
+          },
+          "default": "{\n    options: {},\n}"
+        },
+        {
+          "kind": "variable",
+          "name": "ON_TOAST_PROVIDER_QUEUE_UPDATE_EVENT",
+          "type": {
+            "text": "string"
+          },
+          "default": "'pie-toast-provider-queue-update'",
+          "description": "Event name for when the toast provider queue is updated."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "PRIORITY_ORDER",
+          "declaration": {
+            "name": "PRIORITY_ORDER",
+            "module": "src/defs.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "defaultProps",
+          "declaration": {
+            "name": "defaultProps",
+            "module": "src/defs.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "ON_TOAST_PROVIDER_QUEUE_UPDATE_EVENT",
+          "declaration": {
+            "name": "ON_TOAST_PROVIDER_QUEUE_UPDATE_EVENT",
+            "module": "src/defs.js"
+          }
+        }
+      ]
     },
     {
       "kind": "javascript-module",
@@ -22,7 +73,119 @@
           "kind": "class",
           "description": "",
           "name": "PieToastProvider",
-          "members": [],
+          "members": [
+            {
+              "kind": "field",
+              "name": "_toasts",
+              "type": {
+                "text": "ExtendedToastProps[]"
+              },
+              "privacy": "private",
+              "default": "[]"
+            },
+            {
+              "kind": "field",
+              "name": "_currentToast",
+              "type": {
+                "text": "ExtendedToastProps | null"
+              },
+              "privacy": "private",
+              "default": "null"
+            },
+            {
+              "kind": "field",
+              "name": "options",
+              "privacy": "public",
+              "attribute": "options"
+            },
+            {
+              "kind": "method",
+              "name": "_dispatchQueueUpdateEvent",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "getPriority",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "number"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "type",
+                  "default": "toastDefaultProps.variant",
+                  "type": {
+                    "text": "string"
+                  },
+                  "description": "The variant type of the toast."
+                },
+                {
+                  "name": "hasAction",
+                  "default": "false",
+                  "description": "Whether the toast has an action.",
+                  "type": {
+                    "text": "boolean"
+                  }
+                }
+              ],
+              "description": "Get the priority for a toast."
+            },
+            {
+              "kind": "method",
+              "name": "_dismissToast",
+              "privacy": "private",
+              "description": "Handles the dismissal of the current toast and displays the next one in the queue (if any)."
+            },
+            {
+              "kind": "method",
+              "name": "_showNextToast",
+              "privacy": "private",
+              "description": "Displays the next toast in the queue, if available."
+            },
+            {
+              "kind": "method",
+              "name": "createToast",
+              "privacy": "public",
+              "parameters": [
+                {
+                  "name": "toast",
+                  "type": {
+                    "text": "ToastProps"
+                  },
+                  "description": "The toast props to display."
+                }
+              ],
+              "description": "Adds a new toast to the queue and triggers its display if no toast is currently active."
+            },
+            {
+              "kind": "method",
+              "name": "clearToasts",
+              "privacy": "public",
+              "description": "\nClears all toasts from the queue and dismisses the currently visible toast."
+            }
+          ],
+          "events": [
+            {
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "when a toast is added or removed from the queue.",
+              "name": "pie-toast-provider-queue-update"
+            }
+          ],
+          "attributes": [
+            {
+              "name": "options",
+              "fieldName": "options"
+            }
+          ],
           "mixins": [
             {
               "name": "RtlMixin",
@@ -46,6 +209,14 @@
             "package": "./defs"
           }
         },
+        {
+          "kind": "js",
+          "name": "toaster",
+          "declaration": {
+            "name": "toaster",
+            "module": "./toaster"
+          }
+        },
         {
           "kind": "js",
           "name": "PieToastProvider",
@@ -55,6 +226,31 @@
           }
         }
       ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/toaster.js",
+      "declarations": [
+        {
+          "kind": "variable",
+          "name": "toaster",
+          "type": {
+            "text": "object"
+          },
+          "default": "{\n    _getToastProvider (): PieToastProvider | null {\n        const toastProviders = document.querySelectorAll('pie-toast-provider');\n\n        if (toastProviders.length === 0) {\n            console.error('The pie-toast component requires a pie-toast-provider element present in the DOM.');\n            return null;\n        }\n\n        if (toastProviders.length > 1) {\n            console.error('Multiple pie-toast-provider are found in the DOM. Only one provider is supported currently and should be registered at the root of the app.');\n            return null;\n        }\n\n        return toastProviders[0];\n    },\n    create (toast: ExtendedToastProps) {\n        const toastProvider = this._getToastProvider();\n        if (!toastProvider) return;\n\n        toastProvider.createToast(toast);\n    },\n    clearAll () {\n        const toastProvider = this._getToastProvider();\n        if (!toastProvider) return;\n\n        toastProvider.clearToasts();\n    },\n}",
+          "description": "Singleton toaster interface for global access."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "toaster",
+          "declaration": {
+            "name": "toaster",
+            "module": "src/toaster.js"
+          }
+        }
+      ]
     }
   ]
 }

package/dist/index.d.ts

@@ -1,20 +1,108 @@
+import { ComponentDefaultProps } from '@justeattakeaway/pie-webc-core';
 import type { CSSResult } from 'lit';
 import type { GenericConstructor } from '@justeattakeaway/pie-webc-core';
 import type { LitElement } from 'lit';
+import type { PropertyValues } from 'lit';
 import type { RTLInterface } from '@justeattakeaway/pie-webc-core';
 import type { TemplateResult } from 'lit-html';
+import { ToastProps } from '@justeattakeaway/pie-toast';
+
+export declare type DefaultProps = ComponentDefaultProps<ToastProviderProps>;
+
+export declare const defaultProps: DefaultProps;
+
+export declare interface ExtendedToastProps extends ToastProps {
+    /**
+     * Triggered when the user interacts with the close icon or when the toast auto dismiss.
+     */
+    onPieToastClose?: () => void;
+    /**
+     * Triggered when the toast is opened.
+     */
+    onPieToastOpen?: () => void;
+    /**
+     * Triggered when the user interacts with the leading action.
+     */
+    onPieToastLeadingActionClick?: (event: Event) => void;
+}
+
+/**
+ * Event name for when the toast provider queue is updated.
+ *
+ * @constant
+ */
+export declare const ON_TOAST_PROVIDER_QUEUE_UPDATE_EVENT = "pie-toast-provider-queue-update";
 
 /**
  * @tagname pie-toast-provider
+ * @event {CustomEvent} pie-toast-provider-queue-update - when a toast is added or removed from the queue.
  */
 export declare class PieToastProvider extends PieToastProvider_base implements ToastProviderProps {
+    private _toasts;
+    private _currentToast;
+    options: Partial<ExtendedToastProps>;
+    updated(changedProperties: PropertyValues<this>): void;
+    private _dispatchQueueUpdateEvent;
+    /**
+     * Get the priority for a toast.
+     * @param {string} type - The variant type of the toast.
+     * @param {boolean} hasAction - Whether the toast has an action.
+     * @returns {number} - The priority based on the variant and action.
+     */
+    private getPriority;
+    /**
+     * Handles the dismissal of the current toast and displays the next one in the queue (if any).
+     */
+    private _dismissToast;
+    /**
+     * Displays the next toast in the queue, if available.
+     */
+    private _showNextToast;
+    /**
+     * Adds a new toast to the queue and triggers its display if no toast is currently active.
+     * @param {ToastProps} toast - The toast props to display.
+     */
+    createToast(toast: ExtendedToastProps): void;
+    /**
+     *
+     * Clears all toasts from the queue and dismisses the currently visible toast.
+     */
+    clearToasts(): void;
     render(): TemplateResult<1>;
     static styles: CSSResult;
 }
 
 declare const PieToastProvider_base: GenericConstructor<RTLInterface> & typeof LitElement;
 
+export declare type Priority = keyof typeof PRIORITY_ORDER;
+
+export declare const PRIORITY_ORDER: {
+    readonly 'error-actionable': 1;
+    readonly error: 2;
+    readonly 'warning-actionable': 3;
+    readonly 'success-actionable': 4;
+    readonly 'info-actionable': 5;
+    readonly 'neutral-actionable': 6;
+    readonly warning: 7;
+    readonly success: 8;
+    readonly info: 9;
+    readonly neutral: 10;
+};
+
+/**
+ * Singleton toaster interface for global access.
+ */
+export declare const toaster: {
+    _getToastProvider(): PieToastProvider | null;
+    create(toast: ExtendedToastProps): void;
+    clearAll(): void;
+};
+
 export declare interface ToastProviderProps {
+    /**
+     * Default options for all toasts; accepts all toast props.
+     */
+    options?: Partial<ExtendedToastProps>;
 }
 
 export { }

package/dist/index.js

@@ -1,13 +1,140 @@
-import { LitElement as o, html as s, unsafeCSS as n } from "lit";
-import { RtlMixin as r, defineCustomElement as i } from "@justeattakeaway/pie-webc-core";
-const l = "*,*:after,*:before{box-sizing:inherit}", m = "pie-toast-provider", e = class e extends r(o) {
+import { LitElement as _, html as u, nothing as v, unsafeCSS as m } from "lit";
+import { state as f, property as T } from "lit/decorators.js";
+import { ifDefined as g } from "lit/directives/if-defined.js";
+import { RtlMixin as y, dispatchCustomEvent as P, defineCustomElement as b } from "@justeattakeaway/pie-webc-core";
+import { defaultProps as h } from "@justeattakeaway/pie-toast";
+const $ = "*,*:after,*:before{box-sizing:inherit}.c-toast-provider{--toast-provider-offset: var(--dt-spacing-d);position:absolute;inset-inline-start:var(--toast-provider-offset);inset-block-end:var(--toast-provider-offset)}@media (min-width: 769px){.c-toast-provider{--toast-offset: var(--dt-spacing-e)}}", A = {
+  "error-actionable": 1,
+  error: 2,
+  "warning-actionable": 3,
+  "success-actionable": 4,
+  "info-actionable": 5,
+  "neutral-actionable": 6,
+  warning: 7,
+  success: 8,
+  info: 9,
+  neutral: 10
+}, E = {
+  options: {}
+}, x = "pie-toast-provider-queue-update", N = {
+  _getToastProvider() {
+    const s = document.querySelectorAll("pie-toast-provider");
+    return s.length === 0 ? (console.error("The pie-toast component requires a pie-toast-provider element present in the DOM."), null) : s.length > 1 ? (console.error("Multiple pie-toast-provider are found in the DOM. Only one provider is supported currently and should be registered at the root of the app."), null) : s[0];
+  },
+  create(s) {
+    const t = this._getToastProvider();
+    t && t.createToast(s);
+  },
+  clearAll() {
+    const s = this._getToastProvider();
+    s && s.clearToasts();
+  }
+};
+var O = Object.defineProperty, p = (s, t, e, r) => {
+  for (var o = void 0, a = s.length - 1, n; a >= 0; a--)
+    (n = s[a]) && (o = n(t, e, o) || o);
+  return o && O(t, e, o), o;
+};
+const D = "pie-toast-provider", l = class l extends y(_) {
+  constructor() {
+    super(...arguments), this._toasts = [], this._currentToast = null, this.options = E.options;
+  }
+  updated(t) {
+    t.has("_toasts") && this._dispatchQueueUpdateEvent();
+  }
+  _dispatchQueueUpdateEvent() {
+    P(
+      this,
+      x,
+      this._toasts
+    );
+  }
+  /**
+   * Get the priority for a toast.
+   * @param {string} type - The variant type of the toast.
+   * @param {boolean} hasAction - Whether the toast has an action.
+   * @returns {number} - The priority based on the variant and action.
+   */
+  getPriority(t = h.variant, e = !1) {
+    const r = `${t}${e ? "-actionable" : ""}`;
+    return A[r];
+  }
+  /**
+   * Handles the dismissal of the current toast and displays the next one in the queue (if any).
+   */
+  _dismissToast() {
+    var t, e;
+    (e = (t = this._currentToast) == null ? void 0 : t.onPieToastClose) == null || e.call(t), this._currentToast = null, requestAnimationFrame(() => {
+      this._showNextToast();
+    });
+  }
+  /**
+   * Displays the next toast in the queue, if available.
+   */
+  _showNextToast() {
+    if (this._toasts.length > 0) {
+      const [t, ...e] = this._toasts;
+      this._currentToast = t, this._toasts = e;
+    } else
+      this._currentToast = null;
+  }
+  /**
+   * Adds a new toast to the queue and triggers its display if no toast is currently active.
+   * @param {ToastProps} toast - The toast props to display.
+   */
+  createToast(t) {
+    const e = { ...h, ...this.options, ...t };
+    this._toasts = [...this._toasts, e].sort((r, o) => {
+      var c, d;
+      const a = this.getPriority(o.variant, !!((c = o.leadingAction) != null && c.text));
+      return this.getPriority(r.variant, !!((d = r.leadingAction) != null && d.text)) - a;
+    }), this._currentToast || this._showNextToast();
+  }
+  /**
+   *
+   * Clears all toasts from the queue and dismisses the currently visible toast.
+   */
+  clearToasts() {
+    this._toasts = [], this._currentToast = null;
+  }
   render() {
-    return s`<h1 data-test-id="pie-toast-provider">Hello world!</h1>`;
+    const { _currentToast: t, _dismissToast: e } = this;
+    return u`
+      <div class="c-toast-provider" data-test-id="pie-toast-provider">
+      ${t && u`
+              <pie-toast
+                message="${t.message}"
+                variant="${g(t.variant)}"
+                ?isStrong="${t.isStrong}"
+                ?isDismissible="${t.isDismissible}"
+                ?isMultiline="${t.isMultiline}"
+                .leadingAction="${t.leadingAction}"
+                .duration="${typeof t.duration > "u" ? v : t.duration}"
+                @pie-toast-close="${e}"
+                @pie-toast-open="${t.onPieToastOpen}"
+                @pie-toast-leading-action-click="${t.onPieToastLeadingActionClick}">
+              </pie-toast>
+            `}
+      </div>
+    `;
   }
 };
-e.styles = n(l);
-let t = e;
-i(m, t);
+l.styles = m($);
+let i = l;
+p([
+  f()
+], i.prototype, "_toasts");
+p([
+  f()
+], i.prototype, "_currentToast");
+p([
+  T({ type: Object })
+], i.prototype, "options");
+b(D, i);
 export {
-  t as PieToastProvider
+  x as ON_TOAST_PROVIDER_QUEUE_UPDATE_EVENT,
+  A as PRIORITY_ORDER,
+  i as PieToastProvider,
+  E as defaultProps,
+  N as toaster
 };

package/dist/react.d.ts

@@ -1,25 +1,108 @@
+import { ComponentDefaultProps } from '@justeattakeaway/pie-webc-core';
 import type { CSSResult } from 'lit';
 import type { GenericConstructor } from '@justeattakeaway/pie-webc-core';
 import type { LitElement } from 'lit';
+import type { PropertyValues } from 'lit';
 import * as React_2 from 'react';
 import type { RTLInterface } from '@justeattakeaway/pie-webc-core';
 import type { TemplateResult } from 'lit-html';
+import { ToastProps } from '@justeattakeaway/pie-toast';
 
-export declare const PieToastProvider: React_2.ForwardRefExoticComponent<ToastProviderProps & React_2.RefAttributes<PieToastProvider_2> & ReactBaseType>;
+export declare type DefaultProps = ComponentDefaultProps<ToastProviderProps>;
+
+export declare const defaultProps: DefaultProps;
+
+export declare interface ExtendedToastProps extends ToastProps {
+    /**
+     * Triggered when the user interacts with the close icon or when the toast auto dismiss.
+     */
+    onPieToastClose?: () => void;
+    /**
+     * Triggered when the toast is opened.
+     */
+    onPieToastOpen?: () => void;
+    /**
+     * Triggered when the user interacts with the leading action.
+     */
+    onPieToastLeadingActionClick?: (event: Event) => void;
+}
+
+/**
+ * Event name for when the toast provider queue is updated.
+ *
+ * @constant
+ */
+export declare const ON_TOAST_PROVIDER_QUEUE_UPDATE_EVENT = "pie-toast-provider-queue-update";
+
+export declare const PieToastProvider: React_2.ForwardRefExoticComponent<ToastProviderProps & React_2.RefAttributes<PieToastProvider_2> & PieToastProviderEvents & ReactBaseType>;
 
 /**
  * @tagname pie-toast-provider
+ * @event {CustomEvent} pie-toast-provider-queue-update - when a toast is added or removed from the queue.
  */
 declare class PieToastProvider_2 extends PieToastProvider_base implements ToastProviderProps {
+    private _toasts;
+    private _currentToast;
+    options: Partial<ExtendedToastProps>;
+    updated(changedProperties: PropertyValues<this>): void;
+    private _dispatchQueueUpdateEvent;
+    /**
+     * Get the priority for a toast.
+     * @param {string} type - The variant type of the toast.
+     * @param {boolean} hasAction - Whether the toast has an action.
+     * @returns {number} - The priority based on the variant and action.
+     */
+    private getPriority;
+    /**
+     * Handles the dismissal of the current toast and displays the next one in the queue (if any).
+     */
+    private _dismissToast;
+    /**
+     * Displays the next toast in the queue, if available.
+     */
+    private _showNextToast;
+    /**
+     * Adds a new toast to the queue and triggers its display if no toast is currently active.
+     * @param {ToastProps} toast - The toast props to display.
+     */
+    createToast(toast: ExtendedToastProps): void;
+    /**
+     *
+     * Clears all toasts from the queue and dismisses the currently visible toast.
+     */
+    clearToasts(): void;
     render(): TemplateResult<1>;
     static styles: CSSResult;
 }
 
 declare const PieToastProvider_base: GenericConstructor<RTLInterface> & typeof LitElement;
 
+declare type PieToastProviderEvents = {
+    onPieToastProviderQueueUpdate?: (event: CustomEvent) => void;
+};
+
+export declare type Priority = keyof typeof PRIORITY_ORDER;
+
+export declare const PRIORITY_ORDER: {
+    readonly 'error-actionable': 1;
+    readonly error: 2;
+    readonly 'warning-actionable': 3;
+    readonly 'success-actionable': 4;
+    readonly 'info-actionable': 5;
+    readonly 'neutral-actionable': 6;
+    readonly warning: 7;
+    readonly success: 8;
+    readonly info: 9;
+    readonly neutral: 10;
+};
+
 declare type ReactBaseType = React_2.HTMLAttributes<HTMLElement>;
 
 export declare interface ToastProviderProps {
+    /**
+     * Default options for all toasts; accepts all toast props.
+     */
+    options?: Partial<ExtendedToastProps>;
 }
 
 export { }

package/dist/react.js

@@ -1,13 +1,20 @@
 import * as e from "react";
 import { createComponent as o } from "@lit/react";
 import { PieToastProvider as r } from "./index.js";
+import { ON_TOAST_PROVIDER_QUEUE_UPDATE_EVENT as d, PRIORITY_ORDER as m, defaultProps as T } from "./index.js";
 const t = o({
   displayName: "PieToastProvider",
   elementClass: r,
   react: e,
   tagName: "pie-toast-provider",
-  events: {}
+  events: {
+    onPieToastProviderQueueUpdate: "pie-toast-provider-queue-update"
+    // when a toast is added or removed from the queue.
+  }
 }), s = t;
 export {
-  s as PieToastProvider
+  d as ON_TOAST_PROVIDER_QUEUE_UPDATE_EVENT,
+  m as PRIORITY_ORDER,
+  s as PieToastProvider,
+  T as defaultProps
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@justeattakeaway/pie-toast-provider",
   "description": "PIE Design System Toast Provider built using Web Components",
-  "version": "0.0.0",
+  "version": "0.2.0",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -13,7 +13,7 @@
     "**/*.d.ts"
   ],
   "pieMetadata": {
-    "componentStatus": "alpha"
+    "componentStatus": "beta"
   },
   "scripts": {
     "build": "run -T vite build",
@@ -41,6 +41,7 @@
     "cem-plugin-module-file-extensions": "0.0.5"
   },
   "dependencies": {
+    "@justeattakeaway/pie-toast": "0.7.0",
     "@justeattakeaway/pie-webc-core": "0.24.2"
   },
   "volta": {

package/src/defs.ts

@@ -1,3 +1,56 @@
-// TODO - please remove the eslint disable comment below when you add props to this interface
-// eslint-disable-next-line @typescript-eslint/no-empty-interface
-export interface ToastProviderProps {}
+import { type ToastProps } from '@justeattakeaway/pie-toast';
+
+import { type ComponentDefaultProps } from '@justeattakeaway/pie-webc-core';
+
+export const PRIORITY_ORDER = {
+    'error-actionable': 1,
+    error: 2,
+    'warning-actionable': 3,
+    'success-actionable': 4,
+    'info-actionable': 5,
+    'neutral-actionable': 6,
+    warning: 7,
+    success: 8,
+    info: 9,
+    neutral: 10,
+} as const;
+
+export type Priority = keyof typeof PRIORITY_ORDER;
+
+export interface ExtendedToastProps extends ToastProps {
+    /**
+     * Triggered when the user interacts with the close icon or when the toast auto dismiss.
+     */
+    onPieToastClose?: () => void;
+
+    /**
+     * Triggered when the toast is opened.
+     */
+    onPieToastOpen?: () => void;
+
+    /**
+     * Triggered when the user interacts with the leading action.
+     */
+    onPieToastLeadingActionClick?: (event: Event) => void;
+}
+
+export interface ToastProviderProps {
+    /**
+     * Default options for all toasts; accepts all toast props.
+     */
+    options?: Partial<ExtendedToastProps>;
+}
+
+export type DefaultProps = ComponentDefaultProps<ToastProviderProps>;
+
+export const defaultProps: DefaultProps = {
+    options: {},
+};
+
+/**
+ * Event name for when the toast provider queue is updated.
+ *
+ * @constant
+ */
+
+export const ON_TOAST_PROVIDER_QUEUE_UPDATE_EVENT = 'pie-toast-provider-queue-update';

package/src/index.ts

@@ -1,20 +1,144 @@
-import { LitElement, html, unsafeCSS } from 'lit';
-import { RtlMixin, defineCustomElement } from '@justeattakeaway/pie-webc-core';
-
+import {
+    LitElement,
+    html,
+    nothing,
+    unsafeCSS,
+    type PropertyValues,
+} from 'lit';
+import { state, property } from 'lit/decorators.js';
+import { ifDefined } from 'lit/directives/if-defined.js';
+import {
+    RtlMixin,
+    defineCustomElement,
+    dispatchCustomEvent,
+} from '@justeattakeaway/pie-webc-core';
+import { defaultProps as toastDefaultProps } from '@justeattakeaway/pie-toast';
 import styles from './toast-provider.scss?inline';
-import { type ToastProviderProps } from './defs';
+import {
+    defaultProps,
+    PRIORITY_ORDER,
+    type Priority,
+    type ToastProviderProps,
+    type ExtendedToastProps,
+    ON_TOAST_PROVIDER_QUEUE_UPDATE_EVENT,
+} from './defs';
 
 // Valid values available to consumers
 export * from './defs';
+export { toaster } from './toaster';
 
 const componentSelector = 'pie-toast-provider';
 
 /**
  * @tagname pie-toast-provider
+ * @event {CustomEvent} pie-toast-provider-queue-update - when a toast is added or removed from the queue.
  */
 export class PieToastProvider extends RtlMixin(LitElement) implements ToastProviderProps {
+    @state()
+    private _toasts: ExtendedToastProps[] = [];
+
+    @state()
+    private _currentToast: ExtendedToastProps | null = null;
+
+    @property({ type: Object })
+    public options = defaultProps.options;
+
+    updated (changedProperties: PropertyValues<this>): void {
+        if (changedProperties.has('_toasts' as keyof PieToastProvider)) {
+            this._dispatchQueueUpdateEvent();
+        }
+    }
+
+    private _dispatchQueueUpdateEvent (): void {
+        dispatchCustomEvent(
+            this, ON_TOAST_PROVIDER_QUEUE_UPDATE_EVENT,
+            this._toasts,
+        );
+    }
+
+    /**
+     * Get the priority for a toast.
+     * @param {string} type - The variant type of the toast.
+     * @param {boolean} hasAction - Whether the toast has an action.
+     * @returns {number} - The priority based on the variant and action.
+     */
+    private getPriority (type: ExtendedToastProps['variant'] = toastDefaultProps.variant, hasAction = false): number {
+        const key: Priority = `${type}${hasAction ? '-actionable' : ''}`;
+        return PRIORITY_ORDER[key];
+    }
+
+    /**
+     * Handles the dismissal of the current toast and displays the next one in the queue (if any).
+     */
+    private _dismissToast () {
+        this._currentToast?.onPieToastClose?.();
+        this._currentToast = null;
+        requestAnimationFrame(() => { this._showNextToast(); });
+    }
+
+    /**
+     * Displays the next toast in the queue, if available.
+     */
+    private _showNextToast () {
+        if (this._toasts.length > 0) {
+            const [nextToast, ...remainingToasts] = this._toasts;
+            this._currentToast = nextToast;
+            this._toasts = remainingToasts;
+        } else {
+            this._currentToast = null;
+        }
+    }
+
+    /**
+     * Adds a new toast to the queue and triggers its display if no toast is currently active.
+     * @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);
+
+            return priorityA - priorityB;
+        });
+
+        if (!this._currentToast) {
+            this._showNextToast();
+        }
+    }
+
+    /**
+     *
+     * Clears all toasts from the queue and dismisses the currently visible toast.
+     */
+    public clearToasts () {
+        this._toasts = [];
+        this._currentToast = null;
+    }
+
     render () {
-        return html`<h1 data-test-id="pie-toast-provider">Hello world!</h1>`;
+        const { _currentToast, _dismissToast } = this;
+
+        return html`
+      <div class="c-toast-provider" data-test-id="pie-toast-provider">
+      ${_currentToast &&
+            html`
+              <pie-toast
+                message="${_currentToast.message}"
+                variant="${ifDefined(_currentToast.variant)}"
+                ?isStrong="${_currentToast.isStrong}"
+                ?isDismissible="${_currentToast.isDismissible}"
+                ?isMultiline="${_currentToast.isMultiline}"
+                .leadingAction="${_currentToast.leadingAction}"
+                .duration="${typeof _currentToast.duration === 'undefined' ? nothing : _currentToast.duration}"
+                @pie-toast-close="${_dismissToast}"
+                @pie-toast-open="${_currentToast.onPieToastOpen}"
+                @pie-toast-leading-action-click="${_currentToast.onPieToastLeadingActionClick}">
+              </pie-toast>
+            `}
+      </div>
+    `;
     }
 
     // Renders a `CSSResult` generated from SCSS by Vite
@@ -28,3 +152,4 @@ declare global {
         [componentSelector]: PieToastProvider;
     }
 }
+

package/src/react.ts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { createComponent } from '@lit/react';
+import { createComponent, type EventName } from '@lit/react';
 import { PieToastProvider as PieToastProviderLit } from './index';
 import { type ToastProviderProps } from './defs';
 
@@ -10,10 +10,16 @@ const PieToastProviderReact = createComponent({
     elementClass: PieToastProviderLit,
     react: React,
     tagName: 'pie-toast-provider',
-    events: {},
+    events: {
+        onPieToastProviderQueueUpdate: 'pie-toast-provider-queue-update' as EventName<CustomEvent>, // when a toast is added or removed from the queue.
+    },
 });
 
 type ReactBaseType = React.HTMLAttributes<HTMLElement>
 
+type PieToastProviderEvents = {
+    onPieToastProviderQueueUpdate?: (event: CustomEvent) => void;
+};
+
 export const PieToastProvider = PieToastProviderReact as React.ForwardRefExoticComponent<React.PropsWithoutRef<ToastProviderProps>
-    & React.RefAttributes<PieToastProviderLit> & ReactBaseType>;
+    & React.RefAttributes<PieToastProviderLit> & PieToastProviderEvents & ReactBaseType>;

package/src/toast-provider.scss

@@ -1 +1,15 @@
 @use '@justeattakeaway/pie-css/scss' as p;
+@use '@justeattakeaway/pie-css/scss/settings' as *;
+
+
+.c-toast-provider {
+    --toast-provider-offset: var(--dt-spacing-d);
+
+    position: absolute;
+    inset-inline-start: var(--toast-provider-offset);
+    inset-block-end: var(--toast-provider-offset);
+
+    @include media('>md') {
+        --toast-offset: var(--dt-spacing-e);
+    }
+}

package/src/toaster.ts

@@ -0,0 +1,35 @@
+import { type PieToastProvider } from './index';
+import { type ExtendedToastProps } from './defs';
+
+/**
+ * Singleton toaster interface for global access.
+ */
+export const toaster = {
+    _getToastProvider (): PieToastProvider | null {
+        const toastProviders = document.querySelectorAll('pie-toast-provider');
+
+        if (toastProviders.length === 0) {
+            console.error('The pie-toast component requires a pie-toast-provider element present in the DOM.');
+            return null;
+        }
+
+        if (toastProviders.length > 1) {
+            console.error('Multiple pie-toast-provider are found in the DOM. Only one provider is supported currently and should be registered at the root of the app.');
+            return null;
+        }
+
+        return toastProviders[0];
+    },
+    create (toast: ExtendedToastProps) {
+        const toastProvider = this._getToastProvider();
+        if (!toastProvider) return;
+
+        toastProvider.createToast(toast);
+    },
+    clearAll () {
+        const toastProvider = this._getToastProvider();
+        if (!toastProvider) return;
+
+        toastProvider.clearToasts();
+    },
+};