@iress-oss/ids-components 5.13.1 → 5.14.0

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

@@ -0,0 +1,60 @@
+import { IressProgressProps } from '../../../components/Progress/Progress.types';
+import { ReactNode } from 'react';
+import { IressHTMLAttributes } from '../../../interfaces';
+export interface LongLoadingProps extends IressHTMLAttributes {
+    /**
+     * The children are displayed while loading. This will be displayed above the progress bar and checklist.
+     */
+    children?: ReactNode;
+    /**
+     * An error to display if the loading fails. This will override the `messageList` and show an error message instead.
+     */
+    error?: ReactNode;
+    /**
+     * Estimated time in milliseconds for the loading to finish.
+     * @default 10000
+     */
+    estimatedFinishTime?: number;
+    /**
+     * If set to `true`, will start hiding the loading indicator. It is recommended to use this prop if you are using the `IressLoading.shouldRender` hook to achieve a smooth loading experience.
+     */
+    loaded?: boolean;
+    /**
+     * A checklist to display while loading. The key is the time when you want the item to be checked.
+     */
+    messageList: Record<number, ReactNode>;
+    /**
+     * The long loading pattern will display a checklist of items that are being loaded.
+     *
+     * Use `pattern="long"` for the following use cases:
+     * - 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)
+     */
+    pattern?: 'long';
+    /**
+     * If provided, will use this to set the `value` of the progress bar. If not provided, will use the `estimatedFinishTime` to calculate the progress.
+     */
+    progress?: IressProgressProps['value'];
+    /**
+     * This is a render prop that allows you to override the default progress rendering.
+     * This is useful if you want to use a different progress component or if you want to add additional props to the progress bar.
+     */
+    renderProgress?: (props: Pick<IressProgressProps, 'className' | 'min' | 'max' | 'sectionTitle' | 'value'>) => ReactNode;
+    /**
+     * Set the timeouts for showing the progress bar and message.
+     */
+    timeout?: {
+        /**
+         * The time in milliseconds before this component begins to fade out (if `loaded` is set to `true`).
+         * @default 1300
+         */
+        loaded?: number;
+        /**
+         * The time in milliseconds before the checklist is displayed.
+         * @default 500
+         */
+        message?: number;
+    };
+}
+export declare const LongLoading: ({ children, className, error, estimatedFinishTime, loaded, messageList, progress, renderProgress, timeout, ...restProps }: LongLoadingProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -8,7 +8,7 @@ export interface StartUpLoadingProps extends IressHTMLAttributes {
      */
     children?: ReactNode;
     /**
-     * Estimated time in milliseconds for the loading to finish. If set to `0` or something larger than `60000` (1 minute), will show a spinner.
+     * Estimated time in milliseconds for the loading to finish.
      * @default 3000
      */
     estimatedFinishTime?: number;

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

@@ -0,0 +1,11 @@
+import { IressProgressProps } from '../../../components/Progress/Progress.types';
+/**
+ * This hook is used to calculate the estimated progress of a loading component, allowing you to show an animated progress bar even when real progress is not available.
+ *
+ * @param estimatedFinishTime - The estimated time in milliseconds for the loading to finish.
+ * @param isLoaded - A boolean value that determines if the component waiting to be loaded has finished loading.
+ * @param progress - If provided, will use this as the progress value. If not provided, will use the `estimatedFinishTime` to calculate the progress.
+ * @param latestMessageTimecode - The latest timecode of the message list. It helps us determine if still in progress, particularly when its higher than the estimated finish time.
+ * @returns A number value that represents the current progress of the loading component.
+ */
+export declare const useEstimatedProgressValue: (estimatedFinishTime: number, isLoaded?: boolean, progress?: IressProgressProps["value"], latestMessageTimecode?: number) => number;

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/useShowIndicator.d.ts

@@ -0,0 +1,9 @@
+/**
+ * This hook is used to delay the indicator being shown and removed during the loading process.
+ *
+ * @param isLoaded - A boolean value that determines if the component waiting to be loaded has finished loading.
+ * @param showDelay - Once a component has started loading, how long long we should wait before showing the loading indicator. This is useful to avoid flickering if the component loads quickly.
+ * @param hideDelay - Once a component has loaded, how long we should wait before removing the loading indicator. This is useful to allow the loading indicator to animate out.
+ * @returns A boolean value that determines whether the loading indicator should be shown.
+ */
+export declare const useShowIndicator: (isLoaded?: boolean, showDelay?: number, hideDelay?: 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/dist/src/patterns/Loading/index.d.ts

@@ -1 +1,2 @@
 export * from './Loading';
+export * from './LoadingSuspense';