@iress-oss/ids-mcp-server 6.0.0-alpha.1-canary-20251204032753-fe18cab → 6.0.0-alpha.1-canary-20251204040305-3639454

package/generated/docs/components_patterns-form-recipes-docs.md

@@ -0,0 +1,1597 @@
+Recipes
+=======
+
+With readonly data
+------------------
+
+You can use `IressForm` with readonly data by setting the `readOnly` prop to `true` on controlled elements. This will disable those form controls, but will include the values in the form submission.
+
+Please take note of the following when displaying read only data.
+
+*   It is best to keep readonly data in a separate section of the form, to further avoid confusion with editable fields.
+
+[](./iframe.html?id=patterns-form-recipes--with-readonly-data)
+
+User Details
+------------
+
+First Name
+
+Leia
+
+Last Name
+
+Skywalker
+
+* * *
+
+Email
+
+Submit
+
+```
+
+export const WithReadonlyDataForm \= () \=> {
+  const \[values, setValues\] \= useState<FieldValues\>({
+    firstName: 'Leia',
+    lastName: 'Skywalker',
+    email: 'leia.skywalker@iress.com',
+  });
+  const \[preview, setPreview\] \= useState(false);
+  return (
+    <\>
+      <IressForm
+        onSubmit\={(data) \=> {
+          setValues(data);
+          setPreview(true);
+        }}
+        values\={values}
+      \>
+        <IressContainer\>
+          <IressStack gap\="md"\>
+            <IressText element\="h2"\>User Details</IressText\>
+            <IressRow gutter\="md"\>
+              <IressCol\>
+                <IressFormField
+                  name\="firstName"
+                  label\="First Name"
+                  render\={(controlledProps) \=> (
+                    <IressInput {...controlledProps} readOnly />
+                  )}
+                  mb\="none"
+                />
+              </IressCol\>
+              <IressCol\>
+                <IressFormField
+                  name\="lastName"
+                  label\="Last Name"
+                  render\={(controlledProps) \=> (
+                    <IressInput {...controlledProps} readOnly />
+                  )}
+                  mb\="none"
+                />
+              </IressCol\>
+            </IressRow\>
+            <IressDivider />
+            <IressRow\>
+              <IressCol\>
+                <IressFormField
+                  name\="email"
+                  label\="Email"
+                  render\={(controlledProps) \=> (
+                    <IressInput {...controlledProps} type\="email" />
+                  )}
+                />
+              </IressCol\>
+            </IressRow\>
+            <IressButton type\="submit" mode\="primary"\>
+              Submit            </IressButton\>
+          </IressStack\>
+        </IressContainer\>
+      </IressForm\>
+      <IressModal show\={!!preview} onShowChange\={(show) \=> setPreview(show)}\>
+        <IressTable
+          caption\="Submitted"
+          rows\={Object.entries(values).map((entry) \=> ({
+            name: entry\[0\],
+            value: JSON.stringify(entry\[1\], null, 2),
+          }))}
+        />
+      </IressModal\>
+    </\>
+  );
+};
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| actions | 
+object
+
+
+
+ | \- | Choose option...nonesubmitsave |
+| alert | 
+
+\-
+
+ | \- | Choose option...nonebasicAlert |
+| children | 
+
+array
+
+
+
+ | \- | Choose option...nonesimplesupportedControlsreadOnly |
+| Show React Hook Forms itemsReact Hook Forms | Show React Hook Forms items |
+
+Switching between readonly and edit modes
+-----------------------------------------
+
+It is recommended to use a button to toggle between read-only and editable input modes.
+
+Please take note of the following when switching between modes:
+
+*   Switching is done on a per-section basis, not on a per-field basis.
+*   When the user saves the data, it should switch back to read-only mode to avoid any confusion about whether the changes have been saved.
+
+[](./iframe.html?id=patterns-form-recipes--switch-edit-readonly)
+
+User Details
+------------
+
+First Name
+
+Leia
+
+Last Name
+
+Skywalker
+
+Email
+
+leia.skywalker@iress.com
+
+Dependents
+
+0
+
+Edit
+
+```
+
+const Form \= () \=> {
+  const dependentOptions \= \[
+    { value: 0, label: '0' },
+    { value: 1, label: '1' },
+    { value: 2, label: '2' },
+    { value: 3, label: '3' },
+    { value: 4, label: '4' },
+    { value: 5, label: '5' },
+    { value: 6, label: '6' },
+    { value: 7, label: '7' },
+    { value: 8, label: '8' },
+    { value: 9, label: '9' },
+    { value: 10, label: '10' },
+  \];
+  const \[values, setValues\] \= useState<FieldValues\>({
+    firstName: 'Leia',
+    lastName: 'Skywalker',
+    email: 'leia.skywalker@iress.com',
+    dependents: 0,
+  });
+  const \[editable, setEditable\] \= useState(false);
+  const { success } \= useToaster();
+  return (
+    <IressForm
+      onSubmit\={(data) \=> {
+        setValues(data);
+        setEditable(false);
+        success({
+          content: 'Saved successfully',
+        });
+      }}
+      values\={values}
+    \>
+      <IressContainer\>
+        <IressStack gap\="md"\>
+          <IressText element\="h2"\>User Details</IressText\>
+          <IressRow gutter\="md"\>
+            <IressCol\>
+              <IressFormField
+                name\="firstName"
+                label\="First Name"
+                render\={(controlledProps) \=> (
+                  <IressInput {...controlledProps} readOnly\={!editable} />
+                )}
+              />
+            </IressCol\>
+            <IressCol\>
+              <IressFormField
+                name\="lastName"
+                label\="Last Name"
+                render\={(controlledProps) \=> (
+                  <IressInput {...controlledProps} readOnly\={!editable} />
+                )}
+              />
+            </IressCol\>
+          </IressRow\>
+          <IressRow gutter\="md"\>
+            <IressCol\>
+              <IressFormField
+                name\="email"
+                label\="Email"
+                render\={(controlledProps) \=> (
+                  <IressInput
+                    {...controlledProps}
+                    readOnly\={!editable}
+                    type\="email"
+                  />
+                )}
+              />
+            </IressCol\>
+            <IressCol\>
+              <IressFormField
+                name\="dependents"
+                label\="Dependents"
+                render\={(controlledProps) \=> (
+                  <IressSelect
+                    {...controlledProps}
+                    readOnly\={!editable}
+                    onChange\={(
+                      \_e: React.ChangeEvent<HTMLSelectElement\>,
+                      value?: FormControlValue,
+                    ) \=> controlledProps.onChange(value)}
+                  \>
+                    {dependentOptions.map((option) \=> (
+                      <option key\={option.value} value\={option.value}\>
+                        {option.label}
+                      </option\>
+                    ))}
+                  </IressSelect\>
+                )}
+              />
+            </IressCol\>
+          </IressRow\>
+          {editable ? (
+            <IressInline gap\="sm"\>
+              <IressButton type\="submit" mode\="primary"\>
+                Save              </IressButton\>
+              <IressButton onClick\={() \=> setEditable(false)}\>
+                Cancel              </IressButton\>
+            </IressInline\>
+          ) : (
+            <IressButton
+              onClick\={() \=> setEditable(true)}
+              prepend\={<IressIcon name\="pencil" />}
+            \>
+              Edit            </IressButton\>
+          )}
+        </IressStack\>
+      </IressContainer\>
+    </IressForm\>
+  );
+};
+export const SwitchEditReadonlyForm \= () \=> (
+  <IressToasterProvider\>
+    <Form />
+  </IressToasterProvider\>
+);
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| actions | 
+object
+
+
+
+ | \- | Choose option...nonesubmitsave |
+| alert | 
+
+\-
+
+ | \- | Choose option...nonebasicAlert |
+| children | 
+
+array
+
+
+
+ | \- | Choose option...nonesimplesupportedControlsreadOnly |
+| Show React Hook Forms itemsReact Hook Forms | Show React Hook Forms items |
+
+Alternative form validation
+---------------------------
+
+`IressForm` is always recommended for all validation, as it is the cleanest way (least code) to provide the best form user experience for your users. Please visit the [`IressForm` documentation](/docs/components-form--docs) for different validation examples.
+
+However, if you have more complex requirements and you find `IressForm` too opinionated for your needs, you can always bring your own form validation using a native `form` element and the other IDS components such as `IressField`.
+
+Here is an example showcasing a form using the native form constraints API to achieve validation using IDS components. There are other libraries such as: [Yup](https://github.com/jquense/yup), [Joi](https://github.com/hapijs/joi) or [Zod](https://zod.dev/)) which can improve scalability, with the downside being you will have to maintain all validation yourself.
+
+[](./iframe.html?id=patterns-form-recipes--native-validation)
+
+**\*RequiredName**
+
+**\*RequiredEmail address**
+
+Sign up
+
+```
+
+export const NativeValidationForm \= () \=> {
+  const \[formData, setFormData\] \= useState({
+    name: '',
+    email: '',
+  });
+  const \[errors, setErrors\] \= useState<Record<string, boolean\>>({
+    name: false,
+    email: false,
+  });
+  const \[isSubmitted, setIsSubmitted\] \= useState(false);
+  const hasErrors \= Object.values(errors).some((error) \=> !!error);
+  const handleInputChange \= (e: React.ChangeEvent<InputBaseElement\>) \=> {
+    setFormData({ ...formData, \[e.target.name\]: e.target.value });
+    setErrors({
+      ...errors,
+      \[e.target.name\]: !e.currentTarget.reportValidity(),
+    });
+  };
+  const handleSubmit \= (e: React.FormEvent<HTMLFormElement\>) \=> {
+    e.preventDefault();
+    const form \= e.currentTarget;
+    setIsSubmitted(true);
+    if (!form.checkValidity()) {
+      const fieldData \= Object.fromEntries(new FormData(form).entries());
+      const fieldNames \= Object.keys(fieldData);
+      setErrors(
+        fieldNames.reduce(
+          (newErrors, fieldName) \=> {
+            newErrors\[fieldName\] \= !form
+              .querySelector<HTMLInputElement\>(\`\[name=${fieldName}\]\`)
+              ?.checkValidity();
+            return newErrors;
+          },
+          {} as Record<string, boolean\>,
+        ),
+      );
+    }
+    console.log(formData);
+  };
+  return (
+    <form onSubmit\={handleSubmit} noValidate\>
+      {isSubmitted && hasErrors && (
+        <IressAlert status\="danger"\>
+          There's a problem with your submission.        </IressAlert\>
+      )}
+      <IressField
+        label\="Name"
+        error\={errors.name && 'Name is required'}
+        required
+      \>
+        <IressInput name\="name" onChange\={handleInputChange} required />
+      </IressField\>
+      <IressField
+        label\="Email address"
+        error\={errors.email && 'Email is required'}
+        required
+      \>
+        <IressInput name\="email" onChange\={handleInputChange} required />
+      </IressField\>
+      <IressButton mode\="primary" type\="submit"\>
+        Sign up      </IressButton\>
+    </form\>
+  );
+};
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| actions | 
+object
+
+
+
+ | \- | Choose option...nonesubmitsave |
+| alert | 
+
+\-
+
+ | \- | Choose option...nonebasicAlert |
+| children | 
+
+array
+
+
+
+ | \- | Choose option...nonesimplesupportedControlsreadOnly |
+| Show React Hook Forms itemsReact Hook Forms | Show React Hook Forms items |
+
+Nested forms
+------------
+
+Unfortunately, it is [forbidden to nest form elements as per the HTML specifications](https://developer.mozilla.org/en-US/docs/Learn/Forms/How_to_structure_a_web_form).
+
+To achieve a similar effect, you can use multiple `IressForm` components, and trigger validation in multiple ways:
+
+1.  You can trigger specific forms using the `form` attribute of `IressButton`. The [`form` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#form) allows you to specify the form ID to submit when the button is clicked, which can be any form on the page, and will take precedence over the parent form of a button.
+2.  If you need to trigger multiple forms, you can use the [`requestSubmit` method](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/requestSubmit) on the form element to trigger the validation of multiple forms.
+3.  If you only want to trigger validation and not trigger submission even if the validation passes, you can use the `ref` attribute of `IressForm` and trigger validation manually using `ref.current?.api.trigger()`, which is based on the [React Hook Form API](https://react-hook-form.com/docs/useform/trigger).
+
+The example here showcases triggering validation using the `form` attribute of `IressButton` and the `requestSubmit` method on the form element.
+
+[](./iframe.html?id=patterns-form-recipes--nested-forms)
+
+\*RequiredName
+
+Add new dependant
+
+\*RequiredName
+
+Save
+
+* * *
+
+Submit main formSubmit all forms
+
+```
+
+interface FormData {
+  name: string;
+}
+const MainForm \= () \=> {
+  const \[details, setDetails\] \= useState<FormData | undefined\>();
+  return (
+    <\>
+      <IressForm<FormData>        alert={
+          <IressFormValidationSummary heading\="Please fix the errors for the main form" />
+        }
+        id="mainForm"        onSubmit={(data) \=> {
+          setDetails(data);
+        }}
+      >        <IressFormField<FormData>          name="name"          label="Name"          render={(controlledProps) \=> <IressInput {...controlledProps} />}
+          rules={{ required: true }}
+        />      </IressForm\>
+      <IressModal
+        show\={!!details}
+        onShowChange\={(show) \=> !show && setDetails(undefined)}
+      \>
+        {details && (
+          <IressTable
+            caption\="Submitted main form"
+            rows\={Object.entries(details).map((entry) \=> ({
+              name: entry\[0\],
+              value: JSON.stringify(entry\[1\], null, 2),
+            }))}
+          />
+        )}
+      </IressModal\>
+    </\>
+  );
+};
+const SubForm \= () \=> {
+  const \[details, setDetails\] \= useState<FormData | undefined\>();
+  return (
+    <IressPanel bg\="alt"\>
+      <IressStack gap\="md"\>
+        <IressForm<FormData>          alert={
+            <IressFormValidationSummary heading\="Please fix the errors for the dependants" />
+          }
+          id="subForm"          onSubmit={(data) \=> {
+            setDetails(data);
+          }}
+        >          <IressFieldGroup label\="Add new dependant" inline mb\="none"\>
+            <IressFormField
+              name\="name"
+              label\="Name"
+              render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+              rules\={{ required: true }}
+            />
+            <IressButton type\="submit"\>Save</IressButton\>
+          </IressFieldGroup\>
+        </IressForm\>
+        <IressTable
+          caption\="Dependants"
+          columns\={\[
+            { key: 'name', label: 'Name' },
+            { key: 'value', label: 'Value' },
+          \]}
+          rows\={Object.entries(details ?? {}).map((entry) \=> ({
+            name: entry\[0\],
+            value: JSON.stringify(entry\[1\], null, 2),
+          }))}
+        />
+      </IressStack\>
+    </IressPanel\>
+  );
+};
+export const NestedFormsExample \= () \=> {
+  const submitAllForms \= () \=> {
+    document.querySelector<HTMLFormElement\>('\[id=mainForm\]')?.requestSubmit();
+    document.querySelector<HTMLFormElement\>('\[id=subForm\]')?.requestSubmit();
+  };
+  return (
+    <IressStack gap\="md"\>
+      <MainForm />
+      <SubForm />
+      <IressDivider />
+      <IressInline gap\="md"\>
+        <IressButton type\="submit" form\="mainForm"\>
+          Submit main form        </IressButton\>
+        <IressButton onClick\={submitAllForms}\>Submit all forms</IressButton\>
+      </IressInline\>
+    </IressStack\>
+  );
+};
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| actions | 
+object
+
+
+
+ | \- | Choose option...nonesubmitsave |
+| alert | 
+
+\-
+
+ | \- | Choose option...nonebasicAlert |
+| children | 
+
+array
+
+
+
+ | \- | Choose option...nonesimplesupportedControlsreadOnly |
+| Show React Hook Forms itemsReact Hook Forms | Show React Hook Forms items |
+
+Form Groups
+-----------
+
+Powered by [React Hook Form](https://react-hook-form.com/docs/usefieldarray)'s `useFieldArray`, this example allows you add/edit/delete multiple children sections within ONE form (not nested form).
+
+[](./iframe.html?id=patterns-form-recipes--form-groups)
+
+Form groups
+===========
+
+This is one form with child sections (not nested forms). Play around to add/edit/delete child form sections:
+
+Client
+------
+
+\*RequiredName
+
+\*RequiredSalary
+
+\*RequiredGoal
+
+Dependant 1
+-----------
+
+\*RequiredName
+
+\*RequiredRelationship
+
+\*RequiredAge
+
+Save
+
+Add Dependant
+
+* * *
+
+Submit All
+
+```
+
+interface Client {
+  name: string | undefined;
+  salary: number | undefined;
+  goal: string | undefined;
+}
+interface Dependant {
+  name: string | undefined;
+  relationship: string | undefined;
+  age: number | undefined;
+}
+interface FormValues {
+  client: Client;
+  dependants: Dependant\[\];
+}
+interface ClientProps {
+  control: Control<FormValues\> | undefined;
+}
+interface DependantProps {
+  index: number;
+  control: Control<FormValues\> | undefined;
+  update: (index: number, data: Dependant) \=> void;
+  remove: (index: number) \=> void;
+  getValues: UseFormGetValues<FormValues\>;
+}
+const defaultValues \= {
+  client: {
+    name: '',
+    salary: undefined,
+    goal: '',
+  },
+  dependants: \[
+    {
+      name: '',
+      relationship: '',
+      age: undefined,
+    },
+  \],
+};
+const ClientSection: React.FC<ClientProps\> \= ({ control }) \=> {
+  return (
+    <IressFieldGroup label\={<IressText element\="h2"\>Client</IressText\>} inline\>
+      <IressFormField
+        name\="client.name"
+        label\="Name"
+        control\={control}
+        render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+        rules\={{ required: true }}
+      />
+      <IressFormField
+        name\="client.salary"
+        label\="Salary"
+        control\={control}
+        render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+        rules\={{ required: true }}
+      />
+      <IressFormField
+        name\="client.goal"
+        label\="Goal"
+        control\={control}
+        render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+        rules\={{ required: true }}
+      />
+    </IressFieldGroup\>
+  );
+};
+const DependantSection: React.FC<DependantProps\> \= ({
+  index,
+  update,
+  remove,
+  control,
+  getValues,
+}: DependantProps) \=> {
+  return (
+    <IressPanel bg\="alt"\>
+      <IressInline horizontalAlign\="right"\>
+        <IressCloseButton
+          onClick\={() \=> remove(index)}
+          mb\="\-lg"
+          style\={{ zIndex: 1 }}
+        />
+      </IressInline\>
+      <IressStack gap\="md"\>
+        <IressFieldGroup
+          label\={<IressText element\="h2"\>Dependant {index + 1}</IressText\>}
+          inline
+        \>
+          <IressFormField
+            name\={\`dependants.${index}.name\`}
+            label\="Name"
+            control\={control}
+            render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+            rules\={{ required: true }}
+          />
+          <IressFormField
+            name\={\`dependants.${index}.relationship\`}
+            label\="Relationship"
+            control\={control}
+            render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+            rules\={{ required: true }}
+          />
+          <IressFormField
+            name\={\`dependants.${index}.age\`}
+            label\="Age"
+            control\={control}
+            render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+            rules\={{ required: true }}
+          />
+          <IressButton
+            type\="button"
+            prepend\={<IressIcon name\="check" />}
+            onClick\={() \=> {
+              const data \= getValues();
+              const value \= data?.dependants\[index\];
+              update(index, value);
+            }}
+          \>
+            Save          </IressButton\>
+        </IressFieldGroup\>
+      </IressStack\>
+    </IressPanel\>
+  );
+};
+export const FormGroups \= () \=> {
+  const form \= IressHookForm.useForm<FormValues\>({
+    defaultValues: defaultValues,
+    mode: 'onBlur',
+  });
+  const { control, getValues } \= form;
+  const { fields, append, update, remove } \= IressHookForm.useFieldArray({
+    name: 'dependants',
+    control,
+  });
+  const onSubmit \= (data: FormValues) \=> console.log(data);
+  return (
+    <IressText\>
+      <h1\>Form groups</h1\>
+      <p\>
+        This is one form with child sections (not nested forms). Play around to        add/edit/delete child form sections:      </p\>
+      <IressHookForm<FormValues> id="mainForm" form={form} onSubmit={onSubmit}\>
+        <IressStack gap\="md"\>
+          <ClientSection control\={control} />
+          {fields.map((field, index) \=> (
+            <DependantSection
+              key\={field.id}
+              index\={index}
+              control\={control}
+              update\={update}
+              remove\={remove}
+              getValues\={getValues}
+            />
+          ))}
+          <IressButton
+            type\="button"
+            prepend\={<IressIcon name\="plus" />}
+            onClick\={() \=> {
+              append({ name: '', relationship: '', age: undefined });
+            }}
+          \>
+            Add Dependant          </IressButton\>
+        </IressStack\>
+        <IressDivider my\="md" />
+        <IressButton type\="submit" mode\="primary"\>
+          Submit All        </IressButton\>
+      </IressHookForm\>
+    </IressText\>
+  );
+};
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| actions | 
+object
+
+
+
+ | \- | Choose option...nonesubmitsave |
+| alert | 
+
+\-
+
+ | \- | Choose option...nonebasicAlert |
+| children | 
+
+array
+
+
+
+ | \- | Choose option...nonesimplesupportedControlsreadOnly |
+| Show React Hook Forms itemsReact Hook Forms | Show React Hook Forms items |
+
+Forms in expanders (lazy loading)
+---------------------------------
+
+If you are using forms in expanders, or in other scenarios when the loading of the form may be delayed, it is recommended to only load the form when it is required. This will improve performance of your application, and make it more predictable. It may also fix act warnings in tests if you are seeing some appearing due to conditionally loaded `IressForm` elements.
+
+[](./iframe.html?id=patterns-form-recipes--forms-in-expanders)
+
+Sender
+
+Recipient
+
+```
+
+interface FieldValues {
+  name?: string;
+  email?: string;
+}
+const Form \= (args: IressFormProps<FieldValues\>) \=> (
+  <IressForm {...args}\>
+    <IressStack gap\="md"\>
+      <IressFormField
+        label\="Name"
+        name\="name"
+        render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+        rules\={{
+          required: 'Name is required',
+        }}
+      />
+      <IressFormField
+        label\="Email address"
+        name\="email"
+        render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+        rules\={{
+          minLength: {
+            message: 'Use a longer email address',
+            value: 6,
+          },
+          required: 'Email is required',
+        }}
+      />
+    </IressStack\>
+  </IressForm\>
+);
+export const FormExpanders \= (args: IressFormProps<FieldValues\>) \=> {
+  const \[expander, setExpander\] \= useState('');
+  const isOpen \= (name: string) \=> expander \=== name;
+  return (
+    <IressStack gap\="sm"\>
+      <IressExpander
+        activator\="Sender"
+        open\={isOpen('Sender')}
+        onChange\={(open) \=> open && setExpander('Sender')}
+      \>
+        {isOpen('Sender') && <Form {...args} />}
+      </IressExpander\>
+      <IressExpander
+        activator\="Recipient"
+        open\={isOpen('Recipient')}
+        onChange\={(open) \=> open && setExpander('Recipient')}
+      \>
+        {isOpen('Recipient') && <Form {...args} />}
+      </IressExpander\>
+    </IressStack\>
+  );
+};
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| actions | 
+object
+
+
+
+ | \- | Choose option...nonesubmitsave |
+| alert | 
+
+\-
+
+ | \- | Choose option...nonebasicAlert |
+| children | 
+
+array
+
+
+
+ | \- | Choose option...nonesimplesupportedControlsreadOnly |
+| Show React Hook Forms itemsReact Hook Forms | Show React Hook Forms items |
+
+Conditional fields (useWatch)
+-----------------------------
+
+When you have fields that are conditionally shown, you can use the `IressForm.useWatch` hook to watch the value of another field and conditionally render the field.
+
+**Notes:**
+
+*   You can use the `api.watch` method on the `IressForm`'s ref to watch the value of a field, but it is recommended to use the hook for better performance by isolating re-rendering at the component level.
+
+[](./iframe.html?id=patterns-form-recipes--use-watch)
+
+Conditional fields using `useWatch`
+-----------------------------------
+
+This example demonstrates how to use the `IressForm.useWatch()` hook to watch the value of a field and conditionally render other fields based on that value.
+
+\*RequiredSelect fields to show
+
+Name
+
+Email
+
+Submit
+
+```
+
+interface FieldValues {
+  show?: string\[\];
+  name?: string;
+  email?: string;
+}
+/\*\*
+ \* Conditional fields need to be rendered in a sub-component, to allow it to use the \`useWatch\` \* hook to watch the value of the field dictating the display of conditional fields. \*/
+const FormSectionWithConditionalFields \= () \=> {
+  const show \= IressForm.useWatch<FieldValues\>({ name: 'show' });
+  return (
+    <IressText\>
+      <h2\>
+        Conditional fields using <code\>useWatch</code\>
+      </h2\>
+      <p\>
+        This example demonstrates how to use the{' '}
+        <code\>IressForm.useWatch()</code\> hook to watch the value of a field and        conditionally render other fields based on that value.      </p\>
+      <IressFormField
+        name\="show"
+        label\="Select fields to show"
+        rules\={{
+          required: 'Please select at least one field to show',
+        }}
+        render\={(controlledProps) \=> (
+          <IressCheckboxGroup {...controlledProps} layout\="inline"\>
+            <IressCheckbox value\="name"\>Name</IressCheckbox\>
+            <IressCheckbox value\="email"\>Email</IressCheckbox\>
+          </IressCheckboxGroup\>
+        )}
+      />
+      {show?.includes('name') && (
+        <IressFormField
+          name\="name"
+          label\="Name"
+          rules\={{
+            required: 'Name is required',
+          }}
+          render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+        />
+      )}
+      {show?.includes('email') && (
+        <IressFormField
+          name\="email"
+          label\="Email"
+          rules\={{
+            required: 'Email is required',
+            pattern: {
+              value:
+                /^\[a-zA-Z0-9.!#$%&'\*+/=?^\_\`{|}~-\]+@\[a-zA-Z0-9\](?:\[a-zA-Z0-9-\]{0,61}\[a-zA-Z0-9\])?(?:\\.\[a-zA-Z0-9\](?:\[a-zA-Z0-9-\]{0,61}\[a-zA-Z0-9\])?)\*$/,
+              message: 'Please enter a valid email address',
+            },
+          }}
+          render\={(controlledProps) \=> (
+            <IressInput {...controlledProps} type\="email" />
+          )}
+        /\>
+      )}
+    </IressText\>
+  );
+};
+export const UseWatchForm \= (args: IressFormProps<FieldValues\>) \=> (
+  <IressForm {...args}\>
+    <FormSectionWithConditionalFields />
+  </IressForm\>
+);
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| actions | 
+object
+
+
+
+ | \- | Choose option...nonesubmitsave |
+| alert | 
+
+\-
+
+ | \- | Choose option...nonebasicAlert |
+| children | 
+
+array
+
+
+
+ | \- | Choose option...nonesimplesupportedControlsreadOnly |
+| Show React Hook Forms itemsReact Hook Forms | Show React Hook Forms items |
+
+Hidden inputs
+-------------
+
+You can use hidden inputs to store data that you do not want to display to the user, but still need to include in the form submission. This is useful for storing metadata or other information that is not editable by the user.
+
+Warning
+-------
+
+This is not a recommended practice, as it can lead to security issues if sensitive data is stored in hidden inputs. It is better to use a variable to store your data, and include it in the form submission using the `onSubmit` handler.
+
+[](./iframe.html?id=patterns-form-recipes--hidden-inputs)
+
+Visible Input
+
+Submit
+
+```
+
+export const HiddenInputsForm \= () \=> {
+  const form \= IressForm.useForm();
+  const { register } \= form;
+  // This is a hidden input field that the user cannot see or interact with.
+  // This is the recommended way to handle hidden inputs in Iress forms.
+  const hiddenInputStoredInVariable \= 'hiddenValue';
+  return (
+    <IressHookForm
+      form\={form}
+      onSubmit\={(data) \=> {
+        console.log('Form submitted with data:', {
+          ...data,
+          hiddenInputStoredInVariable,
+        });
+      }}
+    \>
+      <IressStack gap\="md"\>
+        <IressFormField
+          label\="Visible Input"
+          name\="visibleInput"
+          render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+        />
+        {/\* Hidden field - NOT RECOMMENDED \*/}
+        <input
+          type\="hidden"
+          {...register('hiddenField')} // Manually register the hidden field with react-hook-form
+          value\="hiddenValue"
+        />
+        <IressButton type\="submit"\>Submit</IressButton\>
+      </IressStack\>
+    </IressHookForm\>
+  );
+};
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| actions | 
+object
+
+
+
+ | \- | Choose option...nonesubmitsave |
+| alert | 
+
+\-
+
+ | \- | Choose option...nonebasicAlert |
+| children | 
+
+array
+
+
+
+ | \- | Choose option...nonesimplesupportedControlsreadOnly |
+| Show React Hook Forms itemsReact Hook Forms | Show React Hook Forms items |
+
+Validation depend on other fields
+---------------------------------
+
+This example shows how to validate one field based on another field's value.
+
+The budget amount input validates against the selected budget range using the custom `validateBudgetInput` rules.
+
+[](./iframe.html?id=patterns-form-recipes--validation-depend-on-other-fields)
+
+Validation depend on other fields
+=================================
+
+This form demonstrates how to validate a field based on the value of another field. The budget amount field is validated against the selected budget range.
+
+\*RequiredMonthly investment budget
+
+Select your budget rangeLess than $499Between $500 to $999More than $1000
+
+\*RequiredEnter your budget amount ($)
+
+AUD
+
+Submit
+
+* * *
+
+```
+
+interface FormData {
+  primaryField: string;
+  dependentField: string;
+}
+const budgetOptions \= \[
+  { value: 'less-than-499', label: 'Less than $499' },
+  { value: 'between-500-999', label: 'Between $500 to $999' },
+  { value: 'more-than-1000', label: 'More than $1000' },
+\];
+const validateBudgetInput \= (
+  value: string,
+  selectedBudget: string,
+): string | true \=> {
+  if (!selectedBudget) return 'Select budget range first';
+  const numericValue \= parseFloat(value);
+  if (isNaN(numericValue)) return 'Enter a valid number';
+  switch (selectedBudget) {
+    case 'less-than-499':
+      return numericValue < 499 || 'Must be less than $499';
+    case 'between-500-999':
+      return (
+        (numericValue \>= 500 && numericValue <= 999) ||
+        'Must be between $500-$999'
+      );
+    case 'more-than-1000':
+      return numericValue \> 1000 || 'Must be more than $1000';
+    default:
+      return true;
+  }
+};
+export const ValidationDependOnOtherFields \= () \=> {
+  const \[submitted, setSubmitted\] \= useState<FormData | undefined\>(undefined);
+  const form \= IressForm.useForm<FormData\>({
+    defaultValues: {
+      primaryField: '',
+      dependentField: '',
+    },
+  });
+  const onSubmit \= (data: FormData) \=> {
+    console.log(data);
+    setSubmitted(data);
+  };
+  const onError \= (errors: Record<string, unknown\>) \=> {
+    console.log('Form validation errors:', errors);
+  };
+  return (
+    <\>
+      <IressText element\="h1"\>Validation depend on other fields</IressText\>
+      <IressText element\="p"\>
+        This form demonstrates how to validate a field based on the value of        another field. The budget amount field is validated against the selected        budget range.      </IressText\>
+      <IressHookForm form\={form} onSubmit\={onSubmit} onError\={onError}\>
+        <IressStack gap\="md"\>
+          <IressRow\>
+            <IressCol\>
+              <IressFormField
+                name\="primaryField"
+                label\="Monthly investment budget"
+                rules\={{
+                  required: 'Budget range is required',
+                }}
+                render\={(field) \=> (
+                  <IressSelect
+                    {...field}
+                    placeholder\="Select your budget range"
+                  \>
+                    {budgetOptions.map((option) \=> (
+                      <option key\={option.value} value\={option.value}\>
+                        {option.label}
+                      </option\>
+                    ))}
+                  </IressSelect\>
+                )}
+              />
+            </IressCol\>
+          </IressRow\>
+          <IressRow\>
+            <IressCol\>
+              <IressFormField
+                name\="dependentField"
+                label\="Enter your budget amount ($)"
+                rules\={{
+                  required: 'Budget amount is required',
+                  validate: (value: string, formValues: FormData) \=>
+                    validateBudgetInput(value, formValues.primaryField),
+                }}
+                render\={(field) \=> (
+                  <IressInputCurrency {...field} type\="number" />
+                )}
+              />
+            </IressCol\>
+          </IressRow\>
+          <IressButton type\="submit"\>Submit</IressButton\>
+        </IressStack\>
+      </IressHookForm\>
+      <IressDivider />
+      {submitted && (
+        <IressStack gap\="md"\>
+          <IressText element\="h3"\>Submitted Values</IressText\>
+          <IressText\>
+            Budget Range:{' '}
+            {budgetOptions.find(
+              (option) \=> option.value \=== submitted.primaryField,
+            )?.label ?? submitted.primaryField}
+          </IressText\>
+          <IressText\>Budget Amount: ${submitted.dependentField}</IressText\>
+        </IressStack\>
+      )}
+    </\>
+  );
+};
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| actions | 
+object
+
+
+
+ | \- | Choose option...nonesubmitsave |
+| alert | 
+
+\-
+
+ | \- | Choose option...nonebasicAlert |
+| children | 
+
+array
+
+
+
+ | \- | Choose option...nonesimplesupportedControlsreadOnly |
+| Show React Hook Forms itemsReact Hook Forms | Show React Hook Forms items |
+
+Custom form field components
+----------------------------
+
+You can integrate custom components within `IressFormField` to create enhanced form experiences.
+
+This demo showcases how to embed a custom `TranscriptTextBox` component into `IressFormField` while leveraging its built-in validation rules, error handling, and state management without additional implementation.
+
+**Reminder:** When building custom form components, avoid managing error message state internally. This helps maintain the IressForm as the single source of truth and ensures consistent, predictable UI behavior.
+
+Key features demonstrated:
+
+*   **Universal Integration Pattern**: Shows how any custom component can be embedded in IressFormField
+*   **Built-in Validation**: Leverages IressFormField's validation rules with custom validation logic
+*   **Multiple Error Messages**: Displays simultaneous validation errors (e.g., wrong file type AND too large)
+*   **Drag & Drop**: Files can be dragged and dropped directly onto the textarea
+*   **File Upload Button**: Traditional file selection via button click
+*   **Visual Feedback**: UI changes during drag operations with border and background updates
+*   **Form State Management**: Automatically integrates with form context using controlled props
+*   **File Management**: Display uploaded files with remove functionality using `IressPanel`
+
+[](./iframe.html?id=patterns-form-recipes--custom-form-field-components)
+
+Custom FormField Components
+===========================
+
+This demo showcases how to embed any custom component (TranscriptTextBox) into IressFormField while leveraging its form validation, error handling, and state management without additional implementation. When building custom form components, avoid managing error message state internally. This helps maintain the IressForm as the single source of truth and ensures consistent, predictable UI behavior.
+
+\*RequiredTranscript
+
+Upload or copy and paste transcript here
+
+Upload
+
+Submit
+
+```
+
+import React, { useState } from 'react';
+
+interface TranscriptFormValues {
+  transcript: TranscriptData | string;
+}
+interface TranscriptData {
+  content: string;
+  size?: number;
+  type: 'file' | 'text';
+  extension?: string;
+  fileName?: string;
+  rejectedReasons?: REJECTION\_REASONS\[\];
+}
+interface TranscriptTextBoxProps {
+  value: TranscriptData | string;
+  onChange: (data: TranscriptData) \=> void;
+  placeholder?: string;
+  rows?: number;
+  style?: React.CSSProperties;
+  allowedExtensions?: string\[\];
+  maxSizeInMB?: number;
+}
+interface SubmittedValuesDisplayProps {
+  submittedValues: TranscriptFormValues | null;
+  title?: string;
+}
+enum REJECTION\_REASONS {
+  TYPE \= 'type',
+  SIZE \= 'size',
+}
+const validateFile \=
+  (allowedExtensions: string\[\], maxSizeInMB: number) \=>
+  (data: TranscriptData | string) \=> {
+    if (
+      !!data &&
+      typeof data \=== 'object' &&
+      data.type \=== 'file' &&
+      Array.isArray(data.rejectedReasons) &&
+      data.rejectedReasons.length \> 0
+    ) {
+      const errors: string\[\] \= \[\];
+      if (data.rejectedReasons.includes(REJECTION\_REASONS.TYPE)) {
+        errors.push(\`Only .${allowedExtensions.join(', ')} accepted\`);
+      }
+      if (data.rejectedReasons.includes(REJECTION\_REASONS.SIZE)) {
+        errors.push(\`File size must be less than ${maxSizeInMB}MB\`);
+      }
+      if (errors.length \> 0) {
+        return errors.join('. ');
+      }
+    }
+    return true;
+  };
+const TranscriptTextBox \= ({
+  value,
+  onChange,
+  placeholder \= 'Copy and paste transcripts OR drag and drop / upload recordings, transcripts or documents here (.txt format).',
+  rows \= 10,
+  style,
+  allowedExtensions \= \['txt'\],
+  maxSizeInMB \= 10,
+}: TranscriptTextBoxProps) \=> {
+  // Extract content and file info from value
+  const currentData \=
+    typeof value \=== 'string'
+      ? { content: value, type: 'text' as const }
+      : value;
+  const currentFile \=
+    currentData?.type \=== 'file' &&
+    (!currentData.rejectedReasons || currentData.rejectedReasons.length \=== 0)
+      ? {
+          name: currentData.fileName ?? 'Unknown file',
+          size: currentData.size,
+        }
+      : null;
+  const createTranscriptData \= (
+    content: string,
+    type: 'file' | 'text',
+    additionalData?: Partial<TranscriptData\>,
+  ): TranscriptData \=> ({
+    content,
+    type,
+    ...additionalData,
+  });
+  const handleFileRead \= (file: File) \=> {
+    const reader \= new FileReader();
+    reader.onload \= (e) \=> {
+      const content \= e.target?.result as string;
+      onChange(
+        createTranscriptData(content, 'file', {
+          size: file.size,
+          extension: file.name.split('.').pop()?.toLowerCase(),
+          fileName: file.name,
+        }),
+      );
+    };
+    reader.onerror \= () \=> {
+      // Let parent handle errors through validation
+      onChange(
+        createTranscriptData('', 'file', {
+          fileName: file.name,
+        }),
+      );
+    };
+    reader.readAsText(file);
+  };
+  const handleTextChange: IressInputProps<string, number\>\['onChange'\] \= (
+    \_e,
+    textContent \= '',
+  ) \=> {
+    onChange(createTranscriptData(textContent, 'text'));
+  };
+  const onFileSelected \= (files: File\[\]) \=> {
+    if (files.length \=== 0) return;
+    const file \= files\[0\];
+    handleFileRead(file);
+  };
+  const { getRootProps, getInputProps, open, isDragActive } \= useDropzone({
+    multiple: false,
+    noClick: true,
+    maxSize: maxSizeInMB \* 1024 \* 1024,
+    accept: allowedExtensions.reduce(
+      (acc, ext) \=> {
+        const mimeType \=
+          ext \=== 'txt' ? 'text/plain' : 'application/octet-stream';
+        acc\[mimeType\] \= acc\[mimeType\] || \[\];
+        acc\[mimeType\].push(\`.${ext}\`);
+        return acc;
+      },
+      {} as Record<string, string\[\]\>,
+    ),
+    onDrop: (acceptedFiles, rejectedFiles) \=> {
+      if (acceptedFiles.length \> 0) {
+        onFileSelected(acceptedFiles);
+        return;
+      }
+      if (rejectedFiles.length \> 0) {
+        const rejectedFile \= rejectedFiles\[0\];
+        const { file, errors } \= rejectedFile;
+        // Map error codes to rejection reasons
+        const errorCodeMap \= {
+          'file-invalid-type': REJECTION\_REASONS.TYPE,
+          'file-too-large': REJECTION\_REASONS.SIZE,
+        } as const;
+        const rejectedReasons \= errors          .map((error) \=> errorCodeMap\[error.code as keyof typeof errorCodeMap\])
+          .filter((reason): reason is REJECTION\_REASONS \=> Boolean(reason));
+        onChange(
+          createTranscriptData('', 'file', {
+            fileName: file.name,
+            rejectedReasons,
+          }),
+        );
+      }
+    },
+  });
+  const handleUploadClick \= () \=> {
+    open();
+  };
+  const removeFile \= () \=> {
+    onChange(createTranscriptData('', 'text'));
+  };
+  return (
+    <IressStack gap\="sm"\>
+      <div {...getRootProps()} style\={{ position: 'relative' }}\>
+        <input {...getInputProps()} />
+        <IressInput
+          value\={currentData?.content || ''}
+          onChange\={handleTextChange}
+          rows\={rows}
+          placeholder\={isDragActive ? 'Drop your file here...' : placeholder}
+          style\={{
+            boxSizing: 'border-box',
+            border: isDragActive ? '1px dashed #007acc' : undefined,
+            backgroundColor: isDragActive ? '#f0f8ff' : undefined,
+            ...style,
+          }}
+        />
+      </div\>
+      {currentFile && (
+        <IressPanel\>
+          <IressInline horizontalAlign\="between" verticalAlign\="middle"\>
+            <IressText\>📄 {currentFile.name}</IressText\>
+            <IressButton mode\="secondary" onClick\={removeFile}\>
+              Remove            </IressButton\>
+          </IressInline\>
+        </IressPanel\>
+      )}
+      <IressButton
+        mode\="secondary"
+        onClick\={handleUploadClick}
+        prepend\={<IressIcon name\="upload" />}
+      \>
+        Upload      </IressButton\>
+    </IressStack\>
+  );
+};
+const SubmittedValuesDisplay: React.FC<SubmittedValuesDisplayProps\> \= ({
+  submittedValues,
+  title \= 'Submitted Values:',
+}) \=> {
+  if (!submittedValues) {
+    return null;
+  }
+  return (
+    <IressPanel\>
+      <IressStack gap\="sm"\>
+        <IressText textStyle\="typography.body.md.strong"\>{title}</IressText\>
+        <IressText\>
+          <strong\>Type:</strong\>
+          {typeof submittedValues.transcript \=== 'string'
+            ? 'text'
+            : submittedValues.transcript.type}
+        </IressText\>
+        <IressText\>
+          <strong\>Content:</strong\>
+          {typeof submittedValues.transcript \=== 'string'
+            ? submittedValues.transcript
+            : submittedValues.transcript.content}
+        </IressText\>
+        {typeof submittedValues.transcript \=== 'object' &&
+          submittedValues.transcript.fileName && (
+            <IressText\>
+              <strong\>File Name:</strong\> {submittedValues.transcript.fileName}
+            </IressText\>
+          )}
+        {typeof submittedValues.transcript \=== 'object' &&
+          submittedValues.transcript.size && (
+            <IressText\>
+              <strong\>File Size:</strong\>
+              {(submittedValues.transcript.size / 1024).toFixed(2)} KB            </IressText\>
+          )}
+      </IressStack\>
+    </IressPanel\>
+  );
+};
+const Heading \= () \=> {
+  return (
+    <\>
+      <IressText element\="h1"\>Custom FormField Components</IressText\>
+      <IressText element\="p"\>
+        This demo showcases how to embed any custom component        (TranscriptTextBox) into IressFormField while leveraging its form        validation, error handling, and state management without additional        implementation. When building custom form components, avoid managing        error message state internally. This helps maintain the IressForm as the        single source of truth and ensures consistent, predictable UI behavior.      </IressText\>
+    </\>
+  );
+};
+export const CustomFormFieldComponents \= () \=> {
+  const \[submittedValues, setSubmittedValues\] \=
+    useState<TranscriptFormValues | null\>(null);
+  const allowedExtensions \= \['txt'\];
+  const maxSizeInMB \= 0.1;
+  const handleSubmit \= (data: TranscriptFormValues) \=> {
+    setSubmittedValues(data);
+    console.log('Form submitted:', data);
+  };
+  return (
+    <\>
+      <Heading />
+      <IressForm<TranscriptFormValues>        mode="onChange"        onSubmit={handleSubmit}
+        defaultValues={{ transcript: { content: '', type: 'text' } }}
+      >        <IressStack gap\="md"\>
+          <IressFormField
+            label\="Transcript"
+            name\="transcript"
+            hint\="Upload or copy and paste transcript here"
+            render\={(controlledProps) \=> (
+              <TranscriptTextBox
+                {...controlledProps}
+                allowedExtensions\={allowedExtensions}
+                maxSizeInMB\={maxSizeInMB}
+              />
+            )}
+            rules\={{
+              required: 'Transcript is required',
+              validate: {
+                file: validateFile(allowedExtensions, maxSizeInMB),
+              },
+            }}
+          />
+          <IressButton type\="submit" mode\="primary"\>
+            Submit          </IressButton\>
+          <SubmittedValuesDisplay submittedValues\={submittedValues} />
+        </IressStack\>
+      </IressForm\>
+    </\>
+  );
+};
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| actions | 
+object
+
+
+
+ | \- | Choose option...nonesubmitsave |
+| alert | 
+
+\-
+
+ | \- | Choose option...nonebasicAlert |
+| children | 
+
+array
+
+
+
+ | \- | Choose option...nonesimplesupportedControlsreadOnly |
+| Show React Hook Forms itemsReact Hook Forms | Show React Hook Forms items |