diff --git a/apps/pie-docs/src/components/toast/overview/overview.md b/apps/pie-docs/src/components/toast/overview/overview.md index 0ec73914c1..00967df4de 100644 --- a/apps/pie-docs/src/components/toast/overview/overview.md +++ b/apps/pie-docs/src/components/toast/overview/overview.md @@ -224,6 +224,11 @@ Each level takes priority over those below it, queues alongside toasts of the sa tableData: priorityQueue } %} +{% notification { + type: "information", + message: "The priority queue is managed by the [Toast Provider](/components/toast/toast-provider/code/) in engineering." +} %} + --- ## Behaviours diff --git a/apps/pie-docs/src/components/toast/toast-provider/code.md b/apps/pie-docs/src/components/toast/toast-provider/code.md new file mode 100644 index 0000000000..33ca59e398 --- /dev/null +++ b/apps/pie-docs/src/components/toast/toast-provider/code.md @@ -0,0 +1,139 @@ +--- +eleventyNavigation: + key: Toast Provider + parent: Toast + order: 4 +shouldShowContents: true +eleventyComputed: + props: "{% include './props.json' %}" + events: "{% include './events.json' %}" +--- + +## Overview + +

+ + GitHub Workflow Status + + + + GitHub Workflow Status + +

+ +`pie-toast-provider` is a Web Component built using [Lit](https://lit.dev/). It offers a simple and accessible toast provider component for web applications. + +This component can be easily integrated into various frontend frameworks and customised through a set of properties. + +The `pie-toast-provider` component provides centralized management for toast notifications in an application. It ensures that toasts are displayed in [priority order](/components/toast/#priority-queue) based on their variant and actionable state, using a queueing system. The component handles the lifecycle of each toast, including dismissing the current toast and showing the next one. + +{% notification { + type: "information", + iconName: "engineers", + message: "You can try out this component on our [Storybook](https://webc.pie.design/?path=/docs/toast-provider) instance!" +} %} + +## Installation + +To install `pie-toast-provider` in your application, run the following on your command line: + +```shell +npm i @justeattakeaway/pie-webc +``` + +```shell +yarn add @justeattakeaway/pie-webc +``` + +{% notification { + type: "neutral", + iconName: "link", + message: "For more information on using PIE components as part of an application, check out the [Getting Started Guide](https://github.com/justeattakeaway/pie/wiki/Getting-started-with-PIE-Web-Components)." +} %} + +## Props + +{% componentDetailsTable { + tableData: props +} %} + +## Events + +{% componentDetailsTable { + tableData: events +} %} + +## Examples + +The usage guideline is: + +- Place `pie-toast-provider` at the root level of your application or page. +- Use the `toaster` utility from any where in your app to dynamically create toasts. + +### Importing the component + +For HTML: + +```js +// import as module into a js file e.g. main.js +import '@justeattakeaway/pie-webc/components/toast-provider.js' +``` + +```html + + + +``` + +For Native JS Applications, Vue, Angular, Svelte etc.: + +```js +// Vue templates (using Nuxt 3) +import '@justeattakeaway/pie-webc/components/toast-provider.js'; + + +``` + +For React Applications: + +```jsx +import { PieToastProvider } from '@justeattakeaway/pie-webc/react/toast-provider.js'; + + +``` + +### Creating Toasts with `toaster` + +The `toaster` utility dynamically creates toasts. It can be imported and called from any file or component in your application. + +```js +import { toaster } from '@justeattakeaway/pie-webc/components/toast-provider.js'; + +toaster.createToast({ + message: 'This is a success toast!', + variant: 'success', + isDismissible: true, +}); + +``` + +To clear all active and queued toasts: + +```js +toaster.clearToasts(); + +``` + +{% notification { + type: "neutral", + iconName: "link", + message: "For more examples, see [here](https://github.com/justeattakeaway/pie-aperture/tree/main)." +} %} + +## Changelog + +{% notification { + type: "neutral", + iconName: "link", + message: "See [here](https://github.com/justeattakeaway/pie/blob/main/packages/components/pie-toast/CHANGELOG.md)." +} %} diff --git a/apps/pie-docs/src/components/toast/toast-provider/events.json b/apps/pie-docs/src/components/toast/toast-provider/events.json new file mode 100644 index 0000000000..179ef027c8 --- /dev/null +++ b/apps/pie-docs/src/components/toast/toast-provider/events.json @@ -0,0 +1,15 @@ +{ + "headings": [ + "Event", + "Type", + "Description" + ], + "rows": [ + [ + "`pie-toast-provider-queue-update`", + "`CustomEvent`", + "Triggered when a toast is added or removed from the queue." + ] + ] + } + \ No newline at end of file diff --git a/apps/pie-docs/src/components/toast/toast-provider/props.json b/apps/pie-docs/src/components/toast/toast-provider/props.json new file mode 100644 index 0000000000..2d196a2be3 --- /dev/null +++ b/apps/pie-docs/src/components/toast/toast-provider/props.json @@ -0,0 +1,19 @@ +{ + "headings": ["Prop", "Options", "Description", "Default"], + "rows": [ + [ + "options", + { + "type": "code", + "item": [["{}"]] + }, + "Default options for all toasts; accepts all toast props.", + { + "type": "code", + "item": [["{}"]] + } + ] + ] +} + + diff --git a/apps/pie-docs/test/snapshots/expected-routes.snapshot.json b/apps/pie-docs/test/snapshots/expected-routes.snapshot.json index 219c79fc2c..606da0bb8c 100644 --- a/apps/pie-docs/test/snapshots/expected-routes.snapshot.json +++ b/apps/pie-docs/test/snapshots/expected-routes.snapshot.json @@ -86,6 +86,7 @@ "components/toast", "components/toast/code", "components/toast/motion", + "components/toast/toast-provider/code", "components/tooltip", "components/uploader", "designers",