From ee0316bd88ff98ac04a00da2c839980cf1193fc8 Mon Sep 17 00:00:00 2001 From: Raouf Date: Mon, 2 Dec 2024 17:28:21 +0300 Subject: [PATCH 1/2] fix(pie-docs): DSW-2222 add toast provider docs --- .../src/components/toast/overview/overview.md | 5 + .../components/toast/toast-provider/code.md | 139 ++++++++++++++++++ .../toast/toast-provider/events.json | 15 ++ .../toast/toast-provider/props.json | 19 +++ .../snapshots/expected-routes.snapshot.json | 5 + 5 files changed, 183 insertions(+) create mode 100644 apps/pie-docs/src/components/toast/toast-provider/code.md create mode 100644 apps/pie-docs/src/components/toast/toast-provider/events.json create mode 100644 apps/pie-docs/src/components/toast/toast-provider/props.json 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..b430e4588d 100644 --- a/apps/pie-docs/test/snapshots/expected-routes.snapshot.json +++ b/apps/pie-docs/test/snapshots/expected-routes.snapshot.json @@ -78,6 +78,10 @@ "components/tabs", "components/tag", "components/tag/code", + "components/template", + "components/template/code", + "components/template/motion", + "components/template/overview", "components/text-input", "components/text-input/code", "components/textarea", @@ -86,6 +90,7 @@ "components/toast", "components/toast/code", "components/toast/motion", + "components/toast/toast-provider/code", "components/tooltip", "components/uploader", "designers", From 98ad3baf6cb3f8261591a8f7b2d3f3b55cec2ebe Mon Sep 17 00:00:00 2001 From: Raouf Date: Mon, 2 Dec 2024 17:41:12 +0300 Subject: [PATCH 2/2] fix(pie-docs): DSW-2222 update snapshots --- apps/pie-docs/test/snapshots/expected-routes.snapshot.json | 4 ---- 1 file changed, 4 deletions(-) diff --git a/apps/pie-docs/test/snapshots/expected-routes.snapshot.json b/apps/pie-docs/test/snapshots/expected-routes.snapshot.json index b430e4588d..606da0bb8c 100644 --- a/apps/pie-docs/test/snapshots/expected-routes.snapshot.json +++ b/apps/pie-docs/test/snapshots/expected-routes.snapshot.json @@ -78,10 +78,6 @@ "components/tabs", "components/tag", "components/tag/code", - "components/template", - "components/template/code", - "components/template/motion", - "components/template/overview", "components/text-input", "components/text-input/code", "components/textarea",