From 607c64906dce77ee763425abdc2f9463947f8de0 Mon Sep 17 00:00:00 2001
From: "tom.davies" <thomas.davies@sage.com>
Date: Wed, 11 Oct 2023 13:23:59 +0100
Subject: [PATCH] fix(textarea, textbox): ensure inputHint and labelHelp props
 do not render two seperate DOM elements

currently when consumers are opted into the new validation designs two seperate DOM elements are
rendered which both act as hints for the input. This has been addressed by only rendering either the
`inputHint` or `labelHelp` props in the same element, with `inputHint` taking priority
---
 src/components/decimal/decimal.stories.mdx    |  6 +++++
 src/components/decimal/decimal.stories.tsx    |  5 ++++
 .../grouped-character.stories.mdx             |  9 ++++++++
 .../grouped-character.stories.tsx             | 19 +++++++++++++++
 src/components/number/number.stories.mdx      |  9 ++++++++
 src/components/number/number.stories.tsx      |  4 ++++
 src/components/password/password.stories.mdx  |  3 +++
 src/components/password/password.stories.tsx  |  6 ++---
 .../textarea/textarea.component.tsx           | 22 ++++++++----------
 src/components/textarea/textarea.spec.tsx     | 23 +++++++++++++------
 src/components/textarea/textarea.stories.mdx  |  9 ++++++++
 src/components/textarea/textarea.stories.tsx  |  6 +++++
 src/components/textbox/textbox.component.tsx  | 18 +++++++--------
 src/components/textbox/textbox.spec.tsx       | 15 +++++++++---
 src/components/textbox/textbox.stories.mdx    |  9 ++++++++
 src/components/textbox/textbox.stories.tsx    | 14 +++++++++--
 src/components/textbox/textbox.style.ts       | 13 ++---------
 17 files changed, 142 insertions(+), 48 deletions(-)

diff --git a/src/components/decimal/decimal.stories.mdx b/src/components/decimal/decimal.stories.mdx
index 663139b474..f00d766221 100644
--- a/src/components/decimal/decimal.stories.mdx
+++ b/src/components/decimal/decimal.stories.mdx
@@ -105,6 +105,12 @@ import Decimal from "carbon-react/lib/components/decimal";
   <Story name="with fieldHelp" story={stories.WithFieldHelp} />
 </Canvas>
 
+### With inputHint
+
+<Canvas>
+  <Story name="with inputHint" story={stories.WithInputHint} />
+</Canvas>
+
 ### With labelHelp
 
 <Canvas>
diff --git a/src/components/decimal/decimal.stories.tsx b/src/components/decimal/decimal.stories.tsx
index 2af4d730ec..c69921fe76 100644
--- a/src/components/decimal/decimal.stories.tsx
+++ b/src/components/decimal/decimal.stories.tsx
@@ -108,6 +108,11 @@ WithLabelHelp.args = {
   helpAriaLabel: "Help",
 };
 
+export const WithInputHint = DefaultStory.bind({});
+WithInputHint.args = {
+  inputHint: "Hint text (optional).",
+};
+
 export const Required = DefaultStory.bind({});
 Required.args = { required: true };
 
diff --git a/src/components/grouped-character/grouped-character.stories.mdx b/src/components/grouped-character/grouped-character.stories.mdx
index bc16847f93..a0a00d5bb4 100644
--- a/src/components/grouped-character/grouped-character.stories.mdx
+++ b/src/components/grouped-character/grouped-character.stories.mdx
@@ -114,6 +114,15 @@ import GroupedCharacter from "carbon-react/lib/components/grouped-character";
   <Story story={stories.FieldHelp} name="with fieldHelp" />
 </Canvas>
 
+### with inputHint
+
+When the `inputHint` prop is passed, please use a full stop `.` at the end. This forces a pause 
+before any other announcements, this well help screen reader users understand the hint fully.
+
+<Canvas>
+  <Story name="with inputHint" story={stories.InputHint} />
+</Canvas>
+
 ### With labelHelp
 
 <Canvas>
diff --git a/src/components/grouped-character/grouped-character.stories.tsx b/src/components/grouped-character/grouped-character.stories.tsx
index 4d90cd0b14..1e30987d6c 100644
--- a/src/components/grouped-character/grouped-character.stories.tsx
+++ b/src/components/grouped-character/grouped-character.stories.tsx
@@ -149,6 +149,25 @@ export const FieldHelp = () => {
   );
 };
 
+export const InputHint = () => {
+  const [state, setState] = useState("1231231");
+
+  const setValue = ({ target }: CustomEvent) => {
+    setState(target.value.rawValue);
+  };
+
+  return (
+    <GroupedCharacter
+      label="GroupedCharacter"
+      value={state}
+      onChange={setValue}
+      groups={[2, 2, 3]}
+      separator="-"
+      inputHint="Hint text (optional)."
+    />
+  );
+};
+
 export const LabelHelp = () => {
   const [state, setState] = useState("1231231");
 
diff --git a/src/components/number/number.stories.mdx b/src/components/number/number.stories.mdx
index 0390d8ec12..345aa62fb0 100644
--- a/src/components/number/number.stories.mdx
+++ b/src/components/number/number.stories.mdx
@@ -88,6 +88,15 @@ import Number from "carbon-react/lib/components/number";
   <Story name="with fieldHelp" story={stories.WithFieldHelp} />
 </Canvas>
 
+### with inputHint
+
+When the `inputHint` prop is passed, please use a full stop `.` at the end. This forces a pause 
+before any other announcements, this well help screen reader users understand the hint fully.
+
+<Canvas>
+  <Story name="with inputHint" story={stories.WithInputHint} />
+</Canvas>
+
 ### With labelHelp
 
 <Canvas>
diff --git a/src/components/number/number.stories.tsx b/src/components/number/number.stories.tsx
index edd4528db2..6aaf1a98f8 100644
--- a/src/components/number/number.stories.tsx
+++ b/src/components/number/number.stories.tsx
@@ -86,6 +86,10 @@ export const WithFieldHelp: ComponentStory<typeof Number> = () => (
   <Number label="Number" value="123456" fieldHelp="Help" />
 );
 
+export const WithInputHint: ComponentStory<typeof Number> = () => (
+  <Number label="Number" value="123456" inputHint="Hint text (optional)." />
+);
+
 export const WithLabelHelp: ComponentStory<typeof Number> = () => (
   <Number label="Number" value="123456" labelHelp="Help" helpAriaLabel="Help" />
 );
diff --git a/src/components/password/password.stories.mdx b/src/components/password/password.stories.mdx
index b8d8dede57..1f2d73e34a 100644
--- a/src/components/password/password.stories.mdx
+++ b/src/components/password/password.stories.mdx
@@ -61,6 +61,9 @@ the input type will not be able to be changed to `text`. To be used primarily to
 
 ### with inputHint
 
+When the `inputHint` prop is passed, please use a full stop `.` at the end. This forces a pause 
+before any other announcements, this well help screen reader users understand the hint fully.
+
 <Canvas>
   <Story name="with inputHint" story={stories.InputHint} />
 </Canvas>
diff --git a/src/components/password/password.stories.tsx b/src/components/password/password.stories.tsx
index d32e2c149f..d83e77ad24 100644
--- a/src/components/password/password.stories.tsx
+++ b/src/components/password/password.stories.tsx
@@ -39,7 +39,7 @@ export const InputHint = () => {
 
   return (
     <Password
-      inputHint="Please enter a password with at least 8 characters"
+      inputHint="Hint text (optional)."
       label="Password"
       value={state}
       onChange={setValue}
@@ -402,7 +402,7 @@ export const NewDesignsValidation = () => {
                 label={`${size} - ${validationType}`}
                 value={state}
                 onChange={setValue}
-                labelHelp="Hint text (optional)"
+                inputHint="Hint text (optional)"
                 size={size}
                 {...{ [validationType]: "Message" }}
               />
@@ -411,7 +411,7 @@ export const NewDesignsValidation = () => {
                 label={`readOnly - ${size} - ${validationType}`}
                 value="Password"
                 size={size}
-                labelHelp="Hint text (optional)"
+                inputHint="Hint text (optional)."
                 readOnly
                 {...{ [validationType]: "Message" }}
               />
diff --git a/src/components/textarea/textarea.component.tsx b/src/components/textarea/textarea.component.tsx
index f440061a95..9f1caef4e5 100644
--- a/src/components/textarea/textarea.component.tsx
+++ b/src/components/textarea/textarea.component.tsx
@@ -15,11 +15,7 @@ import StyledTextarea, { MIN_HEIGHT } from "./textarea.style";
 import { TooltipProvider } from "../../__internal__/tooltip-provider";
 import useInputAccessibility from "../../hooks/__internal__/useInputAccessibility";
 import { NewValidationContext } from "../carbon-provider/carbon-provider.component";
-import {
-  ErrorBorder,
-  StyledHintText,
-  StyledInputHint,
-} from "../textbox/textbox.style";
+import { ErrorBorder, StyledHintText } from "../textbox/textbox.style";
 import ValidationMessage from "../../__internal__/validation-message";
 import Box from "../box";
 import Logger from "../../__internal__/utils/logger";
@@ -84,7 +80,10 @@ export interface TextareaProps
   label?: string;
   /** Inline label alignment */
   labelAlign?: "left" | "right";
-  /** Text applied to label help tooltip */
+  /** [Legacy] Text applied to label help tooltip. When opted into new design validations
+   * it will render as a hint above the input, unless an `inputHint`
+   * prop is also passed
+   */
   labelHelp?: React.ReactNode;
   /** When true, label is placed in line an input */
   labelInline?: boolean;
@@ -382,13 +381,10 @@ export const Textarea = React.forwardRef(
               adaptiveLabelBreakpoint={adaptiveLabelBreakpoint}
               validationRedesignOptIn={validationRedesignOptIn}
             >
-              {inputHint ? (
-                <StyledInputHint id={inputHintId} data-element="input-hint">
-                  {inputHint}
-                </StyledInputHint>
-              ) : null}
-              {validationRedesignOptIn && labelHelp && (
-                <StyledHintText>{labelHelp}</StyledHintText>
+              {(inputHint || (labelHelp && validationRedesignOptIn)) && (
+                <StyledHintText id={inputHintId} data-element="input-hint">
+                  {inputHint || labelHelp}
+                </StyledHintText>
               )}
               {validationRedesignOptIn ? (
                 <Box position="relative">
diff --git a/src/components/textarea/textarea.spec.tsx b/src/components/textarea/textarea.spec.tsx
index a0c919f5cf..29d798a80a 100644
--- a/src/components/textarea/textarea.spec.tsx
+++ b/src/components/textarea/textarea.spec.tsx
@@ -21,11 +21,7 @@ import { StyledLabelContainer } from "../../__internal__/label/label.style";
 import Tooltip from "../tooltip";
 import StyledHelp from "../help/help.style";
 import CarbonProvider from "../carbon-provider/carbon-provider.component";
-import {
-  ErrorBorder,
-  StyledHintText,
-  StyledInputHint,
-} from "../textbox/textbox.style";
+import { ErrorBorder, StyledHintText } from "../textbox/textbox.style";
 import StyledValidationMessage from "../../__internal__/validation-message/validation-message.style";
 import StyledTextarea from "./textarea.style";
 import Logger from "../../__internal__/utils/logger";
@@ -257,12 +253,12 @@ describe("Textarea", () => {
         describe("and inputHint props are present", () => {
           it("renders a character counter hint", () => {
             wrapper = mount(<Textarea value="test string" inputHint="foo" />);
-            expect(wrapper.find(StyledInputHint).text()).toBe("foo");
+            expect(wrapper.find(StyledHintText).text()).toBe("foo");
           });
 
           it("assigns a character counter hint via guid", () => {
             wrapper = mount(<Textarea value="test string" inputHint="bar" />);
-            expect(wrapper.find(StyledInputHint).prop("id")).toBe(mockedGuid);
+            expect(wrapper.find(StyledHintText).prop("id")).toBe(mockedGuid);
           });
 
           it("should render a valid 'aria-describedby' on input", () => {
@@ -271,6 +267,19 @@ describe("Textarea", () => {
               mockedGuid
             );
           });
+
+          it("rendered text should be provided via inputHint, when labelHelp is also passed", () => {
+            wrapper = mount(
+              <CarbonProvider validationRedesignOptIn>
+                <Textarea
+                  labelHelp="labelHelp"
+                  inputHint="inputHint"
+                  error="foo"
+                />
+              </CarbonProvider>
+            );
+            expect(wrapper.find(StyledHintText).text()).toBe("inputHint");
+          });
         });
 
         describe("and fieldHelp props are present", () => {
diff --git a/src/components/textarea/textarea.stories.mdx b/src/components/textarea/textarea.stories.mdx
index b2552152ac..e760779c21 100644
--- a/src/components/textarea/textarea.stories.mdx
+++ b/src/components/textarea/textarea.stories.mdx
@@ -134,6 +134,15 @@ Include the formatted number count wherever makes sense for the language you're
   <Story name="with fieldHelp" story={stories.FieldHelpStory} />
 </Canvas>
 
+### With inputHint
+
+When the `inputHint` prop is passed, please use a full stop `.` at the end. This forces a pause 
+before any other announcements, this well help screen reader users understand the hint fully.
+
+<Canvas>
+  <Story name="with inputHint" story={stories.InputHintStory} />
+</Canvas>
+
 ### With labelHelp
 
 <Canvas>
diff --git a/src/components/textarea/textarea.stories.tsx b/src/components/textarea/textarea.stories.tsx
index bb3b65d3d9..6fd243443a 100644
--- a/src/components/textarea/textarea.stories.tsx
+++ b/src/components/textarea/textarea.stories.tsx
@@ -122,6 +122,10 @@ export const MaxWidthStory: ComponentStory<typeof Textarea> = () => {
   return <Textarea label="Textarea" maxWidth="70%" />;
 };
 
+export const InputHintStory: ComponentStory<typeof Textarea> = () => {
+  return <Textarea label="Textarea" inputHint="Hint text (optional)." />;
+};
+
 export const LabelHelpStory: ComponentStory<typeof Textarea> = () => {
   return <Textarea label="Textarea" labelHelp="Help" helpAriaLabel="Help" />;
 };
@@ -231,11 +235,13 @@ export const NewDesignValidationStory: ComponentStory<typeof Textarea> = () => {
         >
           <Textarea
             label={`${validationType}`}
+            inputHint="Hint text (optional)."
             {...{ [validationType]: "Message" }}
             m={4}
           />
           <Textarea
             label={`readOnly - ${validationType}`}
+            inputHint="Hint text (optional)."
             readOnly
             {...{ [validationType]: "Message" }}
             m={4}
diff --git a/src/components/textbox/textbox.component.tsx b/src/components/textbox/textbox.component.tsx
index c2be4d911b..7b9d95d288 100644
--- a/src/components/textbox/textbox.component.tsx
+++ b/src/components/textbox/textbox.component.tsx
@@ -17,7 +17,7 @@ import StyledPrefix from "./__internal__/prefix.style";
 import { TooltipProvider } from "../../__internal__/tooltip-provider";
 import useCharacterCount from "../../hooks/__internal__/useCharacterCount";
 import useInputAccessibility from "../../hooks/__internal__/useInputAccessibility/useInputAccessibility";
-import { ErrorBorder, StyledInputHint, StyledHintText } from "./textbox.style";
+import { ErrorBorder, StyledHintText } from "./textbox.style";
 import ValidationMessage from "../../__internal__/validation-message";
 import { NewValidationContext } from "../carbon-provider/carbon-provider.component";
 import NumeralDateContext from "../numeral-date/numeral-date-context";
@@ -79,7 +79,10 @@ export interface CommonTextboxProps
   label?: string;
   /** Inline label alignment */
   labelAlign?: "left" | "right";
-  /** A message that the Help component will display */
+  /** [Legacy] Text applied to label help tooltip. When opted into new design validations
+   * it will render as a hint above the input, unless an `inputHint`
+   * prop is also passed
+   */
   labelHelp?: React.ReactNode;
   /** When true label is inline */
   labelInline?: boolean;
@@ -342,13 +345,10 @@ export const Textbox = React.forwardRef(
             validationRedesignOptIn={validationRedesignOptIn}
             {...filterStyledSystemMarginProps(props)}
           >
-            {inputHint ? (
-              <StyledInputHint id={inputHintId} data-element="input-hint">
-                {inputHint}
-              </StyledInputHint>
-            ) : null}
-            {validationRedesignOptIn && labelHelp && (
-              <StyledHintText>{labelHelp}</StyledHintText>
+            {(inputHint || (labelHelp && validationRedesignOptIn)) && (
+              <StyledHintText id={inputHintId} data-element="input-hint">
+                {inputHint || labelHelp}
+              </StyledHintText>
             )}
             {validationRedesignOptIn ? (
               <Box position="relative">
diff --git a/src/components/textbox/textbox.spec.tsx b/src/components/textbox/textbox.spec.tsx
index 15b373b4c4..6f91557ee4 100644
--- a/src/components/textbox/textbox.spec.tsx
+++ b/src/components/textbox/textbox.spec.tsx
@@ -21,7 +21,7 @@ import {
 import Tooltip from "../tooltip";
 import StyledHelp from "../help/help.style";
 import createGuid from "../../__internal__/utils/helpers/guid";
-import { ErrorBorder, StyledHintText, StyledInputHint } from "./textbox.style";
+import { ErrorBorder, StyledHintText } from "./textbox.style";
 import StyledValidationMessage from "../../__internal__/validation-message/validation-message.style";
 import CarbonProvider from "../carbon-provider/carbon-provider.component";
 import Logger from "../../__internal__/utils/logger";
@@ -403,12 +403,12 @@ describe("Textbox", () => {
   describe("and inputHint props are present", () => {
     it("renders a character counter hint", () => {
       const wrapper = mount(<Textbox value="test string" inputHint="foo" />);
-      expect(wrapper.find(StyledInputHint).text()).toBe("foo");
+      expect(wrapper.find(StyledHintText).text()).toBe("foo");
     });
 
     it("assigns a character counter hint via guid", () => {
       const wrapper = mount(<Textbox value="test string" inputHint="bar" />);
-      expect(wrapper.find(StyledInputHint).prop("id")).toBe(mockedGuid);
+      expect(wrapper.find(StyledHintText).prop("id")).toBe(mockedGuid);
     });
 
     it("should render a valid 'aria-describedby' on input", () => {
@@ -417,6 +417,15 @@ describe("Textbox", () => {
         mockedGuid
       );
     });
+
+    it("rendered text should be provided via inputHint, when labelHelp is also passed", () => {
+      const wrapper = mount(
+        <CarbonProvider validationRedesignOptIn>
+          <Textbox labelHelp="labelHelp" inputHint="inputHint" error="foo" />
+        </CarbonProvider>
+      );
+      expect(wrapper.find(StyledHintText).text()).toBe("inputHint");
+    });
   });
 
   describe("when maxWidth is passed", () => {
diff --git a/src/components/textbox/textbox.stories.mdx b/src/components/textbox/textbox.stories.mdx
index 2039c1f6d4..b47da1a9dc 100644
--- a/src/components/textbox/textbox.stories.mdx
+++ b/src/components/textbox/textbox.stories.mdx
@@ -135,6 +135,15 @@ Include the formatted number count wherever makes sense for the language you're
   <Story name="with fieldHelp" story={stories.WithFieldHelp} />
 </Canvas>
 
+### With inputHint
+
+When the `inputHint` prop is passed, please use a full stop `.` at the end. This forces a pause 
+before any other announcements, this well help screen reader users understand the hint fully.
+
+<Canvas>
+  <Story name="with inputHint" story={stories.WithInputHint} />
+</Canvas>
+
 ### With labelHelp
 
 <Canvas>
diff --git a/src/components/textbox/textbox.stories.tsx b/src/components/textbox/textbox.stories.tsx
index 74ce1d4b80..b6693336e6 100644
--- a/src/components/textbox/textbox.stories.tsx
+++ b/src/components/textbox/textbox.stories.tsx
@@ -153,6 +153,16 @@ export const WithFieldHelp: ComponentStory<typeof Textbox> = () => {
   return <Textbox label="Textbox" value="Textbox" fieldHelp="Help" />;
 };
 
+export const WithInputHint: ComponentStory<typeof Textbox> = () => {
+  return (
+    <Textbox
+      label="Textbox"
+      value="Textbox"
+      inputHint="Hint text (optional)."
+    />
+  );
+};
+
 export const WithLabelHelp: ComponentStory<typeof Textbox> = () => {
   return (
     <Textbox
@@ -271,7 +281,7 @@ export const NewDesignsValidation: ComponentStory<typeof Textbox> = () => {
                 m={4}
                 label={`${size} - ${validationType}`}
                 defaultValue="Textbox"
-                labelHelp="Hint text (optional)"
+                inputHint="Hint text (optional)."
                 size={size}
                 {...{ [validationType]: "Message" }}
               />
@@ -280,7 +290,7 @@ export const NewDesignsValidation: ComponentStory<typeof Textbox> = () => {
                 label={`readOnly - ${size} - ${validationType}`}
                 defaultValue="Textbox"
                 size={size}
-                labelHelp="Hint text (optional)"
+                inputHint="Hint text (optional)."
                 readOnly
                 {...{ [validationType]: "Message" }}
               />
diff --git a/src/components/textbox/textbox.style.ts b/src/components/textbox/textbox.style.ts
index c9a544b518..10c9ccfe08 100644
--- a/src/components/textbox/textbox.style.ts
+++ b/src/components/textbox/textbox.style.ts
@@ -15,24 +15,15 @@ const ErrorBorder = styled.span`
     `}
 `;
 
-const StyledInputHint = styled.p`
+const StyledHintText = styled.div`
   ::after {
     content: " ";
   }
 
-  display: block;
-  flex: 1;
-  margin-top: -3px;
-  margin-bottom: 8px;
-  color: var(--colorsUtilityYin055);
-  white-space: pre-wrap;
-`;
-
-const StyledHintText = styled.div`
   margin-top: 0px;
   margin-bottom: 8px;
   color: var(--colorsUtilityYin055);
   font-size: 14px;
 `;
 
-export { StyledHintText, ErrorBorder, StyledInputHint };
+export { StyledHintText, ErrorBorder };