@iress-oss/ids-components 0.0.1-dev.1 → 0.0.1-dev.3

package/dist/patterns/Loading/LoadingSuspense.js

@@ -0,0 +1,53 @@
+import { jsxs as d, Fragment as a, jsx as n } from "react/jsx-runtime";
+import { useMemo as S, useRef as F, useState as g, useEffect as b, Suspense as R } from "react";
+import { Q as i } from "../../Loading-rKDsRTjZ.js";
+import { useSuspenseResource as I, uncacheSuspenseResource as E } from "./hooks/useSuspenseResource.js";
+const k = ({
+  children: s,
+  delay: r,
+  onLoaded: l,
+  pattern: e,
+  startFrom: c,
+  ...t
+}) => {
+  const w = S(() => r || (e === "component" || e === "default" || e === "validate" ? 0 : e === "long" ? 1300 : 500), [r, e]), x = S(() => c || (e === "component" || e === "default" || e === "long" ? 0 : 250), [c, e]), m = F(!1), [u, j] = g(!1), o = i.shouldRender(u, w, x), [f, C] = g(!1);
+  b(() => {
+    u && !o && (C(!0), l == null || l());
+  }, [u, l, o]);
+  const h = () => {
+    m.current || (m.current = !0, j(() => !0));
+  };
+  return e === "component" || e === "validate" ? /* @__PURE__ */ d(a, { children: [
+    /* @__PURE__ */ n(
+      i,
+      {
+        pattern: e,
+        loaded: u,
+        ...t,
+        children: f && s
+      }
+    ),
+    /* @__PURE__ */ n(R, { fallback: null, children: !f && /* @__PURE__ */ n(v, { onResolved: h, children: !u && s }) })
+  ] }) : /* @__PURE__ */ d(a, { children: [
+    o && /* @__PURE__ */ n(
+      i,
+      {
+        pattern: e,
+        loaded: u,
+        ...t
+      }
+    ),
+    /* @__PURE__ */ n(R, { fallback: null, children: f ? s : /* @__PURE__ */ n(v, { onResolved: h, children: !u && s }) })
+  ] });
+};
+k.use = I;
+k.uncache = E;
+const v = ({
+  onResolved: s,
+  children: r
+}) => (b(() => {
+  s();
+}, [s]), r);
+export {
+  k as IressLoadingSuspense
+};

package/dist/patterns/Loading/hooks/useShouldRenderLoading.js

@@ -1,20 +1,24 @@
-import { useState as c, useEffect as o } from "react";
-const m = (e, r = 500, u = 500) => {
-  const [i, n] = c(!1);
-  return o(() => {
-    const t = setTimeout(() => {
-      e || n(!0);
-    }, u);
-    return () => clearTimeout(t);
-  }, [u, e]), o(() => {
+import { useState as i, useRef as m, useEffect as f } from "react";
+const p = (e, o = 500, r = 250, c = 250) => {
+  const [s, t] = i(r === 0), n = m(0);
+  return f(() => {
+    const u = setTimeout(() => {
+      e || (t(!0), n.current = performance.now());
+    }, r);
+    return () => clearTimeout(u);
+  }, [r, e]), f(() => {
     if (e !== !0)
       return;
-    const t = setTimeout(() => {
-      n(!1);
-    }, r);
-    return () => clearTimeout(t);
-  }, [e, r]), e !== !0 || i;
+    if (!n.current || performance.now() - n.current < c) {
+      t(!1);
+      return;
+    }
+    const u = setTimeout(() => {
+      t(!1);
+    }, o);
+    return () => clearTimeout(u);
+  }, [e, o, c]), e !== !0 || s;
 };
 export {
-  m as useShouldRenderLoading
+  p as useShouldRenderLoading
 };

package/dist/patterns/Loading/hooks/useSuspenseResource.js

@@ -0,0 +1,27 @@
+import { useMemo as c } from "react";
+const a = (e) => {
+  let r = "pending", n, o;
+  const u = e.then(
+    (t) => {
+      r = "success", n = t;
+    },
+    (t) => {
+      r = "error", o = t;
+    }
+  );
+  return {
+    read() {
+      if (r === "pending") throw u;
+      if (r === "error") throw o;
+      return n;
+    }
+  };
+}, s = /* @__PURE__ */ new WeakMap(), d = (e) => c(() => (s.has(e) || s.set(e, a(e())), s.get(e)), [e]).read(), i = (e, r = 1e3) => {
+  setTimeout(() => {
+    s.delete(e);
+  }, r);
+};
+export {
+  i as uncacheSuspenseResource,
+  d as useSuspenseResource
+};

package/dist/src/patterns/Loading/Loading.d.ts

@@ -43,5 +43,5 @@ export declare const IressLoading: {
      * @param delay - Once a component has loaded, how long should the loading indicator be displayed for.
      * @returns A boolean value that determines whether the `IressLoading` component is safe to be removed.
      */
-    shouldRender: (isLoaded: boolean, delay?: number, startFrom?: number) => boolean;
+    shouldRender: (isLoaded: boolean, delay?: number, startFrom?: number, avoidDelayTimeout?: number) => boolean;
 };

package/dist/src/patterns/Loading/LoadingSuspense.d.ts

@@ -0,0 +1,73 @@
+import { ReactNode } from 'react';
+import { StartUpLoadingProps } from './components/StartUpLoading';
+import { ValidateLoadingProps } from './components/ValidateLoading';
+import { PageLoadingProps } from './components/PageLoading';
+import { ComponentLoadingProps } from './components/ComponentLoading';
+import { LongLoadingProps } from './components/LongLoading';
+import { DefaultLoadingProps } from './components/DefaultLoading';
+export type IressLoadingSuspenseProps = (Omit<StartUpLoadingProps, 'loaded'> | ValidateLoadingProps | Omit<PageLoadingProps, 'loaded'> | Omit<ComponentLoadingProps, 'loaded'> | Omit<LongLoadingProps, 'loaded'> | DefaultLoadingProps) & {
+    /**
+     * The content that will be rendered inside the Suspense boundary.
+     * Typically includes lazy-loaded components and components that use the `use` or `IressLoadingSuspense.use` hook.
+     */
+    children?: ReactNode;
+    /**
+     * Duration (in milliseconds) to delay unmounting the fallback
+     * to allow the fade-out animation to complete.
+     * By default it uses the default delay of the pattern.
+     */
+    delay?: number;
+    /**
+     * By default it uses the default delay of the pattern.
+     */
+    onLoaded?: () => void;
+    /**
+     * Duration (in milliseconds) before showing the loading pattern.
+     * Default is 500ms, meaning a user will not even see the loading indicator if the page loads before this time.
+     */
+    startFrom?: number;
+};
+/**
+ * A pattern component that has in-built loading states for different contexts, designed to provide a consistent user experience across Iress applications.
+ *
+ * The `pattern` prop is used to determine the type of loading state to display. The following patterns are available:
+ *
+ * - `component`: Loading pattern for a component that is expected to take some time to load, but has content around it that can be loaded before it (hence not part of page pattern). It also supports updating the state of the component via a slightly different UI. Examples:
+ *   - Charts that can be updated in real-time
+ *   - Tables that load many records and may update in real-time
+ * - `long`: Loading pattern for a component that is expected to take longer than 10 seconds to load. It displays a checklist of items that are being loaded. Examples:
+ *   - Calling multiple slow APIs to load data
+ *   - Loading results from AI
+ *   - Processing a large amount of data as a queue (eg. bulk uploading or large media file uploads)
+ * - `page`: Loading pattern for a page, with out-of-the-box skeleton templates. Examples:
+ *   - Dashboard page with multiple filters/panels
+ *   - Search page with multiple filters and search results
+ *   - Detail page for a record
+ *   - Form page
+ *   - Article page
+ * - `start-up`: Loading pattern when the application is first loaded. Examples:
+ *   - Loading an application for the first time
+ *   - Switching from a different application to a new application
+ *   - Switching from a client's website to an Iress application
+ *   - Switching themes
+ * - `validate`: Loading pattern when validating user input. Examples:
+ *   - Submitting a form
+ *   - Saving a record
+ *
+ * If no `pattern` is provided, it will use the default experience, which only displays a message after a certain amount of time to help stop drop-offs due to uncommon loading times.
+ */
+export declare const IressLoadingSuspense: {
+    ({ children, delay: delayProp, onLoaded, pattern, startFrom: startFromProp, ...restProps }: IressLoadingSuspenseProps): import("react/jsx-runtime").JSX.Element;
+    /**
+     * A polyfill for the `use` hook in React 19. It allows you to suspend a component until the resource (Promise) is resolved.
+     * **Note:** For those using React 19, import the `use` hook from React instead of using this polyfill.
+     * @see https://react.dev/reference/react/use
+     */
+    use: <T>(fetcher: () => Promise<T>) => T;
+    /**
+     * Uncache the resource (Promise) that is being used in the `use` hook.
+     * **Note:** For those using React 19, import the `use` hook from React instead of using this method.
+     * @see https://react.dev/reference/react/use
+     */
+    uncache: (fetcher: () => Promise<unknown>, timeout?: number) => void;
+};

package/dist/src/patterns/Loading/hooks/useShouldRenderLoading.d.ts

@@ -4,6 +4,7 @@
  * @param isLoaded - A boolean value that determines if the component waiting to be loaded has finished loading.
  * @param delay - Once a component has loaded, how long should the loading indicator be displayed for. This is useful to allow the loading indicator to animate out.
  * @param startFrom - If a component is still loading after this time in milliseconds, you should show the loading message. Default is 500ms, meaning a user will not even see the loading indicator if the page loads before this time.
+ * @param avoidDelayTimeout - If the component has a start up animation, this is the time in milliseconds that we will avoid the delay timeout for. This is useful to speed up the loading indicator removal if the component loaded before the first half of an animation finishes.
  * @returns A boolean value that determines whether the `IressLoading` component should be rendered.
  */
-export declare const useShouldRenderLoading: (isLoaded: boolean, delay?: number, startFrom?: number) => boolean;
+export declare const useShouldRenderLoading: (isLoaded: boolean, delay?: number, startFrom?: number, avoidDelayTimeout?: number) => boolean;

package/dist/src/patterns/Loading/hooks/useSuspenseResource.d.ts

@@ -0,0 +1,17 @@
+/**
+ * This is a polyfill for the `use` hook in React 19, allowing you to suspend a component until the resource (Promise) is resolved.
+ * **Note:** For those using React 19, import the `use` hook from React instead of using this polyfill.
+ * @param promise The promise to suspend on. Once it resolves, the component will re-render with the resolved value.
+ * @returns {T | Error | Promise<void>} If the promise has not resolved, it will throw the promise, causing the component to suspend. If it has resolved successfully, it will return the result. If it has errored, it will throw the error.
+ * @see https://react.dev/reference/react/use
+ */
+export declare const useSuspenseResource: <T>(fetcher: () => Promise<T>) => T;
+/**
+ * Our polyfill is not as smart as React's `use` hook, so we need to manually uncache the resource after a certain timeout.
+ * You usually need this if you are calling parameters with your `useSuspenseResource` hook (eg. `useSuspenseResource(() => fetch('/api/data'))`).
+ * **Note:** For those using React 19, import the `use` hook from React instead of using this polyfill.
+ * @param fetcher The function that returns a promise to suspend on (usually an API call).
+ * @param timeout The time in milliseconds after which the resource will be uncached. Default is 1000ms, usually enough to avoid flickering.
+ * @see https://react.dev/reference/react/use
+ */
+export declare const uncacheSuspenseResource: (fetcher: () => Promise<unknown>, timeout?: number) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iress-oss/ids-components",
-  "version": "0.0.1-dev.1",
+  "version": "0.0.1-dev.3",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },