From b929b6ab02f484de4b2e067b7fdd08a2fef753dd Mon Sep 17 00:00:00 2001
From: Adam Kudrna <adam@adamkudrna.cz>
Date: Mon, 20 Oct 2025 16:42:24 +0200
Subject: [PATCH 1/6] Add the missing support of help texts to `InputGroup`
 (#663)

`InputGroup` now supports the `helpTexts` prop.

For `FileInputField`, `Select`, and `TextField`,
help text is not rendered within the `InputGroup`
context. The `helpTexts` prop of `InputGroup`
must be used instead.
---
 src/components/Button/README.md               |  2 +-
 .../FileInputField/FileInputField.jsx         | 10 ++-
 src/components/InputGroup/InputGroup.jsx      | 20 +++++
 .../InputGroup/InputGroup.module.scss         |  3 +-
 src/components/InputGroup/README.md           | 83 +++++++++++++++----
 .../InputGroup/__tests__/InputGroup.spec.tsx  |  4 +-
 src/components/SelectField/SelectField.jsx    |  5 +-
 src/components/TextField/TextField.jsx        |  5 +-
 8 files changed, 111 insertions(+), 21 deletions(-)

diff --git a/src/components/Button/README.md b/src/components/Button/README.md
index be732e6a7..838659b30 100644
--- a/src/components/Button/README.md
+++ b/src/components/Button/README.md
@@ -28,7 +28,7 @@ See [API](#api) for all available options.
 - **Don't overwhelm your UI** with too many high-emphasis actions. There should
     always be one but chances are that having more of them is not necessary.
 
-- Ensure the **button action is well recognazible** across your target audience.
+- Ensure the **button action is well recognizable** across your target audience.
     This is especially important when using the button [with an icon only](#icon-buttons).
 
 ## Priorities
diff --git a/src/components/FileInputField/FileInputField.jsx b/src/components/FileInputField/FileInputField.jsx
index 3d718308b..ee58187fb 100644
--- a/src/components/FileInputField/FileInputField.jsx
+++ b/src/components/FileInputField/FileInputField.jsx
@@ -223,7 +223,7 @@ export const FileInputField = React.forwardRef((props, ref) => {
             </Text>
           </button>
         </div>
-        {helpText && (
+        {(helpText && !inputGroupContext) && (
           <div
             className={styles.helpText}
             id={`${id}__helpText`}
@@ -231,7 +231,7 @@ export const FileInputField = React.forwardRef((props, ref) => {
             {helpText}
           </div>
         )}
-        {validationText && (
+        {(validationText && !inputGroupContext) && (
           <div
             className={styles.validationText}
             id={`${id}__validationText`}
@@ -268,6 +268,9 @@ FileInputField.propTypes = {
   fullWidth: PropTypes.bool,
   /**
    * Optional help text.
+   *
+   * Help text is never rendered when the component is placed into `InputGroup`. Instead, the `InputGroup`
+   * component itself renders all help texts of its nested components.
    */
   helpText: PropTypes.node,
   /**
@@ -321,6 +324,9 @@ FileInputField.propTypes = {
   validationState: PropTypes.oneOf(['invalid', 'valid', 'warning']),
   /**
    * Validation message to be displayed.
+   *
+   * Validation text is never rendered when the component is placed into `InputGroup`. Instead, the `InputGroup`
+   * component itself renders all validation texts of its nested components.
    */
   validationText: PropTypes.node,
 };
diff --git a/src/components/InputGroup/InputGroup.jsx b/src/components/InputGroup/InputGroup.jsx
index cb9c93126..7453472f8 100644
--- a/src/components/InputGroup/InputGroup.jsx
+++ b/src/components/InputGroup/InputGroup.jsx
@@ -18,6 +18,7 @@ import styles from './InputGroup.module.scss';
 export const InputGroup = ({
   children,
   disabled,
+  helpTexts,
   id,
   isLabelVisible,
   label,
@@ -89,6 +90,20 @@ export const InputGroup = ({
             {children}
           </InputGroupContext.Provider>
         </div>
+        {helpTexts && (
+          <ul
+            className={styles.helpText}
+            id={id && `${id}__helpTexts`}
+          >
+            {helpTexts.map((helpText) => (
+              <li key={helpText}>
+                <Text blockLevel>
+                  {helpText}
+                </Text>
+              </li>
+            ))}
+          </ul>
+        )}
         {validationTexts && (
           <ul
             className={styles.validationText}
@@ -111,6 +126,7 @@ export const InputGroup = ({
 InputGroup.defaultProps = {
   children: undefined,
   disabled: false,
+  helpTexts: null,
   id: undefined,
   isLabelVisible: true,
   layout: 'vertical',
@@ -133,6 +149,10 @@ InputGroup.propTypes = {
    * If `true`, the whole input group with all nested inputs and buttons will be disabled.
    */
   disabled: PropTypes.bool,
+  /**
+   * An array of help texts to be displayed.
+   */
+  helpTexts: PropTypes.node,
   /**
    * ID of the root HTML element.
    *
diff --git a/src/components/InputGroup/InputGroup.module.scss b/src/components/InputGroup/InputGroup.module.scss
index 0751322d9..5911714f6 100644
--- a/src/components/InputGroup/InputGroup.module.scss
+++ b/src/components/InputGroup/InputGroup.module.scss
@@ -1,4 +1,4 @@
-// 1. The class name is intentionally singular because it's targeted by other mixins too.
+// 1. The class names are intentionally singular because they are also targeted by other mixins.
 // 2. Use a block-level display mode to prevent extra white space below grouped inputs in Safari.
 // 3. Let wide input groups honor the minimum input width and overflow horizontally without wrapping and distorting
 //    the inputs.
@@ -39,6 +39,7 @@
     }
 
     // 1.
+    .helpText,
     .validationText {
         @include reset.list();
         @include foundation.help-text();
diff --git a/src/components/InputGroup/README.md b/src/components/InputGroup/README.md
index 911034599..27f11f061 100644
--- a/src/components/InputGroup/README.md
+++ b/src/components/InputGroup/README.md
@@ -60,13 +60,14 @@ See [API](#api) for all available options.
   Make sure your inputs fit their container, especially on small screens.
 
 - In the background, InputGroup uses the [`fieldset`][fieldset] element. Not
-  only it improves the [accessibility] of the group, it also allows you to make
-  use of its built-in features like disabling all nested inputs or pairing the
-  group with a form outside. Consult [the MDN docs][fieldset] to learn more.
+  only does it improve the [accessibility] of the group, it also allows you to
+  make use of its built-in features like disabling all nested inputs or pairing
+  the group with a form outside. Consult [the MDN docs][fieldset] to learn more.
 
 - InputGroup currently **supports grouping of**
   [TextField](/components/TextField), [SelectField](/components/SelectField),
-  and [Button](/components/Button) components.
+  [FileInputField](/components/FileInputField), and [Button](/components/Button)
+  components.
 
 - To group [Buttons](/components/Button) only, use the
   [ButtonGroup](/components/ButtonGroup) component which is designed
@@ -104,7 +105,7 @@ You can set the `size` property directly on InputGroup to be shared for all
 fields and buttons inside the group. This property is then passed over to
 individual elements. At the same time, it **cannot be overridden** on the
 fields' or buttons' level. While technically possible, from the design point of
-view it's undesirable to group elements of totally different types or sizes.
+view, it's undesirable to group elements of totally different types or sizes.
 
 ## Invisible Label
 
@@ -136,9 +137,9 @@ the input.
 
 ## Horizontal layout
 
-The default vertical layout is very easy to use and work with. However, there
-are situations where horizontal layout suits better — and that's why React UI
-supports this kind of layout as well.
+The default vertical layout is straightforward to use and work with. However,
+there are situations where horizontal layout suits better — and that's why
+React UI supports this kind of layout as well.
 
 ```docoff-react-preview
 <InputGroup
@@ -150,6 +151,57 @@ supports this kind of layout as well.
 </InputGroup>
 ```
 
+## Help Text
+
+You may provide one or more additional help texts to clarify how the input group
+should be filled.
+
+These messages are not semantically tied to the `children` elements, the
+connection should be expressed in textual form in the actual message.
+
+⚠️ Help texts passed to input elements' `helpText` prop are ignored within
+InputGroup.
+
+```docoff-react-preview
+React.createElement(() => {
+  const [fruit, setFruit] = React.useState('apple');
+  const options = [
+    {
+      label: 'Apple',
+      value: 'apple',
+    },
+    {
+      label: 'Pear',
+      value: 'pear',
+    },
+    {
+      label: 'Cherry',
+      value: 'cherry',
+    },
+  ];
+  return (
+    <InputGroup
+      label="Your favourite fruit"
+      helpTexts={[
+        "Choose one or more kinds of fruit to feel happy.",
+      ]}
+    >
+      <SelectField
+        label="Your favourite fruit"
+        onChange={(e) => setFruit(e.target.value)}
+        options={options}
+        value={fruit}
+      />
+      <TextField
+        label="Variety"
+        placeholder="Eg. Golden delicious"
+      />
+      <Button label="Submit" />
+    </InputGroup>
+  );
+})
+```
+
 ## States
 
 ### Disabled State
@@ -169,12 +221,15 @@ Validation states visually present the result of validation of the grouped
 inputs. Input group's validation state is taken from its child inputs. You
 should always **provide validation messages for states other than valid**
 directly through `validationTexts` prop so users know what happened and what
-action they should take or what options they have. These messages are not
-semantically tied to the `children` elements, the connection should be expressed
-in textual form in the actual message. The individual `children` elements must
-not show any `validationText`, they only show their respective `validationState`.
-Validation messages passed to input elements' `validationText` prop will be
-ignored.
+action they should take or what options they have.
+
+These messages are not semantically tied to the `children` elements, the
+connection should be expressed in textual form in the actual message. The
+individual `children` elements must not show any `validationText`, they only
+show their respective `validationState`.
+
+⚠️ Validation messages passed to input elements' `validationText` prop are
+ignored within InputGroup.
 
 👉 While there is a `required` property to visually denote the whole input group
 is required, there is no functional effect as there is no such HTML attribute
diff --git a/src/components/InputGroup/__tests__/InputGroup.spec.tsx b/src/components/InputGroup/__tests__/InputGroup.spec.tsx
index 51578615b..b0f8e529d 100644
--- a/src/components/InputGroup/__tests__/InputGroup.spec.tsx
+++ b/src/components/InputGroup/__tests__/InputGroup.spec.tsx
@@ -66,6 +66,7 @@ test.describe('InputGroup', () => {
             id={id}
             isLabelVisible
             label={label}
+            helpTexts={['Help text.']}
             validationTexts={['Validation text.']}
           />,
         );
@@ -74,7 +75,8 @@ test.describe('InputGroup', () => {
         await expect(component.getByText(label).first()).toHaveAttribute('id', `${id}__label`);
         await expect(component.getByText(label).last()).toHaveAttribute('id', `${id}__displayLabel`);
         await expect(component.locator(`div[id=${id}__group]`)).not.toBeEmpty();
-        await expect(component.getByRole('list')).toHaveAttribute('id', `${id}__validationTexts`);
+        await expect(component.getByRole('list').first()).toHaveAttribute('id', `${id}__helpTexts`);
+        await expect(component.getByRole('list').last()).toHaveAttribute('id', `${id}__validationTexts`);
       });
     });
 
diff --git a/src/components/SelectField/SelectField.jsx b/src/components/SelectField/SelectField.jsx
index 79e2d4ab5..1aab94fda 100644
--- a/src/components/SelectField/SelectField.jsx
+++ b/src/components/SelectField/SelectField.jsx
@@ -109,7 +109,7 @@ export const SelectField = React.forwardRef((props, ref) => {
             <div className={styles.bottomLine} />
           )}
         </div>
-        {helpText && (
+        {(helpText && !inputGroupContext) && (
           <div
             className={styles.helpText}
             id={id && `${id}__helpText`}
@@ -172,6 +172,9 @@ SelectField.propTypes = {
    *
    * If `key` in the option definition object is set,
    * then `option.key` is used instead of `option.value` in place of `<VALUE>`.
+   *
+   * Help text is never rendered when the component is placed into `InputGroup`. Instead, the `InputGroup`
+   * component itself renders all help texts of its nested components.
    */
   id: PropTypes.string,
   /**
diff --git a/src/components/TextField/TextField.jsx b/src/components/TextField/TextField.jsx
index 04cb375a3..08fae9a2e 100644
--- a/src/components/TextField/TextField.jsx
+++ b/src/components/TextField/TextField.jsx
@@ -84,7 +84,7 @@ export const TextField = React.forwardRef((props, ref) => {
             <div className={styles.bottomLine} />
           )}
         </div>
-        {helpText && (
+        {(helpText && !inputGroupContext) && (
           <div
             className={styles.helpText}
             id={id && `${id}__helpText`}
@@ -132,6 +132,9 @@ TextField.propTypes = {
   fullWidth: PropTypes.bool,
   /**
    * Optional help text.
+   *
+   * Help text is never rendered when the component is placed into `InputGroup`. Instead, the `InputGroup`
+   * component itself renders all help texts of its nested components.
    */
   helpText: PropTypes.node,
   /**

From 4bb63473c93ddadd04cf191001727c6c9a8b8ad0 Mon Sep 17 00:00:00 2001
From: Adam Kudrna <adam@adamkudrna.cz>
Date: Mon, 20 Oct 2025 17:13:11 +0200
Subject: [PATCH 2/6] fixup! Add the missing support of help texts to
 `InputGroup` (#663)

---
 src/components/FileInputField/FileInputField.jsx | 8 ++++----
 src/components/SelectField/SelectField.jsx       | 8 ++++----
 src/components/TextField/TextField.jsx           | 8 ++++----
 3 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/src/components/FileInputField/FileInputField.jsx b/src/components/FileInputField/FileInputField.jsx
index ee58187fb..4d01ec1ee 100644
--- a/src/components/FileInputField/FileInputField.jsx
+++ b/src/components/FileInputField/FileInputField.jsx
@@ -269,8 +269,8 @@ FileInputField.propTypes = {
   /**
    * Optional help text.
    *
-   * Help text is never rendered when the component is placed into `InputGroup`. Instead, the `InputGroup`
-   * component itself renders all help texts of its nested components.
+   * Help text is never rendered when the component is placed into `InputGroup`.
+   * If a help text is needed, it must be defined on the `InputGroup` component instead.
    */
   helpText: PropTypes.node,
   /**
@@ -325,8 +325,8 @@ FileInputField.propTypes = {
   /**
    * Validation message to be displayed.
    *
-   * Validation text is never rendered when the component is placed into `InputGroup`. Instead, the `InputGroup`
-   * component itself renders all validation texts of its nested components.
+   * Validation text is never rendered when the component is placed into `InputGroup`.
+   * If a validation text is needed, it must be defined on the `InputGroup` component instead.
    */
   validationText: PropTypes.node,
 };
diff --git a/src/components/SelectField/SelectField.jsx b/src/components/SelectField/SelectField.jsx
index 1aab94fda..aeb447d24 100644
--- a/src/components/SelectField/SelectField.jsx
+++ b/src/components/SelectField/SelectField.jsx
@@ -173,8 +173,8 @@ SelectField.propTypes = {
    * If `key` in the option definition object is set,
    * then `option.key` is used instead of `option.value` in place of `<VALUE>`.
    *
-   * Help text is never rendered when the component is placed into `InputGroup`. Instead, the `InputGroup`
-   * component itself renders all help texts of its nested components.
+   * Help text is never rendered when the component is placed into `InputGroup`.
+   * If a help text is needed, it must be defined on the `InputGroup` component instead.
    */
   id: PropTypes.string,
   /**
@@ -252,8 +252,8 @@ SelectField.propTypes = {
   /**
    * Validation message to be displayed.
    *
-   * Validation text is never rendered when the component is placed into `InputGroup`. Instead, the `InputGroup`
-   * component itself renders all validation texts of its nested components.
+   * Validation text is never rendered when the component is placed into `InputGroup`.
+   * If a help text is needed, it must be defined on the `InputGroup` component instead.
    */
   validationText: PropTypes.node,
   /**
diff --git a/src/components/TextField/TextField.jsx b/src/components/TextField/TextField.jsx
index 08fae9a2e..a454ff6e8 100644
--- a/src/components/TextField/TextField.jsx
+++ b/src/components/TextField/TextField.jsx
@@ -133,8 +133,8 @@ TextField.propTypes = {
   /**
    * Optional help text.
    *
-   * Help text is never rendered when the component is placed into `InputGroup`. Instead, the `InputGroup`
-   * component itself renders all help texts of its nested components.
+   * Help text is never rendered when the component is placed into `InputGroup`.
+   * If a help text is needed, it must be defined on the `InputGroup` component instead.
    */
   helpText: PropTypes.node,
   /**
@@ -188,8 +188,8 @@ TextField.propTypes = {
   /**
    * Validation message to be displayed.
    *
-   * Validation text is never rendered when the component is placed into `InputGroup`. Instead, the `InputGroup`
-   * component itself renders all validation texts of its nested components.
+   * Validation text is never rendered when the component is placed into `InputGroup`.
+   * If a help text is needed, it must be defined on the `InputGroup` component instead.
    */
   validationText: PropTypes.node,
   /**

From 5a836f6879728c0ee44c66b943b68888e63f91bb Mon Sep 17 00:00:00 2001
From: Adam Kudrna <adam@adamkudrna.cz>
Date: Mon, 20 Oct 2025 17:15:19 +0200
Subject: [PATCH 3/6] fixup! fixup! Add the missing support of help texts to
 `InputGroup` (#663)

---
 src/components/InputGroup/__tests__/InputGroup.spec.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/components/InputGroup/__tests__/InputGroup.spec.tsx b/src/components/InputGroup/__tests__/InputGroup.spec.tsx
index b0f8e529d..bc9d59b2d 100644
--- a/src/components/InputGroup/__tests__/InputGroup.spec.tsx
+++ b/src/components/InputGroup/__tests__/InputGroup.spec.tsx
@@ -63,10 +63,10 @@ test.describe('InputGroup', () => {
 
         const component = await mount(
           <InputGroupForTest
+            helpTexts={['Help text.']}
             id={id}
             isLabelVisible
             label={label}
-            helpTexts={['Help text.']}
             validationTexts={['Validation text.']}
           />,
         );

From 0274478b8f1e20c4a695f0874b23bb33a550cf93 Mon Sep 17 00:00:00 2001
From: Adam Kudrna <adam@adamkudrna.cz>
Date: Mon, 20 Oct 2025 17:19:55 +0200
Subject: [PATCH 4/6] fixup! fixup! fixup! Add the missing support of help
 texts to `InputGroup` (#663)

---
 src/components/InputGroup/InputGroup.jsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/components/InputGroup/InputGroup.jsx b/src/components/InputGroup/InputGroup.jsx
index 7453472f8..f3c0ea429 100644
--- a/src/components/InputGroup/InputGroup.jsx
+++ b/src/components/InputGroup/InputGroup.jsx
@@ -152,7 +152,7 @@ InputGroup.propTypes = {
   /**
    * An array of help texts to be displayed.
    */
-  helpTexts: PropTypes.node,
+  helpTexts: PropTypes.arrayOf(PropTypes.node),
   /**
    * ID of the root HTML element.
    *
@@ -191,7 +191,7 @@ InputGroup.propTypes = {
   /**
    * An array of validation messages to be displayed.
    */
-  validationTexts: PropTypes.node,
+  validationTexts: PropTypes.arrayOf(PropTypes.node),
 };
 
 export const InputGroupWithGlobalProps = withGlobalProps(InputGroup, 'InputGroup');

From 9c309ccf773c75a5f399de06feed2b8fed64963f Mon Sep 17 00:00:00 2001
From: Adam Kudrna <adam@adamkudrna.cz>
Date: Mon, 20 Oct 2025 17:23:24 +0200
Subject: [PATCH 5/6] fixup! fixup! fixup! fixup! Add the missing support of
 help texts to `InputGroup` (#663)

---
 src/components/SelectField/SelectField.jsx | 8 ++++----
 src/components/TextField/TextField.jsx     | 2 +-
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/components/SelectField/SelectField.jsx b/src/components/SelectField/SelectField.jsx
index aeb447d24..d8f3865b8 100644
--- a/src/components/SelectField/SelectField.jsx
+++ b/src/components/SelectField/SelectField.jsx
@@ -156,6 +156,9 @@ SelectField.propTypes = {
   fullWidth: PropTypes.bool,
   /**
    * Optional help text.
+   *
+   * Help text is never rendered when the component is placed into `InputGroup`.
+   * If a help text is needed, it must be defined on the `InputGroup` component instead.
    */
   helpText: PropTypes.node,
   /**
@@ -172,9 +175,6 @@ SelectField.propTypes = {
    *
    * If `key` in the option definition object is set,
    * then `option.key` is used instead of `option.value` in place of `<VALUE>`.
-   *
-   * Help text is never rendered when the component is placed into `InputGroup`.
-   * If a help text is needed, it must be defined on the `InputGroup` component instead.
    */
   id: PropTypes.string,
   /**
@@ -253,7 +253,7 @@ SelectField.propTypes = {
    * Validation message to be displayed.
    *
    * Validation text is never rendered when the component is placed into `InputGroup`.
-   * If a help text is needed, it must be defined on the `InputGroup` component instead.
+   * If a validation text is needed, it must be defined on the `InputGroup` component instead.
    */
   validationText: PropTypes.node,
   /**
diff --git a/src/components/TextField/TextField.jsx b/src/components/TextField/TextField.jsx
index a454ff6e8..2609011f1 100644
--- a/src/components/TextField/TextField.jsx
+++ b/src/components/TextField/TextField.jsx
@@ -189,7 +189,7 @@ TextField.propTypes = {
    * Validation message to be displayed.
    *
    * Validation text is never rendered when the component is placed into `InputGroup`.
-   * If a help text is needed, it must be defined on the `InputGroup` component instead.
+   * If a validation text is needed, it must be defined on the `InputGroup` component instead.
    */
   validationText: PropTypes.node,
   /**

From 1622cf1d89dc8a0c252337f95ac95aea051159d2 Mon Sep 17 00:00:00 2001
From: Adam Kudrna <adam@adamkudrna.cz>
Date: Wed, 22 Oct 2025 16:38:49 +0200
Subject: [PATCH 6/6] fixup! fixup! fixup! fixup! fixup! Add the missing
 support of help texts to `InputGroup` (#663)

---
 src/components/InputGroup/InputGroup.jsx | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/components/InputGroup/InputGroup.jsx b/src/components/InputGroup/InputGroup.jsx
index f3c0ea429..b65cb3a3d 100644
--- a/src/components/InputGroup/InputGroup.jsx
+++ b/src/components/InputGroup/InputGroup.jsx
@@ -90,7 +90,7 @@ export const InputGroup = ({
             {children}
           </InputGroupContext.Provider>
         </div>
-        {helpTexts && (
+        {helpTexts && helpTexts.length > 0 && (
           <ul
             className={styles.helpText}
             id={id && `${id}__helpTexts`}
@@ -104,7 +104,7 @@ export const InputGroup = ({
             ))}
           </ul>
         )}
-        {validationTexts && (
+        {validationTexts && validationTexts.length > 0 && (
           <ul
             className={styles.validationText}
             id={id && `${id}__validationTexts`}
@@ -126,7 +126,7 @@ export const InputGroup = ({
 InputGroup.defaultProps = {
   children: undefined,
   disabled: false,
-  helpTexts: null,
+  helpTexts: undefined,
   id: undefined,
   isLabelVisible: true,
   layout: 'vertical',