@iress-oss/ids-components 6.0.0-alpha.3 → 6.0.0-alpha.30

package/dist/patterns/Form/components/LongForm.d.ts

@@ -0,0 +1,55 @@
+import { FieldValues, UseFormProps } from 'react-hook-form';
+import { ReactElement, ReactNode, Ref } from 'react';
+import { FormPatternProps, FormRef, IressHookFormProps } from '../HookForm/HookForm';
+import { IressPanelProps } from '../../../components/Panel';
+export interface LongFormProps<T extends FieldValues, TContext = object> extends Omit<IressHookFormProps<T, TContext>, 'form'>, FormPatternProps<T, TContext> {
+    /**
+     * The actions to be displayed at the top right of the form.
+     */
+    actions: ReactNode;
+    /**
+     * Footer to be displayed at the bottom of the form.
+     * This can be used for additional information, links, or actions that are relevant to the form but not part of the main content.
+     */
+    footer?: ReactNode;
+    /**
+     * Title displayed at the top of the form, usually the purpose of the form.
+     */
+    heading: ReactNode;
+    /**
+     * Configure the validation strategy **before** a user submits the form the first time.
+     * For long forms, it is recommended to use `onBlur` to avoid overwhelming the user with validation errors.
+     * This means that validation will occur when the user leaves a field, rather than on every change.
+     * @see https://react-hook-form.com/docs/useform#mode
+     * @default 'onBlur'
+     */
+    mode?: UseFormProps<T, TContext>['mode'];
+    /**
+     * Style the panel that wraps the form fields.
+     * @default { bg: "alt" }
+     */
+    panelStyle?: IressPanelProps;
+    /**
+     * Use `pattern="long"` for the following use cases:
+     * - Forms that are used for data entry, such as creating or updating large datasets.
+     * - Forms that are longer than the viewport (usually more than 8-9 fields).
+     */
+    pattern?: 'long';
+    /**
+     * Configure the validation strategy **after** a user submits the form the first time.
+     * During this phase, it is recommended to use `onChange` to provide immediate feedback on field changes so users can correct errors as they go.
+     * @see https://react-hook-form.com/docs/useform#reValidateMode
+     * @default 'onChange'
+     */
+    reValidateMode?: UseFormProps<T, TContext>['reValidateMode'];
+    /**
+     * If set to `true`, the form will have a sticky header that remains at the top of the viewport when scrolling.
+     * This is useful for long forms where you want the header to always be visible.
+     */
+    sticky?: boolean;
+}
+export declare const LongForm: (<T extends FieldValues, TContext = object>(props: LongFormProps<T, TContext> & {
+    ref?: Ref<FormRef<T>>;
+}) => ReactElement) & {
+    displayName: "LongForm";
+};

package/dist/patterns/Form/components/LongForm.js

@@ -1,12 +1,11 @@
 import { jsx as e, jsxs as s } from "react/jsx-runtime";
-import { a as L } from "../../../index.esm-B6vzbp0e.js";
-import { forwardRef as y, useMemo as z } from "react";
+import { useForm as A } from "react-hook-form";
+import { forwardRef as H, useMemo as z } from "react";
 import { IressText as B } from "../../../components/Text/Text.js";
 import { form as C } from "../Form.styles.js";
 import { c as i } from "../../../cx-DN21T1EH.js";
 import { IressHookForm as E } from "../HookForm/HookForm.js";
 import { IressPanel as M } from "../../../components/Panel/Panel.js";
-import "../../../components/Panel/Panel.styles.js";
 import "../../../components/Inline/Inline.styles.js";
 import { IressInline as R } from "../../../components/Inline/Inline.js";
 const T = ({
@@ -29,10 +28,10 @@ const T = ({
   shouldUseNativeValidation: I,
   shouldUnregister: b,
   sticky: v = !1,
-  values: j,
-  ...k
-}, w) => {
-  const A = L({
+  values: L,
+  ...j
+}, k) => {
+  const w = A({
     criteriaMode: f,
     context: d,
     defaultValues: h,
@@ -45,15 +44,15 @@ const T = ({
     shouldFocusError: !m,
     shouldUseNativeValidation: I,
     shouldUnregister: b,
-    values: j
-  }), r = C({ pattern: "long", sticky: v }), H = z(() => typeof o == "string" ? /* @__PURE__ */ e(B, { element: "h2", children: o }) : o, [o]);
+    values: L
+  }), r = C({ pattern: "long", sticky: v }), y = z(() => typeof o == "string" ? /* @__PURE__ */ e(B, { element: "h2", children: o }) : o, [o]);
   return /* @__PURE__ */ s(
     E,
     {
-      form: A,
-      ...k,
+      form: w,
+      ...j,
       className: i(r.root, l),
-      ref: w,
+      ref: k,
       children: [
         /* @__PURE__ */ s(
           R,
@@ -63,7 +62,7 @@ const T = ({
             verticalAlign: "bottom",
             className: r.header,
             children: [
-              H,
+              y,
               /* @__PURE__ */ e("div", { className: r.actions, children: a })
             ]
           }
@@ -83,7 +82,8 @@ const T = ({
       ]
     }
   );
-}, Y = y(T);
+}, q = H(T);
+q.displayName = "LongForm";
 export {
-  Y as LongForm
+  q as LongForm
 };

package/dist/patterns/Form/components/ShortForm.d.ts

@@ -0,0 +1,38 @@
+import { FieldValues, UseFormProps } from 'react-hook-form';
+import { ReactElement, ReactNode, Ref } from 'react';
+import { FormPatternProps, FormRef, IressHookFormProps } from '../HookForm/HookForm';
+export interface ShortFormProps<T extends FieldValues, TContext = object> extends Omit<IressHookFormProps<T, TContext>, 'form'>, FormPatternProps<T, TContext> {
+    /**
+     * The actions to be displayed at the bottom left of the form.
+     */
+    actions?: ReactNode;
+    /**
+     * Title displayed at the top of the form, usually the purpose of the form.
+     */
+    heading?: ReactNode;
+    /**
+     * Configure the validation strategy **before** a user submits the form the first time.
+     * For short forms, it is recommended to use `onSubmit`, as the data is normally familiar to the user (eg. login).
+     * @see https://react-hook-form.com/docs/useform#mode
+     * @default 'onSubmit'
+     */
+    mode?: UseFormProps<T, TContext>['mode'];
+    /**
+     * Use `pattern="short"` for the following use cases:
+     * - Login forms, or similar forms that requires data familiar to the users
+     * - Forms that fit the length of a single screen (less than 8-9 fields)
+     */
+    pattern?: 'short';
+    /**
+     * Configure the validation strategy **after** a user submits the form the first time.
+     * During this phase, it is recommended to use `onChange` to provide immediate feedback on field changes so users can correct errors as they go.
+     * @see https://react-hook-form.com/docs/useform#reValidateMode
+     * @default 'onChange'
+     */
+    reValidateMode?: UseFormProps<T, TContext>['reValidateMode'];
+}
+export declare const ShortForm: (<T extends FieldValues, TContext = object>(props: ShortFormProps<T, TContext> & {
+    ref?: Ref<FormRef<T>>;
+}) => ReactElement) & {
+    displayName: "ShortForm";
+};

package/dist/patterns/Form/components/ShortForm.js

@@ -1,10 +1,10 @@
 import { jsx as H, jsxs as I } from "react/jsx-runtime";
-import { a as b } from "../../../index.esm-B6vzbp0e.js";
-import { forwardRef as g, useMemo as w } from "react";
-import { form as C } from "../Form.styles.js";
-import { IressHookForm as E } from "../HookForm/HookForm.js";
-import { c as M } from "../../../cx-DN21T1EH.js";
-import { IressText as N } from "../../../components/Text/Text.js";
+import { useForm as N } from "react-hook-form";
+import { forwardRef as b, useMemo as g } from "react";
+import { form as w } from "../Form.styles.js";
+import { IressHookForm as C } from "../HookForm/HookForm.js";
+import { c as E } from "../../../cx-DN21T1EH.js";
+import { IressText as M } from "../../../components/Text/Text.js";
 const R = ({
   actions: t,
   alert: r,
@@ -17,45 +17,46 @@ const R = ({
   heading: o,
   mode: i = "onSubmit",
   progressive: a,
-  resetOptions: u,
-  resolver: h,
-  reValidateMode: p = "onChange",
+  resetOptions: h,
+  resolver: p,
+  reValidateMode: u = "onChange",
   shouldUseNativeValidation: F,
   shouldUnregister: l,
   values: x,
   ...d
 }, S) => {
-  const j = b({
+  const y = N({
     criteriaMode: e,
     context: n,
     defaultValues: f,
     delayError: c,
     mode: i,
     progressive: a,
-    resetOptions: u,
-    resolver: h,
-    reValidateMode: p,
+    resetOptions: h,
+    resolver: p,
+    reValidateMode: u,
     shouldFocusError: !r,
     shouldUseNativeValidation: F,
     shouldUnregister: l,
     values: x
-  }), k = C({ pattern: "short" }), y = w(() => typeof o == "string" ? /* @__PURE__ */ H(N, { element: "h2", children: o }) : o, [o]);
+  }), j = w({ pattern: "short" }), k = g(() => typeof o == "string" ? /* @__PURE__ */ H(M, { element: "h2", children: o }) : o, [o]);
   return /* @__PURE__ */ I(
-    E,
+    C,
     {
-      form: j,
+      form: y,
       ...d,
-      className: M(s, k.root),
+      className: E(s, j.root),
       ref: S,
       children: [
-        y,
+        k,
         r,
         m,
         t
       ]
     }
   );
-}, G = g(R);
+}, T = b(R);
+T.displayName = "ShortForm";
 export {
-  G as ShortForm
+  T as ShortForm
 };

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

@@ -0,0 +1,48 @@
+import { StartUpLoadingProps } from './components/StartUpLoading';
+import { DefaultLoadingProps } from './components/DefaultLoading';
+import { ValidateLoadingProps } from './components/ValidateLoading';
+import { ComponentLoadingProps } from './components/ComponentLoading';
+import { PageLoadingProps } from './components/PageLoading';
+import { LongLoadingProps } from './components/LongLoading';
+export type IressLoadingProps = StartUpLoadingProps | ValidateLoadingProps | PageLoadingProps | ComponentLoadingProps | LongLoadingProps | DefaultLoadingProps;
+/**
+ * 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 IressLoading: {
+    ({ pattern, ...restProps }: IressLoadingProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+    /**
+     * This hook is used to smooth the loading experience by delaying the loading indicator being removed after the loading of an element finishes.
+     *
+     * @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.
+     * @returns A boolean value that determines whether the `IressLoading` component is safe to be removed.
+     */
+    shouldRender: (isLoaded: boolean, delay?: number, startFrom?: number, avoidDelayTimeout?: number) => boolean;
+};

package/dist/patterns/Loading/Loading.js

@@ -1,13 +1,14 @@
 import { jsx as i } from "react/jsx-runtime";
-import { StartUpLoading as n } from "./components/StartUpLoading.js";
-import { DefaultLoading as m } from "./components/DefaultLoading.js";
+import { StartUpLoading as m } from "./components/StartUpLoading.js";
+import { DefaultLoading as a } from "./components/DefaultLoading.js";
 import { ValidateLoading as d } from "./components/ValidateLoading.js";
 import { useShouldRenderLoading as f } from "./hooks/useShouldRenderLoading.js";
-import { ComponentLoading as a } from "./components/ComponentLoading.js";
+import { ComponentLoading as e } from "./components/ComponentLoading.js";
 import { PageLoading as g } from "./components/PageLoading.js";
 import { LongLoading as t } from "./components/LongLoading.js";
-const e = ({ pattern: r, ...o }) => r === "component" ? /* @__PURE__ */ i(a, { ...o }) : r === "long" ? /* @__PURE__ */ i(t, { ...o }) : r === "page" ? /* @__PURE__ */ i(g, { ...o }) : r === "start-up" ? /* @__PURE__ */ i(n, { ...o }) : r === "validate" ? /* @__PURE__ */ i(d, { ...o }) : /* @__PURE__ */ i(m, { ...o });
-e.shouldRender = f;
+const n = ({ pattern: r, ...o }) => r === "component" ? /* @__PURE__ */ i(e, { ...o }) : r === "long" ? /* @__PURE__ */ i(t, { ...o }) : r === "page" ? /* @__PURE__ */ i(g, { ...o }) : r === "start-up" ? /* @__PURE__ */ i(m, { ...o }) : r === "validate" ? /* @__PURE__ */ i(d, { ...o }) : /* @__PURE__ */ i(a, { ...o });
+n.displayName = "IressLoading";
+n.shouldRender = f;
 export {
-  e as IressLoading
+  n as IressLoading
 };

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

@@ -0,0 +1,186 @@
+export declare const loading: import('../../styled-system/types').SlotRecipeRuntimeFn<"overlay" | "root" | "message" | "critical", {
+    error: {
+        true: {
+            root: {
+                bg: "colour.system.danger.surface";
+                color: "colour.system.danger.text";
+                opacity: "[1 !important]";
+            };
+        };
+    };
+    instant: {
+        true: {};
+    };
+    loaded: {
+        true: {};
+    };
+    pattern: {
+        component: {
+            root: {
+                position: "relative";
+                opacity: number;
+                transition: "[opacity 0.3s ease-in-out]";
+            };
+            message: {
+                position: "absolute";
+                top: "[50%]";
+                left: "[50%]";
+                transform: "translate(-50%, -50%)";
+                width: "[fit-content]";
+                px: "spacing.2";
+                py: "spacing.1";
+                textStyle: "typography.body.sm";
+                bg: "colour.neutral.20";
+                color: "colour.neutral.70";
+                border: "divider";
+                borderRadius: "radius.system.tag";
+                opacity: number;
+                transition: "[opacity 0.3s ease-in-out]";
+                zIndex: "100";
+            };
+            overlay: {
+                position: "absolute";
+                inset: "[0]";
+                opacity: number;
+                bg: "colour.neutral.10";
+                transition: "[opacity 0.3s ease-in-out]";
+                zIndex: "100";
+            };
+        };
+        default: {
+            root: {
+                position: "absolute";
+                top: "[0]";
+                left: "[50%]";
+                transform: "translateX(-50%)";
+                opacity: number;
+                transition: "[opacity 0.3s ease-in-out]";
+                zIndex: "600";
+            };
+            message: {
+                px: "spacing.4";
+                py: "spacing.2";
+                bg: "colour.neutral.20";
+                color: "colour.neutral.70";
+                border: "divider";
+                borderTopWidth: "0";
+                borderRadius: "radius.system.tag";
+                transition: "[transform 0.3s ease-in-out]";
+                transform: "translateY(-100%)";
+            };
+        };
+        long: {
+            root: {
+                borderRadius: "radius.system.layout";
+                bg: "colour.neutral.20";
+                mx: "auto";
+                opacity: number;
+                transition: "[opacity 0.3s ease-in-out]";
+                width: "overlay.sm";
+            };
+            message: {
+                p: "spacing.10";
+            };
+        };
+        page: {
+            root: {
+                position: "relative";
+                opacity: number;
+                transition: "[opacity 0.2s linear]";
+            };
+            critical: {
+                opacity: number;
+                transition: "[opacity 0.2s linear]";
+                position: "absolute";
+                top: "spacing.0";
+                left: "spacing.0";
+            };
+            message: {
+                opacity: number;
+                transition: "[opacity 0.2s linear]";
+            };
+        };
+        'start-up': {
+            root: {
+                display: "flex";
+                flexDirection: "column";
+                alignItems: "center";
+                justifyContent: "center";
+                opacity: number;
+                transition: "[opacity 0.3s ease-in-out]";
+                position: "fixed";
+                top: "[0]";
+                left: "[0]";
+                right: "[0]";
+                bottom: "[0]";
+                zIndex: "600";
+                bg: "colour.neutral.10";
+            };
+            message: {
+                width: "overlay.sm";
+                maxWidth: "[75vw]";
+                opacity: number;
+                transition: "[opacity 0.3s ease-in-out]";
+            };
+        };
+        validate: {
+            root: {
+                position: "relative";
+            };
+            message: {
+                position: "absolute";
+                left: "spacing.0";
+                width: "[max-content]";
+                color: "colour.neutral.70";
+                padding: "spacing.2";
+                bg: "colour.neutral.10";
+                textStyle: "typography.body.md";
+                animationStyle: "loading-fade-next";
+                display: "inline-grid";
+            };
+        };
+    };
+    position: {
+        bottom: {
+            message: {
+                top: "[100%]";
+            };
+        };
+        top: {
+            message: {
+                bottom: "[100%]";
+            };
+        };
+        right: {
+            message: {
+                position: "static";
+            };
+        };
+    };
+    showCritical: {
+        true: {};
+    };
+    showIndicator: {
+        true: {};
+    };
+    showMessage: {
+        true: {};
+    };
+}>;
+export declare const loadingList: import('../../styled-system/types').SlotRecipeRuntimeFn<"tick" | "svg" | "circle" | "marker" | "root" | "dots" | "item", {
+    finished: {
+        true: {
+            svg: {
+                strokeWidth: number;
+                color: "colour.system.success.fill";
+                stroke: "colour.system.success.onFill";
+                strokeMiterlimit: number;
+                animation: "loadingItemFill 0.4s ease-in-out 0.4s forwards, loadingItemScale 0.3s ease-in-out 0.9s both";
+            };
+            item: {
+                opacity: number;
+                filter: "[grayscale(1)]";
+            };
+        };
+    };
+}>;

package/dist/patterns/Loading/Loading.styles.js

@@ -1,4 +1,4 @@
-import { s as t } from "../../sva-OmxClA9g.js";
+import { s as t } from "../../sva-CsHRIRDW.js";
 const a = t({
   slots: ["root", "message", "critical", "overlay"],
   variants: {
@@ -36,7 +36,7 @@ const a = t({
           bg: "colour.neutral.20",
           color: "colour.neutral.70",
           border: "divider",
-          borderRadius: "radius.system.badge",
+          borderRadius: "radius.system.tag",
           opacity: 0,
           transition: "[opacity 0.3s ease-in-out]",
           zIndex: "100"
@@ -67,7 +67,7 @@ const a = t({
           color: "colour.neutral.70",
           border: "divider",
           borderTopWidth: "0",
-          borderRadius: "radius.system.badge",
+          borderRadius: "radius.system.tag",
           transition: "[transform 0.3s ease-in-out]",
           transform: "translateY(-100%)"
         }

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

@@ -0,0 +1,74 @@
+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;
+    displayName: string;
+    /**
+     * 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;
+};