@iress-oss/ids-components 0.0.1-dev.9 → 5.13.1

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

@@ -0,0 +1,53 @@
+import { ReactNode } from 'react';
+import { IressHTMLAttributes } from '../../../interfaces';
+declare const templates: {
+    chart: import("react/jsx-runtime").JSX.Element;
+};
+export interface ComponentLoadingProps extends IressHTMLAttributes {
+    /**
+     * The chart that is being loaded for the first time or being refreshed/updated.
+     */
+    children: ReactNode;
+    /**
+     * If set to `true`, will hide the skeleton and display the chart.
+     */
+    loaded?: boolean;
+    /**
+     * Use `pattern="component"` for the following use cases:
+     * - Component that is expected to be slow to load, such as a chart, table or large graphic.
+     * - Component that can be refreshed/updated with new data.
+     */
+    pattern?: 'component';
+    /**
+     * Only screen readers will see this message, it is changed to the `message` after the delay.
+     * @default 'Loading...'
+     */
+    screenReaderText?: ReactNode;
+    /**
+     * Which template to use as the skeleton, or you can use a ReactNode to customise the skeleton completely.
+     * @default 'chart'
+     */
+    template?: keyof typeof templates | Exclude<ReactNode, string | number | boolean | null>;
+    /**
+     * Set the timeouts for showing the skeleton and update messages.
+     */
+    timeout?: {
+        /**
+         * The time in milliseconds before the skeleton is displayed.
+         * @default 0
+         */
+        skeleton?: number;
+        /**
+         * The time in milliseconds before the update message is displayed.
+         * @default 1000
+         */
+        update?: number;
+    };
+    /**
+     * Set the chart to be updated. If a `ReactNode` is provided, it will be displayed as the message.
+     * If set to `true`, will display the default message `Updating...`.
+     */
+    update?: ReactNode;
+}
+export declare const ComponentLoading: ({ children, className, loaded, screenReaderText, template, timeout, update, ...restProps }: ComponentLoadingProps) => import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -0,0 +1,27 @@
+import { ReactNode } from 'react';
+import { IressHTMLAttributes } from '../../../interfaces';
+export interface DefaultLoadingProps extends IressHTMLAttributes {
+    /**
+     * Message to display when the loading time is longer than expected.
+     * @default 'This is taking longer than expected...'
+     */
+    children?: ReactNode;
+    /**
+     * Only screen readers will see this message, it is changed to the `children` message after the delay.
+     * @default 'Loading...'
+     */
+    screenReaderText?: ReactNode;
+    /**
+     * Do not set the `pattern` prop when no other pattern can be applied. It will only show the loading message after a delay, and is intended for use when loading is not expected to take a long time.
+     * Example use cases:
+     * - Navigating between different routes
+     * - Calling an API within the page that does not require a loading state
+     */
+    pattern?: 'default';
+    /**
+     * Delay in milliseconds before the message is displayed.
+     * @default 3000
+     */
+    timeout?: number;
+}
+export declare const DefaultLoading: ({ children, className, screenReaderText, timeout, ...restProps }: DefaultLoadingProps) => import("react/jsx-runtime").JSX.Element;

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. If set to `0` or something larger than `60000` (1 minute), will show a spinner.
+     * @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/useShouldRenderLoading.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ * @returns A boolean value that determines whether the `IressLoading` component should be rendered.
+ */
+export declare const useShouldRenderLoading: (isLoaded: boolean, delay?: number, startFrom?: number) => boolean;

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

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

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];