@iress-oss/ids-components 5.20.2 → 5.20.3

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

@@ -0,0 +1,41 @@
+import { ReactNode } from 'react';
+import { IressHTMLAttributes } from '../../../interfaces';
+declare const templates: {
+    page: () => import("react/jsx-runtime").JSX.Element;
+    form: () => import("react/jsx-runtime").JSX.Element;
+    dashboard: () => import("react/jsx-runtime").JSX.Element;
+};
+export interface PageLoadingProps extends Omit<IressHTMLAttributes, 'children'> {
+    /**
+     * If provided, will switch the skeleton to this template. Use when you have critical content that can be displayed while loading to allow the user to see some content while the rest is loading.
+     */
+    critical?: ReactNode;
+    /**
+     * 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;
+    /**
+     * Use `pattern="page"` for the following use cases:
+     * - Detail page for a record
+     * - Form page
+     * - Article page
+     */
+    pattern?: 'page';
+    /**
+     * Only screen readers will see this message.
+     * @default 'Loading...'
+     */
+    screenReaderText?: ReactNode;
+    /**
+     * Which template to use as the skeleton, or you can use a ReactNode to customise the skeleton completely.
+     * @default 'page'
+     */
+    template?: keyof typeof templates | Exclude<ReactNode, string | number | boolean | null>;
+    /**
+     * Delay in milliseconds before the skeleton is displayed.
+     * @default 500
+     */
+    timeout?: number;
+}
+export declare const PageLoading: ({ className, critical, loaded, screenReaderText, template, timeout, ...restProps }: PageLoadingProps) => import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -0,0 +1,67 @@
+import { IressProgressProps } from '../../../components/Progress/Progress.types';
+import { ReactNode } from 'react';
+import { IressHTMLAttributes } from '../../../interfaces';
+export interface StartUpLoadingProps extends IressHTMLAttributes {
+    /**
+     * Message to display when the loading time is longer than expected.
+     * @default 'One moment please...'
+     */
+    children?: ReactNode;
+    /**
+     * Estimated time in milliseconds for the loading to finish.
+     * @default 3000
+     */
+    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 message list to display while loading. The key is the time when you want the message to change to this message.
+     * If using a message list, the `children` will not be displayed.
+     */
+    messageList?: Record<number, ReactNode>;
+    /**
+     * Use `pattern="start-up"` for the following use cases:
+     * - 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
+     */
+    pattern?: 'start-up';
+    /**
+     * 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;
+    /**
+     * Only screen readers will see this message, it is changed to the `children` message after the delay.
+     * @default 'Loading...'
+     */
+    screenReaderText?: 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 200
+         */
+        loaded?: number;
+        /**
+         * The time in milliseconds before the message message is displayed.
+         * @default 2500
+         */
+        message?: number;
+        /**
+         * The time in milliseconds before the progress bar is displayed.
+         * @default 500
+         */
+        progress?: number;
+    };
+}
+export declare const StartUpLoading: ({ className, children, "data-testid": dataTestId, estimatedFinishTime, loaded, messageList, progress, renderProgress, screenReaderText, timeout, ...restProps }: StartUpLoadingProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,38 @@
+import { IressButtonProps } from '../../../components/Button';
+import { ReactNode } from 'react';
+import { IressHTMLAttributes } from '../../../interfaces';
+export interface ValidateLoadingProps extends IressHTMLAttributes {
+    /**
+     * When true, button is in loading state. If provided a string, will be used as the loading text for screen readers.
+     */
+    loading?: IressButtonProps['loading'];
+    /**
+     * Set the message to be displayed when the button is in the loading state.
+     * @default 'This is taking longer than expected...'
+     */
+    message?: ReactNode;
+    /**
+     * Use `pattern="validate"` for the following use cases:
+     * - Submitting a form
+     * - Saving a record
+     */
+    pattern?: 'validate';
+    /**
+     * This sets where the loading message will be displayed.
+     * - `bottom` - The loading message will be displayed below the button. It will be absolute positioned.
+     * - `top` - The loading message will be displayed above the button. It will be absolute positioned.
+     * - `right` - The loading message will be displayed to the right of the button. It will be inline positioned.
+     */
+    position?: 'bottom' | 'top' | 'right';
+    /**
+     * This is a render prop that allows you to override the default button rendering.
+     * This is useful if you want to use a different button component or if you want to add additional props to the button.
+     */
+    renderButton?: (props: Pick<IressButtonProps, 'className' | 'loading'>) => ReactNode;
+    /**
+     * The time in milliseconds before the loading message is displayed.
+     * @default 2500
+     */
+    timeout?: number;
+}
+export declare const ValidateLoading: ({ children, className, loading, message, pattern, position, renderButton, timeout, ...restProps }: ValidateLoadingProps) => string | number | boolean | Iterable<ReactNode> | import("react/jsx-runtime").JSX.Element | null | undefined;

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

@@ -0,0 +1,10 @@
+/**
+ * This hook is used to smooth the loading experience by delaying the loading indicator being removed after the loading of an element finishes, as well as avoiding the indicator completely if the loading is too quick.
+ *
+ * @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, 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

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

package/dist/src/types.d.ts

@@ -0,0 +1,21 @@
+import { BREAKPOINTS, DISPLAY_MODES, FLOATING_UI_ALIGNS, FORM_ELEMENT_WIDTHS, GUTTER_SIZES, HEADING_LEVELS, HORIZONTAL_ALIGNS, LOGGER_LEVELS, PADDING_SIZES, SYSTEM_VALIDATION_STATUSES, TEXT_ALIGNS, TEXT_MODES, TEXT_VARIANTS, VERTICAL_ALIGNS } from './constants';
+import { VariablePaddingSize } from './interfaces';
+import { PaddingSize } from './enums';
+export type Breakpoints = (typeof BREAKPOINTS)[number];
+export type DisplayModes = (typeof DISPLAY_MODES)[number];
+export type FloatingUIContainer = HTMLElement | null | React.MutableRefObject<HTMLElement | null>;
+export type FloatingUIAligns = (typeof FLOATING_UI_ALIGNS)[number];
+export type FormControlValue = string | number | boolean | null;
+export type FormElementWidths = (typeof FORM_ELEMENT_WIDTHS)[number];
+export type GutterSizes = (typeof GUTTER_SIZES)[number];
+export type HeadingLevels = (typeof HEADING_LEVELS)[number];
+export type HorizontalAligns = (typeof HORIZONTAL_ALIGNS)[number];
+export type LoggerLevelsUnion = (typeof LOGGER_LEVELS)[number];
+export type MixedPaddingSize = VariablePaddingSize | PaddingSize | PaddingSizes;
+export type PaddingSizes = (typeof PADDING_SIZES)[number];
+export type ResponsiveProps<T> = Partial<Record<Breakpoints, T>>;
+export type SystemValidationStatuses = (typeof SYSTEM_VALIDATION_STATUSES)[number];
+export type TextAligns = (typeof TEXT_ALIGNS)[number];
+export type TextModes = (typeof TEXT_MODES)[number] | 'body';
+export type TextVariants = (typeof TEXT_VARIANTS)[number];
+export type VerticalAligns = (typeof VERTICAL_ALIGNS)[number];