@iress-oss/ids-mcp-server 0.0.1-dev.0

package/generated/docs/components-text-docs.md

@@ -0,0 +1,394 @@
+[](#text)Text
+=============
+
+Overview
+--------
+
+The `IressText` component allows you to set typographic styles either on one element, or a block on HTML elements.
+
+The quick brown fox jumps over the lazy dog
+
+Hide code
+
+\[data-radix-scroll-area-viewport\] { scrollbar-width: none; -ms-overflow-style: none; -webkit-overflow-scrolling: touch; } \[data-radix-scroll-area-viewport\]::-webkit-scrollbar { display: none; } :where(\[data-radix-scroll-area-viewport\]) { display: flex; flex-direction: column; align-items: stretch; } :where(\[data-radix-scroll-area-content\]) { flex-grow: 1; }
+
+<IressText\>
+  The quick brown fox jumps over the lazy dog
+</IressText\>
+
+Copy
+
+[](#usage)Usage
+---------------
+
+### [](#the-element-prop)The `element` prop
+
+With the `element` prop you can select which HTML element you would like the text component to render as.
+
+It renders as a `div` by default, but can also be set to any standard typography element.
+
+This is a p element.
+
+This is a div element.
+
+This is a span element.
+
+This is a h1 element.
+=====================
+
+This is a h2 element.
+---------------------
+
+### This is a h3 element.
+
+#### This is a h4 element.
+
+##### This is a h5 element.
+
+###### This is a h6 element.
+
+`This is a code element.`
+
+> This is a blockquote element.
+
+This is a caption element.This is a cite element.This is a small element.
+
+Hide code
+
+\[data-radix-scroll-area-viewport\] { scrollbar-width: none; -ms-overflow-style: none; -webkit-overflow-scrolling: touch; } \[data-radix-scroll-area-viewport\]::-webkit-scrollbar { display: none; } :where(\[data-radix-scroll-area-viewport\]) { display: flex; flex-direction: column; align-items: stretch; } :where(\[data-radix-scroll-area-content\]) { flex-grow: 1; }
+
+<IressStack gutter\="md"\>
+  <IressText element\="p"\>
+    This is a p element.  </IressText\>
+  <IressText element\="div"\>
+    This is a div element.  </IressText\>
+  <IressText element\="span"\>
+    This is a span element.  </IressText\>
+  <IressText element\="h1"\>
+    This is a h1 element.  </IressText\>
+  <IressText element\="h2"\>
+    This is a h2 element.  </IressText\>
+  <IressText element\="h3"\>
+    This is a h3 element.  </IressText\>
+  <IressText element\="h4"\>
+    This is a h4 element.  </IressText\>
+  <IressText element\="h5"\>
+    This is a h5 element.  </IressText\>
+  <IressText element\="h6"\>
+    This is a h6 element.  </IressText\>
+  <IressText element\="code"\>
+    This is a code element.  </IressText\>
+  <IressText element\="blockquote"\>
+    This is a blockquote element.  </IressText\>
+  <IressText element\="caption"\>
+    This is a caption element.  </IressText\>
+  <IressText element\="cite"\>
+    This is a cite element.  </IressText\>
+  <IressText element\="small"\>
+    This is a small element.  </IressText\>
+</IressStack\>
+
+Copy
+
+### [](#the-variant-prop)The `variant` prop
+
+The `variant` prop allows you alter the default styling of the element that it selected.
+
+For example, in order to maintain the semantic structure of headings, you may need to style a `h2` element like a `h4`. Or you may want to style your heading using one of our display text formats.
+
+This is the blockquote variant.
+
+This is the body variant.
+
+This is the bold variant.
+
+This is the code variant.
+
+This is the display variant.
+
+This is the display1 variant.
+
+This is the display2 variant.
+
+This is the display3 variant.
+
+This is the display4 variant.
+
+This is the h1 variant.
+
+This is the h2 variant.
+
+This is the h3 variant.
+
+This is the h4 variant.
+
+This is the h5 variant.
+
+This is the h6 variant.
+
+This is the italic variant.
+
+This is the lead variant.
+
+This is the small variant.
+
+This is the cite variant.
+
+This is the caption variant.
+
+Hide code
+
+\[data-radix-scroll-area-viewport\] { scrollbar-width: none; -ms-overflow-style: none; -webkit-overflow-scrolling: touch; } \[data-radix-scroll-area-viewport\]::-webkit-scrollbar { display: none; } :where(\[data-radix-scroll-area-viewport\]) { display: flex; flex-direction: column; align-items: stretch; } :where(\[data-radix-scroll-area-content\]) { flex-grow: 1; }
+
+<IressStack gutter\="md"\>
+  <IressText variant\="blockquote"\>
+    This is the blockquote variant.  </IressText\>
+  <IressText variant\="body"\>
+    This is the body variant.  </IressText\>
+  <IressText variant\="bold"\>
+    This is the bold variant.  </IressText\>
+  <IressText variant\="code"\>
+    This is the code variant.  </IressText\>
+  <IressText variant\="display"\>
+    This is the display variant.  </IressText\>
+  <IressText variant\="display1"\>
+    This is the display1 variant.  </IressText\>
+  <IressText variant\="display2"\>
+    This is the display2 variant.  </IressText\>
+  <IressText variant\="display3"\>
+    This is the display3 variant.  </IressText\>
+  <IressText variant\="display4"\>
+    This is the display4 variant.  </IressText\>
+  <IressText variant\="h1"\>
+    This is the h1 variant.  </IressText\>
+  <IressText variant\="h2"\>
+    This is the h2 variant.  </IressText\>
+  <IressText variant\="h3"\>
+    This is the h3 variant.  </IressText\>
+  <IressText variant\="h4"\>
+    This is the h4 variant.  </IressText\>
+  <IressText variant\="h5"\>
+    This is the h5 variant.  </IressText\>
+  <IressText variant\="h6"\>
+    This is the h6 variant.  </IressText\>
+  <IressText variant\="italic"\>
+    This is the italic variant.  </IressText\>
+  <IressText variant\="lead"\>
+    This is the lead variant.  </IressText\>
+  <IressText variant\="small"\>
+    This is the small variant.  </IressText\>
+  <IressText variant\="cite"\>
+    This is the cite variant.  </IressText\>
+  <IressText variant\="caption"\>
+    This is the caption variant.  </IressText\>
+</IressStack\>
+
+Copy
+
+### [](#the-mode-prop)The `mode` prop
+
+The `mode` prop can be used to set the colour of the text to these predefined mode colours: Body, Muted, Primary, Info, Success, Warning, Danger, Positive and Negative.
+
+This is danger mode.
+
+This is info mode.
+
+This is muted mode.
+
+This is primary mode.
+
+This is success mode.
+
+This is warning mode.
+
+This is positive mode.
+
+This is negative mode.
+
+Nested text mode demonstration:
+
+I am nested, and return to the original colour
+
+Hide code
+
+\[data-radix-scroll-area-viewport\] { scrollbar-width: none; -ms-overflow-style: none; -webkit-overflow-scrolling: touch; } \[data-radix-scroll-area-viewport\]::-webkit-scrollbar { display: none; } :where(\[data-radix-scroll-area-viewport\]) { display: flex; flex-direction: column; align-items: stretch; } :where(\[data-radix-scroll-area-content\]) { flex-grow: 1; }
+
+<IressStack gutter\="md"\>
+  <IressText mode\="danger"\>
+    This is danger mode.  </IressText\>
+  <IressText mode\="info"\>
+    This is info mode.  </IressText\>
+  <IressText mode\="muted"\>
+    This is muted mode.  </IressText\>
+  <IressText mode\="primary"\>
+    This is primary mode.  </IressText\>
+  <IressText mode\="success"\>
+    This is success mode.  </IressText\>
+  <IressText mode\="warning"\>
+    This is warning mode.  </IressText\>
+  <IressText mode\="positive"\>
+    This is positive mode.  </IressText\>
+  <IressText mode\="negative"\>
+    This is negative mode.  </IressText\>
+  <IressText mode\="danger"\>
+    Nested text mode demonstration:{' '}
+    <IressText\>
+      I am nested, and return to the original colour    </IressText\>
+  </IressText\>
+</IressStack\>
+
+Copy
+
+### [](#the-align-prop)The `align` prop
+
+The `align` prop can be used to set the text's alignment.
+
+The quick brown fox jumps over the lazy dog
+
+The quick brown fox jumps over the lazy dog
+
+The quick brown fox jumps over the lazy dog
+
+The quick brown fox jumps over the lazy dog
+
+The quick brown fox jumps over the lazy dog
+
+Hide code
+
+\[data-radix-scroll-area-viewport\] { scrollbar-width: none; -ms-overflow-style: none; -webkit-overflow-scrolling: touch; } \[data-radix-scroll-area-viewport\]::-webkit-scrollbar { display: none; } :where(\[data-radix-scroll-area-viewport\]) { display: flex; flex-direction: column; align-items: stretch; } :where(\[data-radix-scroll-area-content\]) { flex-grow: 1; }
+
+<IressStack gutter\="md"\>
+  <IressText align\="inherit"\>
+    The quick brown fox jumps over the lazy dog  </IressText\>
+  <IressText align\="left"\>
+    The quick brown fox jumps over the lazy dog  </IressText\>
+  <IressText align\="center"\>
+    The quick brown fox jumps over the lazy dog  </IressText\>
+  <IressText align\="right"\>
+    The quick brown fox jumps over the lazy dog  </IressText\>
+  <IressText align\="justify"\>
+    The quick brown fox jumps over the lazy dog  </IressText\>
+</IressStack\>
+
+Copy
+
+[](#behaviour)Behaviour
+-----------------------
+
+### [](#headings-with-icons)Headings with icons
+
+Icons can be added to a heading by simply including the icon as a direct child of the heading, as below.
+
+The icon inherits the font size from the heading, so there is no need to set a size on the icon. If the icon is the first or last child of the heading, it will have some inline spacing added to save you from having to use the `IressInline` component.
+
+H1 heading with icons
+=====================
+
+H2 heading with icons
+---------------------
+
+### H3 heading with icons
+
+#### H4 heading with icons
+
+##### H5 heading with icons
+
+###### H6 heading with icons
+
+Hide code
+
+\[data-radix-scroll-area-viewport\] { scrollbar-width: none; -ms-overflow-style: none; -webkit-overflow-scrolling: touch; } \[data-radix-scroll-area-viewport\]::-webkit-scrollbar { display: none; } :where(\[data-radix-scroll-area-viewport\]) { display: flex; flex-direction: column; align-items: stretch; } :where(\[data-radix-scroll-area-content\]) { flex-grow: 1; }
+
+<IressStack\>
+  <IressText element\="h1"\>
+    <IressIcon name\="smile-wink" />
+    <span\>
+      H1 heading with icons    </span\>
+    <IressIcon name\="smile-wink" />
+  </IressText\>
+  <IressText element\="h2"\>
+    <IressIcon name\="smile-wink" />
+    <span\>
+      H2 heading with icons    </span\>
+    <IressIcon name\="smile-wink" />
+  </IressText\>
+  <IressText element\="h3"\>
+    <IressIcon name\="smile-wink" />
+    <span\>
+      H3 heading with icons    </span\>
+    <IressIcon name\="smile-wink" />
+  </IressText\>
+  <IressText element\="h4"\>
+    <IressIcon name\="smile-wink" />
+    <span\>
+      H4 heading with icons    </span\>
+    <IressIcon name\="smile-wink" />
+  </IressText\>
+  <IressText element\="h5"\>
+    <IressIcon name\="smile-wink" />
+    <span\>
+      H5 heading with icons    </span\>
+    <IressIcon name\="smile-wink" />
+  </IressText\>
+  <IressText element\="h6"\>
+    <IressIcon name\="smile-wink" />
+    <span\>
+      H6 heading with icons    </span\>
+    <IressIcon name\="smile-wink" />
+  </IressText\>
+</IressStack\>
+
+Copy
+
+### [](#block-of-typographic-content)Block of typographic content
+
+If you just need to style a block of typography content, you can just wrap the entire block of HTML with the text component.
+
+Heading text
+------------
+
+This is just raw HTML inside the text component. This is just raw HTML inside the text component.
+
+> Nisi optio dolore debitis porro ex quis odio atque, ut obcaecati dolorem enim molestiae eum voluptatem excepturi quisquam. Someone in latin
+
+You can also use dividers inside blocks to separate content.
+
+* * *
+
+Just like the one above.
+
+Hide code
+
+\[data-radix-scroll-area-viewport\] { scrollbar-width: none; -ms-overflow-style: none; -webkit-overflow-scrolling: touch; } \[data-radix-scroll-area-viewport\]::-webkit-scrollbar { display: none; } :where(\[data-radix-scroll-area-viewport\]) { display: flex; flex-direction: column; align-items: stretch; } :where(\[data-radix-scroll-area-content\]) { flex-grow: 1; }
+
+<IressText\>
+  <h2\>
+    Heading text  </h2\>
+  <p\>
+    This is just raw HTML inside the text component. This is just raw HTML inside the text component.  </p\>
+  <blockquote\>
+    Nisi optio dolore debitis porro ex quis odio atque, ut obcaecati dolorem enim molestiae eum voluptatem excepturi quisquam.{' '}
+    <cite\>
+      Someone in latin    </cite\>
+  </blockquote\>
+  <p\>
+    You can also use dividers inside blocks to separate content.  </p\>
+  <hr />
+  <p\>
+    Just like the one above.  </p\>
+</IressText\>
+
+Copy
+
+On this page
+
+*   [Overview](#overview)
+*   [Props](#props)
+*   [Usage](#usage)
+    *   [The element prop](#the-element-prop)
+    *   [The variant prop](#the-variant-prop)
+    *   [The mode prop](#the-mode-prop)
+    *   [The align prop](#the-align-prop)
+*   [Behaviour](#behaviour)
+    *   [Headings with icons](#headings-with-icons)
+    *   [Block of typographic content](#block-of-typographic-content)

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

@@ -0,0 +1,294 @@
+[](#toaster)Toaster
+===================
+
+Overview
+--------
+
+Toaster provide users with important, time-sensitive information.
+
+`IressToasterProvider` does not change the position on each render, it can only be done on the initial render.
+
+Show toast using provider
+
+Hide code
+
+\[data-radix-scroll-area-viewport\] { scrollbar-width: none; -ms-overflow-style: none; -webkit-overflow-scrolling: touch; } \[data-radix-scroll-area-viewport\]::-webkit-scrollbar { display: none; } :where(\[data-radix-scroll-area-viewport\]) { display: flex; flex-direction: column; align-items: stretch; } :where(\[data-radix-scroll-area-content\]) { flex-grow: 1; }
+
+import {
+  IressButton,
+  IressToasterProvider,
+  IressToasterProviderProps,
+  useToaster,
+} from '@iress-oss/ids-components';
+const ToastWithTrigger \= () \=> {
+  const toaster \= useToaster();
+  return (
+    <IressButton
+      onClick\={() \=>
+        toaster.error({
+          heading: 'Error',
+          children:
+            '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\>
+);
+
+Copy
+
+[](#controlling-toasts)Controlling toasts
+-----------------------------------------
+
+### [](#using-the-iresstoasterprovider)Using the `IressToasterProvider`
+
+The recommended way to create toasts is by using the `<IressToasterProvider />` alongside the `useToaster` hook. By using the `success`, `info` and `error` methods from the hook, you can trigger toasts in your application.
+
+To use, wrap your `<App/>` or the component that you want to use the `useToaster` hook with `<IressToasterProvider />`.
+
+`IressToasterProvider` does not change the position on each render, it can only be done on the initial render.
+
+Show toast using provider
+
+Hide code
+
+\[data-radix-scroll-area-viewport\] { scrollbar-width: none; -ms-overflow-style: none; -webkit-overflow-scrolling: touch; } \[data-radix-scroll-area-viewport\]::-webkit-scrollbar { display: none; } :where(\[data-radix-scroll-area-viewport\]) { display: flex; flex-direction: column; align-items: stretch; } :where(\[data-radix-scroll-area-content\]) { flex-grow: 1; }
+
+import {
+  IressButton,
+  IressToasterProvider,
+  IressToasterProviderProps,
+  useToaster,
+} from '@iress-oss/ids-components';
+const ToastWithTrigger \= () \=> {
+  const toaster \= useToaster();
+  return (
+    <IressButton
+      onClick\={() \=>
+        toaster.error({
+          heading: 'Error',
+          children:
+            '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\>
+);
+
+Copy
+
+[](#examples)Examples
+---------------------
+
+### [](#status)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.
+
+successerrorinfo
+
+Hide code
+
+\[data-radix-scroll-area-viewport\] { scrollbar-width: none; -ms-overflow-style: none; -webkit-overflow-scrolling: touch; } \[data-radix-scroll-area-viewport\]::-webkit-scrollbar { display: none; } :where(\[data-radix-scroll-area-viewport\]) { display: flex; flex-direction: column; align-items: stretch; } :where(\[data-radix-scroll-area-content\]) { flex-grow: 1; }
+
+import {
+  IressButton,
+  IressInline,
+  IressToastProps,
+  IressToasterProps,
+  IressToasterProvider,
+  TOAST\_STATUS,
+  useToaster,
+} from '@iress-oss/ids-components';
+const ToastWithTrigger \= ({ status }: Pick<IressToastProps, 'status'\>) \=> {
+  const toaster \= useToaster();
+  return (
+    <IressButton
+      onClick\={() \=>
+        toaster\[status\]({ children: \`Hello, I am a ${status} toast\` })
+      }
+    \>
+      {status}
+    </IressButton\>
+  );
+};
+export const ToastStatuses \= (args: IressToasterProps) \=> (
+  <IressToasterProvider \>
+    <IressInline gutter\="sm"\>
+      {TOAST\_STATUS.map((status) \=> (
+        <ToastWithTrigger  status\={status} />
+      ))}
+    </IressInline\>
+  </IressToasterProvider\>
+);
+
+Copy
+
+### [](#timeout)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.
+
+1000ms timeout
+
+Hide code
+
+\[data-radix-scroll-area-viewport\] { scrollbar-width: none; -ms-overflow-style: none; -webkit-overflow-scrolling: touch; } \[data-radix-scroll-area-viewport\]::-webkit-scrollbar { display: none; } :where(\[data-radix-scroll-area-viewport\]) { display: flex; flex-direction: column; align-items: stretch; } :where(\[data-radix-scroll-area-content\]) { flex-grow: 1; }
+
+import {
+  IressButton,
+  IressToasterProvider,
+  IressToasterProviderProps,
+  useToaster,
+} from '@iress-oss/ids-components';
+const ToastWithTrigger \= () \=> {
+  const toaster \= useToaster();
+  return (
+    <IressButton
+      onClick\={() \=>
+        toaster.success({
+          children: 'This is a really quick toast',
+          timeout: 1000,
+        })
+      }
+    \>
+      1000ms timeout    </IressButton\>
+  );
+};
+export const ToasterTimeout \= () \=> (
+  <IressToasterProvider \>
+    <ToastWithTrigger />
+  </IressToasterProvider\>
+);
+
+Copy
+
+### [](#position)Position
+
+By default, the `IressToaster`'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 across your app. For this reason, the position is set on the `IressToastProvider` or the `useToaster` hook, and not on the individual toasts.
+
+top-starttop-centertop-end
+
+Toaster positions
+
+bottom-startbottom-centerbottom-end
+
+Hide code
+
+\[data-radix-scroll-area-viewport\] { scrollbar-width: none; -ms-overflow-style: none; -webkit-overflow-scrolling: touch; } \[data-radix-scroll-area-viewport\]::-webkit-scrollbar { display: none; } :where(\[data-radix-scroll-area-viewport\]) { display: flex; flex-direction: column; align-items: stretch; } :where(\[data-radix-scroll-area-content\]) { flex-grow: 1; }
+
+import {
+  IressButton,
+  IressInline,
+  IressPanel,
+  IressStack,
+  IressText,
+  IressToasterProps,
+  IressToasterProvider,
+  IressToasterProviderProps,
+  IressToastProps,
+  useToaster,
+} from '@iress-oss/ids-components';
+import { useState } from 'react';
+const DEFAULT\_TOAST: IressToastProps \= {
+  children: 'Message sent successfully',
+  heading: 'Success',
+  status: 'success',
+};
+const Toaster \= () \=> {
+  const \[position, setPosition\] \=
+    useState<IressToasterProps\['position'\]\>('bottom-end');
+  const { status, ...toast } \= DEFAULT\_TOAST;
+  const toaster \= useToaster(position);
+  const changePosition \= (position: IressToasterProps\['position'\]) \=> {
+    setPosition(position);
+    queueMicrotask(() \=> toaster\[status\](toast));
+  };
+  return (
+    <div style\={{ padding: '80px 150px' }}\>
+      <IressStack gutter\="md"\>
+        <IressInline horizontalAlign\="between" gutter\="sm"\>
+          <IressButton onClick\={() \=> changePosition('top-start')}\>
+            top-start          </IressButton\>
+          <IressButton onClick\={() \=> changePosition('top-center')}\>
+            top-center          </IressButton\>
+          <IressButton onClick\={() \=> changePosition('top-end')}\>
+            top-end          </IressButton\>
+        </IressInline\>
+        <IressPanel background\="transparent" padding\="lg"\>
+          <IressText align\="center"\>Toaster positions</IressText\>
+        </IressPanel\>
+        <IressInline horizontalAlign\="between"\>
+          <IressButton onClick\={() \=> changePosition('bottom-start')}\>
+            bottom-start          </IressButton\>
+          <IressButton onClick\={() \=> changePosition('bottom-center')}\>
+            bottom-center          </IressButton\>
+          <IressButton onClick\={() \=> changePosition('bottom-end')}\>
+            bottom-end          </IressButton\>
+        </IressInline\>
+      </IressStack\>
+    </div\>
+  );
+};
+export const ToasterPositionExamples \= () \=> (
+  <IressToasterProvider \>
+    <Toaster />
+  </IressToasterProvider\>
+);
+
+Copy
+
+[](#migrating-to-version-5)Migrating to version 5
+-------------------------------------------------
+
+### [](#adding-the-provider)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.
+
+\[data-radix-scroll-area-viewport\] {
+  scrollbar-width: none;
+  -ms-overflow-style: none;
+  -webkit-overflow-scrolling: touch;
+}
+\[data-radix-scroll-area-viewport\]::-webkit-scrollbar {
+  display: none;
+}
+:where(\[data-radix-scroll-area-viewport\]) {
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+}
+:where(\[data-radix-scroll-area-content\]) {
+  flex-grow: 1;
+}
+
+const App \= () \=> <IressToasterProvider\>Rest of app here</IressToasterProvider\>;
+
+Copy
+
+On this page
+
+*   [Overview](#overview)
+*   [Props](#props)
+*   [Controlling toasts](#controlling-toasts)
+    *   [Using the IressToasterProvider](#using-the-iresstoasterprovider)
+*   [Examples](#examples)
+    *   [Status](#status)
+    *   [Timeout](#timeout)
+    *   [Position](#position)
+*   [Migrating to version 5](#migrating-to-version-5)
+    *   [Adding the provider](#adding-the-provider)