@iress-oss/ids-mcp-server 0.0.1 → 5.14.2

package/{docs/ids → generated/docs}/introduction-docs.md

@@ -1,11 +1,11 @@
-[](#iress-design-system-ids)Iress Design System (IDS)
-=====================================================
+[](#iress-design-system)Iress Design System
+===========================================
 
-5.13.0
+5.14.2
 
 * * *
 
-IDS consists of a shared visual language, working code, design tools and resources, human interface guidelines, and a community of contributors. It serves a wide range of designers and developers building digital products and experiences.
+The Iress Design System (IDS) serves as a shared visual language, working code, design tools and resources, human interface guidelines, and a community of contributors. It supports designers and developers building digital products for both B2B (Financial Advisors, Paraplanners) and B2B2C (client customers) segments.
 
 [](#whats-new)What's new?
 -------------------------

package/{docs/ids → generated/docs}/patterns-loading-docs.md

@@ -206,7 +206,7 @@ Apart from using the `IressLoading` component, there are a few things you need t
 
 The `IressLoading` component is designed to create a seamless experience for users when loading content. They have been designed to meet best practices and improve user perception of loading times.
 
-![Wait times less than 1 second, no loading indicator. Short wait times (1-3 seconds), use a loading indicator. Long wait times (3-10 seconds), use a loading indicator and provide feedback. Wait times longer than 10 seconds should be a background process.](/@fs/Users/ming.fang/code/design-system/packages/components/src/patterns/Loading/assets/ux-collective-loading-time-matrix.webp)
+![Wait times less than 1 second, no loading indicator. Short wait times (1-3 seconds), use a loading indicator. Long wait times (3-10 seconds), use a loading indicator and provide feedback. Wait times longer than 10 seconds should be a background process.](/@fs/Users/mellisa.hankins/projects/design-system/packages/components/src/patterns/Loading/assets/ux-collective-loading-time-matrix.webp)
 
 Image © [UX Collective](https://uxdesign.cc/loading-progress-indicators-ui-components-series-f4b1fc35339a)
 
@@ -254,7 +254,7 @@ New component
 
 This component is new, please provide feedback to the IDS team if you encounter any issues.
 
-![](/@fs/Users/ming.fang/code/design-system/packages/components/src/patterns/Loading/mocks/retirement-graph.png)
+![](/@fs/Users/mellisa.hankins/projects/design-system/packages/components/src/patterns/Loading/mocks/retirement-graph.png)
 
 Update
 
@@ -607,6 +607,289 @@ Hide codeRefresh
 
 Copy
 
+[](#suspense)Suspense
+---------------------
+
+Since React 18, React has introduced a new way to handle loading states using `Suspense`, allowing you to lazy load components in an efficient manner.
+
+The `IressLoadingSuspense` component is a wrapper around the `IressLoading` component that uses `Suspense` to handle loading states. It is used in the same way as the `IressLoading` component, however you do not need to pass the `loaded` prop or use the `IressLoading.shouldRender` hook. The `IressLoadingSuspense` component will automatically handle the loading state for you.
+
+The wizard example can be translated to use `IressLoadingSuspense` as follows (it includes the slow and fast examples).
+
+**Differences in behaviour**
+
+*   The `IressLoadingSuspense` component will automatically handle the loading state for you, so you do not need to pass the `loaded` prop or use the `IressLoading.shouldRender` hook.
+*   Nested suspense components will be handled by the highest `IressLoadingSuspense` component. This means that if you have multiple nested `IressLoadingSuspense` components, only the top most one will display a loading state. You can see this in the example when you click the Next button, you no longer see the component loading pattern due to it being nested under the page loading pattern.
+
+Hide codeRefresh
+
+\[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; }
+
+interface PageProps {
+  setPage: (page: number) \=> void;
+}
+interface ChartProps {
+  money: number | null;
+}
+const API \= {
+  getHomePage: async () \=> {
+    await new Promise((resolve) \=> {
+      setTimeout(resolve, 3000);
+    });
+    return 1;
+  },
+  getRetirementIncomeProjection: async () \=> {
+    await new Promise((resolve) \=> {
+      setTimeout(resolve, 2000);
+    });
+    return true;
+  },
+  getChart: async () \=> {
+    await new Promise((resolve) \=> {
+      const chartImage \= new Image();
+      chartImage.src \= retirementGraph;
+      setTimeout(resolve, 1000);
+    });
+    return true;
+  },
+  chartUpdate: async () \=>
+    new Promise<boolean\>((resolve) \=> {
+      // Simulate a slow network request.
+      setTimeout(() \=> {
+        resolve(true);
+      }, 2000);
+    }),
+};
+const Graph \= () \=> (
+  <img
+    src\={retirementGraph}
+    alt\=""
+    style\={{ maxWidth: '100%', height: 'auto' }}
+  />
+);
+const Chart \= () \=> {
+  const initialChart \= IressLoadingSuspense.use(API.getChart);
+  const \[updatedChart, setUpdatedChart\] \= useState<boolean | undefined\>();
+  const \[money, setMoney\] \= useState<number | null\>(null);
+  const \[updating, setUpdating\] \= useState(false);
+  const deferredMoney \= useDeferredValue(money);
+  const chart \= updatedChart ?? initialChart;
+  useEffect(() \=> {
+    if (deferredMoney \=== null) {
+      return;
+    }
+    setUpdating(() \=> true);
+    const update \= async () \=> {
+      const newChart \= await API.chartUpdate();
+      setUpdatedChart(newChart);
+      setUpdating(() \=> false);
+    };
+    void update();
+  }, \[deferredMoney\]);
+  return (
+    <IressLoadingSuspense pattern\="component" update\={updating}\>
+      {chart && <Graph />}
+      <IressPanel\>
+        <IressForm<ChartProps>          onSubmit={(projectionData) \=> setMoney(projectionData.money)}
+        >          <IressStack gutter\="md"\>
+            <h3\>Update projection</h3\>
+            <IressFormField
+              name\="money"
+              label\="My money"
+              render\={(controlledProps) \=> (
+                <IressInputCurrency {...controlledProps} />
+              )}
+            />
+            <IressButton type\="submit"\>Update projection</IressButton\>
+          </IressStack\>
+        </IressForm\>
+      </IressPanel\>
+    </IressLoadingSuspense\>
+  );
+};
+const StartPage \= ({ setPage }: PageProps) \=> (
+  <IressText\>
+    <h2\>Maximise your retirement</h2\>
+    <p\>
+      Maximize your retirement in Australia by contributing to your super early      and making voluntary top-ups to benefit from compounding. Take advantage      of employer contributions, government co-contributions, and tax benefits.      Diversify your investments and review your strategy regularly to stay on      track. Consider additional income streams and seek professional advice for      a secure future.    </p\>
+    <hr />
+    <IressButton onClick\={() \=> setPage(2)}\>Next</IressButton\>
+  </IressText\>
+);
+const RetirementIncomeProjectionPage \= () \=> {
+  const promise \= API.getRetirementIncomeProjection;
+  IressLoadingSuspense.use(promise);
+  IressLoadingSuspense.uncache(promise);
+  return (
+    <IressText\>
+      <h2\>Retirement Income Projection</h2\>
+      <p\>
+        We've got enough information to provide you with a retirement income        projection. This will help you understand how much you can expect to        receive in retirement based on your current super balance, your        contributions, and your investment strategy.      </p\>
+      <Chart />
+    </IressText\>
+  );
+};
+const HomePage \= () \=> {
+  const promise \= API.getHomePage;
+  const startPage \= IressLoadingSuspense.use(promise);
+  IressLoadingSuspense.uncache(promise);
+  const \[movedPage, setMovedPage\] \= useState<number | undefined\>();
+  const page \= movedPage ?? startPage;
+  return (
+    <IressContainer style\={{ maxWidth: '600px', paddingBlock: '3rem' }}\>
+      {page \=== 1 && (
+        <IressLoadingSuspense pattern\="page" template\="form"\>
+          {page \=== 1 && <StartPage setPage\={setMovedPage} />}
+        </IressLoadingSuspense\>
+      )}
+      {page \=== 2 && (
+        <IressLoadingSuspense pattern\="page" template\="form"\>
+          <RetirementIncomeProjectionPage />
+        </IressLoadingSuspense\>
+      )}
+    </IressContainer\>
+  );
+};
+export const LoadingSuspenseWizard \= () \=> (
+  <IressLoadingSuspense pattern\="start-up"\>
+    <HomePage />
+  </IressLoadingSuspense\>
+);
+
+Copy
+
+Hide codeRefresh
+
+\[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; }
+
+interface PageProps {
+  setPage: (page: number) \=> void;
+}
+interface ChartProps {
+  money: number | null;
+}
+const API \= {
+  getHomePage: async () \=> {
+    await new Promise((resolve) \=> {
+      setTimeout(resolve, 500);
+    });
+    return 1;
+  },
+  getRetirementIncomeProjection: async () \=> {
+    await new Promise((resolve) \=> {
+      setTimeout(resolve, 200);
+    });
+    return true;
+  },
+  getChart: async () \=> {
+    await new Promise((resolve) \=> {
+      const chartImage \= new Image();
+      chartImage.onload \= resolve;
+      chartImage.src \= retirementGraph;
+    });
+    return true;
+  },
+  chartUpdate: async () \=>
+    new Promise<boolean\>((resolve) \=> {
+      setTimeout(() \=> {
+        resolve(true);
+      }, 200);
+    }),
+};
+const Graph \= () \=> (
+  <img
+    src\={retirementGraph}
+    alt\=""
+    style\={{ maxWidth: '100%', height: 'auto' }}
+  />
+);
+const Chart \= () \=> {
+  const initialChart \= IressLoadingSuspense.use(API.getChart);
+  const \[updatedChart, setUpdatedChart\] \= useState<boolean | undefined\>();
+  const \[money, setMoney\] \= useState<number | null\>(null);
+  const \[updating, setUpdating\] \= useState(false);
+  const deferredMoney \= useDeferredValue(money);
+  const chart \= updatedChart ?? initialChart;
+  useEffect(() \=> {
+    if (deferredMoney \=== null) {
+      return;
+    }
+    setUpdating(() \=> true);
+    const update \= async () \=> {
+      const newChart \= await API.chartUpdate();
+      setUpdatedChart(newChart);
+      setUpdating(() \=> false);
+    };
+    void update();
+  }, \[deferredMoney\]);
+  return (
+    <IressLoadingSuspense pattern\="component" update\={updating}\>
+      {chart && <Graph />}
+      <IressPanel\>
+        <IressForm<ChartProps>          onSubmit={(projectionData) \=> setMoney(projectionData.money)}
+        >          <IressStack gutter\="md"\>
+            <h3\>Update projection</h3\>
+            <IressFormField
+              name\="money"
+              label\="My money"
+              render\={(controlledProps) \=> (
+                <IressInputCurrency {...controlledProps} />
+              )}
+            />
+            <IressButton type\="submit"\>Update projection</IressButton\>
+          </IressStack\>
+        </IressForm\>
+      </IressPanel\>
+    </IressLoadingSuspense\>
+  );
+};
+const StartPage \= ({ setPage }: PageProps) \=> (
+  <IressText\>
+    <h2\>Maximise your retirement</h2\>
+    <p\>
+      Maximize your retirement in Australia by contributing to your super early      and making voluntary top-ups to benefit from compounding. Take advantage      of employer contributions, government co-contributions, and tax benefits.      Diversify your investments and review your strategy regularly to stay on      track. Consider additional income streams and seek professional advice for      a secure future.    </p\>
+    <hr />
+    <IressButton onClick\={() \=> setPage(2)}\>Next</IressButton\>
+  </IressText\>
+);
+const RetirementIncomeProjectionPage \= () \=> {
+  IressLoadingSuspense.use(API.getRetirementIncomeProjection);
+  return (
+    <IressText\>
+      <h2\>Retirement Income Projection</h2\>
+      <p\>
+        We've got enough information to provide you with a retirement income        projection. This will help you understand how much you can expect to        receive in retirement based on your current super balance, your        contributions, and your investment strategy.      </p\>
+      <Chart />
+    </IressText\>
+  );
+};
+const HomePage \= () \=> {
+  const startPage \= IressLoadingSuspense.use(API.getHomePage);
+  const \[movedPage, setMovedPage\] \= useState<number | undefined\>();
+  const page \= movedPage ?? startPage;
+  return (
+    <IressContainer style\={{ maxWidth: '600px', paddingBlock: '3rem' }}\>
+      {page \=== 1 && (
+        <IressLoadingSuspense pattern\="page" template\="form"\>
+          {page \=== 1 && <StartPage setPage\={setMovedPage} />}
+        </IressLoadingSuspense\>
+      )}
+      {page \=== 2 && (
+        <IressLoadingSuspense pattern\="page" template\="form"\>
+          <RetirementIncomeProjectionPage />
+        </IressLoadingSuspense\>
+      )}
+    </IressContainer\>
+  );
+};
+export const LoadingSuspenseWizardFast \= () \=> (
+  <IressLoadingSuspense pattern\="start-up"\>
+    <HomePage />
+  </IressLoadingSuspense\>
+);
+
+Copy
+
 [](#hooks)Hooks
 ---------------
 
@@ -641,6 +924,51 @@ else return <IressText\>Content is loaded</IressText\>;
 
 Copy
 
+### [](#iressloadingsuspenseuse)`IressLoadingSuspense.use`
+
+The `IressLoadingSuspense.use` hook is a polyfill for the React 19 `use` hook, allowing you to have similar functionality in React 18. It is used to handle loading states when using `IressLoadingSuspense`.
+
+It is not as smart as the `use` hook in React 19, it will cache the result of the promise and will not re-fetch the data if the component is re-mounted. You can clear a function's results in the cache by using the `IressLoadingSuspense.uncache` function.
+
+Avoid in React 19
+-----------------
+
+If you are using React 19, it is recommended to use the built-in `use` hook instead of this one. In future releases, this hook will be deprecated and removed from the library.
+
+\[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 HomePage \= () \=> {
+  const pageData \= IressLoadingSuspense.use(API.fetchPage('home'));
+  return (
+    <IressText\>
+      <h2\>{pageData.title}</h2\>
+      <p\>{pageData.description}</p\>
+    </IressText\>
+  );
+};
+export const App \= () \=> (
+  <IressLoadingSuspense pattern\="start-up"\>
+    <HomePage />
+  </IressLoadingSuspense\>
+);
+
+Copy
+
 [](#examples)Examples
 ---------------------
 
@@ -968,7 +1296,9 @@ On this page
     *   [page](#page)
     *   [start-up](#start-up)
     *   [validate](#validate)
+*   [Suspense](#suspense)
 *   [Hooks](#hooks)
     *   [IressLoading.shouldRender](#iressloadingshouldrender)
+    *   [IressLoadingSuspense.use](#iressloadingsuspenseuse)
 *   [Examples](#examples)
     *   [Wizard](#wizard)