feat(react): enable textarea to limit text input to set amount of words

.all-contributorsrc

@@ -1298,6 +1298,7 @@
         "code"
       ]
     },
+    {
       "login": "allisonishida",
       "name": "Allison Ishida",
       "avatar_url": "https://avatars.githubusercontent.com/u/22247062?v=4",
@@ -1332,6 +1333,33 @@
       "contributions": [
         "code"
       ]
+    },
+    {
+      "login": "matejoslav",
+      "name": "Matej Ocovsky",
+      "avatar_url": "https://avatars.githubusercontent.com/u/8973672?v=4",
+      "profile": "https://github.com/matejoslav",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "SamChinellato",
+      "name": "SamChinellato",
+      "avatar_url": "https://avatars.githubusercontent.com/u/49278203?v=4",
+      "profile": "https://samuelechinellato.com/#/",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "stevenpatrick009",
+      "name": "stevenpatrick009",
+      "avatar_url": "https://avatars.githubusercontent.com/u/106097350?v=4",
+      "profile": "https://github.com/stevenpatrick009",
+      "contributions": [
+        "code"
+      ]
     }
   ],
   "commitConvention": "none"

README.md

@@ -261,10 +261,13 @@ check out our [Contributing Guide](/.github/CONTRIBUTING.md) and our
     <td align="center"><a href="https://github.com/Nirajsah"><img src="https://avatars.githubusercontent.com/u/51414373?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Niraj Sah</b></sub></a><br /><a href="https://github.com/carbon-design-system/carbon/commits?author=Nirajsah" title="Code">💻</a></td>
     <td align="center"><a href="https://github.com/allisonishida"><img src="https://avatars.githubusercontent.com/u/22247062?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Allison Ishida</b></sub></a><br /><a href="https://github.com/carbon-design-system/carbon/commits?author=allisonishida" title="Code">💻</a></td>
     <td align="center"><a href="https://github.com/alewitt2"><img src="https://avatars.githubusercontent.com/u/48691328?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Alex Lewitt</b></sub></a><br /><a href="https://github.com/carbon-design-system/carbon/commits?author=alewitt2" title="Code">💻</a></td>
-    <td align="center"><a href="https://haruki-kuriwada.netlify.app/"><img src="https://avatars.githubusercontent.com/u/62743644?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Ruki</b></sub></a><br /><a href="https://github.com/carbon-design-system/carbon/commits?author=kuri-sun" title="Code">💻</a></td>
-    <td align="center"><a href="https://github.com/allisonishida"><img src="https://avatars.githubusercontent.com/u/22247062?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Allison Ishida</b></sub></a><br /><a href="https://github.com/carbon-design-system/carbon/commits?author=allisonishida" title="Code">💻</a></td>
     <td align="center"><a href="https://github.com/Tresau-IBM"><img src="https://avatars.githubusercontent.com/u/148357638?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Tresau-IBM</b></sub></a><br /><a href="https://github.com/carbon-design-system/carbon/commits?author=Tresau-IBM" title="Code">💻</a></td>
-    <td align="center"><a href="https://github.com/alewitt2"><img src="https://avatars.githubusercontent.com/u/48691328?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Alex Lewitt</b></sub></a><br /><a href="https://github.com/carbon-design-system/carbon/commits?author=alewitt2" title="Code">💻</a></td>
+    <td align="center"><a href="https://haruki-kuriwada.netlify.app/"><img src="https://avatars.githubusercontent.com/u/62743644?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Ruki</b></sub></a><br /><a href="https://github.com/carbon-design-system/carbon/commits?author=kuri-sun" title="Code">💻</a></td>
+    <td align="center"><a href="https://github.com/matejoslav"><img src="https://avatars.githubusercontent.com/u/8973672?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Matej Ocovsky</b></sub></a><br /><a href="https://github.com/carbon-design-system/carbon/commits?author=matejoslav" title="Code">💻</a></td>
+    <td align="center"><a href="https://samuelechinellato.com/#/"><img src="https://avatars.githubusercontent.com/u/49278203?v=4?s=100" width="100px;" alt=""/><br /><sub><b>SamChinellato</b></sub></a><br /><a href="https://github.com/carbon-design-system/carbon/commits?author=SamChinellato" title="Code">💻</a></td>
+  </tr>
+  <tr>
+    <td align="center"><a href="https://github.com/stevenpatrick009"><img src="https://avatars.githubusercontent.com/u/106097350?v=4?s=100" width="100px;" alt=""/><br /><sub><b>stevenpatrick009</b></sub></a><br /><a href="https://github.com/carbon-design-system/carbon/commits?author=stevenpatrick009" title="Code">💻</a></td>
   </tr>
 </table>
 

packages/react/__tests__/__snapshots__/PublicAPI-test.js.snap

@@ -8102,6 +8102,15 @@ Map {
       "cols": Object {
         "type": "number",
       },
+      "counterMode": Object {
+        "args": Array [
+          Array [
+            "character",
+            "word",
+          ],
+        ],
+        "type": "oneOf",
+      },
       "defaultValue": Object {
         "args": Array [
           Array [

packages/react/src/components/TextArea/TextArea-test.js

@@ -214,22 +214,69 @@ describe('TextArea', () => {
       ).toEqual(1);
     });
 
-    it('should have label and counter disabled', () => {
+    describe('word counter', () => {
+      it('should not render element with only counterMode prop passed in', () => {
+        render(
+          <TextArea
+            id="wordCounterTestWrapper1"
+            labelText="testLabel"
+            counterMode={'word'}
+          />
+        );
+        expect(
+          // eslint-disable-next-line testing-library/no-node-access
+          screen.getByText('testLabel').closest(`${prefix}--text-area__counter`)
+        ).toEqual(null);
+      });
+    });
+  });
+
+  it('should have label and counter disabled', () => {
+    render(
+      <TextArea
+        disabled
+        enableCounter
+        id="testing"
+        labelText="testLabel"
+        maxCount={100}
+      />
+    );
+    expect(screen.getByText('testLabel')).toHaveClass(
+      `${prefix}--label--disabled`
+    );
+    expect(screen.getByText('0/100')).toHaveClass(`${prefix}--label--disabled`);
+  });
+});
+
+describe('events', () => {
+  describe('disabled textarea', () => {
+    it('should not invoke onClick when textarea is clicked', async () => {
+      const onClick = jest.fn();
       render(
         <TextArea
           disabled
-          enableCounter
           id="testing"
           labelText="testLabel"
-          maxCount={100}
+          onClick={onClick}
         />
       );
-      expect(screen.getByText('testLabel')).toHaveClass(
-        `${prefix}--label--disabled`
-      );
-      expect(screen.getByText('0/100')).toHaveClass(
-        `${prefix}--label--disabled`
+      await userEvent.click(screen.getByLabelText('testLabel'));
+      expect(onClick).not.toHaveBeenCalled();
+    });
+
+    it('should not invoke onChange', async () => {
+      const onChange = jest.fn();
+      render(
+        <TextArea
+          disabled
+          id="testing"
+          labelText="testLabel"
+          onChange={onChange}
+        />
       );
+      await userEvent.click(screen.getByLabelText('testLabel'));
+      await userEvent.keyboard('big blue');
+      expect(onChange).not.toHaveBeenCalled();
     });
   });
 

packages/react/src/components/TextArea/TextArea.tsx

@@ -45,7 +45,7 @@ export interface TextAreaProps
   disabled?: boolean;
 
   /**
-   * Specify whether to display the character counter
+   * Specify whether to display the counter
    */
   enableCounter?: boolean;
 
@@ -88,7 +88,7 @@ export interface TextAreaProps
   light?: boolean;
 
   /**
-   * Max character count allowed for the textarea. This is needed in order for enableCounter to display
+   * Max entity count allowed for the textarea. This is needed in order for enableCounter to display
    */
   maxCount?: number;
 
@@ -138,6 +138,11 @@ export interface TextAreaProps
    * Provide the text that is displayed when the control is in warning state
    */
   warnText?: ReactNodeLike;
+
+  /**
+   * Specify the method used for calculating the counter number
+   */
+  counterMode?: 'character' | 'word';
 }
 
 const TextArea = React.forwardRef((props: TextAreaProps, forwardRef) => {
@@ -156,6 +161,7 @@ const TextArea = React.forwardRef((props: TextAreaProps, forwardRef) => {
     placeholder = '',
     enableCounter = false,
     maxCount = undefined,
+    counterMode = 'character',
     warn = false,
     warnText = '',
     rows = 4,
@@ -165,21 +171,32 @@ const TextArea = React.forwardRef((props: TextAreaProps, forwardRef) => {
   const prefix = usePrefix();
   const { isFluid } = useContext(FormContext);
   const { defaultValue, value } = other;
-  const [textCount, setTextCount] = useState(
-    defaultValue?.toString()?.length || value?.toString()?.length || 0
-  );
+
   const { current: textAreaInstanceId } = useRef(getInstanceId());
 
   const textareaRef = useRef<HTMLTextAreaElement>(null);
   const ref = useMergedRefs([forwardRef, textareaRef]) as
     | React.LegacyRef<HTMLTextAreaElement>
     | undefined;
 
+  function getInitialTextCount(): number {
+    const targetValue =
+      defaultValue || value || textareaRef.current?.value || '';
+    const strValue = targetValue.toString();
+
+    if (counterMode === 'character') {
+      return strValue.length;
+    } else {
+      return strValue.match(/\w+/g)?.length || 0;
+    }
+  }
+
+  const [textCount, setTextCount] = useState(getInitialTextCount());
+
   useEffect(() => {
-    setTextCount(
-      defaultValue?.toString()?.length || value?.toString()?.length || 0
-    );
-  }, [value, defaultValue]);
+    setTextCount(getInitialTextCount());
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [value, defaultValue, counterMode]);
 
   useIsomorphicEffect(() => {
     if (other.cols && textareaRef.current) {
@@ -192,19 +209,92 @@ const TextArea = React.forwardRef((props: TextAreaProps, forwardRef) => {
 
   const textareaProps: {
     id: TextAreaProps['id'];
+    onKeyDown: (evt: React.KeyboardEvent) => void;
     onChange: TextAreaProps['onChange'];
     onClick: TextAreaProps['onClick'];
     maxLength?: number;
+    onPaste?: React.ClipboardEventHandler<HTMLTextAreaElement>;
   } = {
     id,
+    onKeyDown: (evt) => {
+      if (!disabled && enableCounter && counterMode === 'word') {
+        const key = evt.which;
+
+        if (maxCount && textCount >= maxCount && key === 32) {
+          evt.preventDefault();
+        }
+      }
+    },
+    onPaste: (evt) => {
+      if (!disabled) {
+        if (
+          counterMode === 'word' &&
+          enableCounter &&
+          typeof maxCount !== 'undefined' &&
+          textareaRef.current !== null
+        ) {
+          const existingWords: string[] =
+            textareaRef.current.value.match(/\w+/g) || [];
+          const pastedWords: string[] =
+            evt.clipboardData.getData('Text').match(/\w+/g) || [];
+
+          const totalWords = existingWords.length + pastedWords.length;
+
+          if (totalWords > maxCount) {
+            evt.preventDefault();
+
+            const allowedWords = existingWords
+              .concat(pastedWords)
+              .slice(0, maxCount);
+
+            setTimeout(() => {
+              setTextCount(maxCount);
+            }, 0);
+
+            textareaRef.current.value = allowedWords.join(' ');
+          }
+        }
+      }
+    },
     onChange: (evt) => {
-      if (!disabled && onChange) {
-        evt?.persist?.();
-        // delay textCount assignation to give the textarea element value time to catch up if is a controlled input
-        setTimeout(() => {
-          setTextCount(evt.target?.value?.length);
-        }, 0);
-        onChange(evt);
+      if (!disabled) {
+        if (counterMode == 'character') {
+          evt?.persist?.();
+          // delay textCount assignation to give the textarea element value time to catch up if is a controlled input
+          setTimeout(() => {
+            setTextCount(evt.target?.value?.length);
+          }, 0);
+        } else if (counterMode == 'word') {
+          if (!evt.target.value) {
+            setTimeout(() => {
+              setTextCount(0);
+            }, 0);
+
+            return;
+          }
+
+          if (
+            enableCounter &&
+            typeof maxCount !== 'undefined' &&
+            textareaRef.current !== null
+          ) {
+            const matchedWords = evt.target?.value?.match(/\w+/g);
+            if (matchedWords && matchedWords.length <= maxCount) {
+              textareaRef.current.removeAttribute('maxLength');
+
+              setTimeout(() => {
+                setTextCount(matchedWords.length);
+              }, 0);
+            } else if (matchedWords && matchedWords.length > maxCount) {
+              setTimeout(() => {
+                setTextCount(matchedWords.length);
+              }, 0);
+            }
+          }
+        }
+        if (onChange) {
+          onChange(evt);
+        }
       }
     },
     onClick: (evt) => {
@@ -248,7 +338,9 @@ const TextArea = React.forwardRef((props: TextAreaProps, forwardRef) => {
   ) : null;
 
   const counter =
-    enableCounter && maxCount ? (
+    enableCounter &&
+    maxCount &&
+    (counterMode === 'character' || counterMode === 'word') ? (
       <Text
         as="div"
         className={counterClasses}>{`${textCount}/${maxCount}`}</Text>
@@ -298,9 +390,16 @@ const TextArea = React.forwardRef((props: TextAreaProps, forwardRef) => {
   }
 
   if (enableCounter) {
-    textareaProps.maxLength = maxCount;
+    // handle different counter mode
+    if (counterMode == 'character') {
+      textareaProps.maxLength = maxCount;
+    }
   }
-  const ariaAnnouncement = useAnnouncer(textCount, maxCount);
+  const ariaAnnouncement = useAnnouncer(
+    textCount,
+    maxCount,
+    counterMode === 'word' ? 'words' : undefined
+  );
 
   const input = (
     <textarea
@@ -369,6 +468,11 @@ TextArea.propTypes = {
    */
   cols: PropTypes.number,
 
+  /**
+   * Specify the method used for calculating the counter number
+   */
+  counterMode: PropTypes.oneOf(['character', 'word']),
+
   /**
    * Optionally provide the default value of the `<textarea>`
    */
@@ -380,7 +484,7 @@ TextArea.propTypes = {
   disabled: PropTypes.bool,
 
   /**
-   * Specify whether to display the character counter
+   * Specify whether to display the counter
    */
   enableCounter: PropTypes.bool,
 
@@ -426,7 +530,7 @@ TextArea.propTypes = {
   ),
 
   /**
-   * Max character count allowed for the textarea. This is needed in order for enableCounter to display
+   * Max entity count allowed for the textarea. This is needed in order for enableCounter to display
    */
   maxCount: PropTypes.number,