@iress-oss/ids-mcp-server 6.0.0-alpha.1-canary-20251204032753-fe18cab → 6.0.0-alpha.1-canary-20251204040305-3639454

package/generated/docs/components_components-toaster-docs.md

@@ -0,0 +1,451 @@
+Toaster
+=======
+
+Overview
+--------
+
+Toaster provide users with important, time-sensitive information.
+
+* * *
+
+Updated
+
+**Recently updated**
+
+This component has been recently updated with new props. The props have been marked as beta. Please tell us if there are any issues.
+
+[](./iframe.html?id=components-toaster--provider)
+
+`IressToasterProvider` does not change the position on each render, it can only be done on the initial render.
+
+Show toast using provider
+
+```
+
+import {
+  IressButton,
+  IressToasterProvider,
+  type IressToasterProviderProps,
+  useToaster,
+} from '@iress-oss/ids-components';
+const ToastWithTrigger \= () \=> {
+  const toaster \= useToaster();
+  return (
+    <IressButton
+      onClick\={() \=>
+        toaster.error({
+          heading: 'Error',
+          content:
+            'Connection failure. Longer text description should wrap and look like this. Try to limit to 3 lines or less.',
+        })
+      }
+    \>
+      Show toast using provider    </IressButton\>
+  );
+};
+export const SimpleToasterExample \= () \=> (
+  <IressToasterProvider \>
+    <ToastWithTrigger />
+  </IressToasterProvider\>
+);
+
+```
+
+Props
+-----
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| container | 
+object
+
+
+
+ | \- | \- |
+| id | 
+
+A unique identifier for the toaster provider. This is useful if you have multiple toaster providers in your application based on context.
+
+string
+
+
+
+ | \- | Set string |
+
+Usage
+-----
+
+To use the toaster, wrap your `<App/>` or the component that you want to use the toasts within with `<IressToasterProvider />`. This provides the context for the `useToaster` hook, which is used to trigger toasts in your application.
+
+You can use the `success`, `info` and `error` methods from the hook to trigger toasts in your application.
+
+[](./iframe.html?id=components-toaster--provider)
+
+`IressToasterProvider` does not change the position on each render, it can only be done on the initial render.
+
+Show toast using provider
+
+```
+
+import {
+  IressButton,
+  IressToasterProvider,
+  type IressToasterProviderProps,
+  useToaster,
+} from '@iress-oss/ids-components';
+const ToastWithTrigger \= () \=> {
+  const toaster \= useToaster();
+  return (
+    <IressButton
+      onClick\={() \=>
+        toaster.error({
+          heading: 'Error',
+          content:
+            'Connection failure. Longer text description should wrap and look like this. Try to limit to 3 lines or less.',
+        })
+      }
+    \>
+      Show toast using provider    </IressButton\>
+  );
+};
+export const SimpleToasterExample \= () \=> (
+  <IressToasterProvider \>
+    <ToastWithTrigger />
+  </IressToasterProvider\>
+);
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| container | 
+object
+
+
+
+ | \- | \- |
+| id | 
+
+A unique identifier for the toaster provider. This is useful if you have multiple toaster providers in your application based on context.
+
+string
+
+
+
+ | \- | Set string |
+
+### Closing toasts via the provider
+
+If you want to dismiss a toast programmatically, you can use the `close` method from the `useToaster` hook. This method takes a toast ID as an argument, which is returned when you create a toast using the `useToaster` hook.
+
+[](./iframe.html?id=components-toaster--close)
+
+Show toast using provider
+
+```
+
+import {
+  IressButton,
+  IressInline,
+  IressToasterProvider,
+  type IressToasterProviderProps,
+  useToaster,
+} from '@iress-oss/ids-components';
+import { useState } from 'react';
+const ToastWithTrigger \= () \=> {
+  const toaster \= useToaster();
+  const \[lastToastId, setLastToastId\] \= useState<string | null\>(null);
+  return (
+    <IressInline gap\="sm"\>
+      <IressButton        onClick={() \=> {
+          const toastId \= toaster.error({
+            heading: 'Error',
+            content:
+              'Connection failure. Longer text description should wrap and look like this. Try to limit to 3 lines or less.',
+            onClose: () \=> {
+              setLastToastId(null);
+            },
+          });
+          setLastToastId(toastId);
+        }}
+      >        Show toast using provider      </IressButton\>
+      {lastToastId && (
+        <IressButton onClick\={() \=> toaster.close(lastToastId)}\>
+          Close the last toast opened        </IressButton\>
+      )}
+    </IressInline\>
+  );
+};
+export const CloseToastViaProvider \= () \=> (
+  <IressToasterProvider \>
+    <ToastWithTrigger />
+  </IressToasterProvider\>
+);
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| container | 
+object
+
+
+
+ | \- | \- |
+| id | 
+
+A unique identifier for the toaster provider. This is useful if you have multiple toaster providers in your application based on context.
+
+string
+
+
+
+ | \- | Set string |
+
+Examples
+--------
+
+### Status
+
+The toast offers three status that set a distinctive colour and icon. They can be set using the `status` prop. Their different use cases are described here.
+
+[](./iframe.html?id=components-toaster--statuses)
+
+errorinfosuccess
+
+```
+
+import {
+  IressButton,
+  IressInline,
+  IressToasterProvider,
+  type IressToasterProviderProps,
+  type ToastStatus,
+  useToaster,
+} from '@iress-oss/ids-components';
+const ToastWithTrigger \= ({ status }: { status: ToastStatus }) \=> {
+  const toaster \= useToaster();
+  return (
+    <IressButton
+      onClick\={() \=>
+        toaster\[status\]({ content: \`Hello, I am a ${status} toast\` })
+      }
+    \>
+      {status}
+    </IressButton\>
+  );
+};
+export const ToastStatuses \= () \=> (
+  <IressToasterProvider \>
+    <IressInline gap\="sm"\>
+      <ToastWithTrigger  status\="error" />
+      <ToastWithTrigger  status\="info" />
+      <ToastWithTrigger  status\="success" />
+    </IressInline\>
+  </IressToasterProvider\>
+);
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| container | 
+object
+
+
+
+ | \- | \- |
+| id | 
+
+A unique identifier for the toaster provider. This is useful if you have multiple toaster providers in your application based on context.
+
+string
+
+
+
+ | \- | Set string |
+
+### Timeout
+
+By default, toasts will time out after six seconds, after which they will animate out of view. This can be customised using the `timeout` prop when created using the `useToaster` hook.
+
+Timeouts must be set in milliseconds; as an example, if you want a timeout of five seconds, set the timeout to 5000.
+
+[](./iframe.html?id=components-toaster--timeout)
+
+1000ms timeout
+
+```
+
+import {
+  IressButton,
+  IressToasterProvider,
+  type IressToasterProviderProps,
+  useToaster,
+} from '@iress-oss/ids-components';
+const ToastWithTrigger \= () \=> {
+  const toaster \= useToaster();
+  return (
+    <IressButton
+      onClick\={() \=>
+        toaster.success({
+          content: 'This is a really quick toast',
+          timeout: 1000,
+        })
+      }
+    \>
+      1000ms timeout    </IressButton\>
+  );
+};
+export const ToasterTimeout \= () \=> (
+  <IressToasterProvider \>
+    <ToastWithTrigger />
+  </IressToasterProvider\>
+);
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| container | 
+object
+
+
+
+ | \- | \- |
+| id | 
+
+A unique identifier for the toaster provider. This is useful if you have multiple toaster providers in your application based on context.
+
+string
+
+
+
+ | \- | Set string |
+
+### Position
+
+By default, the `IressToasterProvider`'s `position` is set to `bottom-end`, but there may be occasions when you need toasts to appear in a different part of the screen. This can be controlled with the `position` prop on the `IressToasterProvider` component, or as the first argument to `useToaster`. There are 6 positions to choose from.
+
+**Note:** The toast position should be consistent based on context, so users can find them easily.
+
+[](./iframe.html?id=components-toaster--position)
+
+top-starttop-centertop-end
+
+Toaster positions
+
+bottom-startbottom-centerbottom-end
+
+```
+
+import {
+  IressButton,
+  IressInline,
+  IressPanel,
+  IressStack,
+  IressText,
+  IressToasterProvider,
+  type IressToasterProviderProps,
+  type NewToast,
+  useToaster,
+} from '@iress-oss/ids-components';
+const DEFAULT\_TOAST: NewToast \= {
+  content: 'Message sent successfully',
+  heading: 'Success',
+  status: 'success',
+};
+const Toaster \= () \=> {
+  const topStart \= useToaster('top-start');
+  const topCenter \= useToaster('top-center');
+  const topEnd \= useToaster('top-end');
+  const bottomStart \= useToaster('bottom-start');
+  const bottomCenter \= useToaster('bottom-center');
+  const bottomEnd \= useToaster('bottom-end');
+  return (
+    <div style\={{ padding: '80px 150px' }}\>
+      <IressStack gap\="md"\>
+        <IressInline horizontalAlign\="between" gap\="sm"\>
+          <IressButton onClick\={() \=> topStart.success(DEFAULT\_TOAST)}\>
+            top-start          </IressButton\>
+          <IressButton onClick\={() \=> topCenter.success(DEFAULT\_TOAST)}\>
+            top-center          </IressButton\>
+          <IressButton onClick\={() \=> topEnd.success(DEFAULT\_TOAST)}\>
+            top-end          </IressButton\>
+        </IressInline\>
+        <IressPanel bg\="transparent" p\="lg"\>
+          <IressText textAlign\="center"\>Toaster positions</IressText\>
+        </IressPanel\>
+        <IressInline horizontalAlign\="between"\>
+          <IressButton onClick\={() \=> bottomStart.success(DEFAULT\_TOAST)}\>
+            bottom-start          </IressButton\>
+          <IressButton onClick\={() \=> bottomCenter.success(DEFAULT\_TOAST)}\>
+            bottom-center          </IressButton\>
+          <IressButton onClick\={() \=> bottomEnd.success(DEFAULT\_TOAST)}\>
+            bottom-end          </IressButton\>
+        </IressInline\>
+      </IressStack\>
+    </div\>
+  );
+};
+export const ToasterPositionExamples \= () \=> (
+  <IressToasterProvider  id\="bottom-end" position\="bottom-end"\>
+    <IressToasterProvider  id\="bottom-center" position\="bottom-center"\>
+      <IressToasterProvider  id\="bottom-start" position\="bottom-start"\>
+        <IressToasterProvider  id\="top-start" position\="top-start"\>
+          <IressToasterProvider  id\="top-center" position\="top-center"\>
+            <IressToasterProvider  id\="top-end" position\="top-end"\>
+              <Toaster />
+            </IressToasterProvider\>
+          </IressToasterProvider\>
+        </IressToasterProvider\>
+      </IressToasterProvider\>
+    </IressToasterProvider\>
+  </IressToasterProvider\>
+);
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| container | 
+object
+
+
+
+ | \- | \- |
+| id | 
+
+A unique identifier for the toaster provider. This is useful if you have multiple toaster providers in your application based on context.
+
+string
+
+
+
+ | \- | Set string |
+| position | 
+
+\-
+
+ | \- | \- |
+
+Migrating from version 4 and below
+----------------------------------
+
+### Adding the provider
+
+For your components to work as previously, you will need to set up the `IressToasterProvider` at the root of your application. This will allow you to use the `useToaster` hook to trigger toasts from anywhere in your application using the status and props of the toast.
+
+const App \= () \=> <IressToasterProvider\>Rest of app here</IressToasterProvider\>;
+
+```